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'<cose-protected-header>',
         h'<cose-unprotected-header>',
         h'<cose-ciphertext>'
       ]
     }
   }

   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,
              <https://www.rfc-editor.org/info/rfc2119>.

   [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>.

   [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>.

   [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>.

7.  Informative References

   [CTA5009A] Consumer Technology Association, "CTA 5009-A: Fast and
              Readable Geographical Hashing", 2024,
              <https://shop.cta.tech/products/fast-and-readable-
              geographical-hashing-cta-5009>.





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]