--- 1/draft-ietf-ace-cbor-web-token-05.txt 2017-06-29 18:13:09.907909239 -0700 +++ 2/draft-ietf-ace-cbor-web-token-06.txt 2017-06-29 18:13:09.951910298 -0700 @@ -1,23 +1,23 @@ ACE Working Group M. Jones Internet-Draft Microsoft Intended status: Standards Track E. Wahlstroem -Expires: December 7, 2017 +Expires: December 31, 2017 S. Erdtman Spotify AB H. Tschofenig ARM Ltd. - June 5, 2017 + June 29, 2017 CBOR Web Token (CWT) - draft-ietf-ace-cbor-web-token-05 + draft-ietf-ace-cbor-web-token-06 Abstract 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 the Concise Binary Object Representation (CBOR) and CBOR Object Signing and Encryption (COSE) is used for added application layer security protection. A claim is a piece of information asserted 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 @@ -31,21 +31,21 @@ 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 http://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 December 7, 2017. + This Internet-Draft will expire on December 31, 2017. Copyright Notice Copyright (c) 2017 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 (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -54,62 +54,62 @@ include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. CBOR Related Terminology . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Claims . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 3.1. Claim Names . . . . . . . . . . . . . . . . . . . . . . . 4 + 3.1. Registered Claims . . . . . . . . . . . . . . . . . . . . 5 3.1.1. iss (Issuer) Claim . . . . . . . . . . . . . . . . . 5 3.1.2. sub (Subject) Claim . . . . . . . . . . . . . . . . . 5 3.1.3. aud (Audience) Claim . . . . . . . . . . . . . . . . 5 3.1.4. exp (Expiration Time) Claim . . . . . . . . . . . . . 5 3.1.5. nbf (Not Before) Claim . . . . . . . . . . . . . . . 5 3.1.6. iat (Issued At) Claim . . . . . . . . . . . . . . . . 5 3.1.7. cti (CWT ID) Claim . . . . . . . . . . . . . . . . . 6 - 4. Summary of the values, value types, and encoded claim keys . 6 + 4. Summary of the claim names, keys, and value types . . . . . . 6 5. CBOR Tags and Claim Values . . . . . . . . . . . . . . . . . 6 6. CWT CBOR Tag . . . . . . . . . . . . . . . . . . . . . . . . 6 7. Creating and Validating CWTs . . . . . . . . . . . . . . . . 7 7.1. Creating a CWT . . . . . . . . . . . . . . . . . . . . . 7 7.2. Validating a CWT . . . . . . . . . . . . . . . . . . . . 8 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 - 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 - 9.1. CBOR Web Token (CWT) Claims Registry . . . . . . . . . . 9 + 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 + 9.1. CBOR Web Token (CWT) Claims Registry . . . . . . . . . . 10 9.1.1. Registration Template . . . . . . . . . . . . . . . . 10 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 11 - 9.2. Media Type Registration . . . . . . . . . . . . . . . . . 12 + 9.2. Media Type Registration . . . . . . . . . . . . . . . . . 13 9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 13 9.3. CoAP Content-Formats Registration . . . . . . . . . . . . 13 - 9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 13 - 9.4. CBOR Tag registration . . . . . . . . . . . . . . . . . . 13 + 9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 14 + 9.4. CBOR Tag registration . . . . . . . . . . . . . . . . . . 14 9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 14 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 10.1. Normative References . . . . . . . . . . . . . . . . . . 14 10.2. Informative References . . . . . . . . . . . . . . . . . 15 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 15 A.1. Example CWT Claims Set . . . . . . . . . . . . . . . . . 15 A.2. Example keys . . . . . . . . . . . . . . . . . . . . . . 16 A.2.1. 128-bit Symmetric Key as Hex Encoded String . . . . . 16 A.2.2. 256-bit Symmetric Key as Hex Encoded String . . . . . 16 A.2.3. ECDSA P-256 256-bit COSE Key . . . . . . . . . . . . 16 A.3. Example Signed CWT . . . . . . . . . . . . . . . . . . . 17 A.4. Example MACed CWT . . . . . . . . . . . . . . . . . . . . 18 - A.5. Example Encrypted CWT . . . . . . . . . . . . . . . . . . 18 - A.6. Example Nested CWT . . . . . . . . . . . . . . . . . . . 19 - A.7. Example MACed CWT with a floating-point value . . . . . . 20 - Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 21 - Appendix C. Document History . . . . . . . . . . . . . . . . . . 21 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 + A.5. Example Encrypted CWT . . . . . . . . . . . . . . . . . . 19 + A.6. Example Nested CWT . . . . . . . . . . . . . . . . . . . 20 + A.7. Example MACed CWT with a floating-point value . . . . . . 21 + Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 22 + Appendix C. Document History . . . . . . . . . . . . . . . . . . 22 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 1. Introduction The JSON Web Token (JWT) [RFC7519] is a standardized security token format that has found use in OAuth 2.0 and OpenID Connect deployments, among other applications. JWT uses JSON Web Signature (JWS) [RFC7515] and JSON Web Encryption (JWE) [RFC7516] to secure the 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 native applications, but it is considered inefficient for some @@ -125,148 +125,156 @@ derived from JWT. To protect the claims contained in CWTs, the CBOR Object Signing and Encryption (COSE) [I-D.ietf-cose-msg] specification is used. The suggested pronunciation of CWT is the same as the English word "cot". 1.1. CBOR Related Terminology In JSON, maps are called objects and only have one kind of map key: a - string. In COSE, we use strings, negative integers, and unsigned - integers as map keys. The integers are used for compactness of - encoding and easy comparison. The inclusion of strings allows for an - additional range of short encoded values to be used as well. + string. CBOR uses strings, negative integers, and unsigned integers + as map keys. The integers are used for compactness of encoding and + easy comparison. The inclusion of strings allows for an additional + range of short encoded values to be used. 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 "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. This document reuses terminology from JWT [RFC7519] and COSE [I-D.ietf-cose-msg]. - StringOrURI: + StringOrURI The "StringOrURI" term has the same meaning, syntax, and processing rules as the "StringOrUri" term defined in Section 2 of JWT [RFC7519], except that it uses a CBOR text string instead of a JSON string value. - NumericDate: + NumericDate The "NumericDate" term has the same meaning, syntax, and processing rules as the "NumericDate" term defined in Section 2 of JWT [RFC7519], except that the CBOR numeric date representation (from Section 2.4.1 of [RFC7049]) is used. The encoding is - modified so that the leading tag (6.1 or 0xC1) MUST be omitted. + modified so that the leading tag 1 (epoch-based date/time) MUST be + omitted. - CBOR encoded claim key: - The key used to identify a claim value. + Claim Name + The human-readable name used to identify a claim. + + Claim Key + The CBOR map key used to identify a claim. + + Claim Value + The CBOR map value representing the value of the claim. CWT Claims Set - A CBOR map that contains the claims conveyed by the CWT. + The CBOR map that contains the claims conveyed by the CWT. 3. Claims The set of claims that a CWT must contain to be considered valid is context dependent and is outside the scope of this specification. Specific applications of CWTs will require implementations to understand and process some claims in particular ways. However, in the absence of such requirements, all claims that are not understood by implementations MUST be ignored. - To keep CWTs as small as possible, the CBOR encoded claim keys are - represented using integers or text strings. Section 4 summarizes all - keys used to identify the claims defined in this document. + To keep CWTs as small as possible, the Claim Keys are represented + using integers or text strings. Section 4 summarizes all keys used + to identify the claims defined in this document. -3.1. Claim Names +3.1. Registered Claims 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 useful, interoperable claims. Applications using CWTs should define which specific claims they use and when they are required or optional. 3.1.1. iss (Issuer) Claim The "iss" (issuer) claim has the same meaning, syntax, and processing rules as the "iss" claim defined in Section 4.1.1 of JWT [RFC7519], - except that the format MUST be a StringOrURI. The CBOR encoded claim - key 1 MUST be used to identify this claim. + except that the value is of type StringOrURI. The Claim Key 1 is + used to identify this claim. 3.1.2. sub (Subject) Claim The "sub" (subject) claim has the same meaning, syntax, and processing rules as the "sub" claim defined in Section 4.1.2 of JWT - [RFC7519], except that the format MUST be a StringOrURI. The CBOR - encoded claim key 2 MUST be used to identify this claim. + [RFC7519], except that the value is of type StringOrURI. The Claim + Key 2 is used to identify this claim. 3.1.3. aud (Audience) Claim The "aud" (audience) claim has the same meaning, syntax, and processing rules as the "aud" claim defined in Section 4.1.3 of JWT - [RFC7519], except that the format MUST be a StringOrURI. The CBOR - encoded claim key 3 MUST be used to identify this claim. + [RFC7519], except that the value is of type StringOrURI. The Claim + Key 3 is used to identify this claim. 3.1.4. exp (Expiration Time) Claim The "exp" (expiration time) claim has the same meaning, syntax, and processing rules as the "exp" claim defined in Section 4.1.4 of JWT - [RFC7519], except that the format MUST be a NumericDate. The CBOR - encoded claim key 4 MUST be used to identify this claim. + [RFC7519], except that the value is of type NumericDate. The Claim + Key 4 is used to identify this claim. 3.1.5. nbf (Not Before) Claim The "nbf" (not before) claim has the same meaning, syntax, and processing rules as the "nbf" claim defined in Section 4.1.5 of JWT - [RFC7519], except that the format MUST be a NumericDate. The CBOR - encoded claim key 5 MUST be used to identify this claim. + [RFC7519], except that the value is of type NumericDate. The Claim + Key 5 is used to identify this claim. 3.1.6. iat (Issued At) Claim The "iat" (issued at) claim has the same meaning, syntax, and processing rules as the "iat" claim defined in Section 4.1.6 of JWT - [RFC7519], except that the format MUST be a NumericDate. The CBOR - encoded claim key 6 MUST be used to identify this claim. + + [RFC7519], except that the value is of type NumericDate. The Claim + Key 6 is used to identify this claim. 3.1.7. cti (CWT ID) Claim The "cti" (CWT ID) claim has the same meaning, syntax, and processing rules as the "jti" claim defined in Section 4.1.7 of JWT [RFC7519], - except that the format MUST be binary string. The CBOR encoded claim - key 7 MUST be used to identify this claim. + except that the value is of type binary string. The Claim Key 7 is + used to identify this claim. -4. Summary of the values, value types, and encoded claim keys +4. Summary of the claim names, keys, and value types /---------+-----+----------------------------------\ | Name | Key | Value type | |---------+-----+----------------------------------| | iss | 1 | text string | | sub | 2 | text string | | aud | 3 | text string | | exp | 4 | integer or floating-point number | | nbf | 5 | integer or floating-point number | | iat | 6 | integer or floating-point number | | cti | 7 | binary string | \---------+-----+----------------------------------/ - Figure 1: Summary of the values, value types, and encoded claim keys + Figure 1: Summary of the claim names, keys, and value types 5. CBOR Tags and Claim Values The claim values defined in this specification MUST NOT be prefixed - with any CBOR tag. For instance, while CBOR tag 6.1 (seconds-since- - the-epoch) could logically be prefixed to values of the "exp", "nbf", - and "iat" claims, this is unnecessary, since the representation of - the claim values is already specified by the claim definitions. - Tagging claim values would only take up extra space without adding + with any CBOR tag. For instance, while CBOR tag 1 (epoch-based date/ + time) could logically be prefixed to values of the "exp", "nbf", and + "iat" claims, this is unnecessary, since the representation of the + claim values is already specified by the claim definitions. Tagging + claim values would only take up extra space without adding information. However, this does not prohibit future claim definitions from requiring the use of CBOR tags for those specific claims. 6. CWT CBOR Tag How to determine that a CBOR data structure is a CWT is application- dependent. In some cases, this information is known from the application context, such as from the position of the CWT in a data structure at which the value must be a CWT. One method of indicating @@ -377,22 +385,22 @@ follow the steps specified in [I-D.ietf-cose-msg] Section 5 (Encryption Objects) for validating a COSE_Encrypt/ COSE_Encrypt0 object. Let the Message be the resulting plaintext. 6. If the Message begins with a COSE CBOR tag, then the Message is a CWT that was the subject of nested signing, MACing, or encryption operations. In this case, return to Step 1, using the Message as the CWT. - 7. Verify that the Message is a valid CBOR object; let the CWT - Claims Set be this CBOR object. + 7. Verify that the Message is a valid CBOR map; let the CWT Claims + Set be this CBOR map. 8. Security Considerations The security of the CWT relies upon on the protections offered by COSE. Unless the claims in a CWT are protected, an adversary can modify, add, or remove claims. 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 also to ensure that the recipient can authenticate the party that @@ -457,111 +465,112 @@ Claim Description: Brief description of the claim (e.g., "Issuer"). JWT Claim Name: Claim Name of the equivalent JWT claim, as registered in [IANA.JWT.Claims]. CWT claims should normally have a corresponding JWT claim. If a corresponding JWT claim would not make sense, the Designated Experts can choose to accept registrations for which the JWT Claim Name is listed as "N/A". - CBOR Key Value: - Integer values between -256 and 255 and strings of length 1 are - designated as Standards Track Document required. Integer values - from -65536 to 65535 and strings of length 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 marked as private use. + Claim Key: + CBOR map key for the claim. Integer values between -256 and 255 + and strings of length 1 are designated as Standards Track Document + required. Integer values from -65536 to 65535 and strings of + length 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 + marked as private use. - CBOR Major Type: - CBOR major type and optional tag for the claim. + Claim Value Type(s): + CBOR types that can be used for the claim value. Change Controller: For Standards Track RFCs, list the "IESG". For others, give the name of the responsible party. Other details (e.g., postal address, email address, home page URI) may also be included. Specification Document(s): Reference to the document or documents that specify the parameter, preferably including URIs that can be used to retrieve copies of the documents. An indication of the relevant sections may also be included but is not required. 9.1.2. Initial Registry Contents - o Claim Name: N/A + o Claim Name: (RESERVED) o Claim Description: This registration reserves the key value 0. o JWT Claim Name: N/A - o CBOR Key Value: 0 - o CBOR Major Type: N/A + o Claim Key: 0 + o Claim Value Type(s): N/A o Change Controller: IESG o Specification Document(s): [[ this specification ]] o Claim Name: "iss" o Claim Description: Issuer o JWT Claim Name: "iss" - o CBOR Key Value: 1 - o CBOR Major Type: 3 + o Claim Key: 1 + o Claim Value Type(s): text string o Change Controller: IESG o Specification Document(s): Section 3.1.1 of [[ this specification ]] o Claim Name: "sub" o Claim Description: Subject o JWT Claim Name: "sub" - o CBOR Key Value: 2 - o CBOR Major Type: 3 + o Claim Key: 2 + o Claim Value Type(s): text string o Change Controller: IESG o Specification Document(s): Section 3.1.2 of [[ this specification ]] o Claim Name: "aud" o Claim Description: Audience o JWT Claim Name: "aud" - o CBOR Key Value: 3 - o CBOR Major Type: 3 + o Claim Key: 3 + o Claim Value Type(s): text string o Change Controller: IESG o Specification Document(s): Section 3.1.3 of [[ this specification ]] o Claim Name: "exp" o Claim Description: Expiration Time o JWT Claim Name: "exp" - o CBOR Key Value: 4 - o CBOR Major Type: 0, 1, or 7 with subtypes 25, 26, or 27 + o Claim Key: 4 + o Claim Value Type(s): integer or floating-point number o Change Controller: IESG o Specification Document(s): Section 3.1.4 of [[ this specification ]] o Claim Name: "nbf" o Claim Description: Not Before o JWT Claim Name: "nbf" - o CBOR Key Value: 5 - o CBOR Major Type: 0, 1, or 7 with subtypes 25, 26, or 27 + o Claim Key: 5 + o Claim Value Type(s): integer or floating-point number o Change Controller: IESG o Specification Document(s): Section 3.1.5 of [[ this specification ]] o Claim Name: "iat" o Claim Description: Issued At o JWT Claim Name: "iat" - o CBOR Key Value: 6 - o CBOR Major Type: 0, 1, or 7 with subtypes 25, 26, or 27 + o Claim Key: 6 + o Claim Value Type(s): integer or floating-point number o Change Controller: IESG o Specification Document(s): Section 3.1.6 of [[ this specification ]] o Claim Name: "cti" o Claim Description: CWT ID o JWT Claim Name: "jti" - o CBOR Key Value: 7 - o CBOR Major Type: 2 + o Claim Key: 7 + o Claim Value Type(s): binary string o Change Controller: IESG o Specification Document(s): Section 3.1.7 of [[ this specification ]] 9.2. Media Type Registration This section registers the "application/cwt" media type in the "Media Types" registry [IANA.MediaTypes] in the manner described in RFC 6838 [RFC6838], which can be used to indicate that the content is a CWT. @@ -656,21 +665,21 @@ (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . 10.2. Informative References [IANA.JWT.Claims] IANA, "JSON Web Token Claims", . [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an - IANA Considerations Section in RFCs", BCP 26, RFC 5226, + IANA Considerations Section in RFCs", RFC 5226, DOI 10.17487/RFC5226, May 2008, . [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, . [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May @@ -950,20 +959,25 @@ This specification is based on JSON Web Token (JWT) [RFC7519], the authors of which also include Nat Sakimura and John Bradley. It also incorporates suggestions made by many people, notably Carsten Bormann, Jim Schaad, Ludwig Seitz, and Goeran Selander. Appendix C. Document History [[ to be removed by the RFC Editor before publication as an RFC ]] + -06 + + o Addressed review comments by Carsten Bormann and Jim Schaad. All + changes were editorial in nature. + -05 o Addressed working group last call comments with the following changes: o Say that CWT is derived from JWT, rather than CWT is a profile of JWT. o Used CBOR type names in descriptions, rather than major/minor type numbers.