draft-ietf-ace-cbor-web-token-12.txt   draft-ietf-ace-cbor-web-token-13.txt 
ACE Working Group M. Jones ACE Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track E. Wahlstroem Intended status: Standards Track E. Wahlstroem
Expires: August 6, 2018 Expires: September 6, 2018
S. Erdtman S. Erdtman
Spotify AB Spotify AB
H. Tschofenig H. Tschofenig
ARM Ltd. ARM Ltd.
February 2, 2018 March 5, 2018
CBOR Web Token (CWT) CBOR Web Token (CWT)
draft-ietf-ace-cbor-web-token-12 draft-ietf-ace-cbor-web-token-13
Abstract Abstract
CBOR Web Token (CWT) is a compact means of representing claims to be CBOR Web Token (CWT) is a compact means of representing claims to be
transferred between two parties. The claims in a CWT are encoded in transferred between two parties. The claims in a CWT are encoded in
the Concise Binary Object Representation (CBOR) and CBOR Object the Concise Binary Object Representation (CBOR) and CBOR Object
Signing and Encryption (COSE) is used for added application layer Signing and Encryption (COSE) is used for added application layer
security protection. A claim is a piece of information asserted security protection. A claim is a piece of information asserted
about a subject and is represented as a name/value pair consisting of about a subject and is represented as a name/value pair consisting of
a claim name and a claim value. CWT is derived from JSON Web Token a claim name and a claim value. CWT is derived from JSON Web Token
skipping to change at page 1, line 42 skipping to change at page 1, line 42
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 6, 2018. This Internet-Draft will expire on September 6, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 38 skipping to change at page 2, line 38
3.1.7. cti (CWT ID) Claim . . . . . . . . . . . . . . . . . 6 3.1.7. cti (CWT ID) Claim . . . . . . . . . . . . . . . . . 6
4. Summary of the claim names, keys, and value types . . . . . . 6 4. Summary of the claim names, keys, and value types . . . . . . 6
5. CBOR Tags and Claim Values . . . . . . . . . . . . . . . . . 6 5. CBOR Tags and Claim Values . . . . . . . . . . . . . . . . . 6
6. CWT CBOR Tag . . . . . . . . . . . . . . . . . . . . . . . . 6 6. CWT CBOR Tag . . . . . . . . . . . . . . . . . . . . . . . . 6
7. Creating and Validating CWTs . . . . . . . . . . . . . . . . 7 7. Creating and Validating CWTs . . . . . . . . . . . . . . . . 7
7.1. Creating a CWT . . . . . . . . . . . . . . . . . . . . . 7 7.1. Creating a CWT . . . . . . . . . . . . . . . . . . . . . 7
7.2. Validating a CWT . . . . . . . . . . . . . . . . . . . . 8 7.2. Validating a CWT . . . . . . . . . . . . . . . . . . . . 8
8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
9.1. CBOR Web Token (CWT) Claims Registry . . . . . . . . . . 10 9.1. CBOR Web Token (CWT) Claims Registry . . . . . . . . . . 10
9.1.1. Registration Template . . . . . . . . . . . . . . . . 10 9.1.1. Registration Template . . . . . . . . . . . . . . . . 11
9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 11 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 11
9.2. Media Type Registration . . . . . . . . . . . . . . . . . 13 9.2. Media Type Registration . . . . . . . . . . . . . . . . . 13
9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 13 9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 13
9.3. CoAP Content-Formats Registration . . . . . . . . . . . . 13 9.3. CoAP Content-Formats Registration . . . . . . . . . . . . 14
9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 14 9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 14
9.4. CBOR Tag registration . . . . . . . . . . . . . . . . . . 14 9.4. CBOR Tag registration . . . . . . . . . . . . . . . . . . 14
9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 14 9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 14
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
10.1. Normative References . . . . . . . . . . . . . . . . . . 14 10.1. Normative References . . . . . . . . . . . . . . . . . . 14
10.2. Informative References . . . . . . . . . . . . . . . . . 15 10.2. Informative References . . . . . . . . . . . . . . . . . 15
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 15 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 16
A.1. Example CWT Claims Set . . . . . . . . . . . . . . . . . 16 A.1. Example CWT Claims Set . . . . . . . . . . . . . . . . . 16
A.2. Example keys . . . . . . . . . . . . . . . . . . . . . . 16 A.2. Example keys . . . . . . . . . . . . . . . . . . . . . . 16
A.2.1. 128-bit Symmetric Key . . . . . . . . . . . . . . . . 16 A.2.1. 128-bit Symmetric Key . . . . . . . . . . . . . . . . 17
A.2.2. 256-bit Symmetric Key . . . . . . . . . . . . . . . . 17 A.2.2. 256-bit Symmetric Key . . . . . . . . . . . . . . . . 17
A.2.3. ECDSA P-256 256-bit COSE Key . . . . . . . . . . . . 17 A.2.3. ECDSA P-256 256-bit COSE Key . . . . . . . . . . . . 17
A.3. Example Signed CWT . . . . . . . . . . . . . . . . . . . 17 A.3. Example Signed CWT . . . . . . . . . . . . . . . . . . . 18
A.4. Example MACed CWT . . . . . . . . . . . . . . . . . . . . 18 A.4. Example MACed CWT . . . . . . . . . . . . . . . . . . . . 19
A.5. Example Encrypted CWT . . . . . . . . . . . . . . . . . . 19 A.5. Example Encrypted CWT . . . . . . . . . . . . . . . . . . 20
A.6. Example Nested CWT . . . . . . . . . . . . . . . . . . . 20 A.6. Example Nested CWT . . . . . . . . . . . . . . . . . . . 21
A.7. Example MACed CWT with a floating-point value . . . . . . 21 A.7. Example MACed CWT with a floating-point value . . . . . . 22
Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 22 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 23
Appendix C. Document History . . . . . . . . . . . . . . . . . . 22 Appendix C. Document History . . . . . . . . . . . . . . . . . . 23
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26
1. Introduction 1. Introduction
The JSON Web Token (JWT) [RFC7519] is a standardized security token The JSON Web Token (JWT) [RFC7519] is a standardized security token
format that has found use in OAuth 2.0 and OpenID Connect format that has found use in OAuth 2.0 and OpenID Connect
deployments, among other applications. JWT uses JSON Web Signature deployments, among other applications. JWT uses JSON Web Signature
(JWS) [RFC7515] and JSON Web Encryption (JWE) [RFC7516] to secure the (JWS) [RFC7515] and JSON Web Encryption (JWE) [RFC7516] to secure the
contents of the JWT, which is a set of claims represented in JSON. contents of the JWT, which is a set of claims represented in JSON.
The use of JSON for encoding information is popular for Web and The use of JSON for encoding information is popular for Web and
native applications, but it is considered inefficient for some native applications, but it is considered inefficient for some
skipping to change at page 4, line 11 skipping to change at page 4, line 11
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
This document reuses terminology from JWT [RFC7519] and COSE This document reuses terminology from JWT [RFC7519] and COSE
[RFC8152]. [RFC8152].
StringOrURI StringOrURI
The "StringOrURI" term has the same meaning, syntax, and The "StringOrURI" term has the same meaning and processing rules
processing rules as the "StringOrURI" term defined in Section 2 of as the "StringOrURI" term defined in Section 2 of [RFC7519],
[RFC7519], except that it uses a CBOR text string instead of a except that it uses a CBOR text string instead of a JSON string
JSON string value. value.
NumericDate NumericDate
The "NumericDate" term has the same meaning, syntax, and The "NumericDate" term has the same meaning and processing rules
processing rules as the "NumericDate" term defined in Section 2 of as the "NumericDate" term defined in Section 2 of [RFC7519],
[RFC7519], except that the CBOR numeric date representation (from except that the CBOR numeric date representation (from
Section 2.4.1 of [RFC7049]) is used. The encoding is modified so Section 2.4.1 of [RFC7049]) is used. The encoding is modified so
that the leading tag 1 (epoch-based date/time) MUST be omitted. that the leading tag 1 (epoch-based date/time) MUST be omitted.
Claim Name Claim Name
The human-readable name used to identify a claim. The human-readable name used to identify a claim.
Claim Key Claim Key
The CBOR map key used to identify a claim. The CBOR map key used to identify a claim.
Claim Value Claim Value
skipping to change at page 5, line 15 skipping to change at page 5, line 15
3.1. Registered Claims 3.1. Registered Claims
None of the claims defined below are intended to be mandatory to use None of the claims defined below are intended to be mandatory to use
or implement. They rather provide a starting point for a set of or implement. They rather provide a starting point for a set of
useful, interoperable claims. Applications using CWTs should define useful, interoperable claims. Applications using CWTs should define
which specific claims they use and when they are required or which specific claims they use and when they are required or
optional. optional.
3.1.1. iss (Issuer) Claim 3.1.1. iss (Issuer) Claim
The "iss" (issuer) claim has the same meaning, syntax, and processing The "iss" (issuer) claim has the same meaning and processing rules as
rules as the "iss" claim defined in Section 4.1.1 of [RFC7519], the "iss" claim defined in Section 4.1.1 of [RFC7519], except that
except that the value is of type StringOrURI. The Claim Key 1 is the value is of type StringOrURI. The Claim Key 1 is used to
used to identify this claim. identify this claim.
3.1.2. sub (Subject) Claim 3.1.2. sub (Subject) Claim
The "sub" (subject) claim has the same meaning, syntax, and The "sub" (subject) claim has the same meaning and processing rules
processing rules as the "sub" claim defined in Section 4.1.2 of as the "sub" claim defined in Section 4.1.2 of [RFC7519], except that
[RFC7519], except that the value is of type StringOrURI. The Claim the value is of type StringOrURI. The Claim Key 2 is used to
Key 2 is used to identify this claim. identify this claim.
3.1.3. aud (Audience) Claim 3.1.3. aud (Audience) Claim
The "aud" (audience) claim has the same meaning, syntax, and The "aud" (audience) claim has the same meaning and processing rules
processing rules as the "aud" claim defined in Section 4.1.3 of as the "aud" claim defined in Section 4.1.3 of [RFC7519], except that
[RFC7519], except that the value of the audience claim is of type the value of the audience claim is of type StringOrURI when it is not
StringOrURI when it is not an array or the values of the audience an array or the values of the audience array elements are of type
array elements are of type StringOrURI when the audience claim value StringOrURI when the audience claim value is an array. The Claim Key
is an array. The Claim Key 3 is used to identify this claim. 3 is used to identify this claim.
3.1.4. exp (Expiration Time) Claim 3.1.4. exp (Expiration Time) Claim
The "exp" (expiration time) claim has the same meaning, syntax, and The "exp" (expiration time) claim has the same meaning and processing
processing rules as the "exp" claim defined in Section 4.1.4 of rules as the "exp" claim defined in Section 4.1.4 of [RFC7519],
[RFC7519], except that the value is of type NumericDate. The Claim except that the value is of type NumericDate. The Claim Key 4 is
Key 4 is used to identify this claim. used to identify this claim.
3.1.5. nbf (Not Before) Claim 3.1.5. nbf (Not Before) Claim
The "nbf" (not before) claim has the same meaning, syntax, and The "nbf" (not before) claim has the same meaning and processing
processing rules as the "nbf" claim defined in Section 4.1.5 of rules as the "nbf" claim defined in Section 4.1.5 of [RFC7519],
[RFC7519], except that the value is of type NumericDate. The Claim except that the value is of type NumericDate. The Claim Key 5 is
Key 5 is used to identify this claim. used to identify this claim.
3.1.6. iat (Issued At) Claim 3.1.6. iat (Issued At) Claim
The "iat" (issued at) claim has the same meaning, syntax, and The "iat" (issued at) claim has the same meaning and processing rules
processing rules as the "iat" claim defined in Section 4.1.6 of as the "iat" claim defined in Section 4.1.6 of [RFC7519], except that
[RFC7519], except that the value is of type NumericDate. The Claim the value is of type NumericDate. The Claim Key 6 is used to
Key 6 is used to identify this claim. identify this claim.
3.1.7. cti (CWT ID) Claim 3.1.7. cti (CWT ID) Claim
The "cti" (CWT ID) claim has the same meaning, syntax, and processing The "cti" (CWT ID) claim has the same meaning and processing rules as
rules as the "jti" claim defined in Section 4.1.7 of [RFC7519], the "jti" claim defined in Section 4.1.7 of [RFC7519], except that
except that the value is of type byte string. The Claim Key 7 is the value is of type byte string. The Claim Key 7 is used to
used to identify this claim. identify this claim.
4. Summary of the claim names, keys, and value types 4. Summary of the claim names, keys, and value types
+------+-----+----------------------------------+ +------+-----+----------------------------------+
| Name | Key | Value type | | Name | Key | Value type |
+------+-----+----------------------------------+ +------+-----+----------------------------------+
| iss | 1 | text string | | iss | 1 | text string |
| sub | 2 | text string | | sub | 2 | text string |
| aud | 3 | text string | | aud | 3 | text string |
| exp | 4 | integer or floating-point number | | exp | 4 | integer or floating-point number |
skipping to change at page 10, line 12 skipping to change at page 10, line 12
signatures over encrypted text are not considered valid in many signatures over encrypted text are not considered valid in many
jurisdictions. jurisdictions.
9. IANA Considerations 9. IANA Considerations
9.1. CBOR Web Token (CWT) Claims Registry 9.1. CBOR Web Token (CWT) Claims Registry
This section establishes the IANA "CBOR Web Token (CWT) Claims" This section establishes the IANA "CBOR Web Token (CWT) Claims"
registry. registry.
Depending upon the values being requested, registration requests are Registration requests are evaluated using the criteria described in
evaluated on a Standards Track Required, Specification Required, the Claim Key instructions in the registration template below after a
Expert Review, or Private Use basis [RFC8126] after a three-week three-week review period on the cwt-reg-review@ietf.org mailing list,
review period on the cwt-reg-review@ietf.org mailing list, on the on the advice of one or more Designated Experts. However, to allow
advice of one or more Designated Experts. However, to allow for the for the allocation of values prior to publication, the Designated
allocation of values prior to publication, the Designated Experts may Experts may approve registration once they are satisfied that such a
approve registration once they are satisfied that such a
specification will be published. [[ Note to the RFC Editor: The name specification will be published. [[ Note to the RFC Editor: The name
of the mailing list should be determined in consultation with the of the mailing list should be determined in consultation with the
IESG and IANA. Suggested name: cwt-reg-review@ietf.org. ]] IESG and IANA. Suggested name: cwt-reg-review@ietf.org. ]]
Registration requests sent to the mailing list for review should use Registration requests sent to the mailing list for review should use
an appropriate subject (e.g., "Request to register claim: example"). an appropriate subject (e.g., "Request to register claim: example").
Registration requests that are undetermined for a period longer than Registration requests that are undetermined for a period longer than
21 days can be brought to the IESG's attention (using the 21 days can be brought to the IESG's attention (using the
iesg@ietf.org mailing list) for resolution. iesg@ietf.org mailing list) for resolution.
skipping to change at page 10, line 45 skipping to change at page 10, line 44
restricted to claims with general applicability. restricted to claims with general applicability.
It is suggested that multiple Designated Experts be appointed who are It is suggested that multiple Designated Experts be appointed who are
able to represent the perspectives of different applications using able to represent the perspectives of different applications using
this specification in order to enable broadly informed review of this specification in order to enable broadly informed review of
registration decisions. In cases where a registration decision could registration decisions. In cases where a registration decision could
be perceived as creating a conflict of interest for a particular be perceived as creating a conflict of interest for a particular
Expert, that Expert should defer to the judgment of the other Expert, that Expert should defer to the judgment of the other
Experts. Experts.
Since a high degree of overlap is expected between the contents of
the "CBOR Web Token (CWT) Claims" registry and the "JSON Web Token
Claims" registry, overlap in the corresponding pools of Designated
Experts would be useful to help ensure that an appropriate level of
coordination between the registries is maintained.
9.1.1. Registration Template 9.1.1. Registration Template
Claim Name: Claim Name:
The human-readable name requested (e.g., "iss"). The human-readable name requested (e.g., "iss").
Claim Description: Claim Description:
Brief description of the claim (e.g., "Issuer"). Brief description of the claim (e.g., "Issuer").
JWT Claim Name: JWT Claim Name:
Claim Name of the equivalent JWT claim, as registered in Claim Name of the equivalent JWT claim, as registered in
[IANA.JWT.Claims]. CWT claims should normally have a [IANA.JWT.Claims]. CWT claims should normally have a
corresponding JWT claim. If a corresponding JWT claim would not corresponding JWT claim. If a corresponding JWT claim would not
make sense, the Designated Experts can choose to accept make sense, the Designated Experts can choose to accept
registrations for which the JWT Claim Name is listed as "N/A". registrations for which the JWT Claim Name is listed as "N/A".
Claim Key: Claim Key:
CBOR map key for the claim. Integer values between -256 and 255 CBOR map key for the claim. Different ranges of values use
and strings of length 1 are designated as Standards Track different registration policies [RFC8126]. Integer values between
Required. Integer values from -65536 to 65535 and strings of -256 and 255 and strings of length 1 are designated as Standards
length 2 are designated as Specification Required. Integer values Action. Integer values from -65536 to 65535 and strings of length
of greater than 65535 and strings of length greater than 2 are 2 are designated as Specification Required. Integer values of
greater than 65535 and strings of length greater than 2 are
designated as Expert Review. Integer values less than -65536 are designated as Expert Review. Integer values less than -65536 are
marked as Private Use. marked as Private Use.
Claim Value Type(s): Claim Value Type(s):
CBOR types that can be used for the claim value. CBOR types that can be used for the claim value.
Change Controller: Change Controller:
For Standards Track RFCs, list the "IESG". For others, give the For Standards Track RFCs, list the "IESG". For others, give the
name of the responsible party. Other details (e.g., postal name of the responsible party. Other details (e.g., postal
address, email address, home page URI) may also be included. address, email address, home page URI) may also be included.
skipping to change at page 22, line 28 skipping to change at page 23, line 28
) )
Figure 19: MACed CWT with a floating-point value in CBOR diagnostic Figure 19: MACed CWT with a floating-point value in CBOR diagnostic
notation notation
Appendix B. Acknowledgements Appendix B. Acknowledgements
This specification is based on JSON Web Token (JWT) [RFC7519], the This specification is based on JSON Web Token (JWT) [RFC7519], the
authors of which also include Nat Sakimura and John Bradley. It also authors of which also include Nat Sakimura and John Bradley. It also
incorporates suggestions made by many people, including Carsten incorporates suggestions made by many people, including Carsten
Bormann, Esko Dijk, Benjamin Kaduk, Jim Schaad, Ludwig Seitz, and Bormann, Esko Dijk, Benjamin Kaduk, Carlos Martinez, Kathleen
Moriarty, Dan Romascanu, Kyle Rose, Jim Schaad, Ludwig Seitz, and
Goeran Selander. Goeran Selander.
[[ RFC Editor: Is it possible to preserve the non-ASCII spellings of [[ RFC Editor: Is it possible to preserve the non-ASCII spellings of
the names Erik Wahlstroem and Goeran Selander in the final the names Erik Wahlstroem and Goeran Selander in the final
specification? ]] specification? ]]
Appendix C. Document History Appendix C. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]] [[ to be removed by the RFC Editor before publication as an RFC ]]
-13
o Clarified the registration criteria applied to different ranges of
Claim Key values, as suggested by Kathleen Moriarty and Dan
Romascanu.
o No longer describe the syntax of CWT claims as being the same as
that of the corresponding JWT claims, as suggested by Kyle Rose.
o Added guidance about the selection of the Designated Experts, as
suggested by Benjamin Kaduk.
o Acknowledged additional reviewers.
-12 -12
o Updated the RFC 5226 reference to RFC 8126. o Updated the RFC 5226 reference to RFC 8126.
o Made the IANA registration criteria consistent across sections. o Made the IANA registration criteria consistent across sections.
o Stated that registrations for the limited set of values between o Stated that registrations for the limited set of values between
-256 and 255 and strings of length 1 are to be restricted to -256 and 255 and strings of length 1 are to be restricted to
claims with general applicability. claims with general applicability.
 End of changes. 23 change blocks. 
66 lines changed or deleted 87 lines changed or added

This html diff was produced by rfcdiff 1.46. The latest version is available from http://tools.ietf.org/tools/rfcdiff/