Internet DRAFT - draft-lemmons-composite-claims
draft-lemmons-composite-claims
TBD WG C. Lemmons
Internet-Draft Comcast
Intended status: Standards Track 24 October 2022
Expires: 27 April 2023
Composite Token Claims
draft-lemmons-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 27 April 2023.
Copyright Notice
Copyright (c) 2022 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 27 April 2023 [Page 1]
Internet-Draft Composite Token Claims October 2022
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2
3. Claims . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3.1. Logical Claims . . . . . . . . . . . . . . . . . . . . . 3
3.1.1. or (Or) Claim . . . . . . . . . . . . . . . . . . . . 3
3.1.2. nor (Not Or) Claim . . . . . . . . . . . . . . . . . 3
3.1.3. and (And) Claim . . . . . . . . . . . . . . . . . . . 3
3.2. Enveloped Claims . . . . . . . . . . . . . . . . . . . . 4
3.2.1. env (Enveloped) Claim . . . . . . . . . . . . . . . . 4
3.2.2. crit (Critical) Claim . . . . . . . . . . . . . . . . 5
4. Security Considerations . . . . . . . . . . . . . . . . . . . 5
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
6. Normative References . . . . . . . . . . . . . . . . . . . . 6
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 6
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.
3. Claims
Composition claims identify claim sets and define how the
acceptability of the claim sets affects the acceptability of the
composition claim.
Lemmons Expires 27 April 2023 [Page 2]
Internet-Draft Composite Token Claims October 2022
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.
3.1. Logical Claims
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.
3.1.1. or (Or) Claim
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.
3.1.2. nor (Not Or) 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.
3.1.3. and (And) 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.
Lemmons Expires 27 April 2023 [Page 3]
Internet-Draft Composite Token Claims October 2022
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.
3.2. Enveloped Claims
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.
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.
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 same
cardinality as 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. The members of the array in the
plaintext are CBOR data items that are appropriate as values for
the corresponding claim.
For each claim described in the "env" claim that the processor can
decrypt, the claim MAY be processed exactly as though it were a
sibling claim to the "env" claim, including the limitation that a map
of claims is invalid if it contains a claim more than once. An
invalid claim set MUST be rejected. A claim set that contains
duplicate claims MUST be rejected, even if the duplicates are not
decrypted.
Lemmons Expires 27 April 2023 [Page 4]
Internet-Draft Composite Token Claims October 2022
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.
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 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.
4. Security Considerations
All security considerations relevant to CWTs in general will apply to
CWTs that use composition claims.
Lemmons Expires 27 April 2023 [Page 5]
Internet-Draft Composite Token Claims October 2022
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].
5. IANA Considerations
[When claims keys have been identified and selected, this section
will ask IANA to register those keys.]
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>.
[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>.
Author's Address
Chris Lemmons
Comcast
Email: chris_lemmons@comcast.com
Lemmons Expires 27 April 2023 [Page 6]
