| Internet-Draft | Composite Token Claims | October 2023 |
| Lemmons | Expires 25 April 2024 | [Page] |
Composition claims are CBOR Web Token claims that define logical relationships between sets of claims and provide for private claim values via encryption.¶
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 25 April 2024.¶
Copyright (c) 2023 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.¶
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.¶
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 claims identify claim sets and define how the acceptability of the claim sets affects the acceptability of the composition claim.¶
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 claims, 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.¶
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.¶
These claims allow multiple claim sets to be evaluated. This claim identifies 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.¶
The "or" (Or) claim identifies one or more sets of claims of which at least one is valid. 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 "nor" (Nor) claim identifies one or more sets of claims of which none are valid. 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 "and" (And) claim idenfies one or more sets of claims of which all are valid. 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.¶
Eveloped 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.¶
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.¶
Each element of the map is interpreted as follows:¶
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.¶
Use of this claim is OPTIONAL. The Claim Key [add key number] is used to identify this 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 may be present in the token.¶
If a claim listed in the "crit" claim is present in a claim set and the processor cannot understand or process the claim, the claim set MUST be rejected.¶
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 a "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. That is, when a "crit" claim is present, any claims not listed may be assumed to be non-critical.¶
Use of this claim is OPTIONAL. The Claim Key [add key number] is used to identify this claim.¶
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.¶
Additionally, 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.¶
[When claims keys have been identified and selected, this section will ask IANA to register those keys.]¶