idnits 2.17.1 draft-ietf-jose-jws-signing-input-options-04.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (November 11, 2015) is 3088 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 (~~), 2 warnings (==), 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) November 11, 2015 5 Intended status: Standards Track 6 Expires: May 14, 2016 8 JWS Unencoded Payload Option 9 draft-ietf-jose-jws-signing-input-options-04 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 this 25 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 May 14, 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 . . . . . . . . 10 77 8.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 10 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 . . . . . . . . . . . . . . . . . . . . . . . . . 12 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 specification are to be interpreted as described 119 in "Key words for use in RFCs to Indicate Requirement Levels" 120 [RFC2119]. The interpretation should only be applied when the terms 121 appear in 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 JSON Web Tokens (JWTs) [JWT] MUST NOT use "b64" with a "false" value. 342 7. Security Considerations 344 [JWS] base64url-encodes the JWS Payload to restrict the character set 345 used to represent it to characters that are distinct from the 346 delimiters that separate it from other JWS fields. Those delimiters 347 are the period ('.') character for the JWS Compact Serialization and 348 the double-quote ('"') character for the JWS JSON Serialization. 350 When the "b64" (base64url-encode payload) value is "false", these 351 properties are lost. It then becomes the responsibility of the 352 application to ensure that payloads only contain characters that will 353 not cause parsing problems for the serialization used, as described 354 in Section 5, and that the payload will not be modified during 355 transmission. 357 There is no security problem if a JWS correctly created using "b64" 358 with a "false" value is received by an implementation not supporting 359 the "b64" Header Parameter, since the signature will fail to verify 360 and the JWS will therefore be rejected. Likewise, there is no 361 security problem if a JWS is created by an implementation not 362 supporting this extension and received by an implementation 363 supporting it, since the JWS will not use the extension, meaning that 364 the security considerations are the same as for implementations 365 supporting only the functionality specified in [JWS]. 367 The only case in which care may need to be taken is when a JWS is 368 possibly being received by a JWS implementation not supporting this 369 extension and the party producing the JWS might be an attacker that 370 intentionally creates a JWS with a "b64" value of "false" but signs 371 it as if its value was "true". In this case, a JWS implementation 372 not supporting this extension will accept the JWS but treat it as if 373 the payload was encoded, rather than unencoded. 375 While this confused case may seem like a problem that could matter, 376 in fact, if the recipient trusts the creator of a JWS based on its 377 signature and therefore accepts and acts upon the content in the JWS, 378 yet the creator is an attacker, the recipient has much bigger 379 problems than confusion between whether the payload value is encoded 380 or unencoded. In this case, the attacker can sign any payload 381 whatsoever and have the recipient accept it -- including payloads 382 designed to cause harm to the recipient. If the trust established by 383 verifying the signer's key does not actually establish that the 384 creator is a trusted party, then this case in which JWS libraries 385 supporting and not supporting the extension may respectively 386 interpret the attacker's payload as being encoded or unencoded is the 387 least of the application's worries. This can only happen when the 388 trust placed in the creator of the JWS is unfounded. 390 The other relevant perspective on this case is that if an application 391 specifies that JWSs used by it are to be created using "b64" with a 392 "false" value, per Section 6, then correct implementations of that 393 application must use a JWS implementation that implements this 394 extension. Thus, even malicious JWS creators intentionally 395 incorrectly signing JWSs as if the "b64" value was "false" cannot 396 confuse the application as to whether the payload is encoded or 397 unencoded, since any incorrectly signed JWSs will be rejected due to 398 the bad signature. Only if the application is incorrectly 399 implemented and doesn't support this extension when the application 400 requires its use, is a problem possible. But then again, if the 401 application is incorrectly implemented, it likely has bigger problems 402 than confusion about whether the payload is encoded or not. 404 Only if the application dynamically switches between "false" and 405 "true" values for "b64" (something NOT RECOMMENDED in Section 6), 406 would it be necessary for the application to require the use of 407 "crit" with a value of "["b64"]" in such application contexts. That 408 would cause even incorrectly implemented application clients that do 409 not support the extension to nonetheless reject content signed using 410 "b64" with a "false" value. 412 8. IANA Considerations 413 8.1. JWS and JWE Header Parameter Registration 415 This specification registers the "b64" Header Parameter defined in 416 Section 3 in the IANA "JSON Web Signature and Encryption Header 417 Parameters" registry [IANA.JOSE] established by [JWS]. 419 8.1.1. Registry Contents 421 o Header Parameter Name: "b64" 422 o Header Parameter Description: Base64url-Encode Payload 423 o Header Parameter Usage Location(s): JWS 424 o Change Controller: IESG 425 o Specification Document(s): Section 3 of [[ this specification ]] 427 9. References 429 9.1. Normative References 431 [IANA.JOSE] 432 IANA, "JSON Object Signing and Encryption (JOSE)", 433 . 435 [JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 436 DOI 10.17487/RFC7518, May 2015, 437 . 439 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 440 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, 441 May 2015, . 443 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 444 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 445 . 447 [RFC20] Cerf, V., "ASCII format for Network Interchange", STD 80, 448 RFC 20, October 1969, 449 . 451 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 452 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 453 RFC2119, March 1997, 454 . 456 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 457 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, 458 November 2003, . 460 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 461 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, 462 March 2014, . 464 [UNICODE] The Unicode Consortium, "The Unicode Standard", 465 . 467 9.2. Informative References 469 [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/ 470 RFC7517, May 2015, 471 . 473 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 474 Resource Identifier (URI): Generic Syntax", STD 66, 475 RFC 3986, DOI 10.17487/RFC3986, January 2005, 476 . 478 Appendix A. Acknowledgements 480 Anders Rundgren, Richard Barnes, Phillip Hallam-Baker, Jim Schaad, 481 Matt Miller, Martin Thomson, and others have all made the case for 482 being able to use a representation of the payload that is not 483 base64url-encoded in contexts in which it safe to do so. 485 Thanks to Sergey Beryozkin, James Manger, Axel Nennker, Anders 486 Rundgren, Nat Sakimura, Jim Schaad, and Matias Woloski for their 487 reviews of the specification. 489 Appendix B. Document History 491 [[ to be removed by the RFC editor before publication as an RFC ]] 493 -04 495 o Corrected a typo in the JWS JSON Serialization example. 497 o Added to the security considerations, including adding a statement 498 about when "crit" should be used. 500 o Addressed the document shepherd comments. 502 -03 504 o Allowed the ASCII space character and all printable ASCII 505 characters other than period ('.') in non-detached unencoded 506 payloads using the JWS Compact Serialization. 508 o Updated the abstract to say that that the spec updates RFC 7519. 510 o Removed unused references. 512 o Changed the change controller to IESG. 514 -02 516 o Required that "b64" be integrity protected. 518 o Stated that if the JWS has multiple signatures and/or MACs, the 519 "b64" Header Parameter value MUST be the same for all of them. 521 o Stated that if applications use content encoding, they MUST 522 specify whether the encoded or unencoded payload is used as the 523 JWS Payload value. 525 o Reorganized the Unencoded Payload Content Restrictions section. 527 o Added an "updates" clause for RFC 7519 because this specification 528 prohibits JWTs from using "b64":false. 530 -01 532 o Removed the "sph" (secure protected header) Header Parameter. 534 o Changed the title to "JWS Unencoded Payload Option". 536 o Added the section "Unencoded Payload Content Restrictions". 538 o Added an example using the JWS JSON Serialization. 540 -00 542 o Created the -00 JOSE working group draft from 543 draft-jones-jose-jws-signing-input-options-00 with no normative 544 changes. 546 Author's Address 548 Michael B. Jones 549 Microsoft 551 Email: mbj@microsoft.com 552 URI: http://self-issued.info/