idnits 2.17.1 draft-ietf-ace-cbor-web-token-03.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 (March 2, 2017) is 2605 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) == Unused Reference: 'RFC7159' is defined on line 619, but no explicit reference was found in the text ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) == Outdated reference: A later version (-11) exists of draft-greevenbosch-appsawg-cbor-cddl-09 Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). 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: September 3, 2017 6 S. Erdtman 7 Spotify AB 8 H. Tschofenig 9 ARM Ltd. 10 March 2, 2017 12 CBOR Web Token (CWT) 13 draft-ietf-ace-cbor-web-token-03 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 September 3, 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 . . . . . . . . . . . . . . . . . 4 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. CWT CBOR Tag . . . . . . . . . . . . . . . . . . . . . . . . 6 74 6. Creating and Validating CWTs . . . . . . . . . . . . . . . . 6 75 6.1. Creating a CWT . . . . . . . . . . . . . . . . . . . . . 6 76 6.2. Validating a CWT . . . . . . . . . . . . . . . . . . . . 7 77 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9 78 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 79 8.1. CBOR Web Token (CWT) Claims Registry . . . . . . . . . . 9 80 8.1.1. Registration Template . . . . . . . . . . . . . . . . 9 81 8.1.2. Initial Registry Contents . . . . . . . . . . . . . . 10 82 8.2. Media Type Registration . . . . . . . . . . . . . . . . . 11 83 8.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 11 84 8.3. CoAP Content-Formats Registration . . . . . . . . . . . . 12 85 8.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 12 86 8.4. CBOR Tag registration . . . . . . . . . . . . . . . . . . 12 87 8.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 12 88 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 89 9.1. Normative References . . . . . . . . . . . . . . . . . . 13 90 9.2. Informative References . . . . . . . . . . . . . . . . . 14 91 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 14 92 A.1. Example CWT Claims Set . . . . . . . . . . . . . . . . . 14 93 A.2. Example keys . . . . . . . . . . . . . . . . . . . . . . 15 94 A.2.1. 128-bit Symmetric Key as Hex Encoded String . . . . . 15 95 A.2.2. 256-bit Symmetric Key as Hex Encoded String . . . . . 15 96 A.2.3. ECDSA P-256 256-bit COSE Key . . . . . . . . . . . . 15 97 A.3. Example Signed CWT . . . . . . . . . . . . . . . . . . . 16 98 A.4. Example MACed CWT . . . . . . . . . . . . . . . . . . . . 17 99 A.5. Example Encrypted CWT . . . . . . . . . . . . . . . . . . 18 100 A.6. Example Nested CWT . . . . . . . . . . . . . . . . . . . 19 101 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 20 102 Appendix C. Document History . . . . . . . . . . . . . . . . . . 20 103 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 105 1. Introduction 107 The JSON Web Token (JWT) [RFC7519] is a standardized security token 108 format that has found use in OAuth 2.0 and OpenID Connect 109 deployments, among other applications. JWT uses JSON Web Signatures 110 (JWS) [RFC7515] and JSON Web Encryption (JWE) [RFC7516] to secure the 111 contents of the JWT, which is a set of claims represented in JSON 112 [RFC7519]. The use of JSON for encoding information is popular for 113 Web and native applications, but it is considered inefficient for 114 some Internet of Things (IoT) systems that use low power radio 115 technologies. 117 In this document an alternative encoding of claims is defined. 118 Instead of using JSON, as provided by JWTs, this specification uses 119 CBOR [RFC7049] and calls this new structure "CBOR Web Token (CWT)", 120 which is a compact means of representing secured claims to be 121 transferred between two parties. CWT is closely related to JWT. It 122 references the JWT claims and both its name and pronunciation are 123 derived from JWT. To protect the claims contained in CWTs, the CBOR 124 Object Signing and Encryption (COSE) [I-D.ietf-cose-msg] 125 specification is used. 127 The suggested pronunciation of CWT is the same as the English word 128 "cot". 130 2. Terminology 132 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 133 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 134 "OPTIONAL" in this document are to be interpreted as described in 135 "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. 137 This document reuses terminology from JWT [RFC7519] and COSE 138 [I-D.ietf-cose-msg]. 140 Type3StringOrURI: 141 The "Type3StringOrURI" term has the same meaning, syntax, and 142 processing rules as the "StringOrUri" term defined in Section 2 of 143 JWT [RFC7519], except that Type3StringOrURI uses CBOR major type 3 144 instead of a JSON string value. 146 Type6NumericDate: 147 The "Type6NumericDate" term has the same meaning, syntax, and 148 processing rules as the "NumericDate" term defined in Section 2 of 149 JWT [RFC7519], except that Type6NumericDate uses CBOR major type 150 6, with tag value 1, instead of a numeric JSON value. 152 CBOR encoded claim key: 153 The key used to identify a claim value. 155 CWT Claims Set 156 A CBOR map that contains the claims conveyed by the CWT. 158 3. Claims 160 The set of claims that a CWT must contain to be considered valid is 161 context dependent and is outside the scope of this specification. 162 Specific applications of CWTs will require implementations to 163 understand and process some claims in particular ways. However, in 164 the absence of such requirements, all claims that are not understood 165 by implementations MUST be ignored. 167 To keep CWTs as small as possible, the CBOR encoded claim keys are 168 represented using CBOR major type 0. Section 4 summarizes all keys 169 used to identify the claims defined in this document. 171 3.1. Claim Names 173 None of the claims defined below are intended to be mandatory to use 174 or implement. They rather provide a starting point for a set of 175 useful, interoperable claims. Applications using CWTs should define 176 which specific claims they use and when they are required or 177 optional. 179 3.1.1. iss (Issuer) Claim 181 The "iss" (issuer) claim has the same meaning, syntax, and processing 182 rules as the "iss" claim defined in Section 4.1.1 of JWT [RFC7519], 183 except that the format MUST be a Type3StringOrURI. The CBOR encoded 184 claim key 1 MUST be used to identify this claim. 186 3.1.2. sub (Subject) Claim 188 The "sub" (subject) claim has the same meaning, syntax, and 189 processing rules as the "sub" claim defined in Section 4.1.2 of JWT 191 [RFC7519], except that the format MUST be a Type3StringOrURI. The 192 CBOR encoded claim key 2 MUST be used to identify this claim. 194 3.1.3. aud (Audience) Claim 196 The "aud" (audience) claim has the same meaning, syntax, and 197 processing rules as the "aud" claim defined in Section 4.1.3 of JWT 198 [RFC7519], except that the format MUST be a Type3StringOrURI. The 199 CBOR encoded claim key 3 MUST be used to identify this claim. 201 3.1.4. exp (Expiration Time) Claim 203 The "exp" (expiration time) claim has the same meaning, syntax, and 204 processing rules as the "exp" claim defined in Section 4.1.4 of JWT 205 [RFC7519], except that the format MUST be a Type6NumericDate. The 206 CBOR encoded claim key 4 MUST be used to identify this claim. 208 3.1.5. nbf (Not Before) Claim 210 The "nbf" (not before) claim has the same meaning, syntax, and 211 processing rules as the "nbf" claim defined in Section 4.1.5 of JWT 212 [RFC7519], except that the format MUST be a Type6NumericDate. The 213 CBOR encoded claim key 5 MUST be used to identify this claim. 215 3.1.6. iat (Issued At) Claim 217 The "iat" (issued at) claim has the same meaning, syntax, and 218 processing rules as the "iat" claim defined in Section 4.1.6 of JWT 219 [RFC7519], except that the format MUST be a Type6NumericDate. The 220 CBOR encoded claim key 6 MUST be used to identify this claim. 222 3.1.7. cti (CWT ID) Claim 224 The "cti" (CWT ID) claim has the same meaning, syntax, and processing 225 rules as the "jti" claim defined in Section 4.1.7 of JWT [RFC7519], 226 except that the format MUST be of major type 2, binary string. The 227 CBOR encoded claim key 7 MUST be used to identify this claim. 229 4. Summary of the values, CBOR major types and encoded claim keys 230 /---------+------------------------+--------------------------\ 231 | Claim | CBOR encoded claim key | CBOR major type of value | 232 |---------+------------------------+--------------------------| 233 | iss | 1 | 3 | 234 | sub | 2 | 3 | 235 | aud | 3 | 3 | 236 | exp | 4 | 6 tag value 1 | 237 | nbf | 5 | 6 tag value 1 | 238 | iat | 6 | 6 tag value 1 | 239 | cti | 7 | 2 | 240 \---------+------------------------+--------------------------/ 242 Figure 1: Summary of the values, CBOR major types and encoded claim 243 keys. 245 5. CWT CBOR Tag 247 How to determine that a CBOR data structure is a CWT is application- 248 dependent. In some cases, this information is known from the 249 application context, such as from the position of the CWT in a data 250 structure at which the value must be a CWT. One method of indicating 251 that a CBOR object is a CWT is the use of the "application/cwt" 252 content type by a transport protocol. 254 This section defines the CWT CBOR tag as another means for 255 applications to declare that a CBOR data structure is a CWT. Its use 256 is optional, and is intended for use in cases in which this 257 information would not otherwise be known. 259 The CWT tag MUST prefix a tagged object using one of the COSE CBOR 260 tags. In this example, the COSE_Mac0 tag is used. The actual 261 COSE_Mac0 object has been excluded from this example. 263 / CWT CBOR tag / 61( 264 / COSE_Mac0 CBOR tag / 17( 265 / COSE_Mac0 object / 266 ) 267 ) 269 Figure 2: Example of a CWT tag usage 271 6. Creating and Validating CWTs 273 6.1. Creating a CWT 275 To create a CWT, the following steps are performed. The order of the 276 steps is not significant in cases where there are no dependencies 277 between the inputs and outputs of the steps. 279 1. Create a CWT Claims Set containing the desired claims. 281 2. Let the Message be the binary representation of the CWT Claims 282 Set. 284 3. Create a COSE Header containing the desired set of Header 285 Parameters. The COSE Header MUST be valid per the 286 [I-D.ietf-cose-msg] specification. 288 4. Depending upon whether the CWT is signed, MACed, or encrypted, 289 there are three cases: 291 * If the CWT is signed, create a COSE_Sign/COSE_Sign1 object 292 using the Message as the COSE_Sign/COSE_Sign1 Payload; all 293 steps specified in [I-D.ietf-cose-msg] for creating a 294 COSE_Sign/COSE_Sign1 object MUST be followed. 296 * Else, if the CWT is MACed, create a COSE_Mac/COSE_Mac0 object 297 using the Message as the COSE_Mac/COSE_Mac0 Payload; all steps 298 specified in [I-D.ietf-cose-msg] for creating a COSE_Mac/ 299 COSE_Mac0 object MUST be followed. 301 * Else, if the CWT is a COSE_Encrypt/COSE_Encrypt0 object, 302 create a COSE_Encrypt/COSE_Encrypt0 using the Message as the 303 plaintext for the COSE_Encrypt/COSE_Encrypt0 object; all steps 304 specified in [I-D.ietf-cose-msg] for creating a COSE_Encrypt/ 305 COSE_Encrypt0 object MUST be followed. 307 5. If a nested signing, MACing or encryption operation will be 308 performed, let the Message be the COSE_Sign/COSE_Sign1, COSE_Mac/ 309 COSE_Mac0 or COSE_Encrypt/COSE_Encrypt0, and return to Step 3, 310 using a "content type" header value corresponding to the media 311 type "application/cwt" in the new COSE Header created in that 312 step. 313 Note: If integrity (signing/MACing) and confidentiality 314 (encryption) protection are needed, it is recommended to use an 315 authenticated encryption algorithm to save space and processing. 317 6. If needed by the application, add the appropriate COSE CBOR tag 318 to the COSE object to indicate type of COSE object. If also 319 needed by the application, add the CWT CBOR tag to indicate that 320 the COSE object is a CWT. 322 6.2. Validating a CWT 324 When validating a CWT, the following steps are performed. The order 325 of the steps is not significant in cases where there are no 326 dependencies between the inputs and outputs of the steps. If any of 327 the listed steps fail, then the CWT MUST be rejected -- that is, 328 treated by the application as an invalid input. 330 1. Verify that the CWT is a valid CBOR object. 332 2. If the object begins with the CWT CBOR tag, remove it and verify 333 that one of the COSE CBOR tags follows it. 335 3. If the object is tagged with one of the COSE CBOR tags, remove it 336 and verify that it corresponds to the structure of the following 337 COSE object. 339 4. Verify that the resulting COSE Header includes only parameters 340 and values whose syntax and semantics are both understood and 341 supported or that are specified as being ignored when not 342 understood. 344 5. Use the CBOR tag to determine the type of the CWT, COSE_Sign/ 345 COSE_Sign1, COSE_Mac/COSE_Mac0, or COSE_Encrypt/COSE_Encrypt0. 347 6. Depending upon whether the CWT is a signed, MACed, or encrypted, 348 there are three cases: 350 * If the CWT is a COSE_Sign/COSE_Sign1, follow the steps 351 specified in [I-D.ietf-cose-msg] Section 4 (Signing Objects) 352 for validating a COSE_Sign/COSE_Sign1 object. Let the Message 353 be the COSE_Sign/COSE_Sign1 payload. 355 * Else, if the CWT is a COSE_Mac/COSE_Mac0, follow the steps 356 specified in [I-D.ietf-cose-msg] Section 6 (MAC Objects) for 357 validating a COSE_Mac/COSE_Mac0 object. Let the Message be 358 the COSE_Mac/COSE_Mac0 payload. 360 * Else, if the CWT is a COSE_Encrypt/COSE_Encrypt0 object, 361 follow the steps specified in [I-D.ietf-cose-msg] Section 5 362 (Encryption Objects) for validating a COSE_Encrypt/ 363 COSE_Encrypt0 object. Let the Message be the resulting 364 plaintext. 366 7. If the COSE Header contains a "content type" header value 367 corresponding to the media type "application/cwt", then the 368 Message is a CWT that was the subject of nested signing or 369 encryption operations. In this case, return to Step 1, using the 370 Message as the CWT. 372 8. Verify that the Message is a valid CBOR object; let the CWT 373 Claims Set be this CBOR object. 375 7. Security Considerations 377 The security of the CWT is dependent on the protections offered by 378 COSE. Unless the claims in a CWT are protected, an adversary can 379 modify, add, or remove claims. Since the claims conveyed in a CWT 380 may be used to make authorization decisions, it is not only important 381 to protect the CWT in transit but also to ensure that the recipient 382 can authenticate the party that assembled the claims and created the 383 CWT. Without trust of the recipient in the party that created the 384 CWT, no sensible authorization decision can be made. Furthermore, 385 the creator of the CWT needs to carefully evaluate each claim value 386 prior to including it in the CWT so that the recipient can be assured 387 of the validity of the information provided. 389 8. IANA Considerations 391 8.1. CBOR Web Token (CWT) Claims Registry 393 This section establishes the IANA "CBOR Web Token (CWT) Claims" 394 registry. 396 Values are registered on a Specification Required [RFC5226] basis, on 397 the advice of one or more Designated Experts. However, to allow for 398 the allocation of values prior to publication, the Designated Experts 399 may approve registration once they are satisfied that such a 400 specification will be published. 402 Criteria that should be applied by the Designated Experts includes 403 determining whether the proposed registration duplicates existing 404 functionality, whether it is likely to be of general applicability or 405 whether it is useful only for a single application, and whether the 406 registration description is clear. 408 8.1.1. Registration Template 410 Claim Name: 411 The human-readable name requested (e.g., "iss"). 413 Claim Description: 414 Brief description of the claim (e.g., "Issuer"). 416 JWT Claim Name: 417 Claim Name of the equivalent JWT claim as registered in 418 [IANA.JWT.Claims]. CWT claims should normally have a 419 corresponding JWT claim. If a corresponding JWT claim would not 420 make sense, the Designated Experts can choose to accept 421 registrations for which the JWT Claim Name is listed as "N/A". 423 CBOR Key Value: 424 Key value for the claim. The key value MUST be an integer in the 425 range of 1 to 65536. 427 CBOR Major Type: 428 CBOR major type and optional tag for the claim. 430 Change Controller: 431 For Standards Track RFCs, list the "IESG". For others, give the 432 name of the responsible party. Other details (e.g., postal 433 address, email address, home page URI) may also be included. 435 Specification Document(s): 436 Reference to the document or documents that specify the parameter, 437 preferably including URIs that can be used to retrieve copies of 438 the documents. An indication of the relevant sections may also be 439 included but is not required. 441 8.1.2. Initial Registry Contents 443 o Claim Name: "iss" 444 o Claim Description: Issuer 445 o JWT Claim Name: "iss" 446 o CBOR Key Value: 1 447 o CBOR Major Type: 3 448 o Change Controller: IESG 449 o Specification Document(s): Section 3.1.1 of [[ this specification 450 ]] 452 o Claim Name: "sub" 453 o Claim Description: Subject 454 o JWT Claim Name: "sub" 455 o CBOR Key Value: 2 456 o CBOR Major Type: 3 457 o Change Controller: IESG 458 o Specification Document(s): Section 3.1.2 of [[ this specification 459 ]] 461 o Claim Name: "aud" 462 o Claim Description: Audience 463 o JWT Claim Name: "aud" 464 o CBOR Key Value: 3 465 o CBOR Major Type: 3 466 o Change Controller: IESG 467 o Specification Document(s): Section 3.1.3 of [[ this specification 468 ]] 470 o Claim Name: "exp" 471 o Claim Description: Expiration Time 472 o JWT Claim Name: "exp" 473 o CBOR Key Value: 4 474 o CBOR Major Type: 6, tag value 1 475 o Change Controller: IESG 476 o Specification Document(s): Section 3.1.4 of [[ this specification 477 ]] 479 o Claim Name: "nbf" 480 o Claim Description: Not Before 481 o JWT Claim Name: "nbf" 482 o CBOR Key Value: 5 483 o CBOR Major Type: 6, tag value 1 484 o Change Controller: IESG 485 o Specification Document(s): Section 3.1.5 of [[ this specification 486 ]] 488 o Claim Name: "iat" 489 o Claim Description: Issued At 490 o JWT Claim Name: "iat" 491 o CBOR Key Value: 6 492 o CBOR Major Type: 6, tag value 1 493 o Change Controller: IESG 494 o Specification Document(s): Section 3.1.6 of [[ this specification 495 ]] 497 o Claim Name: "cti" 498 o Claim Description: CWT ID 499 o JWT Claim Name: "jti" 500 o CBOR Key Value: 7 501 o CBOR Major Type: 2 502 o Change Controller: IESG 503 o Specification Document(s): Section 3.1.7 of [[ this specification 504 ]] 506 8.2. Media Type Registration 508 This section registers the "application/cwt" media type [RFC2046] in 509 the "Media Types" registry [IANA.MediaTypes] in the manner described 510 in RFC 6838 [RFC6838], which can be used to indicate that the content 511 is a CWT. 513 8.2.1. Registry Contents 515 o Type name: application 516 o Subtype name: cwt 517 o Required parameters: N/A 518 o Optional parameters: N/A 519 o Encoding considerations: binary 520 o Security considerations: See the Security Considerations section 521 of [[ this specification ]] 522 o Interoperability considerations: N/A 523 o Published specification: [[ this specification ]] 524 o Applications that use this media type: IoT applications sending 525 security tokens over HTTP(S) and other transports. 526 o Fragment identifier considerations: N/A 527 o Additional information: 529 Magic number(s): N/A 530 File extension(s): N/A 531 Macintosh file type code(s): N/A 533 o Person & email address to contact for further information: 534 IESG, iesg@ietf.org 535 o Intended usage: COMMON 536 o Restrictions on usage: none 537 o Author: Michael B. Jones, mbj@microsoft.com 538 o Change controller: IESG 539 o Provisional registration? No 541 8.3. CoAP Content-Formats Registration 543 This section registers the CoAP Content-Format ID for the 544 "application/cwt" media type in the "CoAP Content-Formats" registry 545 [IANA.CoAP.Content-Formats] established by [RFC7252]. 547 8.3.1. Registry Contents 549 o Media Type: application/cwt 550 o Encoding: - 551 o Id: TBD (maybe 61) 552 o Reference: [[ this specification ]] 554 8.4. CBOR Tag registration 556 This section registers the CWT CBOR tag in the "CBOR Tags" registry 557 [IANA.CBOR.Tags] established by [RFC7049]. 559 8.4.1. Registry Contents 561 o CBOR Tag: TBD (maybe 61 to use the same value as the Content- 562 Format) 563 o Data Item: CBOR Web Token (CWT) 564 o Semantics: CBOR Web Token (CWT), as defined in [[ this 565 specification ]] 566 o Reference: [[ this specification ]] 567 o Point of Contact: Michael B. Jones, mbj@microsoft.com 569 9. References 571 9.1. Normative References 573 [I-D.ietf-cose-msg] 574 Schaad, J., "CBOR Object Signing and Encryption (COSE)", 575 draft-ietf-cose-msg-24 (work in progress), November 2016. 577 [IANA.CBOR.Tags] 578 IANA, "Concise Binary Object Representation (CBOR) Tags", 579 . 582 [IANA.CoAP.Content-Formats] 583 IANA, "CoAP Content-Formats", 584 . 587 [IANA.JWT.Claims] 588 IANA, "JSON Web Token Claims", 589 . 591 [IANA.MediaTypes] 592 IANA, "Media Types", 593 . 595 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 596 Extensions (MIME) Part Two: Media Types", RFC 2046, 597 DOI 10.17487/RFC2046, November 1996, 598 . 600 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 601 Requirement Levels", BCP 14, RFC 2119, 602 DOI 10.17487/RFC2119, March 1997, 603 . 605 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 606 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 607 DOI 10.17487/RFC5226, May 2008, 608 . 610 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 611 Specifications and Registration Procedures", BCP 13, 612 RFC 6838, DOI 10.17487/RFC6838, January 2013, 613 . 615 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 616 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 617 October 2013, . 619 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 620 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 621 2014, . 623 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 624 Application Protocol (CoAP)", RFC 7252, 625 DOI 10.17487/RFC7252, June 2014, 626 . 628 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 629 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 630 2015, . 632 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 633 RFC 7516, DOI 10.17487/RFC7516, May 2015, 634 . 636 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 637 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 638 . 640 9.2. Informative References 642 [I-D.greevenbosch-appsawg-cbor-cddl] 643 Vigano, C. and H. Birkholz, "CBOR data definition language 644 (CDDL): a notational convention to express CBOR data 645 structures", draft-greevenbosch-appsawg-cbor-cddl-09 (work 646 in progress), September 2016. 648 Appendix A. Examples 650 This appendix includes a set of CWT examples that show how the CWT 651 Claims Set can be protected. There are examples that are signed, 652 MACed, encrypted, and that use nested signing and encryption. To 653 make the examples easier to read, they are presented both as hex 654 strings and in the extended CBOR diagnostic notation 655 [I-D.greevenbosch-appsawg-cbor-cddl]. 657 A.1. Example CWT Claims Set 659 The CWT Claims Set used for the different examples displays usage of 660 all the defined claims. For signed and MACed examples, the CWT 661 Claims Set is the CBOR encoding as a binary string. 663 a702656572696b77037818636f61703a2f2f6c696768742e6578616d706c652e 664 636f6d041a5612aeb0051a5610d9f0061a5610d9f00175636f61703a2f2f6173 665 2e6578616d706c652e636f6d07420b71 667 Figure 3: Example CWT Claims Set as hex string 669 { 670 / iss / 1: "coap://as.example.com", 671 / sub / 2: "erikw", 672 / aud / 3: "coap://light.example.com", 673 / exp / 4: 1444064944, 674 / nbf / 5: 1443944944, 675 / iat / 6: 1443944944, 676 / cti / 7: h'0b71' 677 } 679 Figure 4: Example CWT Claims Set in CBOR diagnostic notation 681 A.2. Example keys 683 This section contains the keys used to sign, MAC, and encrypt the 684 messages in this appendix. Line breaks are for display purposes 685 only. 687 A.2.1. 128-bit Symmetric Key as Hex Encoded String 689 9e4f3e65cc1a558b39ce97b3db469b04 691 A.2.2. 256-bit Symmetric Key as Hex Encoded String 693 e60198ac1650ec9210d7f4f5b27aeae2ada8f4adada555909edca75ce2ae506e 695 A.2.3. ECDSA P-256 256-bit COSE Key 697 a6225820feb11ca73b028a10cf77d58a2dfdf2a11eab8ffeeeaaeeb03097ffee 698 9f3ef2fc2358200657fada2568959c49a404583fe237290ebeb1956f3ad3d966 699 ea09e33369d7b103260102215820c4f9160fc22682991c59c4d96e8accc2da3c 700 c7b7a9bc197c7c1e1bc6d0c1dc612001 702 Figure 5: ECDSA 256-bit COSE Key as hex string 704 { 705 / d / -4: h'0657fada2568959c49a404583fe237290ebeb1956f3ad3d966 706 ea09e33369d7b1', 707 / y / -3: h'feb11ca73b028a10cf77d58a2dfdf2a11eab8ffeeeaaeeb030 708 97ffee9f3ef2fc', 709 / x / -2: h'c4f9160fc22682991c59c4d96e8accc2da3cc7b7a9bc197c7c 710 1e1bc6d0c1dc61', 711 / crv / -1: 1 / P-256 / 712 / kty / 1: 2 / EC2 /, 713 / alg / 3: -7, \ ECDSA 256 \ 714 } 716 Figure 6: ECDSA 256-bit COSE Key in CBOR diagnostic notation 718 A.3. Example Signed CWT 720 This section shows a signed CWT with a single recipient and a full 721 CWT Claims Set. 723 The signature is generated using the private ECDSA key from 724 Appendix A.2.3 and it can be validated using the public part of the 725 ECDSA key from Appendix A.2.3. Line breaks are for display purposes 726 only. 728 d28446a203183d0126a05850a702656572696b77037818636f61703a2f2f6c69 729 6768742e6578616d706c652e636f6d041a5612aeb0051a5610d9f0061a5610d9 730 f00175636f61703a2f2f61732e6578616d706c652e636f6d07420b7158407eef 731 29abe962ac185e5a372d95d69ce1b5683c5c25efb69a81710dc5173254f5179a 732 639827694c22828819704eb026676ca78aaf8da76672a6b5537fb90e710d 734 Figure 7: Signed CWT as hex string 736 18( 737 [ 738 / protected / h'a203183d0126' / { 739 / content type / 3: 61, / CWT / 740 / alg / 1: -7 / ECDSA 256 / 741 } / , 742 / unprotected / {}, 743 / payload / h'a702656572696b77037818636f61703a2f2f6c69676874 744 2e6578616d706c652e636f6d041a5612aeb0051a5610d9 745 f0061a5610d9f00175636f61703a2f2f61732e6578616d 746 706c652e636f6d07420b71' / { 747 / iss / 1: "coap://as.example.com", 748 / sub / 2: "erikw", 749 / aud / 3: "coap://light.example.com", 750 / exp / 4: 1444064944, 751 / nbf / 5: 1443944944, 752 / iat / 6: 1443944944, 753 / cti / 7: h'0b71' 754 } / , 755 / signature / h'7eef29abe962ac185e5a372d95d69ce1b5683c5c25ef 756 b69a81710dc5173254f5179a639827694c2282881970 757 4eb026676ca78aaf8da76672a6b5537fb90e710d' 758 ] 759 ) 761 Figure 8: Signed CWT in CBOR diagnostic notation 763 A.4. Example MACed CWT 765 This section shows a MACed CWT with a single recipient and a full CWT 766 Claims Set. 768 The MAC is generated using the 256-bit symmetric key from 769 Appendix A.2.2 with a 64-bit truncation. Line breaks are for display 770 purposes only. 772 d18446a203183d0104a05850a702656572696b77037818636f61703a2f2f6c69 773 6768742e6578616d706c652e636f6d041a5612aeb0051a5610d9f0061a5610d9 774 f00175636f61703a2f2f61732e6578616d706c652e636f6d07420b7148b59884 775 6f1ce93f9d 777 Figure 9: MACed CWT as hex string 779 17( 780 [ 781 / protected / h'a203183d0104' / { 782 / content type / 3: 61, / CWT / 783 / alg / 1: 4 / HMAC 256/64 / 784 } / , 785 / unprotected / {}, 786 / payload / h'a702656572696b77037818636f61703a2f2f6c69676874 787 2e6578616d706c652e636f6d041a5612aeb0051a5610d9 788 f0061a5610d9f00175636f61703a2f2f61732e6578616d 789 706c652e636f6d07420b71' / { 790 / iss / 1: "coap://as.example.com", 791 / sub / 2: "erikw", 792 / aud / 3: "coap://light.example.com", 793 / exp / 4: 1444064944, 794 / nbf / 5: 1443944944, 795 / iat / 6: 1443944944, 796 / cti / 7: h'0b71' 797 } / , 798 / tag / h'b598846f1ce93f9d' 799 ] 800 ) 802 Figure 10: MACed CWT in CBOR diagnostic notation 804 A.5. Example Encrypted CWT 806 This section shows an encrypted CWT with a single recipient and a 807 full CWT Claims Set. 809 The encryption is done with AES-CCM mode using the 128-bit symmetric 810 key from Appendix A.2.1 with a 64-bit tag and 13-byte nonce, i.e., 811 COSE AES-CCM-16-64-128. Line breaks are for display purposes only. 813 d08346a203183d010aa1054dadbe290e8c9c23067a558b15795858f7a8ec3e32 814 3bb6e006e8aec087666f6fc0d65d7aa272f5f1dde1dfb52fd3a5e1ace97e5bfc 815 8f05a146fd8a9feab7bb9e722254e2660612f956041264c06ea3b95afb0d8ce3 816 138bc80baf2511565d3dad63ea7534699fa449 818 Figure 11: Encrypted CWT as hex string 820 16( 821 [ 822 / protected / h'a203183d010a' / { 823 / content type / 3: 61, / CWT / 824 / alg / 1: 10 / AES-CCM-16-64-128 / 825 } /, 826 / unprotected / { 827 / iv / 5: h'adbe290e8c9c23067a558b1579' 828 }, 829 / ciphertext / h'f7a8ec3e323bb6e006e8aec087666f6fc0d65d7aa27 830 2f5f1dde1dfb52fd3a5e1ace97e5bfc8f05a146fd8a 831 9feab7bb9e722254e2660612f956041264c06ea3b95 832 afb0d8ce3138bc80baf2511565d3dad63ea7534699f 833 a449' 834 ] 835 ) 837 Figure 12: Encrypted CWT in CBOR diagnostic notation 839 A.6. Example Nested CWT 841 This section shows a Nested CWT, signed and then encrypted, with a 842 single recipient and a full CWT Claims Set. 844 The signature is generated using the private ECDSA key from 845 Appendix A.2.3 and it can be validated using the public ECDSA parts 846 from Appendix A.2.3. The encryption is done with AES-CCM mode using 847 the 128-bit symmetric key from Appendix A.2.1 with a 64-bit tag and 848 13-byte nonce, i.e., COSE AES-CCM-16-64-128. The content type is set 849 to CWT to indicate that there are multiple layers of COSE protection 850 before finding the CWT Claims Set. The decrypted ciphertext will be a 851 COSE_sign1 structure. In this example, it is the same one as in 852 Appendix A.3, i.e., a Signed CWT Claims Set. Note that there is no 853 limitation to the number of layers; this is an example with two 854 layers. Line breaks are for display purposes only. 856 d08346a203183d010aa1054d2653469d58937647a6a1bb023458a65da538206c33 857 cf941df7ea933ba7b93c60322017f9db9c904608fce2688b51028b5b912f9010 858 ae72802bf65778593c7270b20683b1587824eb4074e03323ccf0541b495a3757 859 f353a8424b6ceeaaec1898964d8a03e04e514a5b0ca143b57689a2a9f1c6c84d 860 535d1966adf900dfaf0dd045d2325c40150a07d602b65c60e62894c870ad5fc2 861 cb709e4d17d381806797b6cf118608e18c3facd0a0ac09d88ea73d4ed7e3b57c 863 Figure 13: Signed and Encrypted CWT as hex string 865 16( 866 [ 867 / protected / h'a203183d010a' / { 868 / content type / 3: 61, / CWT / 869 / alg / 1: 10 / AES-CCM-16-64-128 / 870 } / , 871 / unprotected / { 872 / iv / 5: h'2653469d58937647a6a1bb0234' 873 }, 874 / ciphertext / h'5da538206c33cf941df7ea933ba7b93c60322017f9d 875 b9c904608fce2688b51028b5b912f9010ae72802bf6 876 5778593c7270b20683b1587824eb4074e03323ccf05 877 41b495a3757f353a8424b6ceeaaec1898964d8a03e0 878 4e514a5b0ca143b57689a2a9f1c6c84d535d1966adf 879 900dfaf0dd045d2325c40150a07d602b65c60e62894 880 c870ad5fc2cb709e4d17d381806797b6cf118608e18 881 c3facd0a0ac09d88ea73d4ed7e3b57c' 882 ] 883 ) 885 Figure 14: Signed and Encrypted CWT in CBOR diagnostic notation 887 Appendix B. Acknowledgements 889 This specification is based on JSON Web Token (JWT) [RFC7519], the 890 authors of which also include Nat Sakimura and John Bradley. Ludwig 891 Seitz and Goeran Selander have made contributions the specification. 893 Appendix C. Document History 895 [[ to be removed by the RFC Editor before publication as an RFC ]] 897 -03 899 o Reworked the examples to include signed, MACed, encrypted, and 900 nested CWTs. 901 o Defined the CWT CBOR tag and explained its usage. 903 -02 905 o Added IANA registration for the application/cwt media type. 906 o Clarified the nested CWT language. 907 o Corrected nits identified by Ludwig Seitz. 909 -01 911 o Added IANA registration for CWT Claims. 913 o Added IANA registration for the application/cwt CoAP content- 914 format type. 915 o Added Samuel Erdtman as an editor. 916 o Changed Erik's e-mail address. 918 -00 920 o Created the initial working group version based on draft- 921 wahlstroem-ace-cbor-web-token-00. 923 Authors' Addresses 925 Michael B. Jones 926 Microsoft 928 Email: mbj@microsoft.com 929 URI: http://self-issued.info/ 931 Erik Wahlstroem 932 Sweden 934 Email: erik@wahlstromstekniska.se 936 Samuel Erdtman 937 Spotify AB 938 Birger Jarlsgatan 61, 4tr 939 Stockholm 113 56 940 Sweden 942 Phone: +46702691499 943 Email: erdtman@spotify.com 945 Hannes Tschofenig 946 ARM Ltd. 947 Hall in Tirol 6060 948 Austria 950 Email: Hannes.Tschofenig@arm.com