RFC 9597
CBOR Web Token (CWT) Claims in COSE Headers
RFC 9597: CBOR Web Token (CWT) Claims in COSE Headers 🎀
Title block tea ☕
- Number: RFC 9597
- Authors: Tobias Looker (Mattr) and Michael B. Jones (Self-Issued Consulting) ✨
- Category: Standards Track 🔥
- ISSN: 2070-1721
- Date: June 2024 🌸
- Obsoletes / Updates: none listed in the title block 💅
Abstract 🦋
Okay bestie, this doc is about putting CWT claims into the header parameters of ANY CBOR Object Signing and Encryption (COSE) structure 💖. Why? So apps can use CWT claims in encrypted COSE structures and/or COSE structures with detached signatures, and have some claims visible before decryption and/or without digging into the detached payload. It's also for payloads that aren't CWT Claims Sets, even payloads that aren't CBOR at all. Main character energy 👑
Status of This Memo 📜
This is an Internet Standards Track document. ✨
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community, it has received public review, and it has been approved for publication by the Internet Engineering Steering Group (IESG). If you want more info on Internet Standards, check out Section 2 of RFC 7841 🎀
Info about the current status of this document, any errata, and how to give feedback is at https://www.rfc-editor.org/info/rfc9597 🌈
Copyright Notice 🔒
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. 💜
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as in effect on the date of publication of this document. Please read these carefully, because they spell out your rights and restrictions for this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions, and they're provided without warranty as described in the Revised BSD License. Don't skip the fine print, it matters 🙈
Table of Contents 🧚
1. Introduction
1.1. Requirements Terminology
2. Representation
3. Privacy Considerations
4. Security Considerations
5. IANA Considerations
6. References
6.1. Normative References
6.2. Informative References
Acknowledgements
Authors' Addresses1. Introduction ✨
Okay so in some COSE applications, it's super useful to have a standard way to represent CWT claims [RFC8392] in the header parameters. This covers encrypted COSE structures (which may or may not be an encrypted CWT) and/or anything with a detached signature. Another use case is CWT claims with payloads that aren't CWT Claims Sets, including payloads that aren't CBOR at all. For example, an app might want an "iss" (issuer) claim in a COSE_Sign1 structure when the thing being signed is a non-CBOR data structure, like a bitmap image, and the issuer value is used for key discovery 🦋
Section 5.3 of [RFC7519], "JSON Web Token (JWT)", already defined a similar mechanism for expressing selected JWT-based claims as JSON Object Signing and Encryption (JOSE) header parameters. That JWT feature existed so certain claims, like the Issuer value, could still be visible to software processing the JWT even when the JWT is encrypted. CWTs never got a matching feature, which was an omission this specification fixes 🙌
Putting CWT claim values straight into COSE header parameter values would NOT work, since the numeric header parameter assignments and the numeric CWT claim assignments conflict. So instead, this specification defines a single header parameter, registered in the IANA "COSE Header Parameters" registry, that creates a place to store CWT claims in a COSE header parameter 💅
This spec doesn't define how to use CWT claims and their semantics for particular apps, whether they're in the COSE payload, the CWT Claims header parameter, or both. So understanding how to process the CWT Claims header parameter requires unambiguously knowing the intended interpretation. The info needed for that MAY come from other header parameters. Unless there's already a natural way to provide this info at an appropriate level of integrity protection and authentication, a RECOMMENDED way to include it in the COSE structure is the use of the "typ" (type) Header Parameter [RFC9596]. Other methods for determining the intended interpretation MAY also be used. Recipients of the CWT Claims header parameter MUST NOT use the information in it beyond the integrity protection or authentication afforded to the CWT Claims header and the information used to derive its intended interpretation. Read that twice, it's important 🫶
1.1. Requirements Terminology 🎀
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 🌸
2. Representation 🍓
This document defines the following COSE header parameter:
+========+=======+=======+==============+===============+===========+
| Name | Label | Value | Value | Description | Reference |
| | | Type | Registry | | |
+========+=======+=======+==============+===============+===========+
| CWT | 15 | map | map keys in | Location | Section 2 |
| Claims | | | [CWT.Claims] | for CWT | of RFC |
| | | | | Claims in | 9597 |
| | | | | COSE Header | |
| | | | | Parameters | |
+--------+-------+-------+--------------+---------------+-----------+Table 1
This next bit is a non-normative description of the value type for the CWT claim header parameter, written in CDDL [RFC8610]. Vibes only 💜
CWT-Claims = {
* Claim-Label => any
}
Claim-Label = int / textOkay, so if CWT claims show up in BOTH the payload and the header of a CWT, the app receiving it MUST verify that their values are identical, unless the app defines other specific processing rules for those claims. Super important check 🔥
It is RECOMMENDED that the CWT Claims header parameter only be used in a protected header, so the contents can't be malleable 🔒 The header parameter MUST only occur once in either the protected or the unprotected header of a COSE structure. One and done 💅
The CWT Claims header parameter MAY be used in any COSE object that uses header parameters, such as COSE_Sign objects. Its use is NOT restricted to CWTs, so go wild 🌈
3. Privacy Considerations 🙈
Some registered CWT claims may contain privacy-sensitive info. Since CWT claims in COSE headers are NOT encrypted, when privacy-sensitive info is present in these claims, apps and protocols using them should make sure these COSE objects are only visible to parties who are appropriately allowed to access that sensitive info 🔐
4. Security Considerations 🛡️
Implementers should also review the security considerations for CWT, which are documented in Section 8 of [RFC8392]. 💀
As described in [RFC9052], if the COSE payload is transported separately ("detached content"), then it's the app's job to make sure it gets transported without changes. Don't be the reason things break 😭
The reason apps need to verify that CWT claims present in both the payload and the header of a CWT are identical, unless they define other specific processing rules for those claims, is to avoid confusion. Different values for the same claim could lead to inconsistent processing, and nobody wants that 🙅♀️
Processing info in claims BEFORE validating that their integrity is cryptographically secure can pose security risks. This is true whether the claims are in the payload or a header parameter. Implementers must ensure that any tentative decisions made based on previously unverified info are confirmed once the cryptographic processing is complete. This includes any info that was used to derive the intended interpretation of the CWT claims parameter. Please don't skip this one, it's the drama that causes real problems 😱
5. IANA Considerations 🌷
IANA has registered the new COSE header parameter "CWT Claims" defined in Table 1 in the "COSE Header Parameters" registry [COSE.HeaderParameters]. Registered and official ✨
6. References 📚
6.1. Normative References 💜
[COSE.HeaderParameters]
IANA, "COSE Header Parameters",
<https://www.iana.org/assignments/cose/>.
[CWT.Claims]
IANA, "CBOR Web Token (CWT) Claims",
<https://www.iana.org/assignments/cwt/>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig,
"CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392,
May 2018, <https://www.rfc-editor.org/info/rfc8392>.
[RFC9596] Jones, M.B. and O. Steele, "CBOR Object Signing and
Encryption (COSE) "typ" (type) Header Parameter",
RFC 9596, DOI 10.17487/RFC9596, June 2024,
<https://www.rfc-editor.org/info/rfc9596>.6.2. Informative References 🦋
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<https://www.rfc-editor.org/info/rfc7519>.
[RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
Definition Language (CDDL): A Notational Convention to
Express Concise Binary Object Representation (CBOR) and
JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
June 2019, <https://www.rfc-editor.org/info/rfc8610>.
[RFC9052] Schaad, J., "CBOR Object Signing and Encryption (COSE):
Structures and Process", STD 96, RFC 9052,
DOI 10.17487/RFC9052, August 2022,
<https://www.rfc-editor.org/info/rfc9052>.Acknowledgements 🫶
Huge thank you to Daisuke Ajitomi, Claudio Allocchio, Carsten Bormann, Laurence Lundblade, Ivaylo Petrov, Ines Robles, Orie Steele, Hannes Tschofenig, Paul Wouters, and Peter Yee for their valuable contributions to this spec. Legends 👑
Authors' Addresses 💌
Tobias Looker
Mattr
Email: tobias.looker@mattr.global
Michael B. Jones
Self-Issued Consulting
Email: michael_b_jones@hotmail.com
URI: https://self-issued.info/📦 where this page comes from
- ietf: rfc9597 2024-06
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms