idnits 2.17.1 draft-ietf-ace-cbor-web-token-01.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 : ---------------------------------------------------------------------------- ** There are 19 instances of too long lines in the document, the longest one being 107 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 7, 2016) is 2847 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC7159' is defined on line 493, but no explicit reference was found in the text == Outdated reference: A later version (-24) exists of draft-ietf-cose-msg-14 ** 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) Summary: 4 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 E. Wahlstroem 3 Internet-Draft 4 Intended status: Informational M. Jones 5 Expires: January 8, 2017 Microsoft 6 H. Tschofenig 7 ARM Ltd. 8 S. Erdtman 9 Spotify AB 10 July 7, 2016 12 CBOR Web Token (CWT) 13 draft-ietf-ace-cbor-web-token-01 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 January 8, 2017. 43 Copyright Notice 45 Copyright (c) 2016 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 . . . . . . . . . . . . . . . . 4 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. Creating and Validating CWTs . . . . . . . . . . . . . . . . 6 74 5.1. Creating a CWT . . . . . . . . . . . . . . . . . . . . . 6 75 5.2. Validating a CWT . . . . . . . . . . . . . . . . . . . . 7 76 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 77 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 78 7.1. CBOR Web Token (CWT) Claims Registry . . . . . . . . . . 8 79 7.1.1. Registration Template . . . . . . . . . . . . . . . . 8 80 7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 9 81 7.2. CoAP Content-Format Registration . . . . . . . . . . . . 10 82 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 10 83 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 84 8.1. Normative References . . . . . . . . . . . . . . . . . . 11 85 8.2. Informative References . . . . . . . . . . . . . . . . . 12 86 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 12 87 A.1. CWT with "aud" and symmetric key . . . . . . . . . . . . 12 88 A.2. CWT with "aud" and EC key . . . . . . . . . . . . . . . . 13 89 A.3. Full CWT . . . . . . . . . . . . . . . . . . . . . . . . 15 90 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 18 91 Appendix C. Document History . . . . . . . . . . . . . . . . . . 19 92 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 94 1. Introduction 96 The JSON Web Token (JWT) [RFC7519] is a standardized security token 97 format that has found use in OAuth 2.0 and OpenID Connect 98 deployments, among other applications. JWT uses JSON Web Signatures 99 (JWS) [RFC7515] and JSON Web Encryption (JWE) [RFC7516] to secure the 100 contents of the JWT, which is a set of claims represented in JSON 101 [RFC7519]. The use of JSON for encoding information is popular for 102 Web and native applications, but it is considered inefficient for 103 some Internet of Things (IoT) systems that use low power radio 104 technologies. 106 In this document an alternative encoding of claims is defined. 107 Instead of using JSON, as provided by JWTs, this specification uses 108 CBOR [RFC7049] and calls this new structure "CBOR Web Token (CWT)", 109 which is a compact means of representing secured claims to be 110 transferred between two parties. CWT is closely related to JWT. It 111 references the JWT claims and both its name and pronunciation are 112 derived from JWT. To protect the claims contained in CWTs, the CBOR 113 Object Signing and Encryption (COSE) [I-D.ietf-cose-msg] 114 specification is used. 116 The suggested pronunciation of CWT is the same as the English word 117 "cot". 119 2. Terminology 121 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 122 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 123 "OPTIONAL" in this document are to be interpreted as described in 124 "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. 126 This document reuses terminology from JWT [RFC7519] and COSE 127 [I-D.ietf-cose-msg]. 129 Type3StringOrURI: 130 The "Type3StringOrURI" term has the same meaning, syntax, and 131 processing rules as the "StringOrUri" term defined in Section 2 of 132 JWT [RFC7519], except that Type3StringOrURI uses CBOR major type 3 133 instead of a JSON string value. 135 Type6NumericDate: 136 The "Type6NumericDate" term has the same meaning, syntax, and 137 processing rules as the "NumericDate" term defined in Section 2 of 138 JWT [RFC7519], except that Type6NumericDate uses CBOR major type 139 6, with tag value 1, instead of a numeric JSON value. 141 CBOR encoded claim key: 143 The key used to identify a claim value. 145 3. Claims 147 The set of claims that a CWT must contain to be considered valid is 148 context dependent and is outside the scope of this specification. 149 Specific applications of CWTs will require implementations to 150 understand and process some claims in particular ways. However, in 151 the absence of such requirements, all claims that are not understood 152 by implementations MUST be ignored. 154 To keep CWTs as small as possible, the CBOR encoded claim keys are 155 represented using CBOR major type 0. Section 4 summaries all keys 156 used to identity the claims defined in this document. 158 3.1. Claim Names 160 None of the claims defined below are intended to be mandatory to use 161 or implement. They rather provide a starting point for a set of 162 useful, interoperable claims. Applications using CWTs should define 163 which specific claims they use and when they are required or 164 optional. 166 3.1.1. iss (Issuer) Claim 168 The "iss" (issuer) claim has the same meaning, syntax, and processing 169 rules as the "iss" claim defined in Section 4.1.1 of JWT [RFC7519], 170 except that the format MUST be a Type3StringOrURI. The CBOR encoded 171 claim key 1 MUST be used to identify this claim. 173 3.1.2. sub (Subject) Claim 175 The "sub" (subject) claim has the same meaning, syntax, and 176 processing rules as the "sub" claim defined in Section 4.1.2 of JWT 177 [RFC7519], except that the format MUST be a Type3StringOrURI. The 178 CBOR encoded claim key 2 MUST be used to identify this claim. 180 3.1.3. aud (Audience) Claim 182 The "aud" (audience) claim has the same meaning, syntax, and 183 processing rules as the "aud" claim defined in Section 4.1.3 of JWT 184 [RFC7519], except that the format MUST be a Type3StringOrURI. The 185 CBOR encoded claim key 3 MUST be used to identify this claim. 187 3.1.4. exp (Expiration Time) Claim 189 The "exp" (expiration time) claim has the same meaning, syntax, and 190 processing rules as the "exp" claim defined in Section 4.1.4 of JWT 191 [RFC7519], except that the format MUST be a Type6NumericDate. The 192 CBOR encoded claim key 4 MUST be used to identify this claim. 194 3.1.5. nbf (Not Before) Claim 196 The "nbf" (not before) claim has the same meaning, syntax, and 197 processing rules as the "nbf" claim defined in Section 4.1.5 of JWT 198 [RFC7519], except that the format MUST be a Type6NumericDate. The 199 CBOR encoded claim key 5 MUST be used to identify this claim. 201 3.1.6. iat (Issued At) Claim 203 The "iat" (issued at) claim has the same meaning, syntax, and 204 processing rules as the "iat" claim defined in Section 4.1.6 of JWT 205 [RFC7519], except that the format MUST be a Type6NumericDate. The 206 CBOR encoded claim key 6 MUST be used to identify this claim. 208 3.1.7. cti (CWT ID) Claim 210 The "cti" (CWT ID) claim has the same meaning, syntax, and processing 211 rules as the "jti" claim defined in Section 4.1.7 of JWT [RFC7519], 212 except that the format MUST be of major type 2, binary string. The 213 CBOR encoded claim key 7 MUST be used to identify this claim. 215 4. Summary of the values, CBOR major types and encoded claim keys 217 /---------+------------------------+--------------------------\ 218 | Claim | CBOR encoded claim key | CBOR major type of value | 219 |---------+------------------------+--------------------------| 220 | iss | 1 | 3 | 221 | sub | 2 | 3 | 222 | aud | 3 | 3 | 223 | exp | 4 | 6 tag value 1 | 224 | nbf | 5 | 6 tag value 1 | 225 | iat | 6 | 6 tag value 1 | 226 | cti | 7 | 2 | 227 \---------+------------------------+--------------------------/ 229 Figure 1: Summary of the values, CBOR major types and encoded claim 230 keys. 232 5. Creating and Validating CWTs 234 5.1. Creating a CWT 236 To create a CWT, the following steps are performed. The order of the 237 steps is not significant in cases where there are no dependencies 238 between the inputs and outputs of the steps. 240 1. Create a CWT Claims Set containing the desired claims. 242 2. Let the Message be the binary representation of the CWT Claims 243 Set. 245 3. Create a COSE Header containing the desired set of Header 246 Parameters. The CWT Header MUST be a valid according to the 247 [I-D.ietf-cose-msg] specification. 249 4. Depending upon whether the CWT is signed, MACed or encrypted, 250 there are three cases: 252 * If the CWT is signed, create a COSE_Sign/COSE_Sign1 object 253 using the Message as the COSE_Sign/COSE_Sign1 Payload; all 254 steps specified in [I-D.ietf-cose-msg] for creating a 255 COSE_Sign/COSE_Sign1 object MUST be followed. 257 * Else, if the CWT is MACed, create a COSE_Mac/COSE_Mac0 object 258 using the Message as the COSE_Mac/COSE_Mac0 Payload; all steps 259 specified in [I-D.ietf-cose-msg] for creating a COSE_Mac/ 260 COSE_Mac0 object MUST be followed. 262 * Else, if the CWT is a COSE_Encrypt/COSE_Encrypt0 object, 263 create a COSE_Encrypt/COSE_Encrypt0 using the Message as the 264 plaintext for the COSE_Encrypt/COSE_Encrypt0 object; all steps 265 specified in [I-D.ietf-cose-msg] for creating a COSE_Encrypt/ 266 COSE_Encrypt0 object MUST be followed. 268 5. If a nested signing, MACing or encryption operation will be 269 performed, let the Message be the COSE_Sign/COSE_Sign1, COSE_Mac/ 270 COSE_Mac0 or COSE_Encrypt/COSE_Encrypt0, and return to Step 3, 271 using "content type" header value of "CWT" in the new COSE Header 272 created in that step. 273 Note: If integrity (signing/MACing) and confidentiality 274 (encryption) protection are needed, it is recommended to use an 275 authenticated encryption algorithm to save space and processing. 277 5.2. Validating a CWT 279 When validating a CWT, the following steps are performed. The order 280 of the steps is not significant in cases where there are no 281 dependencies between the inputs and outputs of the steps. If any of 282 the listed steps fail, then the CWT MUST be rejected -- that is, 283 treated by the application as an invalid input. 285 1. Verify that the CWT is a valid CBOR object. 287 2. Verify that the resulting COSE Header includes only parameters 288 and values whose syntax and semantics are both understood and 289 supported or that are specified as being ignored when not 290 understood. 292 3. Use the CBOR tag to determine the type the CWT, COSE_Sign/ 293 COSE_Sign1, COSE_Mac/COSE_Mac0 or COSE_Encrypt/COSE_Encrypt0. 295 4. Depending upon whether the CWT is a COSE_Sign/COSE_Sign1, 296 COSE_Mac/COSE_Mac0 or COSE_Encrypt/COSE_Encrypt0, there are three 297 cases: 299 * If the CWT is a COSE_Sign/COSE_Sign1, follow the steps 300 specified in [I-D.ietf-cose-msg] Section 4 (Signing Objects) 301 for validating a COSE_Sign/COSE_Sign1 object. Let the Message 302 be the COSE_Sign/COSE_Sign1 payload. 304 * Else, if the CWT is a COSE_Mac/COSE_Mac0, follow the steps 305 specified in [I-D.ietf-cose-msg] Section 6 (MAC Objects) for 306 validating a COSE_Mac/COSE_Mac0 object. Let the Message be 307 the COSE_Mac/COSE_Mac0 payload. 309 * Else, if the CWT is a COSE_Encrypt/COSE_Encrypt0 object, 310 follow the steps specified in [I-D.ietf-cose-msg] Section 5 311 (Encryption Objects) for validating a COSE_Encrypt/ 312 COSE_Encrypt0 object. Let the Message be the resulting 313 plaintext. 315 5. If the JOSE Header contains a "content type" value of "CWT", then 316 the Message is a CWT that was the subject of nested signing or 317 encryption operations. In this case, return to Step 1, using the 318 Message as the CWT. 320 6. Verify that the Message is a valid CBOR object; let the CWT 321 Claims Set be this CBOR object. 323 6. Security Considerations 325 The security of the CWT is dependent on the protection offered by 326 COSE. Without protecting the claims contained in a CWT an adversary 327 is able to modify, add or remove claims. Since the claims conveyed 328 in a CWT are used to make authorization decisions it is not only 329 important to protect the CWT in transit but also to ensure that the 330 recipient is able to authenticate the party that collected the claims 331 and created the CWT. Without trust of the recipient in the party 332 that created the CWT no sensible authorization decision can be made. 333 Furthermore, the creator of the CWT needs to carefully evaluate each 334 claim value prior to including it in the CWT so that the recipient 335 can be assured about the correctness of the provided information. 337 7. IANA Considerations 339 7.1. CBOR Web Token (CWT) Claims Registry 341 This section establishes the IANA "CBOR Web Token (CWT) Claims" 342 registry. 344 Values are registered on a Specification Required [RFC5226] basis, on 345 the advice of one or more Designated Experts. However, to allow for 346 the allocation of values prior to publication, the Designated Experts 347 may approve registration once they are satisfied that such a 348 specification will be published. 350 Criteria that should be applied by the Designated Experts includes 351 determining whether the proposed registration duplicates existing 352 functionality, whether it is likely to be of general applicability or 353 whether it is useful only for a single application, and whether the 354 registration description is clear. 356 7.1.1. Registration Template 358 Claim Name: 359 The human-readable name requested (e.g., "iss"). 361 Claim Description: 362 Brief description of the claim (e.g., "Issuer"). 364 JWT Claim Name: 365 Claim Name of the equivalent JWT claim as registered in 366 [IANA.JWT.Claims]. CWT claims should normally have a 367 corresponding JWT claim. If a corresponding JWT claim would not 368 make sense, the Designated Experts can choose to accept 369 registrations for which the JWT Claim Name is listed as "N/A". 371 CBOR Key Value: 372 Key value for the claim. The key value MUST be an integer in the 373 range of 1 to 65536. 375 CBOR Major Type: 376 CBOR Major type and optional tag for the claim. 378 Change Controller: 379 For Standards Track RFCs, list the "IESG". For others, give the 380 name of the responsible party. Other details (e.g., postal 381 address, email address, home page URI) may also be included. 383 Specification Document(s): 384 Reference to the document or documents that specify the parameter, 385 preferably including URIs that can be used to retrieve copies of 386 the documents. An indication of the relevant sections may also be 387 included but is not required. 389 7.1.2. Initial Registry Contents 391 o Claim Name: "iss" 392 o Claim Description: Issuer 393 o JWT Claim Name: "iss" 394 o CBOR Key Value: 1 395 o CBOR Major Type: 3 396 o Change Controller: IESG 397 o Specification Document(s): Section 3.1.1 of [[ this specification 398 ]] 400 o Claim Name: "sub" 401 o Claim Description: Subject 402 o JWT Claim Name: "sub" 403 o CBOR Key Value: 2 404 o CBOR Major Type: 3 405 o Change Controller: IESG 406 o Specification Document(s): Section 3.1.2 of [[ this specification 407 ]] 409 o Claim Name: "aud" 410 o Claim Description: Audience 411 o JWT Claim Name: "aud" 412 o CBOR Key Value: 3 413 o CBOR Major Type: 3 414 o Change Controller: IESG 415 o Specification Document(s): Section 3.1.3 of [[ this specification 416 ]] 418 o Claim Name: "exp" 419 o Claim Description: Expiration Time 420 o JWT Claim Name: "exp" 421 o CBOR Key Value: 4 422 o CBOR Major Type: 6, tag value 1 423 o Change Controller: IESG 424 o Specification Document(s): Section 3.1.4 of [[ this specification 425 ]] 427 o Claim Name: "nbf" 428 o Claim Description: Not Before 429 o JWT Claim Name: "nbf" 430 o CBOR Key Value: 5 431 o CBOR Major Type: 6, tag value 1 432 o Change Controller: IESG 433 o Specification Document(s): Section 3.1.5 of [[ this specification 434 ]] 436 o Claim Name: "iat" 437 o Claim Description: Issued At 438 o JWT Claim Name: "iat" 439 o CBOR Key Value: 6 440 o CBOR Major Type: 6, tag value 1 441 o Change Controller: IESG 442 o Specification Document(s): Section 3.1.6 of [[ this specification 443 ]] 445 o Claim Name: "cti" 446 o Claim Description: CWT ID 447 o JWT Claim Name: "jti" 448 o CBOR Key Value: 7 449 o CBOR Major Type: 2 450 o Change Controller: IESG 451 o Specification Document(s): Section 3.1.7 of [[ this specification 452 ]] 454 7.2. CoAP Content-Format Registration 456 This section registers the "application/cwt" CoAP Content-Format ID 457 in the "CoRE Parameters" sub-registry "CoAP Content-Format" in the 458 manner described in [RFC7252]. 460 7.2.1. Registry Contents 462 o Media Type: application/cwt 463 o Encoding: - 464 o Id: TBD (maybe 61) 465 o Reference: [[ this specification ]] 467 8. References 469 8.1. Normative References 471 [I-D.ietf-cose-msg] 472 Schaad, J., "CBOR Object Signing and Encryption (COSE)", 473 draft-ietf-cose-msg-14 (work in progress), June 2016. 475 [IANA.JWT.Claims] 476 IANA, "JSON Web Token Claims", 477 . 479 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 480 Requirement Levels", BCP 14, RFC 2119, 481 DOI 10.17487/RFC2119, March 1997, 482 . 484 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 485 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 486 DOI 10.17487/RFC5226, May 2008, 487 . 489 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 490 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 491 October 2013, . 493 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 494 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 495 2014, . 497 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 498 Application Protocol (CoAP)", RFC 7252, 499 DOI 10.17487/RFC7252, June 2014, 500 . 502 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 503 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 504 2015, . 506 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 507 RFC 7516, DOI 10.17487/RFC7516, May 2015, 508 . 510 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 511 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 512 . 514 8.2. Informative References 516 [I-D.seitz-ace-oauth-authz] 517 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 518 H. Tschofenig, "Authorization for the Internet of Things 519 using OAuth 2.0", draft-seitz-ace-oauth-authz-00 (work in 520 progress), October 2015. 522 Appendix A. Examples 524 Three examples of CWTs follow. 526 A.1. CWT with "aud" and symmetric key 528 A CWT used in the context of ACE requires at least the "aud" and a 529 "cks" claim (defined elsewhere). This means that "iss", "alg", 530 "key_ops" and others are pre-established and assumed. This would 531 look like this non-normative JSON. 533 { 534 "aud":"coap://light.example.com", 535 "cks": 536 [ // COSE_Key is a CBOR map with an array of keys 537 { 538 "kty":4, // symmetric key is indicated using kty 4 539 "k": "loremipsum" // the symmetric key 540 } 541 ] 542 } 544 Figure 2: "aud" claim and symmetric key in non-normative JSON 546 Using the CBOR encoded claim keys according to Section 4 and COSE 547 [I-D.ietf-cose-msg] makes a CWT with "aud" and a symmetric key look 548 like this in CBOR diagnostic notation: 550 { 551 3: "coap://light.example.com", 552 8: 553 [ 554 { 555 1: 4, 556 -1: "loremipsum" 557 } 558 ] 559 } 561 Figure 3: CWT in CBOR diagnostic notation 563 Defined in CBOR. 565 a2 # map(2) 566 03 # unsigned(3) 567 78 18 # text(24) 568 636f61703a2f2f6c696768742e6578616d706c652e636f6d # "coap://light.example.com" 569 08 # unsigned(8) 570 81 # array(1) 571 a2 # map(2) 572 01 # unsigned(1) 573 04 # unsigned(4) 574 20 # negative(0) 575 6a # text(10) 576 6c6f72656d697073756d # "loremipsum" 578 Figure 4: CWT with "aud" and symmetric key in CBOR 580 Size of the CWT with a symmetric key of 10 bytes is 45 bytes. This 581 is then packaged signed and encrypted using COSE. 583 A.2. CWT with "aud" and EC key 585 Token with "aud" set to "coap://light.example.com" and an EC key with 586 "kid" set to "11". 588 { 589 "aud": "coap://light.example.com", 590 "cks": 591 [ // COSE_Key is a CBOR map with an array of keys 592 { 593 "kty": "EC", 594 "kid": "11", 595 "crv": 1, // using P-384 596 "x": h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff', 597 "y": h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e' 598 } 599 ] 600 } 602 Figure 5: "aud" claim and EC key in non-normative JSON 604 Using the CBOR encoded claim keys according to Section 4 and COSE 605 [I-D.ietf-cose-msg] makes a CWT with "aud" and an EC key look like 606 this in CBOR diagnostic notation: 608 { 609 3: "coap://light.example.com", 610 8: 611 [ 612 { 613 1: 2, 614 2: "11", 615 -1: 1, 616 -2: h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff', 617 -3: h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e' 618 } 619 ] 620 } 622 Figure 6: CWT with EC key in CBOR diagnostic notation 624 Defined in CBOR. 626 a2 # map(2) 627 03 # unsigned(3) 628 78 18 # text(24) 629 636f61703a2f2f6c696768742e6578616d706c652e636f6d # "coap://light.example.com" 630 08 # unsigned(8) 631 81 # array(1) 632 a5 # map(5) 633 01 # unsigned(1) 634 02 # unsigned(2) 635 02 # unsigned(2) 636 62 # text(2) 637 3131 # "11" 638 20 # negative(0) 639 01 # unsigned(1) 640 21 # negative(1) 641 58 20 # bytes(32) 642 bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff # "\xBA\xC5\xB1\x1C\xAD\x8F\x99\xF9\xC7+\x05\xCFK\x9E&\xD2D\xDC\x18\x9FtR(%Z!\x9A\x86\xD6\xA0\x9E\xFF" 643 22 # negative(2) 644 58 20 # bytes(32) 645 20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e # "\x13\x8B\xF8-\xC1\xB6\xD5b\xBE\x0F\xA5J\xB7\x80J:d\xB6\xD7,\xCF\xEDko\xB6\xED(\xBB\xFC\x11~" 647 Figure 7: CWT with EC in CBOR 649 Size of the CWT with an EC key is 109 bytes. This is then packaged 650 signed and encrypted using COSE. 652 A.3. Full CWT 654 CWT using all claims defined by this specification, plus extensions 655 for AIF and an EC key. 657 { 658 "iss": "coap://as.example.com", 659 "aud": "coap://light.example.com", 660 "sub": "erikw", 661 "exp": 1444064944, 662 "nbf": 1443944944, 663 "iat": 1443944944, 664 "cti": 2929, 665 "cks": 666 [ // COSE_Key is a CBOR map with an array of keys 667 { 668 "kty": "EC", 669 "kid": "11", 670 "crv": 1, // using P-384 671 "x": h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff', 672 "y": h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e' 673 } 674 ], 675 "aif": [["/s/light", 1], ["/a/led", 5], ["/dtls", 2]] 676 } 678 Figure 8: All claims, "aif" and EC key in non-normative JSON 680 Using the CBOR encoded claim keys according to Section 4 and COSE 681 [I-D.ietf-cose-msg] makes a full CWT look like this in CBOR 682 diagnostic notation: 684 { 685 1: "coap://as.example.com", 686 3: "coap://light.example.com", 687 2: "erikw", 688 4: 1(1444064944), 689 5: 1(1443944944), 690 6: 1(1443944944), 691 7: 2929, 692 8: [ 693 { 694 1: 2, 695 2: "11", 696 -1: 1, 697 -2: h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff', 698 -3: h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e' 699 } 700 ], 701 9: [["/s/light", 1], ["/a/led", 5], ["/dtls", 2]] 702 } 704 Figure 9: Full CWT with EC key in CBOR diagnostic notation 706 Defined in CBOR. 708 a9 # map(9) 709 01 # unsigned(1) 710 75 # text(21) 711 636f61703a2f2f61732e6578616d706c652e636f6d # "coap://as.example.com" 712 03 # unsigned(3) 713 78 18 # text(24) 714 636f61703a2f2f6c696768742e6578616d706c652e636f6d # "coap://light.example.com" 715 02 # unsigned(2) 716 65 # text(5) 717 6572696b77 # "erikw" 718 04 # unsigned(4) 719 c1 # tag(1) 720 1a 5612aeb0 # unsigned(1444064944) 721 05 # unsigned(5) 722 c1 # tag(1) 723 1a 5610d9f0 # unsigned(1443944944) 724 06 # unsigned(6) 725 c1 # tag(1) 726 1a 5610d9f0 # unsigned(1443944944) 727 07 # unsigned(7) 728 19 0b71 # unsigned(2929) 729 08 # unsigned(8) 730 81 # array(1) 731 a5 # map(5) 732 01 # unsigned(1) 733 02 # unsigned(2) 734 02 # unsigned(2) 735 62 # text(2) 736 3131 # "11" 737 20 # negative(0) 738 01 # unsigned(1) 739 21 # negative(1) 740 58 20 # bytes(32) 741 bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff # "\xBA\xC5\xB1\x1C\xAD\x8F\x99\xF9\xC7+\x05\xCFK\x9E&\xD2D\xDC\x18\x9FtR(%Z!\x9A\x86\xD6\xA0\x9E\xFF" 742 22 # negative(2) 743 58 20 # bytes(32) 744 20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e # "\x13\x8B\xF8-\xC1\xB6\xD5b\xBE\x0F\xA5J\xB7\x80J:d\xB6\xD7,\xCF\xEDko\xB6\xED(\xBB\xFC\x11~" 745 09 # unsigned(9) 746 83 # array(3) 747 82 # array(2) 748 68 # text(8) 749 2f732f6c69676874 # "/s/light" 750 01 # unsigned(1) 751 82 # array(2) 752 66 # text(6) 753 2f612f6c6564 # "/a/led" 754 05 # unsigned(5) 755 82 # array(2) 756 65 # text(5) 757 2f64746c73 # "/dtls" 758 02 # unsigned(2) 760 Figure 10: Full CWT with EC in CBOR 762 Size of the CWT with an EC key is 194 bytes. This is then packaged 763 signed and encrypted using COSE. 765 Appendix B. Acknowledgements 767 This specification is based on JSON Web Token (JWT) [RFC7519], the 768 authors of which also include Nat Sakimura and John Bradley. A straw 769 man proposal of CWT was written in the draft "Authorization for the 770 Internet of Things using OAuth 2.0" [I-D.seitz-ace-oauth-authz] with 771 the help of Ludwig Seitz and Goeran Selander. 773 Appendix C. Document History 775 [[ to be removed by the RFC Editor before publication as an RFC ]] 777 -01 779 o Added IANA registration for CWT Claims. 780 o Added IANA registration for the application/cwt CoAP content- 781 format type. 782 o Added Samuel Erdtman as an editor. 783 o Changed Erik's e-mail address. 785 -00 787 o Created the initial working group version based on draft- 788 wahlstroem-ace-cbor-web-token-00. 790 Authors' Addresses 792 Erik Wahlstroem 793 Sweden 795 Email: erik@wahlstromstekniska.se 797 Michael B. Jones 798 Microsoft 800 Email: mbj@microsoft.com 801 URI: http://self-issued.info/ 803 Hannes Tschofenig 804 ARM Ltd. 805 Hall in Tirol 6060 806 Austria 808 Email: Hannes.Tschofenig@arm.com 810 Samuel Erdtman 811 Spotify AB 812 Birger Jarlsgatan 61, 4tr 813 Stockholm 113 56 814 Sweden 816 Phone: +46702691499 817 Email: erdtman@spotify.com