idnits 2.17.00 (12 Aug 2021) /tmp/idnits60916/draft-ietf-ace-cbor-web-token-02.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 (January 13, 2017) is 1953 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC7159' is defined on line 554, but no explicit reference was found in the text == Outdated reference: draft-ietf-cose-msg has been published as RFC 8152 ** 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 M. Jones 3 Internet-Draft Microsoft 4 Intended status: Informational E. Wahlstroem 5 Expires: July 17, 2017 6 S. Erdtman 7 Spotify AB 8 H. Tschofenig 9 ARM Ltd. 10 January 13, 2017 12 CBOR Web Token (CWT) 13 draft-ietf-ace-cbor-web-token-02 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 July 17, 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 . . . . . . . . . . . . . . . . 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. Media Type Registration . . . . . . . . . . . . . . . . . 10 82 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 10 83 7.3. CoAP Content-Formats Registration . . . . . . . . . . . . 11 84 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 11 85 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 86 8.1. Normative References . . . . . . . . . . . . . . . . . . 11 87 8.2. Informative References . . . . . . . . . . . . . . . . . 13 88 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 13 89 A.1. CWT with "aud" and symmetric key . . . . . . . . . . . . 13 90 A.2. CWT with "aud" and EC key . . . . . . . . . . . . . . . . 14 91 A.3. Full CWT . . . . . . . . . . . . . . . . . . . . . . . . 16 92 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 19 93 Appendix C. Document History . . . . . . . . . . . . . . . . . . 20 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 96 1. Introduction 98 The JSON Web Token (JWT) [RFC7519] is a standardized security token 99 format that has found use in OAuth 2.0 and OpenID Connect 100 deployments, among other applications. JWT uses JSON Web Signatures 101 (JWS) [RFC7515] and JSON Web Encryption (JWE) [RFC7516] to secure the 102 contents of the JWT, which is a set of claims represented in JSON 103 [RFC7519]. The use of JSON for encoding information is popular for 104 Web and native applications, but it is considered inefficient for 105 some Internet of Things (IoT) systems that use low power radio 106 technologies. 108 In this document an alternative encoding of claims is defined. 109 Instead of using JSON, as provided by JWTs, this specification uses 110 CBOR [RFC7049] and calls this new structure "CBOR Web Token (CWT)", 111 which is a compact means of representing secured claims to be 112 transferred between two parties. CWT is closely related to JWT. It 113 references the JWT claims and both its name and pronunciation are 114 derived from JWT. To protect the claims contained in CWTs, the CBOR 115 Object Signing and Encryption (COSE) [I-D.ietf-cose-msg] 116 specification is used. 118 The suggested pronunciation of CWT is the same as the English word 119 "cot". 121 2. Terminology 123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 125 "OPTIONAL" in this document are to be interpreted as described in 126 "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. 128 This document reuses terminology from JWT [RFC7519] and COSE 129 [I-D.ietf-cose-msg]. 131 Type3StringOrURI: 132 The "Type3StringOrURI" term has the same meaning, syntax, and 133 processing rules as the "StringOrUri" term defined in Section 2 of 134 JWT [RFC7519], except that Type3StringOrURI uses CBOR major type 3 135 instead of a JSON string value. 137 Type6NumericDate: 138 The "Type6NumericDate" term has the same meaning, syntax, and 139 processing rules as the "NumericDate" term defined in Section 2 of 140 JWT [RFC7519], except that Type6NumericDate uses CBOR major type 141 6, with tag value 1, instead of a numeric JSON value. 143 CBOR encoded claim key: 145 The key used to identify a claim value. 147 CWT Claims Set 148 A CBOR map that contains the claims conveyed by the CWT. 150 3. Claims 152 The set of claims that a CWT must contain to be considered valid is 153 context dependent and is outside the scope of this specification. 154 Specific applications of CWTs will require implementations to 155 understand and process some claims in particular ways. However, in 156 the absence of such requirements, all claims that are not understood 157 by implementations MUST be ignored. 159 To keep CWTs as small as possible, the CBOR encoded claim keys are 160 represented using CBOR major type 0. Section 4 summarizes all keys 161 used to identify the claims defined in this document. 163 3.1. Claim Names 165 None of the claims defined below are intended to be mandatory to use 166 or implement. They rather provide a starting point for a set of 167 useful, interoperable claims. Applications using CWTs should define 168 which specific claims they use and when they are required or 169 optional. 171 3.1.1. iss (Issuer) Claim 173 The "iss" (issuer) claim has the same meaning, syntax, and processing 174 rules as the "iss" claim defined in Section 4.1.1 of JWT [RFC7519], 175 except that the format MUST be a Type3StringOrURI. The CBOR encoded 176 claim key 1 MUST be used to identify this claim. 178 3.1.2. sub (Subject) Claim 180 The "sub" (subject) claim has the same meaning, syntax, and 181 processing rules as the "sub" claim defined in Section 4.1.2 of JWT 182 [RFC7519], except that the format MUST be a Type3StringOrURI. The 183 CBOR encoded claim key 2 MUST be used to identify this claim. 185 3.1.3. aud (Audience) Claim 187 The "aud" (audience) claim has the same meaning, syntax, and 188 processing rules as the "aud" claim defined in Section 4.1.3 of JWT 189 [RFC7519], except that the format MUST be a Type3StringOrURI. The 190 CBOR encoded claim key 3 MUST be used to identify this claim. 192 3.1.4. exp (Expiration Time) Claim 194 The "exp" (expiration time) claim has the same meaning, syntax, and 195 processing rules as the "exp" claim defined in Section 4.1.4 of JWT 196 [RFC7519], except that the format MUST be a Type6NumericDate. The 197 CBOR encoded claim key 4 MUST be used to identify this claim. 199 3.1.5. nbf (Not Before) Claim 201 The "nbf" (not before) claim has the same meaning, syntax, and 202 processing rules as the "nbf" claim defined in Section 4.1.5 of JWT 203 [RFC7519], except that the format MUST be a Type6NumericDate. The 204 CBOR encoded claim key 5 MUST be used to identify this claim. 206 3.1.6. iat (Issued At) Claim 208 The "iat" (issued at) claim has the same meaning, syntax, and 209 processing rules as the "iat" claim defined in Section 4.1.6 of JWT 210 [RFC7519], except that the format MUST be a Type6NumericDate. The 211 CBOR encoded claim key 6 MUST be used to identify this claim. 213 3.1.7. cti (CWT ID) Claim 215 The "cti" (CWT ID) claim has the same meaning, syntax, and processing 216 rules as the "jti" claim defined in Section 4.1.7 of JWT [RFC7519], 217 except that the format MUST be of major type 2, binary string. The 218 CBOR encoded claim key 7 MUST be used to identify this claim. 220 4. Summary of the values, CBOR major types and encoded claim keys 222 /---------+------------------------+--------------------------\ 223 | Claim | CBOR encoded claim key | CBOR major type of value | 224 |---------+------------------------+--------------------------| 225 | iss | 1 | 3 | 226 | sub | 2 | 3 | 227 | aud | 3 | 3 | 228 | exp | 4 | 6 tag value 1 | 229 | nbf | 5 | 6 tag value 1 | 230 | iat | 6 | 6 tag value 1 | 231 | cti | 7 | 2 | 232 \---------+------------------------+--------------------------/ 234 Figure 1: Summary of the values, CBOR major types and encoded claim 235 keys. 237 5. Creating and Validating CWTs 239 5.1. Creating a CWT 241 To create a CWT, the following steps are performed. The order of the 242 steps is not significant in cases where there are no dependencies 243 between the inputs and outputs of the steps. 245 1. Create a CWT Claims Set containing the desired claims. 247 2. Let the Message be the binary representation of the CWT Claims 248 Set. 250 3. Create a COSE Header containing the desired set of Header 251 Parameters. The COSE Header MUST be valid according to the 252 [I-D.ietf-cose-msg] specification. 254 4. Depending upon whether the CWT is signed, MACed or encrypted, 255 there are three cases: 257 * If the CWT is signed, create a COSE_Sign/COSE_Sign1 object 258 using the Message as the COSE_Sign/COSE_Sign1 Payload; all 259 steps specified in [I-D.ietf-cose-msg] for creating a 260 COSE_Sign/COSE_Sign1 object MUST be followed. 262 * Else, if the CWT is MACed, create a COSE_Mac/COSE_Mac0 object 263 using the Message as the COSE_Mac/COSE_Mac0 Payload; all steps 264 specified in [I-D.ietf-cose-msg] for creating a COSE_Mac/ 265 COSE_Mac0 object MUST be followed. 267 * Else, if the CWT is a COSE_Encrypt/COSE_Encrypt0 object, 268 create a COSE_Encrypt/COSE_Encrypt0 using the Message as the 269 plaintext for the COSE_Encrypt/COSE_Encrypt0 object; all steps 270 specified in [I-D.ietf-cose-msg] for creating a COSE_Encrypt/ 271 COSE_Encrypt0 object MUST be followed. 273 5. If a nested signing, MACing or encryption operation will be 274 performed, let the Message be the COSE_Sign/COSE_Sign1, COSE_Mac/ 275 COSE_Mac0 or COSE_Encrypt/COSE_Encrypt0, and return to Step 3, 276 using a "content type" header value corresponding to the media 277 type "application/cwt" in the new COSE Header created in that 278 step. 279 Note: If integrity (signing/MACing) and confidentiality 280 (encryption) protection are needed, it is recommended to use an 281 authenticated encryption algorithm to save space and processing. 283 5.2. Validating a CWT 285 When validating a CWT, the following steps are performed. The order 286 of the steps is not significant in cases where there are no 287 dependencies between the inputs and outputs of the steps. If any of 288 the listed steps fail, then the CWT MUST be rejected -- that is, 289 treated by the application as an invalid input. 291 1. Verify that the CWT is a valid CBOR object. 293 2. Verify that the resulting COSE Header includes only parameters 294 and values whose syntax and semantics are both understood and 295 supported or that are specified as being ignored when not 296 understood. 298 3. Use the CBOR tag to determine the type of the CWT, COSE_Sign/ 299 COSE_Sign1, COSE_Mac/COSE_Mac0, or COSE_Encrypt/COSE_Encrypt0. 301 4. Depending upon whether the CWT is a COSE_Sign/COSE_Sign1, 302 COSE_Mac/COSE_Mac0 or COSE_Encrypt/COSE_Encrypt0, there are three 303 cases: 305 * If the CWT is a COSE_Sign/COSE_Sign1, follow the steps 306 specified in [I-D.ietf-cose-msg] Section 4 (Signing Objects) 307 for validating a COSE_Sign/COSE_Sign1 object. Let the Message 308 be the COSE_Sign/COSE_Sign1 payload. 310 * Else, if the CWT is a COSE_Mac/COSE_Mac0, follow the steps 311 specified in [I-D.ietf-cose-msg] Section 6 (MAC Objects) for 312 validating a COSE_Mac/COSE_Mac0 object. Let the Message be 313 the COSE_Mac/COSE_Mac0 payload. 315 * Else, if the CWT is a COSE_Encrypt/COSE_Encrypt0 object, 316 follow the steps specified in [I-D.ietf-cose-msg] Section 5 317 (Encryption Objects) for validating a COSE_Encrypt/ 318 COSE_Encrypt0 object. Let the Message be the resulting 319 plaintext. 321 5. If the COSE Header contains a "content type" header value 322 corresponding to the media type "application/cwt", then the 323 Message is a CWT that was the subject of nested signing or 324 encryption operations. In this case, return to Step 1, using the 325 Message as the CWT. 327 6. Verify that the Message is a valid CBOR object; let the CWT 328 Claims Set be this CBOR object. 330 6. Security Considerations 332 The security of the CWT is dependent on the protection offered by 333 COSE. Without protecting the claims contained in a CWT an adversary 334 is able to modify, add or remove claims. Since the claims conveyed 335 in a CWT are used to make authorization decisions it is not only 336 important to protect the CWT in transit but also to ensure that the 337 recipient is able to authenticate the party that collected the claims 338 and created the CWT. Without trust of the recipient in the party 339 that created the CWT no sensible authorization decision can be made. 340 Furthermore, the creator of the CWT needs to carefully evaluate each 341 claim value prior to including it in the CWT so that the recipient 342 can be assured about the correctness of the provided information. 344 7. IANA Considerations 346 7.1. CBOR Web Token (CWT) Claims Registry 348 This section establishes the IANA "CBOR Web Token (CWT) Claims" 349 registry. 351 Values are registered on a Specification Required [RFC5226] basis, on 352 the advice of one or more Designated Experts. However, to allow for 353 the allocation of values prior to publication, the Designated Experts 354 may approve registration once they are satisfied that such a 355 specification will be published. 357 Criteria that should be applied by the Designated Experts includes 358 determining whether the proposed registration duplicates existing 359 functionality, whether it is likely to be of general applicability or 360 whether it is useful only for a single application, and whether the 361 registration description is clear. 363 7.1.1. Registration Template 365 Claim Name: 366 The human-readable name requested (e.g., "iss"). 368 Claim Description: 369 Brief description of the claim (e.g., "Issuer"). 371 JWT Claim Name: 372 Claim Name of the equivalent JWT claim as registered in 373 [IANA.JWT.Claims]. CWT claims should normally have a 374 corresponding JWT claim. If a corresponding JWT claim would not 375 make sense, the Designated Experts can choose to accept 376 registrations for which the JWT Claim Name is listed as "N/A". 378 CBOR Key Value: 379 Key value for the claim. The key value MUST be an integer in the 380 range of 1 to 65536. 382 CBOR Major Type: 383 CBOR major type and optional tag for the claim. 385 Change Controller: 386 For Standards Track RFCs, list the "IESG". For others, give the 387 name of the responsible party. Other details (e.g., postal 388 address, email address, home page URI) may also be included. 390 Specification Document(s): 391 Reference to the document or documents that specify the parameter, 392 preferably including URIs that can be used to retrieve copies of 393 the documents. An indication of the relevant sections may also be 394 included but is not required. 396 7.1.2. Initial Registry Contents 398 o Claim Name: "iss" 399 o Claim Description: Issuer 400 o JWT Claim Name: "iss" 401 o CBOR Key Value: 1 402 o CBOR Major Type: 3 403 o Change Controller: IESG 404 o Specification Document(s): Section 3.1.1 of [[ this specification 405 ]] 407 o Claim Name: "sub" 408 o Claim Description: Subject 409 o JWT Claim Name: "sub" 410 o CBOR Key Value: 2 411 o CBOR Major Type: 3 412 o Change Controller: IESG 413 o Specification Document(s): Section 3.1.2 of [[ this specification 414 ]] 416 o Claim Name: "aud" 417 o Claim Description: Audience 418 o JWT Claim Name: "aud" 419 o CBOR Key Value: 3 420 o CBOR Major Type: 3 421 o Change Controller: IESG 422 o Specification Document(s): Section 3.1.3 of [[ this specification 423 ]] 425 o Claim Name: "exp" 426 o Claim Description: Expiration Time 427 o JWT Claim Name: "exp" 428 o CBOR Key Value: 4 429 o CBOR Major Type: 6, tag value 1 430 o Change Controller: IESG 431 o Specification Document(s): Section 3.1.4 of [[ this specification 432 ]] 434 o Claim Name: "nbf" 435 o Claim Description: Not Before 436 o JWT Claim Name: "nbf" 437 o CBOR Key Value: 5 438 o CBOR Major Type: 6, tag value 1 439 o Change Controller: IESG 440 o Specification Document(s): Section 3.1.5 of [[ this specification 441 ]] 443 o Claim Name: "iat" 444 o Claim Description: Issued At 445 o JWT Claim Name: "iat" 446 o CBOR Key Value: 6 447 o CBOR Major Type: 6, tag value 1 448 o Change Controller: IESG 449 o Specification Document(s): Section 3.1.6 of [[ this specification 450 ]] 452 o Claim Name: "cti" 453 o Claim Description: CWT ID 454 o JWT Claim Name: "jti" 455 o CBOR Key Value: 7 456 o CBOR Major Type: 2 457 o Change Controller: IESG 458 o Specification Document(s): Section 3.1.7 of [[ this specification 459 ]] 461 7.2. Media Type Registration 463 This section registers the "application/cwt" media type [RFC2046] in 464 the "Media Types" registry [IANA.MediaTypes] in the manner described 465 in RFC 6838 [RFC6838], which can be used to indicate that the content 466 is a CWT. 468 7.2.1. Registry Contents 470 o Type name: application 471 o Subtype name: cwt 472 o Required parameters: N/A 473 o Optional parameters: N/A 474 o Encoding considerations: binary 475 o Security considerations: See the Security Considerations section 476 of [[ this specification ]] 477 o Interoperability considerations: N/A 478 o Published specification: [[ this specification ]] 479 o Applications that use this media type: IoT applications sending 480 security tokens over HTTP(S) and other transports. 481 o Fragment identifier considerations: N/A 482 o Additional information: 484 Magic number(s): N/A 485 File extension(s): N/A 486 Macintosh file type code(s): N/A 488 o Person & email address to contact for further information: 489 IESG, iesg@ietf.org 490 o Intended usage: COMMON 491 o Restrictions on usage: none 492 o Author: Michael B. Jones, mbj@microsoft.com 493 o Change controller: IESG 494 o Provisional registration? No 496 7.3. CoAP Content-Formats Registration 498 This section registers the CoAP Content-Format ID for the 499 "application/cwt" media type in the "CoAP Content-Formats" registry 500 [IANA.CoAP.Content-Formats] established by [RFC7252]. 502 7.3.1. Registry Contents 504 o Media Type: application/cwt 505 o Encoding: - 506 o Id: TBD (maybe 61) 507 o Reference: [[ this specification ]] 509 8. References 511 8.1. Normative References 513 [I-D.ietf-cose-msg] 514 Schaad, J., "CBOR Object Signing and Encryption (COSE)", 515 draft-ietf-cose-msg-24 (work in progress), November 2016. 517 [IANA.CoAP.Content-Formats] 518 IANA, "CoAP Content-Formats", 519 . 522 [IANA.JWT.Claims] 523 IANA, "JSON Web Token Claims", 524 . 526 [IANA.MediaTypes] 527 IANA, "Media Types", 528 . 530 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 531 Extensions (MIME) Part Two: Media Types", RFC 2046, 532 DOI 10.17487/RFC2046, November 1996, 533 . 535 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 536 Requirement Levels", BCP 14, RFC 2119, 537 DOI 10.17487/RFC2119, March 1997, 538 . 540 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 541 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 542 DOI 10.17487/RFC5226, May 2008, 543 . 545 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 546 Specifications and Registration Procedures", BCP 13, 547 RFC 6838, DOI 10.17487/RFC6838, January 2013, 548 . 550 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 551 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 552 October 2013, . 554 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 555 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 556 2014, . 558 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 559 Application Protocol (CoAP)", RFC 7252, 560 DOI 10.17487/RFC7252, June 2014, 561 . 563 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 564 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 565 2015, . 567 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 568 RFC 7516, DOI 10.17487/RFC7516, May 2015, 569 . 571 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 572 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 573 . 575 8.2. Informative References 577 [I-D.seitz-ace-oauth-authz] 578 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 579 H. Tschofenig, "Authorization for the Internet of Things 580 using OAuth 2.0", draft-seitz-ace-oauth-authz-00 (work in 581 progress), October 2015. 583 Appendix A. Examples 585 Three examples of CWTs follow. 587 A.1. CWT with "aud" and symmetric key 589 A CWT used in the context of ACE requires at least the "aud" and a 590 "cks" claim (defined elsewhere). This means that "iss", "alg", 591 "key_ops" and others are pre-established and assumed. This would 592 look like this non-normative JSON. 594 { 595 "aud":"coap://light.example.com", 596 "cks": 597 [ // COSE_Key is a CBOR map with an array of keys 598 { 599 "kty":4, // symmetric key is indicated using kty 4 600 "k": "loremipsum" // the symmetric key 601 } 602 ] 603 } 605 Figure 2: "aud" claim and symmetric key in non-normative JSON 607 Using the CBOR encoded claim keys according to Section 4 and COSE 608 [I-D.ietf-cose-msg] makes a CWT with "aud" and a symmetric key look 609 like this in CBOR diagnostic notation: 611 { 612 3: "coap://light.example.com", 613 8: 614 [ 615 { 616 1: 4, 617 -1: "loremipsum" 618 } 619 ] 620 } 622 Figure 3: CWT 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 a2 # map(2) 633 01 # unsigned(1) 634 04 # unsigned(4) 635 20 # negative(0) 636 6a # text(10) 637 6c6f72656d697073756d # "loremipsum" 639 Figure 4: CWT with "aud" and symmetric key in CBOR 641 Size of the CWT with a symmetric key of 10 bytes is 45 bytes. This 642 is then packaged signed and encrypted using COSE. 644 A.2. CWT with "aud" and EC key 646 Token with "aud" set to "coap://light.example.com" and an EC key with 647 "kid" set to "11". 649 { 650 "aud": "coap://light.example.com", 651 "cks": 652 [ // COSE_Key is a CBOR map with an array of keys 653 { 654 "kty": "EC", 655 "kid": "11", 656 "crv": 1, // using P-384 657 "x": h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff', 658 "y": h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e' 659 } 660 ] 661 } 663 Figure 5: "aud" claim and EC key in non-normative JSON 665 Using the CBOR encoded claim keys according to Section 4 and COSE 666 [I-D.ietf-cose-msg] makes a CWT with "aud" and an EC key look like 667 this in CBOR diagnostic notation: 669 { 670 3: "coap://light.example.com", 671 8: 672 [ 673 { 674 1: 2, 675 2: "11", 676 -1: 1, 677 -2: h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff', 678 -3: h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e' 679 } 680 ] 681 } 683 Figure 6: CWT with EC key in CBOR diagnostic notation 685 Defined in CBOR. 687 a2 # map(2) 688 03 # unsigned(3) 689 78 18 # text(24) 690 636f61703a2f2f6c696768742e6578616d706c652e636f6d # "coap://light.example.com" 691 08 # unsigned(8) 692 81 # array(1) 693 a5 # map(5) 694 01 # unsigned(1) 695 02 # unsigned(2) 696 02 # unsigned(2) 697 62 # text(2) 698 3131 # "11" 699 20 # negative(0) 700 01 # unsigned(1) 701 21 # negative(1) 702 58 20 # bytes(32) 703 bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff # "\xBA\xC5\xB1\x1C\xAD\x8F\x99\xF9\xC7+\x05\xCFK\x9E&\xD2D\xDC\x18\x9FtR(%Z!\x9A\x86\xD6\xA0\x9E\xFF" 704 22 # negative(2) 705 58 20 # bytes(32) 706 20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e # "\x13\x8B\xF8-\xC1\xB6\xD5b\xBE\x0F\xA5J\xB7\x80J:d\xB6\xD7,\xCF\xEDko\xB6\xED(\xBB\xFC\x11~" 708 Figure 7: CWT with EC in CBOR 710 Size of the CWT with an EC key is 109 bytes. This is then packaged 711 signed and encrypted using COSE. 713 A.3. Full CWT 715 CWT using all claims defined by this specification, plus extensions 716 for AIF and an EC key. 718 { 719 "iss": "coap://as.example.com", 720 "aud": "coap://light.example.com", 721 "sub": "erikw", 722 "exp": 1444064944, 723 "nbf": 1443944944, 724 "iat": 1443944944, 725 "cti": 2929, 726 "cks": 727 [ // COSE_Key is a CBOR map with an array of keys 728 { 729 "kty": "EC", 730 "kid": "11", 731 "crv": 1, // using P-384 732 "x": h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff', 733 "y": h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e' 734 } 735 ], 736 "aif": [["/s/light", 1], ["/a/led", 5], ["/dtls", 2]] 737 } 739 Figure 8: All claims, "aif" and EC key in non-normative JSON 741 Using the CBOR encoded claim keys according to Section 4 and COSE 742 [I-D.ietf-cose-msg] makes a full CWT look like this in CBOR 743 diagnostic notation: 745 { 746 1: "coap://as.example.com", 747 3: "coap://light.example.com", 748 2: "erikw", 749 4: 1(1444064944), 750 5: 1(1443944944), 751 6: 1(1443944944), 752 7: 2929, 753 8: [ 754 { 755 1: 2, 756 2: "11", 757 -1: 1, 758 -2: h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff', 759 -3: h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e' 760 } 761 ], 762 9: [["/s/light", 1], ["/a/led", 5], ["/dtls", 2]] 763 } 765 Figure 9: Full CWT with EC key in CBOR diagnostic notation 767 Defined in CBOR. 769 a9 # map(9) 770 01 # unsigned(1) 771 75 # text(21) 772 636f61703a2f2f61732e6578616d706c652e636f6d # "coap://as.example.com" 773 03 # unsigned(3) 774 78 18 # text(24) 775 636f61703a2f2f6c696768742e6578616d706c652e636f6d # "coap://light.example.com" 776 02 # unsigned(2) 777 65 # text(5) 778 6572696b77 # "erikw" 779 04 # unsigned(4) 780 c1 # tag(1) 781 1a 5612aeb0 # unsigned(1444064944) 782 05 # unsigned(5) 783 c1 # tag(1) 784 1a 5610d9f0 # unsigned(1443944944) 785 06 # unsigned(6) 786 c1 # tag(1) 787 1a 5610d9f0 # unsigned(1443944944) 788 07 # unsigned(7) 789 19 0b71 # unsigned(2929) 790 08 # unsigned(8) 791 81 # array(1) 792 a5 # map(5) 793 01 # unsigned(1) 794 02 # unsigned(2) 795 02 # unsigned(2) 796 62 # text(2) 797 3131 # "11" 798 20 # negative(0) 799 01 # unsigned(1) 800 21 # negative(1) 801 58 20 # bytes(32) 802 bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff # "\xBA\xC5\xB1\x1C\xAD\x8F\x99\xF9\xC7+\x05\xCFK\x9E&\xD2D\xDC\x18\x9FtR(%Z!\x9A\x86\xD6\xA0\x9E\xFF" 803 22 # negative(2) 804 58 20 # bytes(32) 805 20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e # "\x13\x8B\xF8-\xC1\xB6\xD5b\xBE\x0F\xA5J\xB7\x80J:d\xB6\xD7,\xCF\xEDko\xB6\xED(\xBB\xFC\x11~" 806 09 # unsigned(9) 807 83 # array(3) 808 82 # array(2) 809 68 # text(8) 810 2f732f6c69676874 # "/s/light" 811 01 # unsigned(1) 812 82 # array(2) 813 66 # text(6) 814 2f612f6c6564 # "/a/led" 815 05 # unsigned(5) 816 82 # array(2) 817 65 # text(5) 818 2f64746c73 # "/dtls" 819 02 # unsigned(2) 821 Figure 10: Full CWT with EC in CBOR 823 Size of the CWT with an EC key is 194 bytes. This is then packaged 824 signed and encrypted using COSE. 826 Appendix B. Acknowledgements 828 This specification is based on JSON Web Token (JWT) [RFC7519], the 829 authors of which also include Nat Sakimura and John Bradley. A straw 830 man proposal of CWT was written in the draft "Authorization for the 831 Internet of Things using OAuth 2.0" [I-D.seitz-ace-oauth-authz] with 832 the help of Ludwig Seitz and Goeran Selander. 834 Appendix C. Document History 836 [[ to be removed by the RFC Editor before publication as an RFC ]] 838 -02 840 o Added IANA registration for the application/cwt media type. 841 o Clarified the nested CWT language. 842 o Corrected nits identified by Ludwig Seitz. 844 -01 846 o Added IANA registration for CWT Claims. 847 o Added IANA registration for the application/cwt CoAP content- 848 format type. 849 o Added Samuel Erdtman as an editor. 850 o Changed Erik's e-mail address. 852 -00 854 o Created the initial working group version based on draft- 855 wahlstroem-ace-cbor-web-token-00. 857 Authors' Addresses 859 Michael B. Jones 860 Microsoft 862 Email: mbj@microsoft.com 863 URI: http://self-issued.info/ 865 Erik Wahlstroem 866 Sweden 868 Email: erik@wahlstromstekniska.se 870 Samuel Erdtman 871 Spotify AB 872 Birger Jarlsgatan 61, 4tr 873 Stockholm 113 56 874 Sweden 876 Phone: +46702691499 877 Email: erdtman@spotify.com 878 Hannes Tschofenig 879 ARM Ltd. 880 Hall in Tirol 6060 881 Austria 883 Email: Hannes.Tschofenig@arm.com