idnits 2.17.00 (12 Aug 2021) /tmp/idnits3145/draft-ietf-jose-jws-signing-input-options-09.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 -- No information found for rfc7519 - is the name correct? -- The document date (December 23, 2015) is 2334 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 180 -- Looks like a reference, but probably isn't: '46' on line 180 -- Looks like a reference, but probably isn't: '48' on line 180 -- Looks like a reference, but probably isn't: '50' on line 180 ** Obsolete normative reference: RFC 7159 -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE' Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 7 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 23, 2015 5 Intended status: Standards Track 6 Expires: June 25, 2016 8 JWS Unencoded Payload Option 9 draft-ietf-jose-jws-signing-input-options-09 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 stating that JSON Web Tokens 25 (JWTs) MUST NOT use the unencoded payload option defined by this 26 specification. 28 Status of this Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on June 25, 2016. 45 Copyright Notice 47 Copyright (c) 2015 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 64 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 65 3. The "b64" Header Parameter . . . . . . . . . . . . . . . . . . 4 66 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 4.1. Example with Header Parameters {"alg":"HS256"} . . . . . . 5 68 4.2. Example with Header Parameters 69 {"alg":"HS256","b64":false,"crit":["b64"]} . . . . . . . . 6 70 5. Unencoded Payload Content Restrictions . . . . . . . . . . . . 6 71 5.1. Unencoded Detached Payload . . . . . . . . . . . . . . . . 7 72 5.2. Unencoded JWS Compact Serialization Payload . . . . . . . 7 73 5.3. Unencoded JWS JSON Serialization Payload . . . . . . . . . 7 74 6. Using "crit" with "b64" . . . . . . . . . . . . . . . . . . . 8 75 7. Intended Use by Applications . . . . . . . . . . . . . . . . . 8 76 8. Security Considerations . . . . . . . . . . . . . . . . . . . 8 77 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 78 9.1. JWS and JWE Header Parameter Registration . . . . . . . . 9 79 9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 9 80 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 81 10.1. Normative References . . . . . . . . . . . . . . . . . . . 9 82 10.2. Informative References . . . . . . . . . . . . . . . . . . 10 83 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10 84 Appendix B. Document History . . . . . . . . . . . . . . . . . . 11 85 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 87 1. Introduction 89 The "JSON Web Signature (JWS)" [JWS] specification defines the JWS 90 Signing Input as the input to the digital signature or MAC 91 computation, with the value ASCII(BASE64URL(UTF8(JWS Protected 92 Header)) || '.' || BASE64URL(JWS Payload)). While this works well in 93 practice for many use cases, including those accommodating arbitrary 94 payload values, other use cases have been described in which 95 base64url-encoding the payload is unnecessary and/or an impediment to 96 adoption, particularly when the payload is large and/or detached. 98 This specification introduces a new JWS Header Parameter value that 99 generalizes the JWS Signing Input computation in a manner that makes 100 base64url-encoding the payload selectable and optional. The primary 101 set of use cases where this enhancement may be helpful are those in 102 which the payload may be very large and where means are already in 103 place to enable the payload to be communicated between the parties 104 without modifications. Appendix F of [JWS] describes how to 105 represent JWSs with detached content, which would typically be used 106 for these use cases. 108 The advantages of not having to base64url-encode a large payload are 109 that allocation of the additional storage to hold the base64url- 110 encoded form is avoided and the base64url-encoding computation never 111 has to be performed. In summary, this option can help avoid 112 unnecessary copying and transformations of the potentially large 113 payload, resulting in sometimes significant space and time 114 improvements for deployments. 116 1.1. Notational Conventions 118 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 119 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 120 "OPTIONAL" in this document are to be interpreted as described in 121 "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. 122 The interpretation should only be applied when the terms appear in 123 all capital letters. 125 BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per 126 Section 2 of [JWS]. 128 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 129 of STRING, where STRING is a sequence of zero or more Unicode 130 [UNICODE] characters. 132 ASCII(STRING) denotes the octets of the ASCII [RFC20] representation 133 of STRING, where STRING is a sequence of zero or more ASCII 134 characters. 136 The concatenation of two values A and B is denoted as A || B. 138 2. Terminology 140 This specification uses the same terminology as the JSON Web 141 Signature [JWS] and JSON Web Algorithms [JWA] specifications. 143 3. The "b64" Header Parameter 145 This Header Parameter modifies the JWS Payload representation and the 146 JWS Signing Input computation in the following way: 148 b64 149 The "b64" (base64url-encode payload) Header Parameter determines 150 whether the payload is represented in the JWS and the JWS Signing 151 Input as ASCII(BASE64URL(JWS Payload)) or as the JWS Payload value 152 itself with no encoding performed. When the "b64" value is 153 "false", the payload is represented simply as the JWS Payload 154 value; otherwise, it is represented as ASCII(BASE64URL(JWS 155 Payload)). The "b64" value is a JSON boolean, with a default 156 value of "true". When used, this Header Parameter MUST be 157 integrity protected; therefore, it MUST occur only within the JWS 158 Protected Header. Use of this Header Parameter is OPTIONAL. If 159 the JWS has multiple signatures and/or MACs, the "b64" Header 160 Parameter value MUST be the same for all of them. Note that 161 unless the payload is detached, many payload values would cause 162 errors parsing the resulting JWSs, as described in Section 5. 164 The following table shows the JWS Signing Input computation, 165 depending upon the value of this parameter: 167 +-------+-----------------------------------------------------------+ 168 | "b64" | JWS Signing Input Formula | 169 +-------+-----------------------------------------------------------+ 170 | true | ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || | 171 | | BASE64URL(JWS Payload)) | 172 | false | ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.') || | 173 | | JWS Payload | 174 +-------+-----------------------------------------------------------+ 176 4. Examples 178 This section gives examples of JWSs showing the difference that using 179 the "b64" Header Parameter makes. The examples all use the JWS 180 Payload value [36, 46, 48, 50]. This octet sequence represents the 181 ASCII characters "$.02"; its base64url-encoded representation is 182 "JC4wMg". 184 The following table shows a set of Header Parameter values without 185 using a false "b64" Header Parameter value and a set using it, with 186 the resulting JWS Signing Input values represented as ASCII 187 characters: 189 +-----------------------------+-------------------------------------+ 190 | JWS Protected Header | JWS Signing Input Value | 191 +-----------------------------+-------------------------------------+ 192 | {"alg":"HS256"} | eyJhbGciOiJIUzI1NiJ9.JC4wMg | 193 | {"alg":"HS256","b64":false, | eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2U | 194 | "crit":["b64"]} | sImNyaXQiOlsiYjY0Il19.$.02 | 195 +-----------------------------+-------------------------------------+ 197 These examples use the HMAC key from Appendix A.1 of [JWS], which is 198 represented below as a JWK [JWK] (with line breaks within values for 199 display purposes only): 201 { 202 "kty":"oct", 203 "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75 204 aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow" 205 } 207 The rest of this section shows complete representations for the two 208 JWSs above. 210 4.1. Example with Header Parameters {"alg":"HS256"} 212 The complete JWS representation for this example using the JWS 213 Compact Serialization and a non-detached payload (with line breaks 214 for display purposes only) is: 216 eyJhbGciOiJIUzI1NiJ9 217 . 218 JC4wMg 219 . 220 5mvfOroL-g7HyqJoozehmsaqmvTYGEq5jTI1gVvoEoQ 222 Note that this JWS uses only features defined by [JWS] and does not 223 use the new "b64" Header Parameter. It is the "control", so that 224 differences when it is used can be easily seen. 226 The equivalent representation for this example using the flattened 227 JWS JSON Serialization is: 229 { 230 "protected": 231 "eyJhbGciOiJIUzI1NiJ9", 232 "payload": 233 "JC4wMg", 234 "signature": 235 "5mvfOroL-g7HyqJoozehmsaqmvTYGEq5jTI1gVvoEoQ" 236 } 238 4.2. Example with Header Parameters {"alg":"HS256","b64":false,"crit": 239 ["b64"]} 241 The complete JWS representation for this example using the JWS 242 Compact Serialization and a detached payload (with line breaks for 243 display purposes only) is: 245 eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19 246 . 247 . 248 A5dxf2s96_n5FLueVuW1Z_vh161FwXZC4YLPff6dmDY 250 Note that the payload "$.02" cannot be represented in this JWS in its 251 unencoded form because it contains a period ('.') character, which 252 would cause parsing problems. This JWS is therefore shown with a 253 detached payload. 255 The complete JWS representation for this example using the flattened 256 JWS JSON Serialization and a non-detached payload is: 258 { 259 "protected": 260 "eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19", 261 "payload": 262 "$.02", 263 "signature": 264 "A5dxf2s96_n5FLueVuW1Z_vh161FwXZC4YLPff6dmDY" 265 } 267 If using a detached payload with the JWS JSON Serialization, the 268 "payload" element would be omitted. 270 5. Unencoded Payload Content Restrictions 272 When the "b64" value is "false", different restrictions on the 273 payload contents apply, depending upon the circumstances, as 274 described in this section. The restrictions prevent the use of 275 payload values that would cause errors parsing the resulting JWSs. 277 Note that because the character sets that can be used for unencoded 278 non-detached payloads differ between the two serializations, some 279 JWSs using a "b64" value of "false" cannot be syntactically converted 280 between the JWS JSON Serialization and the JWS Compact Serialization. 281 See Section 8 for security considerations on using unencoded 282 payloads. 284 5.1. Unencoded Detached Payload 286 Appendix F of [JWS] describes how to represent JWSs with detached 287 content. A detached payload can contain any octet sequence 288 representable by the application. The payload value will not cause 289 problems parsing the JWS, since it is not represented as part of the 290 JWS. If an application uses a content encoding when representing the 291 payload, then it MUST specify whether the signature or MAC is 292 performed over the content-encoded representation or over the 293 unencoded content. 295 5.2. Unencoded JWS Compact Serialization Payload 297 When using the JWS Compact Serialization, unencoded non-detached 298 payloads using period ('.') characters would cause parsing errors; 299 such payloads MUST NOT be used with the JWS Compact Serialization. 300 Similarly, if a JWS using the JWS Compact Serialization and a non- 301 detached payload is to be transmitted in a context that requires URL 302 safe characters, then the application MUST ensure that the payload 303 contains only the URL-safe characters 'a'-'z', 'A'-'Z', '0'-'9', dash 304 ('-'), underscore ('_'), and tilde ('~'). The payload value is the 305 ASCII representation of the characters in the payload string. The 306 ASCII space character and all printable ASCII characters other than 307 period ('.') (those characters in the ranges %x20-2D and %x2F-7E) MAY 308 be included in a non-detached payload using the JWS Compact 309 Serialization, provided that the application can transmit the 310 resulting JWS without modification. 312 No meaning or special semantics are attached to any characters in the 313 payload. For instance, the percent ('%') character represents 314 itself, and is not used by JWS objects for percent-encoding 315 [RFC3986]. Applications, of course, are free to utilize content 316 encoding rules of their choosing, provided that the encoded 317 representations utilize only allowed payload characters. 319 5.3. Unencoded JWS JSON Serialization Payload 321 When using the JWS JSON Serialization, unencoded non-detached 322 payloads must consist of the octets of the UTF-8 encoding of a 323 sequence of Unicode code points that are representable in a JSON 324 string. The payload value is determined after performing any JSON 325 string escape processing, per Section 8.3 of RFC 7159 [RFC7159], and 326 then UTF-8-encoding the resulting Unicode code points. This means, 327 for instance, that these payloads represented as JSON strings are 328 equivalent ("$.02", "\u0024.02"). Unassigned Unicode code point 329 values MUST NOT be used to represent the payload. 331 6. Using "crit" with "b64" 333 The "crit" Header Parameter MUST be included with "b64" in its set of 334 values when using the "b64" Header Parameter to cause implementations 335 not implementing "b64" to reject the JWS (instead of it being 336 misinterpreted). 338 7. Intended Use by Applications 340 Application profiles should specify whether "b64" with a "false" 341 value is to be used by the application in each application context or 342 not, with it then being consistently applied in each application 343 context. For instance, an application that uses detached payloads 344 might specify that "b64" with a "false" value always be used. It is 345 NOT RECOMMENDED that this parameter value be dynamically varied with 346 different payloads in the same application context. 348 While it is legal to use "b64" with a "true" value, it is RECOMMENDED 349 that "b64" simply be omitted in this case, since it would be 350 selecting the behavior already specified in [JWS]. 352 For interoperability reasons, JSON Web Tokens [JWT] MUST NOT use 353 "b64" with a "false" value. 355 8. Security Considerations 357 [JWS] base64url-encodes the JWS Payload to restrict the set of 358 characters used to represent it so that the representation does not 359 contain characters used for delimiters in JWS representations. Those 360 delimiters are the period ('.') character for the JWS Compact 361 Serialization and the double-quote ('"') character for the JWS JSON 362 Serialization. When the "b64" (base64url-encode payload) value is 363 "false", these properties are lost. It then becomes the 364 responsibility of the application to ensure that payloads only 365 contain characters that will not cause parsing problems for the 366 serialization used, as described in Section 5. The application also 367 incurs the responsibility to ensure that the payload will not be 368 modified during transmission. 370 Note that if a JWS were to be created with a "b64" value of "false" 371 without including the "crit" Header Parameter with "b64" in its set 372 of values and it were received by an implementation not supporting 373 the "b64" Header Parameter, then the signature or MAC would still 374 verify but the recipient would believe that the intended JWS Payload 375 value is the base64url decoding of the payload value received, rather 376 than the payload value received itself. For example, if the payload 377 value received were "NDA1", an implementation not supporting this 378 extension would interpret the intended payload as being the base64url 379 decoding of this value, which is "405". Requiring the use of the 380 "crit" Header Parameter with "b64" in the set of values prevents this 381 misinterpretation. 383 9. IANA Considerations 385 9.1. JWS and JWE Header Parameter Registration 387 This specification registers the "b64" Header Parameter defined in 388 Section 3 in the IANA "JSON Web Signature and Encryption Header 389 Parameters" registry [IANA.JOSE] established by [JWS]. 391 9.1.1. Registry Contents 393 o Header Parameter Name: "b64" 394 o Header Parameter Description: Base64url-Encode Payload 395 o Header Parameter Usage Location(s): JWS 396 o Change Controller: IESG 397 o Specification Document(s): Section 3 of [[ this specification ]] 399 10. References 401 10.1. Normative References 403 [IANA.JOSE] 404 IANA, "JSON Object Signing and Encryption (JOSE)", 405 . 407 [JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 408 DOI 10.17487/RFC7518, May 2015, 409 . 411 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 412 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, 413 May 2015, . 415 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 416 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 417 . 419 [RFC20] Cerf, V., "ASCII format for Network Interchange", STD 80, 420 RFC 20, October 1969, 421 . 423 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 424 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 425 RFC2119, March 1997, 426 . 428 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 429 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, 430 November 2003, . 432 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 433 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, 434 March 2014, . 436 [UNICODE] The Unicode Consortium, "The Unicode Standard", 437 . 439 10.2. Informative References 441 [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/ 442 RFC7517, May 2015, 443 . 445 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 446 Resource Identifier (URI): Generic Syntax", STD 66, 447 RFC 3986, DOI 10.17487/RFC3986, January 2005, 448 . 450 Appendix A. Acknowledgements 452 Anders Rundgren, Richard Barnes, Phillip Hallam-Baker, Jim Schaad, 453 Matt Miller, Martin Thomson, and others have all made the case for 454 being able to use a representation of the payload that is not 455 base64url-encoded in contexts in which it safe to do so. 457 Thanks to Sergey Beryozkin, Stephen Farrell, Benjamin Kaduk, James 458 Manger, Kathleen Moriarty, Axel Nennker, Anders Rundgren, Nat 459 Sakimura, Jim Schaad, Robert Sparks, and Matias Woloski for their 460 reviews of the specification and thanks to Vladimir Dzhuvinov for 461 verifying the examples. 463 Appendix B. Document History 465 [[ to be removed by the RFC editor before publication as an RFC ]] 467 -09 469 o Addressed Stephen Farrell's DISCUSS and comments. In particular, 470 made the use of "crit" required with "b64". 472 -08 474 o Addressed Gen-Art review comments by Robert Sparks, Ops-Dir review 475 comments by Stefan Winter, and ballot comments by Benoit Claise. 477 -07 479 o Addressed Gen-Art review comments by Robert Sparks and Sec-Dir 480 review comments by Benjamin Kaduk. 482 -06 484 o Addressed review comments by Kathleen Moriarty. 486 -05 488 o Reworked the security considerations text on preventing confusion 489 between encoded and unencoded payloads. 491 -04 493 o Corrected a typo in the JWS JSON Serialization example. 495 o Added to the security considerations, including adding a statement 496 about when "crit" should be used. 498 o Addressed the document shepherd comments. 500 -03 502 o Allowed the ASCII space character and all printable ASCII 503 characters other than period ('.') in non-detached unencoded 504 payloads using the JWS Compact Serialization. 506 o Updated the abstract to say that that the spec updates RFC 7519. 508 o Removed unused references. 510 o Changed the change controller to IESG. 512 -02 514 o Required that "b64" be integrity protected. 516 o Stated that if the JWS has multiple signatures and/or MACs, the 517 "b64" Header Parameter value MUST be the same for all of them. 519 o Stated that if applications use content encoding, they MUST 520 specify whether the encoded or unencoded payload is used as the 521 JWS Payload value. 523 o Reorganized the Unencoded Payload Content Restrictions section. 525 o Added an "updates" clause for RFC 7519 because this specification 526 prohibits JWTs from using "b64":false. 528 -01 530 o Removed the "sph" (secure protected header) Header Parameter. 532 o Changed the title to "JWS Unencoded Payload Option". 534 o Added the section "Unencoded Payload Content Restrictions". 536 o Added an example using the JWS JSON Serialization. 538 -00 540 o Created the -00 JOSE working group draft from 541 draft-jones-jose-jws-signing-input-options-00 with no normative 542 changes. 544 Author's Address 546 Michael B. Jones 547 Microsoft 549 Email: mbj@microsoft.com 550 URI: http://self-issued.info/