COSE WG C. Lemmons Internet-Draft Comcast Intended status: Standards Track 21 October 2024 Expires: 24 April 2025 Composite Token Claims draft-lemmons-cose-composite-claims-00 Abstract Composition claims are CBOR Web Token claims that define logical relationships between sets of claims and provide for private claim values via encryption. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 24 April 2025. 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) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to 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 are provided without warranty as described in the Revised BSD License. Lemmons Expires 24 April 2025 [Page 1] Internet-Draft Composite Token Claims October 2024 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 3. Claims . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3.1. Logical Claims . . . . . . . . . . . . . . . . . . . . . 3 3.1.1. or (Or) Claim . . . . . . . . . . . . . . . . . . . . 3 3.1.2. nor (Not Or) Claim . . . . . . . . . . . . . . . . . 4 3.1.3. and (And) Claim . . . . . . . . . . . . . . . . . . . 4 3.1.4. Examples . . . . . . . . . . . . . . . . . . . . . . 5 3.2. Enveloped Claims . . . . . . . . . . . . . . . . . . . . 6 3.2.1. env (Enveloped) Claim . . . . . . . . . . . . . . . . 6 3.2.2. crit (Critical) Claim . . . . . . . . . . . . . . . . 7 3.2.3. Example . . . . . . . . . . . . . . . . . . . . . . . 8 3.2.4. Profiling the "env" Claim . . . . . . . . . . . . . . 9 3.2.5. Other methods of selectively disclosing claims . . . 9 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 6. Normative References . . . . . . . . . . . . . . . . . . . . 11 7. Informative References . . . . . . . . . . . . . . . . . . . 11 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 1. Introduction Composition claims are claims defined for CBOR Web Tokens (CWTs) [RFC7519]. These claims include logical operators "or", "nor", and "and" as well as a wrapper that encrypts the values, but not the keys, of some claims. 2. 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. This document reuses terminology from CWT [RFC7519] and COSE [RFC9052]. This term is defined by this specification: Composition Claim A composition claim is a CWT claim that contains, as part of its value, one or more CWT claim sets. Lemmons Expires 24 April 2025 [Page 2] Internet-Draft Composite Token Claims October 2024 3. Claims Composition claims contain one or more claim sets. In CWTs without composition claims, there is exactly one set of claims, so the acceptability of the claim set decides the acceptability of the CWT. However, this document defines multiple sets of claim sets, so it instead refers to accepting or rejecting claim sets. If the primary claim set is unacceptable, the CWT is unacceptable and MUST be rejected. Some applications use tokens to convey information. For example, a token might simply have a subject claim that identifies the bearer and the relying party simply uses that as information, not necessarily as a means by which to provide or deny access or make some other kind of decision. In this context, the token simply describes all situations in which the token would accurately describe that situation. That is to say, the token describes the set of contexts in which it would be acceptable. Composition claims can be nested to an arbitrary level of depth. Implementations MAY limit the depth of composition nesting by rejecting CWTs with too many levels but MUST support at least four levels of nesting. 3.1. Logical Claims These claims identify one or more sets of claims in a logical relation. The type of these claims is array and the elements of the array are maps that are themselves sets of claims. For the following CDDL, Claims-Set is a map of claims as defined in [RFC8392]. It is described informatively in [draft-ietf-rats-eat] Appendix D. 3.1.1. or (Or) Claim The "or" (Or) claim identifies one or more sets of claims of which at least one is acceptable. If every set of claims in an "or" claim would, when considered with all the other relevant claims, result in the claim set being rejected, the claim set containing the "or" claim MUST be rejected. Use of this claim is OPTIONAL. The Claim Key [add key number] is used to identify this claim. The "or" (OR) claim is described by the following CDDL: Lemmons Expires 24 April 2025 [Page 3] Internet-Draft Composite Token Claims October 2024 $$Claims-Set-Claims //= ( or-claim-label => or-claim-value ) or-claim-label = TBD or-claim-value = [ + Claims-Set ] 3.1.2. nor (Not Or) Claim The "nor" (Nor) claim identifies one or more sets of claims of which none are acceptable. If any set of claims in a "nor" claim would, when considered with all other relevant claims, result in the claim set being accepted, the claim set containing the "nor" MUST be rejected. This is the logical negation of the "or" claim. Use of this claim is OPTIONAL. The Claim Key [add key number] is used to identify this claim. The "nor" (NOR) claim is described by the following CDDL: $$Claims-Set-Claims //= ( nor-claim-label => nor-claim-value ) nor-claim-label = TBD nor-claim-value = [ + Claims-Set ] 3.1.3. and (And) Claim The "and" (And) claim identifies one or more sets of claims of which all are acceptable. If any claim in an "and" claim would, when considered with all other relevant claims, result in the claim set being rejected, the claim set containing the "and" claim MUST be rejected. The "and" claim is often unnecessary because a given claim set is only accepted when all its claims are acceptable. However, CBOR maps cannot have duplicate keys, so claims cannot be repeated more than once. The "and" claim is useful for claims that may be claimed multiple times, including the "or" and "nor" claims. Use of this claim is OPTIONAL. The Claim Key [add key number] is used to identify this claim. The "and" (AND) claim is described by the following CDDL: $$Claims-Set-Claims //= ( and-claim-label => and-claim-value ) and-claim-label = TBD and-claim-value = [ + Claims-Set ] Lemmons Expires 24 April 2025 [Page 4] Internet-Draft Composite Token Claims October 2024 3.1.4. Examples These logical claims can be used to describe more complex relationships between claims. For example, the following claim set describes a token with multiple subject claims. This token describes a situation where either of the two subjects must be true, but the issuer is not disclosing which one must be true or even whether the two subjects are genuinely different. { /or/ TBD: [ { /sub/ 2: "george@example.net" }, { /sub/ 2: "harriet@example.net" } ] } A relying party that receives this token does not know if the bearer is George or Harriet, but it knows that the bearer is one of them. The "nor" claim is useful both as a logical negation, even when only one claim is present. For example, consider the following claim set: { /nor/ TBD: [ { /aud/ 3: "https://example.com" } ] } This token is intended for any audience except "example.com". Complex relationshops can also be described using the claims in combination. The "geohash" claim [CTA5009A] describes a geographical region. For example: { { /aud/ 3: "https://example.com" }, { /geohash/ 282: "9q8yy" }, { /nor/ TBD: [ { /geohash/ 282: ["9q8yy9", "9q8yyd"] } ] } } This token describes an audience of "https://example.com" (https://example.com") and a region described by the geohash of "9q8yy" that does not include the region described by "9q8yy9" or "9q8yyd". Lemmons Expires 24 April 2025 [Page 5] Internet-Draft Composite Token Claims October 2024 And if a very complex relationship is required, the "and" claim can be used to combine multiple claims. For example, consider the following claim set: { /and/ TBD: [ { /or/ TBD: [ { /sub/ 2: "george@example.net" }, { /sub/ 2: "harriet@example.net" } ] }, { /or/ TBD: [ { /aud/ 3: "https://example.com" }, { /aud/ 3: "https://example.net" } ] } ] } This admittedly contrived example describes a token that is valid for either George or Harriet and is intended for either https://example.com (https://example.com) or https://example.net (https://example.net). It is a bit contrived because the "aud" claim already describes a list of acceptable audiences. The use of the "and" claim is required in order to effectively repeat the "or" claim, because a single claim set cannot contain the same claim twice. 3.2. Enveloped Claims Enveloped claims identify a set of claims that should be considered as part of a set of claims, but that require decryption before they can be processed. This is sometimes useful when some processors do not need to evaluate some claims in order to determine if a claim set is acceptable. 3.2.1. env (Enveloped) Claim The "env" (Enveloped) claim allows an issuer to make private claims that cannot be read by a processor that does not possess the decryption key. The type of this claim is a map; the keys of the map are either claim keys (string, unsigned integer, or negative integer) or arrays of claim keys; the values of the map are COSE_Encrypt or COSE_Encrypt0 objects, as defined by Section 5 of [RFC9052]. The plaintext of the Enveloped Message is either a CBOR data item or a CBOR array of data items. Lemmons Expires 24 April 2025 [Page 6] Internet-Draft Composite Token Claims October 2024 Each element of the map is interpreted as follows: * If the key is a claim key, the plaintext of the Enveloped Message in its value is a CBOR data item that is appropriate as a value for that claim. * If the key is an array of claim keys, the plaintext of the Enveloped Message in its value is an array with the cardinality equal to or larger than the array of claim keys. Each member of the array in the plaintext corresponds with the member in the array in the key with the same index. Elements of the value array with indexes that do not correspond with elements of the key array MUST be ignored. The members of the array in the plaintext are CBOR data items that are appropriate as values for the corresponding claim. The array of claim keys MUST contain at least one element. These claims described in the "env" claim MAY be processed exactly as though the "env" claim were replaced with the decrypted claims, including the limitation that a map of claims is invalid if it contains a claim more than once. The "env" claim is removed from the map before looking for duplicates, so an "env" claim that contains an "env" claim may potentially be accepted. An invalid claim set MUST be rejected. A claim set that contains duplicate claims MUST be rejected, even if the duplicates are not decrypted. Since claims are optionally decrypted and added as sibling claims, issuers can ensure that this occurs by adding them to the "crit" claim. In the absence of a "crit" claim, the relying party MAY choose not to decrypt the claims. Indeed, a relying party may not even have the decryption key for claims that are not relevant to its processing. Use of this claim is OPTIONAL. The Claim Key [add key number] is used to identify this claim. 3.2.2. crit (Critical) Claim The "crit" (Critical) claim lists the claims required to process this token. The type of this claim is array and the elements of the array are strings, negative integers, or unsigned integers. The elements of the array correspond to claims that MUST be present in the token. If a claim listed in the "crit" claim is present in a claim set and the processor cannot process the claim for any reason, the claim set MUST be rejected. Lemmons Expires 24 April 2025 [Page 7] Internet-Draft Composite Token Claims October 2024 If a claim listed in the "crit" claim is not present in a claim set, the claim set MUST be rejected. If a claim listed in the "crit" claim is present in a claim set as part of an "env" claim (and, should it be decrypted, be processed as a sibling of that "env" claim), if the value of the claim is not decrypted (for any reason) and processed and any possible value of the claim would result in the request being rejected, the claim set MUST be rejected. Since any processor MAY decrypt or not decrypt claim values in a "env" claim, this means a processor MAY reject any claim set that contains a claim that could have a value that would require rejection. If a "crit" claim is present in a claim set, a processor SHOULD consider claims it does not understand to be acceptable if they are not present in the "crit" claim, unless application-specific processing defines otherwise. That is, when a "crit" claim is present, any claims not listed may by default be assumed to be non- critical. Use of this claim is OPTIONAL. The Claim Key [add key number] is used to identify this claim. 3.2.3. Example Consider a very simple token that might be passed like this: { /iss/ 1: "https://example.com", /sub/ 2: "george@example.net", /aud/ 3: "https://example.com" } The identity of George is present and clear in the token. Some parties receiving this token might need to know that George is the subject. However, some may not. For example: * An intermediary proxy that only needs to know that the issuer is https://example.com (https://example.com) and the audience is https://example.com (https://example.com). * An origin behind the proxy that needs to know that George is the subject as well, so that it can customize its response. The intermediary is a relying party but does not need to know George's identity. The origin, however does. A token that permits this might look like this: Lemmons Expires 24 April 2025 [Page 8] Internet-Draft Composite Token Claims October 2024 { /iss/ 1: "https://example.com", /aud/ 3: "https://example.com", /env/ TBD: { [/sub/ 2]: [ h'', h'', h'' ] } } And the contents of the ciphertext might be: ["george@example.net", h'b73814740f877e8aa691fdab6cda'] The intermediary can process the token without decrypting the "env" claim. The origin can decrypt the "env" claim and learn that George is the subject. The issuer used additional padding in the plaintext in order to avoid disclosing the length of the subject value. 3.2.4. Profiling the "env" Claim The "env" claim is only useful when the issuer can reliably expect a relying party that needs to understand the claim to be able to decrypt it. This document does not specify several important required details: * How the issuer and relying party establish trust. * How the issuer conveys the decryption key to the relying party. * How the issuer and relying party agree on the supported ciphers. These details are of necessity left to the application profile, since they will vary between applications. The "crit" claim can be used to ensure that the relying party knows which claims are encrypted and must be decrypted. 3.2.5. Other methods of selectively disclosing claims The "env" claim is only suitable for protecting claims under the following circumstances: * The issuer is the one that decides which claims are disclosed and to whom. * The issuer can reasonably pad the plaintext to avoid revealing the length of the claim. This requires the issuer to know the maximum length of claims that might be present. * The bearer does not need to control which claims are disclosed. Lemmons Expires 24 April 2025 [Page 9] Internet-Draft Composite Token Claims October 2024 * The claim labels are not sensitive information. If these are not the case, the "env" claim is not suitable. If the bearer is the one that controls selective disclosure, [draft-ietf- oauth-selective-disclosure-08] may be more appropriate. SD-JWTs also protect the claim labels, which the "env" claim does not. When the claims for different audiences are significantly different, multiple encrypted tokens can be used. This is likely to lead to larger sets of tokens in general, but is a very flexible approach. This protects the entire contents of each token from all parties that do not possess the decryption key for that token. 4. Security Considerations All security considerations relevant to CWTs in general will apply to CWTs that use composition claims. Additionally, processors of CWTs with composition claims will need to be aware of the possibility of receiving highly nested tokens. Excessive nesting can lead to overflows or other processing errors. The security of the "env" claim is subject to all the considerations detailed for COSE objects in Section 12 of [RFC9052]. Particular attention is required to length attacks. If the length of the Enveloped Claims is revealing as to its contents, as it most often will be in this context, issuers MUST pad the content appropriately in order to maintain the secrecy of its contents. "env" claims permit additional elements to be added after arrays of claim keys that can be used for padding when it is required. Since the "env" claim only encrypts the contents of the claim and not its key, it discloses the presence of a given claim. When this is undesirable, another composite claim like "and", "or", or even potentially "env" can be be used to mask the presence of the claim within. 5. IANA Considerations This specification requests that IANA register the following claim keys in the "CBOR Web Token (CWT) Claims" registry established by [RFC8392]: Claim Name: or Claim Description: Logical OR JWT Claim Name: N/A Claim Key: TBD (greater than 285) Claim Value Type(s): array Change Controller: IETF Lemmons Expires 24 April 2025 [Page 10] Internet-Draft Composite Token Claims October 2024 Claim Name: nor Claim Description: Logical NOR JWT Claim Name: N/A Claim Key: TBD (greater than 285) Claim Value Type(s): array Change Controller: IETF Claim Name: and Claim Description: Logical AND JWT Claim Name: N/A Claim Key: TBD (greater than 285) Claim Value Type(s): array Change Controller: IETF Claim Name: enc Claim Description: Logical AND JWT Claim Name: N/A Claim Key: TBD (greater than 285) Claim Value Type(s): array Change Controller: IETF Claim Name: crit Claim Description: Logical AND JWT Claim Name: N/A Claim Key: TBD (between 41 and 255) Claim Value Type(s): array Change Controller: IETF 6. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8392] Jones, M., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "CBOR Web Token (CWT)", RFC 8392, DOI 10.17487/RFC8392, May 2018, . [RFC9052] Schaad, J., "CBOR Object Signing and Encryption (COSE): Structures and Process", STD 96, RFC 9052, DOI 10.17487/RFC9052, August 2022, . 7. Informative References [CTA5009A] Consumer Technology Association, "CTA 5009-A: Fast and Readable Geographical Hashing", 2024, . Lemmons Expires 24 April 2025 [Page 11] Internet-Draft Composite Token Claims October 2024 Author's Address Chris Lemmons Comcast Email: chris_lemmons@comcast.com Lemmons Expires 24 April 2025 [Page 12]