idnits 2.17.1 draft-ietf-jose-jws-signing-input-options-07.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 13, 2015) is 3050 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 13, 2015 5 Intended status: Standards Track 6 Expires: June 15, 2016 8 JWS Unencoded Payload Option 9 draft-ietf-jose-jws-signing-input-options-07 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 15, 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. Intended Use by Applications . . . . . . . . . . . . . . . . . 8 74 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 75 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 76 8.1. JWS and JWE Header Parameter Registration . . . . . . . . 9 77 8.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 9 78 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 79 9.1. Normative References . . . . . . . . . . . . . . . . . . . 10 80 9.2. Informative References . . . . . . . . . . . . . . . . . . 11 81 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11 82 Appendix B. Document History . . . . . . . . . . . . . . . . . . 11 83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13 85 1. Introduction 87 The "JSON Web Signature (JWS)" [JWS] specification defines the JWS 88 Signing Input as the input to the digital signature or MAC 89 computation, with the value ASCII(BASE64URL(UTF8(JWS Protected 90 Header)) || '.' || BASE64URL(JWS Payload)). While this works well in 91 practice for many use cases, including those accommodating arbitrary 92 payload values, other use cases have been described in which 93 base64url-encoding the payload is unnecessary and/or an impediment to 94 adoption, particularly when the payload is large and/or detached. 96 This specification introduces a new JWS Header Parameter value that 97 generalizes the JWS Signing Input computation in a manner that makes 98 base64url-encoding the payload selectable and optional. The primary 99 set of use cases where this enhancement may be helpful are those in 100 which the payload may be very large and where means are already in 101 place to enable the payload to be communicated between the parties 102 without modifications. Appendix F of [JWS] describes how to 103 represent JWSs with detached content, which would typically be used 104 for these use cases. 106 The advantages of not having to base64url-encode a large payload are 107 that allocation of the additional storage to hold the base64url- 108 encoded form is avoided and the base64url-encoding computation never 109 has to be performed. In summary, this option can help avoid 110 unnecessary copying and transformations of the potentially large 111 payload, resulting in sometimes significant space and time 112 improvements for deployments. 114 1.1. Notational Conventions 116 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 117 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 118 "OPTIONAL" in this document are to be interpreted as described in 119 "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. 120 The interpretation should only be applied when the terms appear in 121 all capital letters. 123 BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per 124 Section 2 of [JWS]. 126 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 127 of STRING, where STRING is a sequence of zero or more Unicode 128 [UNICODE] characters. 130 ASCII(STRING) denotes the octets of the ASCII [RFC20] representation 131 of STRING, where STRING is a sequence of zero or more ASCII 132 characters. 134 The concatenation of two values A and B is denoted as A || B. 136 2. Terminology 138 This specification uses the same terminology as the "JSON Web 139 Signature (JWS)" [JWS] and "JSON Web Algorithms (JWA)" [JWA] 140 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 7 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. Intended Use by Applications 331 It is intended that application profiles specify up front whether 332 "b64" with a "false" value is to be used by the application in each 333 application context or not, with it then being consistently applied 334 in each application context. For instance, an application that uses 335 detached payloads might specify that "b64" with a "false" value 336 always be used. It is NOT RECOMMENDED that this parameter value be 337 dynamically varied with different payloads in the same application 338 context. 340 For interoperability reasons, JSON Web Tokens (JWTs) [JWT] MUST NOT 341 use "b64" with a "false" value. 343 7. Security Considerations 345 [JWS] base64url-encodes the JWS Payload to restrict the set of 346 characters used to represent it so that the representation does not 347 contain characters used for delimiters in JWS representations. Those 348 delimiters are the period ('.') character for the JWS Compact 349 Serialization and the double-quote ('"') character for the JWS JSON 350 Serialization. When the "b64" (base64url-encode payload) value is 351 "false", these properties are lost. It then becomes the 352 responsibility of the application to ensure that payloads only 353 contain characters that will not cause parsing problems for the 354 serialization used, as described in Section 5. The application also 355 incurs the responsibility to ensure that the payload will not be 356 modified during transmission. 358 Note that if a JWS is created with a "b64" value of "false" and is 359 received by an implementation not supporting the "b64" Header 360 Parameter, then the signature or MAC may still verify but the 361 recipient will believe that the intended JWS Payload value is the 362 base64url decoding of the payload value received, rather than the 363 payload value received itself. For example, if the payload value 364 received is "NDA1", an implementation not supporting this extension 365 will think that the intended payload is the base64url decoding of 366 this value, which is "405". 368 There are several ways for applications using this extension to 369 address this situation: 371 1. They can require that only JWS implementations that support this 372 extension be used. Then the potential confusion between encoded 373 and unencoded payload values cannot occur. This is necessary for 374 JWSs using this extension to be successfully used by any 375 application. 377 2. They can require the use of the "crit" Header Parameter with 378 "b64" in the set of values. Then any JWS using this extension 379 will be rejected by implementations not supporting this 380 extension. 382 3. They can always send unencoded payloads that contain characters 383 outside the set used for base64url-encoding (such as including a 384 '$' character), if this is reasonable for the application to do. 385 Then JWS implementations not understanding this extension will 386 reject the JWS because the attempt to base64url-decode the 387 payload value will fail. 389 Note that methods 2 and 3 are sufficient to cause JWSs using this 390 extension to be rejected by implementations not supporting this 391 extension but they are not sufficient to enable JWSs using this 392 extension to be successfully used by applications. Thus, method 1 - 393 requiring support for this extension - is the preferred approach and 394 the only means for this extension to be practically useful to 395 applications. Method 2 - requiring the use of "crit" - while 396 theoretically useful to ensure that confusion between encoded and 397 unencoded payloads cannot occur, is not particularly useful in 398 practice, since method 1 is still required for the extension to be 399 usable. When method 1 is employed, method 2 doesn't add any value 400 and since it increases the size of the JWS, its use is not required 401 by this specification. 403 8. IANA Considerations 405 8.1. JWS and JWE Header Parameter Registration 407 This specification registers the "b64" Header Parameter defined in 408 Section 3 in the IANA "JSON Web Signature and Encryption Header 409 Parameters" registry [IANA.JOSE] established by [JWS]. 411 8.1.1. Registry Contents 413 o Header Parameter Name: "b64" 414 o Header Parameter Description: Base64url-Encode Payload 415 o Header Parameter Usage Location(s): JWS 416 o Change Controller: IESG 417 o Specification Document(s): Section 3 of [[ this specification ]] 419 9. References 421 9.1. Normative References 423 [IANA.JOSE] 424 IANA, "JSON Object Signing and Encryption (JOSE)", 425 . 427 [JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 428 DOI 10.17487/RFC7518, May 2015, 429 . 431 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 432 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, 433 May 2015, . 435 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 436 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 437 . 439 [RFC20] Cerf, V., "ASCII format for Network Interchange", STD 80, 440 RFC 20, October 1969, 441 . 443 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 444 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 445 RFC2119, March 1997, 446 . 448 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 449 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, 450 November 2003, . 452 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 453 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, 454 March 2014, . 456 [UNICODE] The Unicode Consortium, "The Unicode Standard", 457 . 459 9.2. Informative References 461 [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/ 462 RFC7517, May 2015, 463 . 465 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 466 Resource Identifier (URI): Generic Syntax", STD 66, 467 RFC 3986, DOI 10.17487/RFC3986, January 2005, 468 . 470 Appendix A. Acknowledgements 472 Anders Rundgren, Richard Barnes, Phillip Hallam-Baker, Jim Schaad, 473 Matt Miller, Martin Thomson, and others have all made the case for 474 being able to use a representation of the payload that is not 475 base64url-encoded in contexts in which it safe to do so. 477 Thanks to Sergey Beryozkin, Benjamin Kaduk, James Manger, Kathleen 478 Moriarty, Axel Nennker, Anders Rundgren, Nat Sakimura, Jim Schaad, 479 Robert Sparks, and Matias Woloski for their reviews of the 480 specification and thanks to Vladimir Dzhuvinov for verifying the 481 examples. 483 Appendix B. Document History 485 [[ to be removed by the RFC editor before publication as an RFC ]] 487 -06 489 o Addressed Gen-Art review comments by Robert Sparks and Sec-Dir 490 review comments by Benjamin Kaduk. 492 -06 494 o Addressed review comments by Kathleen Moriarty. 496 -05 498 o Reworked the security considerations text on preventing confusion 499 between encoded and unencoded payloads. 501 -04 503 o Corrected a typo in the JWS JSON Serialization example. 505 o Added to the security considerations, including adding a statement 506 about when "crit" should be used. 508 o Addressed the document shepherd comments. 510 -03 512 o Allowed the ASCII space character and all printable ASCII 513 characters other than period ('.') in non-detached unencoded 514 payloads using the JWS Compact Serialization. 516 o Updated the abstract to say that that the spec updates RFC 7519. 518 o Removed unused references. 520 o Changed the change controller to IESG. 522 -02 524 o Required that "b64" be integrity protected. 526 o Stated that if the JWS has multiple signatures and/or MACs, the 527 "b64" Header Parameter value MUST be the same for all of them. 529 o Stated that if applications use content encoding, they MUST 530 specify whether the encoded or unencoded payload is used as the 531 JWS Payload value. 533 o Reorganized the Unencoded Payload Content Restrictions section. 535 o Added an "updates" clause for RFC 7519 because this specification 536 prohibits JWTs from using "b64":false. 538 -01 540 o Removed the "sph" (secure protected header) Header Parameter. 542 o Changed the title to "JWS Unencoded Payload Option". 544 o Added the section "Unencoded Payload Content Restrictions". 546 o Added an example using the JWS JSON Serialization. 548 -00 550 o Created the -00 JOSE working group draft from 551 draft-jones-jose-jws-signing-input-options-00 with no normative 552 changes. 554 Author's Address 556 Michael B. Jones 557 Microsoft 559 Email: mbj@microsoft.com 560 URI: http://self-issued.info/