idnits 2.17.1 draft-ietf-jose-jws-signing-input-options-08.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 (December 16, 2015) is 3054 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) -- Looks like a reference, but probably isn't: '36' on line 179 -- Looks like a reference, but probably isn't: '46' on line 179 -- Looks like a reference, but probably isn't: '48' on line 179 -- Looks like a reference, but probably isn't: '50' on line 179 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE' Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Updates: 7519 (if approved) December 16, 2015 5 Intended status: Standards Track 6 Expires: June 18, 2016 8 JWS Unencoded Payload Option 9 draft-ietf-jose-jws-signing-input-options-08 11 Abstract 13 JSON Web Signature (JWS) represents the payload of a JWS as a 14 base64url encoded value and uses this value in the JWS Signature 15 computation. While this enables arbitrary payloads to be integrity 16 protected, some have described use cases in which the base64url 17 encoding is unnecessary and/or an impediment to adoption, especially 18 when the payload is large and/or detached. This specification 19 defines a means of accommodating these use cases by defining an 20 option to change the JWS Signing Input computation to not base64url- 21 encode the payload. This option is intended to broaden the set of 22 use cases for which the use of JWS is a good fit. 24 This specification updates RFC 7519 by prohibiting the use of the 25 unencoded payload option in JSON Web Tokens (JWTs). 27 Status of this Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on June 18, 2016. 44 Copyright Notice 46 Copyright (c) 2015 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 3. The "b64" Header Parameter . . . . . . . . . . . . . . . . . . 4 65 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 4.1. Example with Header Parameters {"alg":"HS256"} . . . . . . 5 67 4.2. Example with Header Parameters 68 {"alg":"HS256","b64":false} . . . . . . . . . . . . . . . 6 69 5. Unencoded Payload Content Restrictions . . . . . . . . . . . . 6 70 5.1. Unencoded Detached Payload . . . . . . . . . . . . . . . . 7 71 5.2. Unencoded JWS Compact Serialization Payload . . . . . . . 7 72 5.3. Unencoded JWS JSON Serialization Payload . . . . . . . . . 7 73 6. Using "crit" with "b64" . . . . . . . . . . . . . . . . . . . 8 74 7. Intended Use by Applications . . . . . . . . . . . . . . . . . 8 75 8. Security Considerations . . . . . . . . . . . . . . . . . . . 8 76 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 77 9.1. JWS and JWE Header Parameter Registration . . . . . . . . 10 78 9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 10 79 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 80 10.1. Normative References . . . . . . . . . . . . . . . . . . . 10 81 10.2. Informative References . . . . . . . . . . . . . . . . . . 11 82 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11 83 Appendix B. Document History . . . . . . . . . . . . . . . . . . 11 84 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13 86 1. Introduction 88 The "JSON Web Signature (JWS)" [JWS] specification defines the JWS 89 Signing Input as the input to the digital signature or MAC 90 computation, with the value ASCII(BASE64URL(UTF8(JWS Protected 91 Header)) || '.' || BASE64URL(JWS Payload)). While this works well in 92 practice for many use cases, including those accommodating arbitrary 93 payload values, other use cases have been described in which 94 base64url-encoding the payload is unnecessary and/or an impediment to 95 adoption, particularly when the payload is large and/or detached. 97 This specification introduces a new JWS Header Parameter value that 98 generalizes the JWS Signing Input computation in a manner that makes 99 base64url-encoding the payload selectable and optional. The primary 100 set of use cases where this enhancement may be helpful are those in 101 which the payload may be very large and where means are already in 102 place to enable the payload to be communicated between the parties 103 without modifications. Appendix F of [JWS] describes how to 104 represent JWSs with detached content, which would typically be used 105 for these use cases. 107 The advantages of not having to base64url-encode a large payload are 108 that allocation of the additional storage to hold the base64url- 109 encoded form is avoided and the base64url-encoding computation never 110 has to be performed. In summary, this option can help avoid 111 unnecessary copying and transformations of the potentially large 112 payload, resulting in sometimes significant space and time 113 improvements for deployments. 115 1.1. Notational Conventions 117 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 119 "OPTIONAL" in this document are to be interpreted as described in 120 "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. 121 The interpretation should only be applied when the terms appear in 122 all capital letters. 124 BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per 125 Section 2 of [JWS]. 127 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 128 of STRING, where STRING is a sequence of zero or more Unicode 129 [UNICODE] characters. 131 ASCII(STRING) denotes the octets of the ASCII [RFC20] representation 132 of STRING, where STRING is a sequence of zero or more ASCII 133 characters. 135 The concatenation of two values A and B is denoted as A || B. 137 2. Terminology 139 This specification uses the same terminology as the JSON Web 140 Signature [JWS] and JSON Web Algorithms [JWA] specifications. 142 3. The "b64" Header Parameter 144 This Header Parameter modifies the JWS Payload representation and the 145 JWS Signing Input computation in the following way: 147 b64 148 The "b64" (base64url-encode payload) Header Parameter determines 149 whether the payload is represented in the JWS and the JWS Signing 150 Input as ASCII(BASE64URL(JWS Payload)) or as the JWS Payload value 151 itself with no encoding performed. When the "b64" value is 152 "false", the payload is represented simply as the JWS Payload 153 value; otherwise, it is represented as ASCII(BASE64URL(JWS 154 Payload)). The "b64" value is a JSON boolean, with a default 155 value of "true". When used, this Header Parameter MUST be 156 integrity protected; therefore, it MUST occur only within the JWS 157 Protected Header. Use of this Header Parameter is OPTIONAL. If 158 the JWS has multiple signatures and/or MACs, the "b64" Header 159 Parameter value MUST be the same for all of them. Note that 160 unless the payload is detached, many payload values would cause 161 errors parsing the resulting JWSs, as described in Section 5. 163 The following table shows the JWS Signing Input computation, 164 depending upon the value of this parameter: 166 +-------+-----------------------------------------------------------+ 167 | "b64" | JWS Signing Input Formula | 168 +-------+-----------------------------------------------------------+ 169 | true | ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || | 170 | | BASE64URL(JWS Payload)) | 171 | false | ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.') || | 172 | | JWS Payload | 173 +-------+-----------------------------------------------------------+ 175 4. Examples 177 This section gives examples of JWSs showing the difference that using 178 the "b64" Header Parameter makes. The examples all use the JWS 179 Payload value [36, 46, 48, 50]. This octet sequence represents the 180 ASCII characters "$.02"; its base64url-encoded representation is 181 "JC4wMg". 183 The following table shows a set of Header Parameter values without 184 using a false "b64" Header Parameter value and a set using it, with 185 the resulting JWS Signing Input values represented as ASCII 186 characters: 188 +-----------------------------+-------------------------------------+ 189 | JWS Protected Header | JWS Signing Input Value | 190 +-----------------------------+-------------------------------------+ 191 | {"alg":"HS256"} | eyJhbGciOiJIUzI1NiJ9.JC4wMg | 192 | {"alg":"HS256","b64":false} | eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2V | 193 | | 9.$.02 | 194 +-----------------------------+-------------------------------------+ 196 These examples use the HMAC key from Appendix A.1 of [JWS], which is 197 represented below as a JWK [JWK] (with line breaks within values for 198 display purposes only): 200 { 201 "kty":"oct", 202 "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75 203 aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow" 204 } 206 The rest of this section shows complete representations for the two 207 JWSs above. 209 4.1. Example with Header Parameters {"alg":"HS256"} 211 The complete JWS representation for this example using the JWS 212 Compact Serialization and a non-detached payload (with line breaks 213 for display purposes only) is: 215 eyJhbGciOiJIUzI1NiJ9 216 . 217 JC4wMg 218 . 219 5mvfOroL-g7HyqJoozehmsaqmvTYGEq5jTI1gVvoEoQ 221 Note that this JWS uses only features defined by [JWS] and does not 222 use the new "b64" Header Parameter. It is the "control", so that 223 differences when it is used can be easily seen. 225 The equivalent representation for this example using the flattened 226 JWS JSON Serialization is: 228 { 229 "protected": 230 "eyJhbGciOiJIUzI1NiJ9", 231 "payload": 232 "JC4wMg", 233 "signature": 234 "5mvfOroL-g7HyqJoozehmsaqmvTYGEq5jTI1gVvoEoQ" 235 } 237 4.2. Example with Header Parameters {"alg":"HS256","b64":false} 239 The complete JWS representation for this example using the JWS 240 Compact Serialization and a detached payload (with line breaks for 241 display purposes only) is: 243 eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2V9 244 . 245 . 246 GsyM6AQJbQHY8aQKCbZSPJHzMRWo3HKIlcDuXof7nqs 248 Note that the payload "$.02" cannot be represented in this JWS in its 249 unencoded form because it contains a period ('.') character, which 250 would cause parsing problems. This JWS is therefore shown with a 251 detached payload. 253 The complete JWS representation for this example using the flattened 254 JWS JSON Serialization and a non-detached payload is: 256 { 257 "protected": 258 "eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2V9", 259 "payload": 260 "$.02", 261 "signature": 262 "GsyM6AQJbQHY8aQKCbZSPJHzMRWo3HKIlcDuXof7nqs" 263 } 265 If using a detached payload with the JWS JSON Serialization, the 266 "payload" element would be omitted. 268 5. Unencoded Payload Content Restrictions 270 When the "b64" value is "false", different restrictions on the 271 payload contents apply, depending upon the circumstances, as 272 described in this section. The restrictions prevent the use of 273 payload values that would cause errors parsing the resulting JWSs. 275 Note that because the character sets that can be used for unencoded 276 non-detached payloads differ between the two serializations, some 277 JWSs using a "b64" value of "false" cannot be syntactically converted 278 between the JWS JSON Serialization and the JWS Compact Serialization. 279 See Section 8 for security considerations on using unencoded 280 payloads. 282 5.1. Unencoded Detached Payload 284 Appendix F of [JWS] describes how to represent JWSs with detached 285 content. A detached payload can contain any octet sequence 286 representable by the application. The payload value will not cause 287 problems parsing the JWS, since it is not represented as part of the 288 JWS. If an application uses a content encoding when representing the 289 payload, then it MUST specify whether the signature or MAC is 290 performed over the content-encoded representation or over the 291 unencoded content. 293 5.2. Unencoded JWS Compact Serialization Payload 295 When using the JWS Compact Serialization, unencoded non-detached 296 payloads using period ('.') characters would cause parsing errors; 297 such payloads MUST NOT be used with the JWS Compact Serialization. 298 Similarly, if a JWS using the JWS Compact Serialization and a non- 299 detached payload is to be transmitted in a context that requires URL 300 safe characters, then the application MUST ensure that the payload 301 contains only the URL-safe characters 'a'-'z', 'A'-'Z', '0'-'9', dash 302 ('-'), underscore ('_'), and tilde ('~'). The payload value is the 303 ASCII representation of the characters in the payload string. The 304 ASCII space character and all printable ASCII characters other than 305 period ('.') (those characters in the ranges %x20-2D and %x2F-7E) MAY 306 be included in a non-detached payload using the JWS Compact 307 Serialization, provided that the application can transmit the 308 resulting JWS without modification. 310 No meaning or special semantics are attached to any characters in the 311 payload. For instance, the percent ('%') character represents 312 itself, and is not used by JWS objects for percent-encoding 313 [RFC3986]. Applications, of course, are free to utilize content 314 encoding rules of their choosing, provided that the encoded 315 representations utilize only allowed payload characters. 317 5.3. Unencoded JWS JSON Serialization Payload 319 When using the JWS JSON Serialization, unencoded non-detached 320 payloads must consist of the octets of the UTF-8 encoding of a 321 sequence of Unicode code points that are representable in a JSON 322 string. The payload value is determined after performing any JSON 323 string escape processing, per Section 8.3 of RFC 7159 [RFC7159], and 324 then UTF-8-encoding the resulting Unicode code points. This means, 325 for instance, that these payloads represented as JSON strings are 326 equivalent ("$.02", "\u0024.02"). Unassigned Unicode code point 327 values MUST NOT be used to represent the payload. 329 6. Using "crit" with "b64" 331 If a JWS using "b64" with a value of "false" might be processed by 332 implementations not implementing this extension, then the "crit" 333 Header Parameter MUST be included with "b64" in its set of values to 334 cause such implementations to reject the JWS. Conversely, if used in 335 environments in which all participants implement this extension, then 336 "crit" need not be included, since its inclusion would have no 337 effect, other than increasing the JWS size and processing costs. 339 7. Intended Use by Applications 341 It is intended that application profiles specify up front whether 342 "b64" with a "false" value is to be used by the application in each 343 application context or not, with it then being consistently applied 344 in each application context. For instance, an application that uses 345 detached payloads might specify that "b64" with a "false" value 346 always be used. It is NOT RECOMMENDED that this parameter value be 347 dynamically varied with different payloads in the same application 348 context. 350 While it is legal to use "b64" with a "true" value, it is RECOMMENDED 351 that "b64" simply be omitted in this case, since it would be 352 selecting the behavior already specified in [JWS]. 354 For interoperability reasons, JSON Web Tokens [JWT] MUST NOT use 355 "b64" with a "false" value. 357 8. Security Considerations 359 [JWS] base64url-encodes the JWS Payload to restrict the set of 360 characters used to represent it so that the representation does not 361 contain characters used for delimiters in JWS representations. Those 362 delimiters are the period ('.') character for the JWS Compact 363 Serialization and the double-quote ('"') character for the JWS JSON 364 Serialization. When the "b64" (base64url-encode payload) value is 365 "false", these properties are lost. It then becomes the 366 responsibility of the application to ensure that payloads only 367 contain characters that will not cause parsing problems for the 368 serialization used, as described in Section 5. The application also 369 incurs the responsibility to ensure that the payload will not be 370 modified during transmission. 372 Note that if a JWS is created with a "b64" value of "false" and is 373 received by an implementation not supporting the "b64" Header 374 Parameter, then the signature or MAC may still verify but the 375 recipient will believe that the intended JWS Payload value is the 376 base64url decoding of the payload value received, rather than the 377 payload value received itself. For example, if the payload value 378 received is "NDA1", an implementation not supporting this extension 379 will think that the intended payload is the base64url decoding of 380 this value, which is "405". 382 There are several ways for applications using this extension to 383 address this situation: 385 1. They can require that only JWS implementations that support this 386 extension be used. Then the potential confusion between encoded 387 and unencoded payload values cannot occur. This is already 388 necessary for JWSs using this extension to be successfully used 389 by applications, since otherwise they will be unable to obtain 390 the payload values. 392 2. They can require the use of the "crit" Header Parameter with 393 "b64" in the set of values. Then any JWS using this extension 394 will be rejected by implementations not supporting this 395 extension. Note that including "crit" does not enable 396 applications not implementing "b64" to obtain the payload value. 398 3. They can always send unencoded payloads that contain characters 399 outside the set used for base64url-encoding (such as including a 400 '$' character), if this is reasonable for the application to do. 401 Then JWS implementations not understanding this extension will 402 reject the JWS because the attempt to base64url-decode the 403 payload value will fail. 405 Note that methods 2 and 3 are sufficient to cause JWSs using this 406 extension to be rejected by implementations not supporting this 407 extension but they are not sufficient to enable JWSs using this 408 extension to be successfully used by applications. Thus, method 1 - 409 requiring support for this extension - is the preferred approach and 410 the only means for this extension to be practically useful to 411 applications. Method 2 - requiring the use of "crit" - while 412 theoretically useful to ensure that confusion between encoded and 413 unencoded payloads cannot occur, is not particularly useful in 414 practice, since method 1 is still required for the extension to be 415 usable. When method 1 is employed, method 2 doesn't add any value 416 and since it increases the size of the JWS, its use is not required 417 by this specification. 419 9. IANA Considerations 421 9.1. JWS and JWE Header Parameter Registration 423 This specification registers the "b64" Header Parameter defined in 424 Section 3 in the IANA "JSON Web Signature and Encryption Header 425 Parameters" registry [IANA.JOSE] established by [JWS]. 427 9.1.1. Registry Contents 429 o Header Parameter Name: "b64" 430 o Header Parameter Description: Base64url-Encode Payload 431 o Header Parameter Usage Location(s): JWS 432 o Change Controller: IESG 433 o Specification Document(s): Section 3 of [[ this specification ]] 435 10. References 437 10.1. Normative References 439 [IANA.JOSE] 440 IANA, "JSON Object Signing and Encryption (JOSE)", 441 . 443 [JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 444 DOI 10.17487/RFC7518, May 2015, 445 . 447 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 448 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, 449 May 2015, . 451 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 452 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 453 . 455 [RFC20] Cerf, V., "ASCII format for Network Interchange", STD 80, 456 RFC 20, October 1969, 457 . 459 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 460 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 461 RFC2119, March 1997, 462 . 464 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 465 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, 466 November 2003, . 468 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 469 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, 470 March 2014, . 472 [UNICODE] The Unicode Consortium, "The Unicode Standard", 473 . 475 10.2. Informative References 477 [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/ 478 RFC7517, May 2015, 479 . 481 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 482 Resource Identifier (URI): Generic Syntax", STD 66, 483 RFC 3986, DOI 10.17487/RFC3986, January 2005, 484 . 486 Appendix A. Acknowledgements 488 Anders Rundgren, Richard Barnes, Phillip Hallam-Baker, Jim Schaad, 489 Matt Miller, Martin Thomson, and others have all made the case for 490 being able to use a representation of the payload that is not 491 base64url-encoded in contexts in which it safe to do so. 493 Thanks to Sergey Beryozkin, Benjamin Kaduk, James Manger, Kathleen 494 Moriarty, Axel Nennker, Anders Rundgren, Nat Sakimura, Jim Schaad, 495 Robert Sparks, and Matias Woloski for their reviews of the 496 specification and thanks to Vladimir Dzhuvinov for verifying the 497 examples. 499 Appendix B. Document History 501 [[ to be removed by the RFC editor before publication as an RFC ]] 503 -08 505 o Addressed Gen-Art review comments by Robert Sparks, Ops-Dir review 506 comments by Stefan Winter, and ballot comments by Benoit Claise. 508 -07 510 o Addressed Gen-Art review comments by Robert Sparks and Sec-Dir 511 review comments by Benjamin Kaduk. 513 -06 515 o Addressed review comments by Kathleen Moriarty. 517 -05 519 o Reworked the security considerations text on preventing confusion 520 between encoded and unencoded payloads. 522 -04 524 o Corrected a typo in the JWS JSON Serialization example. 526 o Added to the security considerations, including adding a statement 527 about when "crit" should be used. 529 o Addressed the document shepherd comments. 531 -03 533 o Allowed the ASCII space character and all printable ASCII 534 characters other than period ('.') in non-detached unencoded 535 payloads using the JWS Compact Serialization. 537 o Updated the abstract to say that that the spec updates RFC 7519. 539 o Removed unused references. 541 o Changed the change controller to IESG. 543 -02 545 o Required that "b64" be integrity protected. 547 o Stated that if the JWS has multiple signatures and/or MACs, the 548 "b64" Header Parameter value MUST be the same for all of them. 550 o Stated that if applications use content encoding, they MUST 551 specify whether the encoded or unencoded payload is used as the 552 JWS Payload value. 554 o Reorganized the Unencoded Payload Content Restrictions section. 556 o Added an "updates" clause for RFC 7519 because this specification 557 prohibits JWTs from using "b64":false. 559 -01 561 o Removed the "sph" (secure protected header) Header Parameter. 563 o Changed the title to "JWS Unencoded Payload Option". 565 o Added the section "Unencoded Payload Content Restrictions". 567 o Added an example using the JWS JSON Serialization. 569 -00 571 o Created the -00 JOSE working group draft from 572 draft-jones-jose-jws-signing-input-options-00 with no normative 573 changes. 575 Author's Address 577 Michael B. Jones 578 Microsoft 580 Email: mbj@microsoft.com 581 URI: http://self-issued.info/