idnits 2.17.1 draft-ietf-ace-cbor-web-token-00.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 (May 20, 2016) is 2898 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: '2' is defined on line 251, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7159 (ref. '2') (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7049 (ref. '6') (Obsoleted by RFC 8949) == Outdated reference: A later version (-24) exists of draft-ietf-cose-msg-12 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 E. Wahlstroem 3 Internet-Draft Nexus Technology 4 Intended status: Informational M. Jones 5 Expires: November 21, 2016 Microsoft 6 H. Tschofenig 7 ARM Ltd. 8 May 20, 2016 10 CBOR Web Token (CWT) 11 draft-ietf-ace-cbor-web-token-00 13 Abstract 15 CBOR Web Token (CWT) is a compact means of representing claims to be 16 transferred between two parties. CWT is a profile of the JSON Web 17 Token (JWT) that is optimized for constrained devices. The claims in 18 a CWT are encoded in the Concise Binary Object Representation (CBOR) 19 and CBOR Object Signing and Encryption (COSE) is used for added 20 application layer security protection. A claim is a piece of 21 information asserted about a subject and is represented as a name/ 22 value pair consisting of a claim name and a claim value. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on November 21, 2016. 41 Copyright Notice 43 Copyright (c) 2016 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3. Claims . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 3.1. Claim Names . . . . . . . . . . . . . . . . . . . . . . . 4 62 3.1.1. iss (Issuer) Claim . . . . . . . . . . . . . . . . . 4 63 3.1.2. sub (Subject) Claim . . . . . . . . . . . . . . . . . 4 64 3.1.3. aud (Audience) Claim . . . . . . . . . . . . . . . . 4 65 3.1.4. exp (Expiration Time) Claim . . . . . . . . . . . . . 4 66 3.1.5. nbf (Not Before) Claim . . . . . . . . . . . . . . . 4 67 3.1.6. iat (Issued At) Claim . . . . . . . . . . . . . . . . 5 68 3.1.7. cti (CWT ID) Claim . . . . . . . . . . . . . . . . . 5 69 4. Summary of the values, CBOR major types and encoded claim 70 keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 71 5. Security Considerations . . . . . . . . . . . . . . . . . . . 5 72 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 73 7. Normative References . . . . . . . . . . . . . . . . . . . . 6 74 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 6 75 A.1. CWT with "aud" and symmetric key . . . . . . . . . . . . 7 76 A.2. CWT with "aud" and EC key . . . . . . . . . . . . . . . . 8 77 A.3. Full CWT . . . . . . . . . . . . . . . . . . . . . . . . 10 78 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 12 79 Appendix C. Document History . . . . . . . . . . . . . . . . . . 12 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 82 1. Introduction 84 The JSON Web Token (JWT) [5] is a standardized security token format 85 that has found use in OAuth 2.0 and OpenID Connect deployments, among 86 other applications. JWT uses JSON Web Signatures (JWS) [3] and JSON 87 Web Encryption (JWE) [4] to secure the contents of the JWT, which is 88 a set of claims represented in JSON [5]. The use of JSON for 89 encoding information is popular for Web and native applications, but 90 it is considered inefficient for some Internet of Things (IoT) 91 systems that use low power radio technologies. 93 In this document an alternative encoding of claims is defined. 94 Instead of using JSON, as provided by JWTs, this specification uses 95 CBOR [6] and calls this new structure "CBOR Web Token (CWT)", which 96 is a compact means of representing secured claims to be transferred 97 between two parties. CWT is closely related to JWT. It references 98 the JWT claims and both its name and pronunciation are derived from 99 JWT. To protect the claims contained in CWTs, the CBOR Object 100 Signing and Encryption (COSE) [7] specification is used. 102 The suggested pronunciation of CWT is the same as the English word 103 "cot". 105 2. Terminology 107 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 108 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 109 "OPTIONAL" in this document are to be interpreted as described in 110 "Key words for use in RFCs to Indicate Requirement Levels" [1]. 112 This document reuses terminology from JWT [5] and COSE [7]. 114 Type3StringOrURI: 116 The "Type3StringOrURI" term has the same meaning, syntax, and 117 processing rules as the "StringOrUri" term defined in Section 2 of 118 JWT [5], except that Type3StringOrURI uses CBOR major type 3 119 instead of a JSON string value. 121 FIXME: Use tag 32 for URIs? 123 Type6NumericDate: 125 The "Type6NumericDate" term has the same meaning, syntax, and 126 processing rules as the "NumericDate" term defined in Section 2 of 127 JWT [5], except that Type6NumericDate uses CBOR major type 6, with 128 tag value 1, instead of a numeric JSON value. 130 CBOR encoded claim key: 132 The key used to identify a claim value. 134 3. Claims 136 The set of claims that a CWT must contain to be considered valid is 137 context dependent and is outside the scope of this specification. 138 Specific applications of CWTs will require implementations to 139 understand and process some claims in particular ways. However, in 140 the absence of such requirements, all claims that are not understood 141 by implementations MUST be ignored. 143 To keep CWTs as small as possible, the CBOR encoded claim keys are 144 represented using CBOR major type 0. Section 4 summaries all keys 145 used to identity the claims defined in this document. 147 3.1. Claim Names 149 None of the claims defined below are intended to be mandatory to use 150 or implement. They rather provide a starting point for a set of 151 useful, interoperable claims. Applications using CWTs should define 152 which specific claims they use and when they are required or 153 optional. 155 3.1.1. iss (Issuer) Claim 157 The "iss" (issuer) claim has the same meaning, syntax, and processing 158 rules as the "iss" claim defined in Section 4.1.1 of JWT [5], except 159 that the format MUST be a Type3StringOrURI. The CBOR encoded claim 160 key 1 MUST be used to identify this claim. 162 3.1.2. sub (Subject) Claim 164 The "sub" (subject) claim has the same meaning, syntax, and 165 processing rules as the "sub" claim defined in Section 4.1.2 of JWT 166 [5], except that the format MUST be a Type3StringOrURI. The CBOR 167 encoded claim key 2 MUST be used to identify this claim. 169 3.1.3. aud (Audience) Claim 171 The "aud" (audience) claim has the same meaning, syntax, and 172 processing rules as the "aud" claim defined in Section 4.1.3 of JWT 173 [5], except that the format MUST be a Type3StringOrURI. The CBOR 174 encoded claim key 3 MUST be used to identify this claim. 176 3.1.4. exp (Expiration Time) Claim 178 The "exp" (expiration time) claim has the same meaning, syntax, and 179 processing rules as the "exp" claim defined in Section 4.1.4 of JWT 180 [5], except that the format MUST be a Type6NumericDate. The CBOR 181 encoded claim key 4 MUST be used to identify this claim. 183 3.1.5. nbf (Not Before) Claim 185 The "nbf" (not before) claim has the same meaning, syntax, and 186 processing rules as the "nbf" claim defined in Section 4.1.5 of JWT 187 [5], except that the format MUST be a Type6NumericDate. The CBOR 188 encoded claim key 5 MUST be used to identify this claim. 190 3.1.6. iat (Issued At) Claim 192 The "iat" (issued at) claim has the same meaning, syntax, and 193 processing rules as the "iat" claim defined in Section 4.1.6 of JWT 194 [5], except that the format MUST be a Type6NumericDate. The CBOR 195 encoded claim key 6 MUST be used to identify this claim. 197 3.1.7. cti (CWT ID) Claim 199 The "cti" (CWT ID) claim has the same meaning, syntax, and processing 200 rules as the "jti" claim defined in Section 4.1.7 of JWT [5], except 201 that the format MUST be of major type 3 with a case-sensitive string 202 value. The CBOR encoded claim key 7 MUST be used to identify this 203 claim. 205 4. Summary of the values, CBOR major types and encoded claim keys 207 /---------+------------------------+--------------------------\ 208 | Claim | CBOR encoded claim key | CBOR major type of value | 209 |---------+------------------------+--------------------------| 210 | iss | 1 | 3 | 211 | sub | 2 | 3 | 212 | aud | 3 | 3 | 213 | exp | 4 | 6 tag value 1 | 214 | nbf | 5 | 6 tag value 1 | 215 | iat | 6 | 6 tag value 1 | 216 | cti | 7 | 3 | 217 \---------+------------------------+--------------------------/ 219 Figure 1: Summary of the values, CBOR major types and encoded claim 220 keys. 222 Note: Claims defined by the OpenID Foundation have not yet been 223 included in the table above. 225 5. Security Considerations 227 The security of the CWT is dependent on the protection offered by 228 COSE. Without protecting the claims contained in a CWT an adversary 229 is able to modify, add or remove claims. Since the claims conveyed 230 in a CWT are used to make authorization decisions it is not only 231 important to protect the CWT in transit but also to ensure that the 232 recipient is able to authenticate the party that collected the claims 233 and created the CWT. Without trust of the recipient in the party 234 that created the CWT no sensible authorization decision can be made. 235 Furthermore, the creator of the CWT needs to carefully evaluate each 236 claim value prior to including it in the CWT so that the recipient 237 can be assured about the correctness of the provided information. 239 6. IANA Considerations 241 This section will create a registry for CWT claims, possibly relating 242 them to the JWT Claims Registry. 244 7. Normative References 246 [1] Bradner, S., "Key words for use in RFCs to Indicate 247 Requirement Levels", BCP 14, RFC 2119, 248 DOI 10.17487/RFC2119, March 1997, 249 . 251 [2] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 252 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 253 2014, . 255 [3] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 256 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 257 2015, . 259 [4] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 260 RFC 7516, DOI 10.17487/RFC7516, May 2015, 261 . 263 [5] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 264 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 265 . 267 [6] Bormann, C. and P. Hoffman, "Concise Binary Object 268 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 269 October 2013, . 271 [7] Schaad, J., "CBOR Encoded Message Syntax", draft-ietf- 272 cose-msg-12 (work in progress), May 2016. 274 [8] Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 275 H. Tschofenig, "Authorization for the Internet of Things 276 using OAuth 2.0", draft-seitz-ace-oauth-authz-00 (work in 277 progress), October 2015. 279 Appendix A. Examples 281 Three examples of CWTs follow. 283 A.1. CWT with "aud" and symmetric key 285 A CWT used in the context of ACE requires at least the "aud" and a 286 "cks" claim (defined elsewhere). This means that "iss", "alg", 287 "key_ops" and others are pre-established and assumed. This would 288 look like this non-normative JSON. 290 { 291 "aud":"coap://light.example.com", 292 "cks": 293 [ // COSE_Key is a CBOR map with an array of keys 294 { 295 "kty":4, // symmetric key is indicated using kty 4 296 "k": "loremipsum" // the symmetric key 297 } 298 ] 299 } 301 Figure 2: "aud" claim and symmetric key in non-normative JSON 303 Using the CBOR encoded claim keys according to Section 4 and COSE [7] 304 makes a CWT with "aud" and a symmetric key look like this in CBOR 305 diagnostic notation: 307 { 308 3: "coap://light.example.com", 309 8: 310 [ 311 { 312 1: 4, 313 -1: "loremipsum" 314 } 315 ] 316 } 318 Figure 3: CWT in CBOR diagnostic notation 320 Defined in CBOR. 322 a2 # map(2) 323 03 # unsigned(3) 324 78 18 # text(24) 325 636f61703a2f2f6c696768742e6578616d706c652e636f6d # "coap://light.example.com" 326 08 # unsigned(8) 327 81 # array(1) 328 a2 # map(2) 329 01 # unsigned(1) 330 04 # unsigned(4) 331 20 # negative(0) 332 6a # text(10) 333 6c6f72656d697073756d # "loremipsum" 335 Figure 4: CWT with "aud" and symmetric key in CBOR 337 Size of the CWT with a symmetric key of 10 bytes is 45 bytes. This 338 is then packaged signed and encrypted using COSE. 340 A.2. CWT with "aud" and EC key 342 Token with "aud" set to "coap://light.example.com" and an EC key with 343 "kid" set to "11". 345 { 346 "aud": "coap://light.example.com", 347 "cks": 348 [ // COSE_Key is a CBOR map with an array of keys 349 { 350 "kty": "EC", 351 "kid": "11", 352 "crv": 1, // using P-384 353 "x": h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff', 354 "y": h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e' 355 } 356 ] 357 } 359 Figure 5: "aud" claim and EC key in non-normative JSON 361 Using the CBOR encoded claim keys according to Section 4 and COSE [7] 362 makes a CWT with "aud" and an EC key look like this in CBOR 363 diagnostic notation: 365 { 366 3: "coap://light.example.com", 367 8: 368 [ 369 { 370 1: 2, 371 2: "11", 372 -1: 1, 373 -2: h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff', 374 -3: h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e' 375 } 376 ] 377 } 379 Figure 6: CWT with EC key in CBOR diagnostic notation 381 Defined in CBOR. 383 a2 # map(2) 384 03 # unsigned(3) 385 78 18 # text(24) 386 636f61703a2f2f6c696768742e6578616d706c652e636f6d # "coap://light.example.com" 387 08 # unsigned(8) 388 81 # array(1) 389 a5 # map(5) 390 01 # unsigned(1) 391 02 # unsigned(2) 392 02 # unsigned(2) 393 62 # text(2) 394 3131 # "11" 395 20 # negative(0) 396 01 # unsigned(1) 397 21 # negative(1) 398 58 20 # bytes(32) 399 bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff # "\xBA\xC5\xB1\x1C\xAD\x8F\x99\xF9\xC7+\x05\xCFK\x9E&\xD2D\xDC\x18\x9FtR(%Z!\x9A\x86\xD6\xA0\x9E\xFF" 400 22 # negative(2) 401 58 20 # bytes(32) 402 20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e # "\x13\x8B\xF8-\xC1\xB6\xD5b\xBE\x0F\xA5J\xB7\x80J:d\xB6\xD7,\xCF\xEDko\xB6\xED(\xBB\xFC\x11~" 404 Figure 7: CWT with EC in CBOR 406 Size of the CWT with an EC key is 109 bytes. This is then packaged 407 signed and encrypted using COSE. 409 A.3. Full CWT 411 CWT using all claims defined by this specification, plus extensions 412 for AIF and an EC key. 414 { 415 "iss": "coap://as.example.com", 416 "aud": "coap://light.example.com", 417 "sub": "erikw", 418 "exp": 1444064944, 419 "nbf": 1443944944, 420 "iat": 1443944944, 421 "cti": 2929, 422 "cks": 423 [ // COSE_Key is a CBOR map with an array of keys 424 { 425 "kty": "EC", 426 "kid": "11", 427 "crv": 1, // using P-384 428 "x": h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff', 429 "y": h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e' 430 } 431 ], 432 "aif": [["/s/light", 1], ["/a/led", 5], ["/dtls", 2]] 433 } 435 Figure 8: All claims, "aif" and EC key in non-normative JSON 437 Using the CBOR encoded claim keys according to Section 4 and COSE [7] 438 makes a full CWT look like this in CBOR diagnostic notation: 440 { 441 1: "coap://as.example.com", 442 3: "coap://light.example.com", 443 2: "erikw", 444 4: 1(1444064944), 445 5: 1(1443944944), 446 6: 1(1443944944), 447 7: 2929, 448 8: [ 449 { 450 1: 2, 451 2: "11", 452 -1: 1, 453 -2: h'bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff', 454 -3: h'20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e' 455 } 456 ], 457 9: [["/s/light", 1], ["/a/led", 5], ["/dtls", 2]] 458 } 460 Figure 9: Full CWT with EC key in CBOR diagnostic notation 462 Defined in CBOR. 464 a9 # map(9) 465 01 # unsigned(1) 466 75 # text(21) 467 636f61703a2f2f61732e6578616d706c652e636f6d # "coap://as.example.com" 468 03 # unsigned(3) 469 78 18 # text(24) 470 636f61703a2f2f6c696768742e6578616d706c652e636f6d # "coap://light.example.com" 471 02 # unsigned(2) 472 65 # text(5) 473 6572696b77 # "erikw" 474 04 # unsigned(4) 475 c1 # tag(1) 476 1a 5612aeb0 # unsigned(1444064944) 477 05 # unsigned(5) 478 c1 # tag(1) 479 1a 5610d9f0 # unsigned(1443944944) 480 06 # unsigned(6) 481 c1 # tag(1) 482 1a 5610d9f0 # unsigned(1443944944) 483 07 # unsigned(7) 484 19 0b71 # unsigned(2929) 485 08 # unsigned(8) 486 81 # array(1) 487 a5 # map(5) 488 01 # unsigned(1) 489 02 # unsigned(2) 490 02 # unsigned(2) 491 62 # text(2) 492 3131 # "11" 493 20 # negative(0) 494 01 # unsigned(1) 495 21 # negative(1) 496 58 20 # bytes(32) 497 bac5b11cad8f99f9c72b05cf4b9e26d244dc189f745228255a219a86d6a09eff # "\xBA\xC5\xB1\x1C\xAD\x8F\x99\xF9\xC7+\x05\xCFK\x9E&\xD2D\xDC\x18\x9FtR(%Z!\x9A\x86\xD6\xA0\x9E\xFF" 498 22 # negative(2) 499 58 20 # bytes(32) 500 20138bf82dc1b6d562be0fa54ab7804a3a64b6d72ccfed6b6fb6ed28bbfc117e # "\x13\x8B\xF8-\xC1\xB6\xD5b\xBE\x0F\xA5J\xB7\x80J:d\xB6\xD7,\xCF\xEDko\xB6\xED(\xBB\xFC\x11~" 501 09 # unsigned(9) 502 83 # array(3) 503 82 # array(2) 504 68 # text(8) 505 2f732f6c69676874 # "/s/light" 506 01 # unsigned(1) 507 82 # array(2) 508 66 # text(6) 509 2f612f6c6564 # "/a/led" 510 05 # unsigned(5) 511 82 # array(2) 512 65 # text(5) 513 2f64746c73 # "/dtls" 514 02 # unsigned(2) 516 Figure 10: Full CWT with EC in CBOR 518 Size of the CWT with an EC key is 194 bytes. This is then packaged 519 signed and encrypted using COSE. 521 Appendix B. Acknowledgements 523 A straw man proposal of CWT was written in the draft "Authorization 524 for the Internet of Things using OAuth 2.0" [8] with the help of 525 Ludwig Seitz, Goeran Selander, and Samuel Erdtman. 527 Appendix C. Document History 529 [[ to be removed by the RFC Editor before publication as an RFC ]] 531 -00 532 o Created the initial working group version based on draft- 533 wahlstroem-ace-cbor-web-token-00. 535 Authors' Addresses 537 Erik Wahlstroem 538 Nexus Technology 539 Sweden 541 Email: erik.wahlstrom@nexusgroup.com 542 URI: https://www.nexusgroup.com 544 Michael B. Jones 545 Microsoft 547 Email: mbj@microsoft.com 548 URI: http://self-issued.info/ 550 Hannes Tschofenig 551 ARM Ltd. 552 Hall in Tirol 6060 553 Austria 555 Email: Hannes.Tschofenig@arm.com