draft-ietf-ace-cbor-web-token-13.txt   draft-ietf-ace-cbor-web-token-14.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: September 6, 2018 Expires: September 16, 2018
S. Erdtman S. Erdtman
Spotify AB Spotify AB
H. Tschofenig H. Tschofenig
ARM Ltd. ARM Ltd.
March 5, 2018 March 15, 2018
CBOR Web Token (CWT) CBOR Web Token (CWT)
draft-ietf-ace-cbor-web-token-13 draft-ietf-ace-cbor-web-token-14
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 September 6, 2018. This Internet-Draft will expire on September 16, 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 3, line 13 skipping to change at page 3, line 13
A.2.1. 128-bit Symmetric Key . . . . . . . . . . . . . . . . 17 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 . . . . . . . . . . . . . . . . . . . 18 A.3. Example Signed CWT . . . . . . . . . . . . . . . . . . . 18
A.4. Example MACed CWT . . . . . . . . . . . . . . . . . . . . 19 A.4. Example MACed CWT . . . . . . . . . . . . . . . . . . . . 19
A.5. Example Encrypted CWT . . . . . . . . . . . . . . . . . . 20 A.5. Example Encrypted CWT . . . . . . . . . . . . . . . . . . 20
A.6. Example Nested CWT . . . . . . . . . . . . . . . . . . . 21 A.6. Example Nested CWT . . . . . . . . . . . . . . . . . . . 21
A.7. Example MACed CWT with a floating-point value . . . . . . 22 A.7. Example MACed CWT with a floating-point value . . . . . . 22
Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 23 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 23
Appendix C. Document History . . . . . . . . . . . . . . . . . . 23 Appendix C. Document History . . . . . . . . . . . . . . . . . . 23
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27
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 and processing rules The "StringOrURI" term in this specification has the same meaning
as the "StringOrURI" term defined in Section 2 of [RFC7519], and processing rules as the JWT "StringOrURI" term defined in
except that it uses a CBOR text string instead of a JSON string Section 2 of [RFC7519], except that it is represented as a CBOR
value. text string instead of a JSON text string.
NumericDate NumericDate
The "NumericDate" term has the same meaning and processing rules The "NumericDate" term in this specification has the same meaning
as the "NumericDate" term defined in Section 2 of [RFC7519], and processing rules as the JWT "NumericDate" term defined in
except that the CBOR numeric date representation (from Section 2 of [RFC7519], except that it is represented as a CBOR
Section 2.4.1 of [RFC7049]) is used. The encoding is modified so numeric date (from Section 2.4.1 of [RFC7049]) instead of a JSON
that the leading tag 1 (epoch-based date/time) MUST be omitted. number. The encoding is modified so 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
The CBOR map value representing the value of the claim. The CBOR map value representing the value of the claim.
skipping to change at page 5, line 17 skipping to change at page 5, line 17
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 and processing rules as The "iss" (issuer) claim has the same meaning and processing rules as
the "iss" claim defined in Section 4.1.1 of [RFC7519], except that the "iss" claim defined in Section 4.1.1 of [RFC7519], except that
the value is of type StringOrURI. The Claim Key 1 is used to the value is a StringOrURI. The Claim Key 1 is used to identify this
identify this claim. claim.
3.1.2. sub (Subject) Claim 3.1.2. sub (Subject) Claim
The "sub" (subject) claim has the same meaning and processing rules The "sub" (subject) claim has the same meaning and processing rules
as the "sub" claim defined in Section 4.1.2 of [RFC7519], except that as the "sub" claim defined in Section 4.1.2 of [RFC7519], except that
the value is of type StringOrURI. The Claim Key 2 is used to the value is a StringOrURI. The Claim Key 2 is used to identify this
identify this claim. claim.
3.1.3. aud (Audience) Claim 3.1.3. aud (Audience) Claim
The "aud" (audience) claim has the same meaning and processing rules The "aud" (audience) claim has the same meaning and processing rules
as the "aud" claim defined in Section 4.1.3 of [RFC7519], except that as the "aud" claim defined in Section 4.1.3 of [RFC7519], except that
the value of the audience claim is of type StringOrURI when it is not the value of the audience claim is a StringOrURI when it is not an
an array or the values of the audience array elements are of type array or each of the audience array element values is a StringOrURI
StringOrURI when the audience claim value is an array. The Claim Key when the audience claim value is an array. The Claim Key 3 is used
3 is used to identify this claim. 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 and processing The "exp" (expiration time) claim has the same meaning and processing
rules as the "exp" claim defined in Section 4.1.4 of [RFC7519], rules as the "exp" claim defined in Section 4.1.4 of [RFC7519],
except that the value is of type NumericDate. The Claim Key 4 is except that the value is a NumericDate. The Claim Key 4 is used to
used to identify this claim. 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 and processing The "nbf" (not before) claim has the same meaning and processing
rules as the "nbf" claim defined in Section 4.1.5 of [RFC7519], rules as the "nbf" claim defined in Section 4.1.5 of [RFC7519],
except that the value is of type NumericDate. The Claim Key 5 is except that the value is a NumericDate. The Claim Key 5 is used to
used to identify this claim. 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 and processing rules The "iat" (issued at) claim has the same meaning and processing rules
as the "iat" claim defined in Section 4.1.6 of [RFC7519], except that as the "iat" claim defined in Section 4.1.6 of [RFC7519], except that
the value is of type NumericDate. The Claim Key 6 is used to the value is a NumericDate. The Claim Key 6 is used to identify this
identify this claim. claim.
3.1.7. cti (CWT ID) Claim 3.1.7. cti (CWT ID) Claim
The "cti" (CWT ID) claim has the same meaning and processing rules as The "cti" (CWT ID) claim has the same meaning and processing rules as
the "jti" claim defined in Section 4.1.7 of [RFC7519], except that the "jti" claim defined in Section 4.1.7 of [RFC7519], except that
the value is of type byte string. The Claim Key 7 is used to the value is a byte string. The Claim Key 7 is used to identify this
identify this claim. 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 9, line 41 skipping to change at page 9, line 41
Since the claims conveyed in a CWT may be used to make authorization Since the claims conveyed in a CWT may be used to make authorization
decisions, it is not only important to protect the CWT in transit but decisions, it is not only important to protect the CWT in transit but
also to ensure that the recipient can authenticate the party that also to ensure that the recipient can authenticate the party that
assembled the claims and created the CWT. Without trust of the assembled the claims and created the CWT. Without trust of the
recipient in the party that created the CWT, no sensible recipient in the party that created the CWT, no sensible
authorization decision can be made. Furthermore, the creator of the authorization decision can be made. Furthermore, the creator of the
CWT needs to carefully evaluate each claim value prior to including CWT needs to carefully evaluate each claim value prior to including
it in the CWT so that the recipient can be assured of the validity of it in the CWT so that the recipient can be assured of the validity of
the information provided. the information provided.
While syntactically, the signing and encryption operations for Nested While syntactically the signing and encryption operations for Nested
CWTs may be applied in any order, if both signing and encryption are CWTs may be applied in any order, if both signing and encryption are
necessary, normally producers should sign the message and then necessary, normally producers should sign the message and then
encrypt the result (thus encrypting the signature). This prevents encrypt the result (thus encrypting the signature). This prevents
attacks in which the signature is stripped, leaving just an encrypted attacks in which the signature is stripped, leaving just an encrypted
message, as well as providing privacy for the signer. Furthermore, message, as well as providing privacy for the signer. Furthermore,
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
skipping to change at page 10, line 36 skipping to change at page 10, line 36
iesg@ietf.org mailing list) for resolution. iesg@ietf.org mailing list) for resolution.
Criteria that should be applied by the Designated Experts includes Criteria that should be applied by the Designated Experts includes
determining whether the proposed registration duplicates existing determining whether the proposed registration duplicates existing
functionality, whether it is likely to be of general applicability or functionality, whether it is likely to be of general applicability or
whether it is useful only for a single application, and whether the whether it is useful only for a single application, and whether the
registration description is clear. Registrations for the limited set registration description is clear. Registrations for the limited set
of values between -256 and 255 and strings of length 1 are to be of values between -256 and 255 and strings of length 1 are to be
restricted to claims with general applicability. restricted to claims with general applicability.
IANA must only accept registry updates from the Designated Experts
and should direct all requests for registration to the review mailing
list.
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 Since a high degree of overlap is expected between the contents of
the "CBOR Web Token (CWT) Claims" registry and the "JSON Web Token the "CBOR Web Token (CWT) Claims" registry and the "JSON Web Token
skipping to change at page 11, line 22 skipping to change at page 11, line 22
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. Different ranges of values use CBOR map key for the claim. Different ranges of values use
different registration policies [RFC8126]. Integer values between different registration policies [RFC8126]. Integer values from
-256 and 255 and strings of length 1 are designated as Standards -256 to 255 and strings of length 1 are designated as Standards
Action. Integer values from -65536 to 65535 and strings of length Action. Integer values from -65536 to -257 and from 256 to 65535
2 are designated as Specification Required. Integer values of and strings of length 2 are designated as Specification Required.
greater than 65535 and strings of length greater than 2 are Integer values greater than 65535 and strings of length greater
designated as Expert Review. Integer values less than -65536 are than 2 are designated as Expert Review. Integer values less than
marked as Private Use. -65536 are 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.
Specification Document(s): Specification Document(s):
skipping to change at page 23, 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, Carlos Martinez, Kathleen Bormann, Alissa Cooper, Esko Dijk, Benjamin Kaduk, Warren Kumari,
Moriarty, Dan Romascanu, Kyle Rose, Jim Schaad, Ludwig Seitz, and Carlos Martinez, Alexey Melnikov, Kathleen Moriarty, Eric Rescorla,
Dan Romascanu, Adam Roach, 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 ]]
-14
o Cleaned up the descriptions of the numeric ranges of claim keys
being registered in the registration template for the "CBOR Web
Token (CWT) Claims" registry, as suggested by Adam Roach.
o Clarified the relationships between the JWT and CWT "NumericDate"
and "StringOrURI" terms, as suggested by Adam Roach.
o Eliminated unnecessary uses of the word "type", as suggested by
Adam Roach.
o Added the text "IANA must only accept registry updates from the
Designated Experts and should direct all requests for registration
to the review mailing list" from RFC 7519, as suggested by Amanda
Baber of IANA, which is also intended to address Alexey Melnikov's
comment.
o Removed a superfluous comma, as suggested by Warren Kumari.
o Acknowledged additional reviewers.
-13 -13
o Clarified the registration criteria applied to different ranges of o Clarified the registration criteria applied to different ranges of
Claim Key values, as suggested by Kathleen Moriarty and Dan Claim Key values, as suggested by Kathleen Moriarty and Dan
Romascanu. Romascanu.
o No longer describe the syntax of CWT claims as being the same as 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. that of the corresponding JWT claims, as suggested by Kyle Rose.
o Added guidance about the selection of the Designated Experts, as o Added guidance about the selection of the Designated Experts, as
 End of changes. 19 change blocks. 
40 lines changed or deleted 68 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/