idnits 2.17.00 (12 Aug 2021) /tmp/idnits53433/draft-ietf-ace-cbor-web-token-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 13, 2017) is 1863 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: draft-ietf-cose-msg has been published as RFC 8152 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ACE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track E. Wahlstroem 5 Expires: October 15, 2017 6 S. Erdtman 7 Spotify AB 8 H. Tschofenig 9 ARM Ltd. 10 April 13, 2017 12 CBOR Web Token (CWT) 13 draft-ietf-ace-cbor-web-token-04 15 Abstract 17 CBOR Web Token (CWT) is a compact means of representing claims to be 18 transferred between two parties. CWT is a profile of the JSON Web 19 Token (JWT) that is optimized for constrained devices. The claims in 20 a CWT are encoded in the Concise Binary Object Representation (CBOR) 21 and CBOR Object Signing and Encryption (COSE) is used for added 22 application layer security protection. A claim is a piece of 23 information asserted about a subject and is represented as a name/ 24 value pair consisting of a claim name and a claim value. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on October 15, 2017. 43 Copyright Notice 45 Copyright (c) 2017 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 3. Claims . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 3.1. Claim Names . . . . . . . . . . . . . . . . . . . . . . . 4 64 3.1.1. iss (Issuer) Claim . . . . . . . . . . . . . . . . . 4 65 3.1.2. sub (Subject) Claim . . . . . . . . . . . . . . . . . 5 66 3.1.3. aud (Audience) Claim . . . . . . . . . . . . . . . . 5 67 3.1.4. exp (Expiration Time) Claim . . . . . . . . . . . . . 5 68 3.1.5. nbf (Not Before) Claim . . . . . . . . . . . . . . . 5 69 3.1.6. iat (Issued At) Claim . . . . . . . . . . . . . . . . 5 70 3.1.7. cti (CWT ID) Claim . . . . . . . . . . . . . . . . . 5 71 4. Summary of the values, CBOR major types and encoded claim 72 keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 73 5. CBOR Tags and Claim Values . . . . . . . . . . . . . . . . . 6 74 6. CWT CBOR Tag . . . . . . . . . . . . . . . . . . . . . . . . 6 75 7. Creating and Validating CWTs . . . . . . . . . . . . . . . . 7 76 7.1. Creating a CWT . . . . . . . . . . . . . . . . . . . . . 7 77 7.2. Validating a CWT . . . . . . . . . . . . . . . . . . . . 8 78 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 79 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 80 9.1. CBOR Web Token (CWT) Claims Registry . . . . . . . . . . 9 81 9.1.1. Registration Template . . . . . . . . . . . . . . . . 10 82 9.1.2. Initial Registry Contents . . . . . . . . . . . . . . 10 83 9.2. Media Type Registration . . . . . . . . . . . . . . . . . 12 84 9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 12 85 9.3. CoAP Content-Formats Registration . . . . . . . . . . . . 12 86 9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 12 87 9.4. CBOR Tag registration . . . . . . . . . . . . . . . . . . 13 88 9.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 13 89 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 90 10.1. Normative References . . . . . . . . . . . . . . . . . . 13 91 10.2. Informative References . . . . . . . . . . . . . . . . . 14 92 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 14 93 A.1. Example CWT Claims Set . . . . . . . . . . . . . . . . . 14 94 A.2. Example keys . . . . . . . . . . . . . . . . . . . . . . 15 95 A.2.1. 128-bit Symmetric Key as Hex Encoded String . . . . . 15 96 A.2.2. 256-bit Symmetric Key as Hex Encoded String . . . . . 15 97 A.2.3. ECDSA P-256 256-bit COSE Key . . . . . . . . . . . . 15 98 A.3. Example Signed CWT . . . . . . . . . . . . . . . . . . . 16 99 A.4. Example MACed CWT . . . . . . . . . . . . . . . . . . . . 17 100 A.5. Example Encrypted CWT . . . . . . . . . . . . . . . . . . 17 101 A.6. Example Nested CWT . . . . . . . . . . . . . . . . . . . 18 102 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 19 103 Appendix C. Document History . . . . . . . . . . . . . . . . . . 19 104 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 106 1. Introduction 108 The JSON Web Token (JWT) [RFC7519] is a standardized security token 109 format that has found use in OAuth 2.0 and OpenID Connect 110 deployments, among other applications. JWT uses JSON Web Signature 111 (JWS) [RFC7515] and JSON Web Encryption (JWE) [RFC7516] to secure the 112 contents of the JWT, which is a set of claims represented in JSON. 113 The use of JSON for encoding information is popular for Web and 114 native applications, but it is considered inefficient for some 115 Internet of Things (IoT) systems that use low power radio 116 technologies. 118 An alternative encoding of claims is defined in this document. 119 Instead of using JSON, as provided by JWTs, this specification uses 120 CBOR [RFC7049] and calls this new structure "CBOR Web Token (CWT)", 121 which is a compact means of representing secured claims to be 122 transferred between two parties. CWT is closely related to JWT. It 123 references the JWT claims and both its name and pronunciation are 124 derived from JWT. To protect the claims contained in CWTs, the CBOR 125 Object Signing and Encryption (COSE) [I-D.ietf-cose-msg] 126 specification is used. 128 The suggested pronunciation of CWT is the same as the English word 129 "cot". 131 2. Terminology 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 135 "OPTIONAL" in this document are to be interpreted as described in 136 "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. 138 This document reuses terminology from JWT [RFC7519] and COSE 139 [I-D.ietf-cose-msg]. 141 StringOrURI: 142 The "StringOrURI" term has the same meaning, syntax, and 143 processing rules as the "StringOrUri" term defined in Section 2 of 144 JWT [RFC7519], except that a CWT StringOrURI uses CBOR major type 145 3 (text string) instead of a JSON string value. 147 NumericDate: 148 The "NumericDate" term has the same meaning, syntax, and 149 processing rules as the "NumericDate" term defined in Section 2 of 150 JWT [RFC7519], except that a CWT NumericDate uses one of the CBOR 151 numeric types (0, 1, or 7 with subtypes 25, 26, or 27), instead of 152 a numeric JSON value. The numeric date values that can used for a 153 CWT NumericDate are identical to the epoch-based date/time values 154 that are specified to follow the tag defined in Section 2.4.1 155 (Date and Time) of [RFC7049], except that the tag itself need not 156 be present. 158 CBOR encoded claim key: 159 The key used to identify a claim value. 161 CWT Claims Set 162 A CBOR map that contains the claims conveyed by the CWT. 164 3. Claims 166 The set of claims that a CWT must contain to be considered valid is 167 context dependent and is outside the scope of this specification. 168 Specific applications of CWTs will require implementations to 169 understand and process some claims in particular ways. However, in 170 the absence of such requirements, all claims that are not understood 171 by implementations MUST be ignored. 173 To keep CWTs as small as possible, the CBOR encoded claim keys are 174 represented using CBOR major type 0. Section 4 summarizes all keys 175 used to identify the claims defined in this document. 177 3.1. Claim Names 179 None of the claims defined below are intended to be mandatory to use 180 or implement. They rather provide a starting point for a set of 181 useful, interoperable claims. Applications using CWTs should define 182 which specific claims they use and when they are required or 183 optional. 185 3.1.1. iss (Issuer) Claim 187 The "iss" (issuer) claim has the same meaning, syntax, and processing 188 rules as the "iss" claim defined in Section 4.1.1 of JWT [RFC7519], 189 except that the format MUST be a StringOrURI. The CBOR encoded claim 190 key 1 MUST be used to identify this claim. 192 3.1.2. sub (Subject) Claim 194 The "sub" (subject) claim has the same meaning, syntax, and 195 processing rules as the "sub" claim defined in Section 4.1.2 of JWT 196 [RFC7519], except that the format MUST be a StringOrURI. The CBOR 197 encoded claim key 2 MUST be used to identify this claim. 199 3.1.3. aud (Audience) Claim 201 The "aud" (audience) claim has the same meaning, syntax, and 202 processing rules as the "aud" claim defined in Section 4.1.3 of JWT 203 [RFC7519], except that the format MUST be a StringOrURI. The CBOR 204 encoded claim key 3 MUST be used to identify this claim. 206 3.1.4. exp (Expiration Time) Claim 208 The "exp" (expiration time) claim has the same meaning, syntax, and 209 processing rules as the "exp" claim defined in Section 4.1.4 of JWT 210 [RFC7519], except that the format MUST be a CWT NumericDate. The 211 CBOR encoded claim key 4 MUST be used to identify this claim. 213 3.1.5. nbf (Not Before) Claim 215 The "nbf" (not before) claim has the same meaning, syntax, and 216 processing rules as the "nbf" claim defined in Section 4.1.5 of JWT 217 [RFC7519], except that the format MUST be a CWT NumericDate. The 218 CBOR encoded claim key 5 MUST be used to identify this claim. 220 3.1.6. iat (Issued At) Claim 222 The "iat" (issued at) claim has the same meaning, syntax, and 223 processing rules as the "iat" claim defined in Section 4.1.6 of JWT 224 [RFC7519], except that the format MUST be a CWT NumericDate. The 225 CBOR encoded claim key 6 MUST be used to identify this claim. 227 3.1.7. cti (CWT ID) Claim 229 The "cti" (CWT ID) claim has the same meaning, syntax, and processing 230 rules as the "jti" claim defined in Section 4.1.7 of JWT [RFC7519], 231 except that the format MUST be of major type 2, binary string. The 232 CBOR encoded claim key 7 MUST be used to identify this claim. 234 4. Summary of the values, CBOR major types and encoded claim keys 235 /---------+------------------------+-------------------------------\ 236 | Claim | CBOR encoded claim key | CBOR major type of value | 237 |---------+------------------------+-------------------------------| 238 | iss | 1 | 3 | 239 | sub | 2 | 3 | 240 | aud | 3 | 3 | 241 | exp | 4 | 0, 1, or 7 with float subtype | 242 | nbf | 5 | 0, 1, or 7 with float subtype | 243 | iat | 6 | 0, 1, or 7 with float subtype | 244 | cti | 7 | 2 | 245 \---------+------------------------+-------------------------------/ 247 Figure 1: Summary of the values, CBOR major types and encoded claim 248 keys. 250 5. CBOR Tags and Claim Values 252 The use of CBOR tags to prefix any of the claim values defined in 253 this specification is NOT RECOMMENDED. For instance, while CBOR tag 254 6.1 (seconds-since-the-epoch) could logically be prefixed to values 255 of the "exp", "nbf", and "iat" claims, this is unnecessary, since the 256 representation of the claim values is already specified by the claim 257 definitions. Tagging claim values would only take up extra space, 258 without adding information. However, other claims defined by other 259 specifications can specify that a tag prefix the claim value, when 260 appropriate. 262 6. CWT CBOR Tag 264 How to determine that a CBOR data structure is a CWT is application- 265 dependent. In some cases, this information is known from the 266 application context, such as from the position of the CWT in a data 267 structure at which the value must be a CWT. One method of indicating 268 that a CBOR object is a CWT is the use of the "application/cwt" 269 content type by a transport protocol. 271 This section defines the CWT CBOR tag as another means for 272 applications to declare that a CBOR data structure is a CWT. Its use 273 is optional, and is intended for use in cases in which this 274 information would not otherwise be known. 276 If present, the CWT tag MUST prefix a tagged object using one of the 277 COSE CBOR tags. In this example, the COSE_Mac0 tag is used. The 278 actual COSE_Mac0 object has been excluded from this example. 280 / CWT CBOR tag / 61( 281 / COSE_Mac0 CBOR tag / 17( 282 / COSE_Mac0 object / 283 ) 284 ) 286 Figure 2: Example of a CWT tag usage 288 7. Creating and Validating CWTs 290 7.1. Creating a CWT 292 To create a CWT, the following steps are performed. The order of the 293 steps is not significant in cases where there are no dependencies 294 between the inputs and outputs of the steps. 296 1. Create a CWT Claims Set containing the desired claims. 298 2. Let the Message be the binary representation of the CWT Claims 299 Set. 301 3. Create a COSE Header containing the desired set of Header 302 Parameters. The COSE Header MUST be valid per the 303 [I-D.ietf-cose-msg] specification. 305 4. Depending upon whether the CWT is signed, MACed, or encrypted, 306 there are three cases: 308 * If the CWT is signed, create a COSE_Sign/COSE_Sign1 object 309 using the Message as the COSE_Sign/COSE_Sign1 Payload; all 310 steps specified in [I-D.ietf-cose-msg] for creating a 311 COSE_Sign/COSE_Sign1 object MUST be followed. 313 * Else, if the CWT is MACed, create a COSE_Mac/COSE_Mac0 object 314 using the Message as the COSE_Mac/COSE_Mac0 Payload; all steps 315 specified in [I-D.ietf-cose-msg] for creating a COSE_Mac/ 316 COSE_Mac0 object MUST be followed. 318 * Else, if the CWT is a COSE_Encrypt/COSE_Encrypt0 object, 319 create a COSE_Encrypt/COSE_Encrypt0 using the Message as the 320 plaintext for the COSE_Encrypt/COSE_Encrypt0 object; all steps 321 specified in [I-D.ietf-cose-msg] for creating a COSE_Encrypt/ 322 COSE_Encrypt0 object MUST be followed. 324 5. If a nested signing, MACing or encryption operation will be 325 performed, let the Message be the COSE_Sign/COSE_Sign1, COSE_Mac/ 326 COSE_Mac0 or COSE_Encrypt/COSE_Encrypt0, and return to Step 3, 327 using a "content type" header value corresponding to the media 328 type "application/cwt" in the new COSE Header created in that 329 step. 331 6. If needed by the application, add the appropriate COSE CBOR tag 332 to the COSE object to indicate type of COSE object. If also 333 needed by the application, add the CWT CBOR tag to indicate that 334 the COSE object is a CWT. 336 7.2. Validating a CWT 338 When validating a CWT, the following steps are performed. The order 339 of the steps is not significant in cases where there are no 340 dependencies between the inputs and outputs of the steps. If any of 341 the listed steps fail, then the CWT MUST be rejected -- that is, 342 treated by the application as invalid input. 344 1. Verify that the CWT is a valid CBOR object. 346 2. If the object begins with the CWT CBOR tag, remove it and verify 347 that one of the COSE CBOR tags follows it. 349 3. If the object is tagged with one of the COSE CBOR tags, remove it 350 and verify that it corresponds to the structure of the following 351 COSE object. 353 4. Verify that the resulting COSE Header includes only parameters 354 and values whose syntax and semantics are both understood and 355 supported or that are specified as being ignored when not 356 understood. 358 5. Use the CBOR tag to determine the type of the CWT, COSE_Sign/ 359 COSE_Sign1, COSE_Mac/COSE_Mac0, or COSE_Encrypt/COSE_Encrypt0. 361 6. Depending upon whether the CWT is a signed, MACed, or encrypted, 362 there are three cases: 364 * If the CWT is a COSE_Sign/COSE_Sign1, follow the steps 365 specified in [I-D.ietf-cose-msg] Section 4 (Signing Objects) 366 for validating a COSE_Sign/COSE_Sign1 object. Let the Message 367 be the COSE_Sign/COSE_Sign1 payload. 369 * Else, if the CWT is a COSE_Mac/COSE_Mac0, follow the steps 370 specified in [I-D.ietf-cose-msg] Section 6 (MAC Objects) for 371 validating a COSE_Mac/COSE_Mac0 object. Let the Message be 372 the COSE_Mac/COSE_Mac0 payload. 374 * Else, if the CWT is a COSE_Encrypt/COSE_Encrypt0 object, 375 follow the steps specified in [I-D.ietf-cose-msg] Section 5 376 (Encryption Objects) for validating a COSE_Encrypt/ 377 COSE_Encrypt0 object. Let the Message be the resulting 378 plaintext. 380 7. If the COSE Header contains a "content type" header value 381 corresponding to the media type "application/cwt", then the 382 Message is a CWT that was the subject of nested signing or 383 encryption operations. In this case, return to Step 1, using the 384 Message as the CWT. 386 8. Verify that the Message is a valid CBOR object; let the CWT 387 Claims Set be this CBOR object. 389 8. Security Considerations 391 The security of the CWT is dependent on the protections offered by 392 COSE. Unless the claims in a CWT are protected, an adversary can 393 modify, add, or remove claims. Since the claims conveyed in a CWT 394 may be used to make authorization decisions, it is not only important 395 to protect the CWT in transit but also to ensure that the recipient 396 can authenticate the party that assembled the claims and created the 397 CWT. Without trust of the recipient in the party that created the 398 CWT, no sensible authorization decision can be made. Furthermore, 399 the creator of the CWT needs to carefully evaluate each claim value 400 prior to including it in the CWT so that the recipient can be assured 401 of the validity of the information provided. 403 9. IANA Considerations 405 9.1. CBOR Web Token (CWT) Claims Registry 407 This section establishes the IANA "CBOR Web Token (CWT) Claims" 408 registry. 410 Values are registered on a Specification Required [RFC5226] basis, on 411 the advice of one or more Designated Experts. However, to allow for 412 the allocation of values prior to publication, the Designated Experts 413 may approve registration once they are satisfied that such a 414 specification will be published. 416 Criteria that should be applied by the Designated Experts includes 417 determining whether the proposed registration duplicates existing 418 functionality, whether it is likely to be of general applicability or 419 whether it is useful only for a single application, and whether the 420 registration description is clear. 422 9.1.1. Registration Template 424 Claim Name: 425 The human-readable name requested (e.g., "iss"). 427 Claim Description: 428 Brief description of the claim (e.g., "Issuer"). 430 JWT Claim Name: 431 Claim Name of the equivalent JWT claim, as registered in 432 [IANA.JWT.Claims]. CWT claims should normally have a 433 corresponding JWT claim. If a corresponding JWT claim would not 434 make sense, the Designated Experts can choose to accept 435 registrations for which the JWT Claim Name is listed as "N/A". 437 CBOR Key Value: 438 Key value for the claim. The key value MUST be an integer in the 439 range of 1 to 65536. 441 CBOR Major Type: 442 CBOR major type and optional tag for the claim. 444 Change Controller: 445 For Standards Track RFCs, list the "IESG". For others, give the 446 name of the responsible party. Other details (e.g., postal 447 address, email address, home page URI) may also be included. 449 Specification Document(s): 450 Reference to the document or documents that specify the parameter, 451 preferably including URIs that can be used to retrieve copies of 452 the documents. An indication of the relevant sections may also be 453 included but is not required. 455 9.1.2. Initial Registry Contents 457 o Claim Name: "iss" 458 o Claim Description: Issuer 459 o JWT Claim Name: "iss" 460 o CBOR Key Value: 1 461 o CBOR Major Type: 3 462 o Change Controller: IESG 463 o Specification Document(s): Section 3.1.1 of [[ this specification 464 ]] 466 o Claim Name: "sub" 467 o Claim Description: Subject 468 o JWT Claim Name: "sub" 469 o CBOR Key Value: 2 470 o CBOR Major Type: 3 471 o Change Controller: IESG 472 o Specification Document(s): Section 3.1.2 of [[ this specification 473 ]] 475 o Claim Name: "aud" 476 o Claim Description: Audience 477 o JWT Claim Name: "aud" 478 o CBOR Key Value: 3 479 o CBOR Major Type: 3 480 o Change Controller: IESG 481 o Specification Document(s): Section 3.1.3 of [[ this specification 482 ]] 484 o Claim Name: "exp" 485 o Claim Description: Expiration Time 486 o JWT Claim Name: "exp" 487 o CBOR Key Value: 4 488 o CBOR Major Type: 0, 1, or 7 with subtypes 25, 26, or 27 489 o Change Controller: IESG 490 o Specification Document(s): Section 3.1.4 of [[ this specification 491 ]] 493 o Claim Name: "nbf" 494 o Claim Description: Not Before 495 o JWT Claim Name: "nbf" 496 o CBOR Key Value: 5 497 o CBOR Major Type: 0, 1, or 7 with subtypes 25, 26, or 27 498 o Change Controller: IESG 499 o Specification Document(s): Section 3.1.5 of [[ this specification 500 ]] 502 o Claim Name: "iat" 503 o Claim Description: Issued At 504 o JWT Claim Name: "iat" 505 o CBOR Key Value: 6 506 o CBOR Major Type: 0, 1, or 7 with subtypes 25, 26, or 27 507 o Change Controller: IESG 508 o Specification Document(s): Section 3.1.6 of [[ this specification 509 ]] 511 o Claim Name: "cti" 512 o Claim Description: CWT ID 513 o JWT Claim Name: "jti" 514 o CBOR Key Value: 7 515 o CBOR Major Type: 2 516 o Change Controller: IESG 517 o Specification Document(s): Section 3.1.7 of [[ this specification 518 ]] 520 9.2. Media Type Registration 522 This section registers the "application/cwt" media type in the "Media 523 Types" registry [IANA.MediaTypes] in the manner described in RFC 6838 524 [RFC6838], which can be used to indicate that the content is a CWT. 526 9.2.1. Registry Contents 528 o Type name: application 529 o Subtype name: cwt 530 o Required parameters: N/A 531 o Optional parameters: N/A 532 o Encoding considerations: binary 533 o Security considerations: See the Security Considerations section 534 of [[ this specification ]] 535 o Interoperability considerations: N/A 536 o Published specification: [[ this specification ]] 537 o Applications that use this media type: IoT applications sending 538 security tokens over HTTP(S) and other transports. 539 o Fragment identifier considerations: N/A 540 o Additional information: 542 Magic number(s): N/A 543 File extension(s): N/A 544 Macintosh file type code(s): N/A 546 o Person & email address to contact for further information: 547 IESG, iesg@ietf.org 548 o Intended usage: COMMON 549 o Restrictions on usage: none 550 o Author: Michael B. Jones, mbj@microsoft.com 551 o Change controller: IESG 552 o Provisional registration? No 554 9.3. CoAP Content-Formats Registration 556 This section registers the CoAP Content-Format ID for the 557 "application/cwt" media type in the "CoAP Content-Formats" registry 558 [IANA.CoAP.Content-Formats]. 560 9.3.1. Registry Contents 562 o Media Type: application/cwt 563 o Encoding: - 564 o Id: TBD (maybe 61) 565 o Reference: [[ this specification ]] 567 9.4. CBOR Tag registration 569 This section registers the CWT CBOR tag in the "CBOR Tags" registry 570 [IANA.CBOR.Tags]. 572 9.4.1. Registry Contents 574 o CBOR Tag: TBD (maybe 61 to use the same value as the Content- 575 Format) 576 o Data Item: CBOR Web Token (CWT) 577 o Semantics: CBOR Web Token (CWT), as defined in [[ this 578 specification ]] 579 o Reference: [[ this specification ]] 580 o Point of Contact: Michael B. Jones, mbj@microsoft.com 582 10. References 584 10.1. Normative References 586 [I-D.ietf-cose-msg] 587 Schaad, J., "CBOR Object Signing and Encryption (COSE)", 588 draft-ietf-cose-msg-24 (work in progress), November 2016. 590 [IANA.CBOR.Tags] 591 IANA, "Concise Binary Object Representation (CBOR) Tags", 592 . 595 [IANA.CoAP.Content-Formats] 596 IANA, "CoAP Content-Formats", 597 . 600 [IANA.MediaTypes] 601 IANA, "Media Types", 602 . 604 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 605 Requirement Levels", BCP 14, RFC 2119, 606 DOI 10.17487/RFC2119, March 1997, 607 . 609 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 610 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 611 October 2013, . 613 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 614 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 615 . 617 10.2. Informative References 619 [IANA.JWT.Claims] 620 IANA, "JSON Web Token Claims", 621 . 623 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 624 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 625 DOI 10.17487/RFC5226, May 2008, 626 . 628 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 629 Specifications and Registration Procedures", BCP 13, 630 RFC 6838, DOI 10.17487/RFC6838, January 2013, 631 . 633 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 634 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 635 2015, . 637 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 638 RFC 7516, DOI 10.17487/RFC7516, May 2015, 639 . 641 Appendix A. Examples 643 This appendix includes a set of CWT examples that show how the CWT 644 Claims Set can be protected. There are examples that are signed, 645 MACed, encrypted, and that use nested signing and encryption. To 646 make the examples easier to read, they are presented both as hex 647 strings and in the extended CBOR diagnostic notation described in 648 Section 6 of [RFC7049]. 650 A.1. Example CWT Claims Set 652 The CWT Claims Set used for the different examples displays usage of 653 all the defined claims. For signed and MACed examples, the CWT 654 Claims Set is the CBOR encoding as a binary string. 656 a70175636f61703a2f2f61732e6578616d706c652e636f6d02656572696b7703 657 7818636f61703a2f2f6c696768742e6578616d706c652e636f6d041a5612aeb0 658 051a5610d9f0061a5610d9f007420b71 660 Figure 3: Example CWT Claims Set as hex string 662 { 663 / iss / 1: "coap://as.example.com", 664 / sub / 2: "erikw", 665 / aud / 3: "coap://light.example.com", 666 / exp / 4: 1444064944, 667 / nbf / 5: 1443944944, 668 / iat / 6: 1443944944, 669 / cti / 7: h'0b71' 670 } 672 Figure 4: Example CWT Claims Set in CBOR diagnostic notation 674 A.2. Example keys 676 This section contains the keys used to sign, MAC, and encrypt the 677 messages in this appendix. Line breaks are for display purposes 678 only. 680 A.2.1. 128-bit Symmetric Key as Hex Encoded String 682 8e82e68e61654ecb5a369fe8be7572dd 684 A.2.2. 256-bit Symmetric Key as Hex Encoded String 686 403697de87af64611c1d32a05dab0fe1fcb715a86ab435f1ec99192d79569388 688 A.2.3. ECDSA P-256 256-bit COSE Key 690 a622582060f7f1a780d8a783bfb7a2dd6b2796e8128dbbcef9d3d168db952997 691 1a36e7b92358206c1382765aec5358f117733d281c1c7bdc39884d04a45a1e6c 692 67c858bc206c1903260102215820143329cce7868e416927599cf65a34f3ce2f 693 fda55a7eca69ed8919a394d42f0f2001 695 Figure 5: ECDSA 256-bit COSE Key as hex string 697 { 698 / d / -4: h'6c1382765aec5358f117733d281c1c7bdc39884d04a45a1e 699 6c67c858bc206c19', 700 / y / -3: h'60f7f1a780d8a783bfb7a2dd6b2796e8128dbbcef9d3d168 701 db9529971a36e7b9', 702 / x / -2: h'143329cce7868e416927599cf65a34f3ce2ffda55a7eca69 703 ed8919a394d42f0f', 704 / crv / -1: 1 / P-256 / , 705 / kty / 1: 2 / EC2 / , 706 / alg / 3: -7 / ECDSA 256 / 707 } 709 Figure 6: ECDSA 256-bit COSE Key in CBOR diagnostic notation 711 A.3. Example Signed CWT 713 This section shows a signed CWT with a single recipient and a full 714 CWT Claims Set. 716 The signature is generated using the private key listed in 717 Appendix A.2.3 and it can be validated using the public key from 718 Appendix A.2.3. Line breaks are for display purposes only. 720 d28443a10126a05850a70175636f61703a2f2f61732e6578616d706c652e636f6 721 d02656572696b77037818636f61703a2f2f6c696768742e6578616d706c652e63 722 6f6d041a5612aeb0051a5610d9f0061a5610d9f007420b7158401fe410abce650 723 effed497f05d7f9462de67d571384097de0d96f1e2514d284cdd85634f269af6c 724 36c64f22e7691abb464bed2ff23176cdba9fd9e213f637d082 726 Figure 7: Signed CWT as hex string 728 18( 729 [ 730 / protected / h'a10126' / { 731 / alg / 1: -7 / ECDSA 256 / 732 } / , 733 / unprotected / {}, 734 / payload / h'a70175636f61703a2f2f61732e6578616d706c652e63 735 6f6d02656572696b77037818636f61703a2f2f6c6967 736 68742e6578616d706c652e636f6d041a5612aeb0051a 737 5610d9f0061a5610d9f007420b71' / { 738 / iss / 1: "coap://as.example.com", 739 / sub / 2: "erikw", 740 / aud / 3: "coap://light.example.com", 741 / exp / 4: 1444064944, 742 / nbf / 5: 1443944944, 743 / iat / 6: 1443944944, 744 / cti / 7: h'0b71' 745 } / , 746 / signature / h'1fe410abce650effed497f05d7f9462de67d571384 747 097de0d96f1e2514d284cdd85634f269af6c36c64f 748 22e7691abb464bed2ff23176cdba9fd9e213f637d0 749 82' 750 ] 751 ) 753 Figure 8: Signed CWT in CBOR diagnostic notation 755 A.4. Example MACed CWT 757 This section shows a MACed CWT with a single recipient and a full CWT 758 Claims Set. 760 The MAC is generated using the 256-bit symmetric key from 761 Appendix A.2.2 with a 64-bit truncation. Line breaks are for display 762 purposes only. 764 d83dd18443a10104a05850a70175636f61703a2f2f61732e6578616d706c652e 765 636f6d02656572696b77037818636f61703a2f2f6c696768742e6578616d706c 766 652e636f6d041a5612aeb0051a5610d9f0061a5610d9f007420b7148093101ef 767 6d789200 769 Figure 9: MACed CWT with CWT tag as hex string 771 61( 772 17( 773 [ 774 / protected / h'a10104' / { 775 / alg / 1: 4 / HMAC 256/64 / 776 } / , 777 / unprotected / {}, 778 / payload / h'a70175636f61703a2f2f61732e6578616d706c652e636f 779 6d02656572696b77037818636f61703a2f2f6c69676874 780 2e6578616d706c652e636f6d041a5612aeb0051a5610d9 781 f0061a5610d9f007420b71' / { 782 / iss / 1: "coap://as.example.com", 783 / sub / 2: "erikw", 784 / aud / 3: "coap://light.example.com", 785 / exp / 4: 1444064944, 786 / nbf / 5: 1443944944, 787 / iat / 6: 1443944944, 788 / cti / 7: h'0b71' 789 } / , 790 / tag / h'093101ef6d789200' 791 ] 792 ) 793 ) 795 Figure 10: MACed CWT with CWT tag in CBOR diagnostic notation 797 A.5. Example Encrypted CWT 799 This section shows an encrypted CWT with a single recipient and a 800 full CWT Claims Set. 802 The encryption is done with AES-CCM mode using the 128-bit symmetric 803 key from Appendix A.2.1 with a 64-bit tag and 13-byte nonce, i.e., 804 COSE AES-CCM-16-64-128. Line breaks are for display purposes only. 806 d08343a1010aa1054d3a869e378e72b77d077c29be025858d275ad9cd7df1b10 807 ba8cde785c74b1e1e6ada287e2baf1451b06862529b784d230b0111773b6c369 808 1319aec4dcc379fe47115a5d62632727c05f4567fc84dd79554db86676a14978 809 42de805d8be93180af4d6ff3043886a0 811 Figure 11: Encrypted CWT as hex string 813 16( 814 [ 815 / protected / h'a1010a' / { 816 / alg / 1: 10 / AES-CCM-16-64-128 / 817 } /, 818 / unprotected / { 819 / iv / 5: h'3a869e378e72b77d077c29be02' 820 }, 821 / ciphertext / h'd275ad9cd7df1b10ba8cde785c74b1e1e6ada287e2b 822 af1451b06862529b784d230b0111773b6c3691319ae 823 c4dcc379fe47115a5d62632727c05f4567fc84dd795 824 54db86676a1497842de805d8be93180af4d6ff30438 825 86a0' 826 ] 827 ) 829 Figure 12: Encrypted CWT in CBOR diagnostic notation 831 A.6. Example Nested CWT 833 This section shows a Nested CWT, signed and then encrypted, with a 834 single recipient and a full CWT Claims Set. 836 The signature is generated using the private ECDSA key from 837 Appendix A.2.3 and it can be validated using the public ECDSA parts 838 from Appendix A.2.3. The encryption is done with AES-CCM mode using 839 the 128-bit symmetric key from Appendix A.2.1 with a 64-bit tag and 840 13-byte nonce, i.e., COSE AES-CCM-16-64-128. The content type is set 841 to CWT to indicate that there are multiple layers of COSE protection 842 before finding the CWT Claims Set. The decrypted ciphertext will be a 843 COSE_sign1 structure. In this example, it is the same one as in 844 Appendix A.3, i.e., a Signed CWT Claims Set. Note that there is no 845 limitation to the number of layers; this is an example with two 846 layers. Line breaks are for display purposes only. 848 d08346a203183d010aa1054d9120e5dc42c9f9aec05ebe8a4858a538be026c02 849 4a40b19d6dbea3ddb18b31021f874a097a05ff3cdaa4665bafc8e46a3d7f37ad 850 f002fe57eee267f8f62a9c1621af75e1ecd742a3d801c2cc82358cf104a8d902 851 4d38a599ea6027d482dc2948a88fe83f9734804299c832401029e2d32a984789 852 c8e9563e8d2a751323bb7e4462b549e0fa89ef93f78bf6425635fba76b4aa804 853 7908e89b3b7c3d59d8a80e22f70a1b6ee8c162c564341c2f15cec252d3da038c 855 Figure 13: Signed and Encrypted CWT as hex string 857 16( 858 [ 859 / protected / h'a203183d010a' / { 860 / content type / 3: 61, / CWT / 861 / alg / 1: 10 / AES-CCM-16-64-128 / 862 } / , 863 / unprotected / { 864 / iv / 5: h'9120e5dc42c9f9aec05ebe8a48' 865 }, 866 / ciphertext / h'38be026c024a40b19d6dbea3ddb18b31021f874a097 867 a05ff3cdaa4665bafc8e46a3d7f37adf002fe57eee2 868 67f8f62a9c1621af75e1ecd742a3d801c2cc82358cf 869 104a8d9024d38a599ea6027d482dc2948a88fe83f97 870 34804299c832401029e2d32a984789c8e9563e8d2a7 871 51323bb7e4462b549e0fa89ef93f78bf6425635fba7 872 6b4aa8047908e89b3b7c3d59d8a80e22f70a1b6ee8c 873 162c564341c2f15cec252d3da038c' 874 ] 875 ) 877 Figure 14: Signed and Encrypted CWT in CBOR diagnostic notation 879 Appendix B. Acknowledgements 881 This specification is based on JSON Web Token (JWT) [RFC7519], the 882 authors of which also include Nat Sakimura and John Bradley. Ludwig 883 Seitz and Goeran Selander have made contributions the specification. 885 Appendix C. Document History 887 [[ to be removed by the RFC Editor before publication as an RFC ]] 889 -04 891 o Specified that the use of CBOR tags to prefix any of the claim 892 values defined in this specification is NOT RECOMMENDED. 894 -03 895 o Reworked the examples to include signed, MACed, encrypted, and 896 nested CWTs. 897 o Defined the CWT CBOR tag and explained its usage. 899 -02 901 o Added IANA registration for the application/cwt media type. 902 o Clarified the nested CWT language. 903 o Corrected nits identified by Ludwig Seitz. 905 -01 907 o Added IANA registration for CWT Claims. 908 o Added IANA registration for the application/cwt CoAP content- 909 format type. 910 o Added Samuel Erdtman as an editor. 911 o Changed Erik's e-mail address. 913 -00 915 o Created the initial working group version based on draft- 916 wahlstroem-ace-cbor-web-token-00. 918 Authors' Addresses 920 Michael B. Jones 921 Microsoft 923 Email: mbj@microsoft.com 924 URI: http://self-issued.info/ 926 Erik Wahlstroem 927 Sweden 929 Email: erik@wahlstromstekniska.se 931 Samuel Erdtman 932 Spotify AB 933 Birger Jarlsgatan 61, 4tr 934 Stockholm 113 56 935 Sweden 937 Phone: +46702691499 938 Email: erdtman@spotify.com 939 Hannes Tschofenig 940 ARM Ltd. 941 Hall in Tirol 6060 942 Austria 944 Email: Hannes.Tschofenig@arm.com