idnits 2.17.1 draft-ietf-jose-jws-signing-input-options-03.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 (October 13, 2015) is 3118 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 176 -- Looks like a reference, but probably isn't: '46' on line 176 -- Looks like a reference, but probably isn't: '48' on line 176 -- Looks like a reference, but probably isn't: '50' on line 176 ** 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) October 13, 2015 5 Intended status: Standards Track 6 Expires: April 15, 2016 8 JWS Unencoded Payload Option 9 draft-ietf-jose-jws-signing-input-options-03 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 April 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} . . . . . . . . . . . . . . . 5 69 5. Unencoded Payload Content Restrictions . . . . . . . . . . . . 6 70 5.1. Unencoded Detached Payload . . . . . . . . . . . . . . . . 6 71 5.2. Unencoded JWS Compact Serialization Payload . . . . . . . 7 72 5.3. Unencoded JWS JSON Serialization Payload . . . . . . . . . 7 73 6. Intended Use by Applications . . . . . . . . . . . . . . . . . 7 74 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 75 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 76 8.1. JWS and JWE Header Parameter Registration . . . . . . . . 8 77 8.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 8 78 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 79 9.1. Normative References . . . . . . . . . . . . . . . . . . . 8 80 9.2. Informative References . . . . . . . . . . . . . . . . . . 9 81 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 82 Appendix B. Document History . . . . . . . . . . . . . . . . . . 10 83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11 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 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 124 of STRING, where STRING is a sequence of zero or more Unicode 125 [UNICODE] characters. 127 ASCII(STRING) denotes the octets of the ASCII [RFC20] representation 128 of STRING, where STRING is a sequence of zero or more ASCII 129 characters. 131 The concatenation of two values A and B is denoted as A || B. 133 2. Terminology 135 This specification uses the same terminology as the "JSON Web 136 Signature (JWS)" [JWS] and "JSON Web Algorithms (JWA)" [JWA] 137 specifications. 139 3. The "b64" Header Parameter 141 This Header Parameter modifies the JWS Payload representation and the 142 JWS Signing Input computation in the following way: 144 b64 145 The "b64" (base64url-encode payload) Header Parameter determines 146 whether the payload is represented in the JWS and the JWS Signing 147 Input as ASCII(BASE64URL(JWS Payload)) or as the JWS Payload value 148 itself with no encoding performed. When the "b64" value is 149 "false", the payload is represented simply as the JWS Payload 150 value; otherwise, it is represented as ASCII(BASE64URL(JWS 151 Payload)). The "b64" value is a JSON boolean, with a default 152 value of "true". When used, this Header Parameter MUST be 153 integrity protected; therefore, it MUST occur only within the JWS 154 Protected Header. Use of this Header Parameter is OPTIONAL. If 155 the JWS has multiple signatures and/or MACs, the "b64" Header 156 Parameter value MUST be the same for all of them. Note that 157 unless the payload is detached, many payload values would cause 158 errors parsing the resulting JWSs, as described in Section 5. 160 The following table shows the JWS Signing Input computation, 161 depending upon the value of this parameter: 163 +-------+-----------------------------------------------------------+ 164 | "b64" | JWS Signing Input Formula | 165 +-------+-----------------------------------------------------------+ 166 | true | ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || | 167 | | BASE64URL(JWS Payload)) | 168 | false | ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.') || | 169 | | JWS Payload | 170 +-------+-----------------------------------------------------------+ 172 4. Examples 174 This section gives examples of JWSs showing the difference that using 175 the "b64" Header Parameter makes. The examples all use the JWS 176 Payload value [36, 46, 48, 50]. This octet sequence represents the 177 ASCII characters "$.02"; its base64url-encoded representation is 178 "JC4wMg". 180 The following table shows a set of Header Parameter values without 181 using a false "b64" Header Parameter value and a set using it, with 182 the resulting JWS Signing Input values represented as ASCII 183 characters: 185 +-----------------------------+-------------------------------------+ 186 | JWS Protected Header | JWS Signing Input Value | 187 +-----------------------------+-------------------------------------+ 188 | {"alg":"HS256"} | eyJhbGciOiJIUzI1NiJ9.JC4wMg | 189 | {"alg":"HS256","b64":false} | eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2V | 190 | | 9.$.02 | 191 +-----------------------------+-------------------------------------+ 193 These examples use the HMAC key from Appendix A.1 of [JWS], which is 194 represented below as a JWK [JWK] (with line breaks within values for 195 display purposes only): 197 { 198 "kty":"oct", 199 "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75 200 aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow" 201 } 203 The rest of this section shows complete representations for the two 204 JWSs above. 206 4.1. Example with Header Parameters {"alg":"HS256"} 208 The complete JWS representation for this example using the JWS 209 Compact Serialization and a non-detached payload (with line breaks 210 for display purposes only) is: 212 eyJhbGciOiJIUzI1NiJ9 213 . 214 JC4wMg 215 . 216 5mvfOroL-g7HyqJoozehmsaqmvTYGEq5jTI1gVvoEoQ 218 Note that this JWS uses only features defined by [JWS] and does not 219 use the new "b64" Header Parameter. It is the "control", so that 220 differences when it is used can be easily seen. 222 4.2. Example with Header Parameters {"alg":"HS256","b64":false} 224 The complete JWS representation for this example using the JWS 225 Compact Serialization and a detached payload (with line breaks for 226 display purposes only) is: 228 eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2V9 229 . 230 . 231 GsyM6AQJbQHY8aQKCbZSPJHzMRWo3HKIlcDuXof7nqs 233 Note that the payload "$.02" cannot be represented in this JWS in its 234 unencoded form because it contains a period ('.') character, which 235 would cause parsing problems. This JWS is therefore shown with a 236 detached payload. 238 The complete JWS representation for this example using the flattened 239 JWS JSON Serialization and a non-detached payload is: 241 { 242 "protected": 243 "eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2V9", 244 "payload": 245 "$.02", 246 "signature", 247 "GsyM6AQJbQHY8aQKCbZSPJHzMRWo3HKIlcDuXof7nqs" 248 } 250 If using a detached payload with the JWS JSON Serialization, the 251 "payload" element would be omitted. 253 5. Unencoded Payload Content Restrictions 255 When the "b64" value is "false", different restrictions on the 256 payload contents apply, depending upon the circumstances, as 257 described in this section. The restrictions prevent the use of 258 payload values that would cause errors parsing the resulting JWSs. 260 Note that because the character sets that can be used for unencoded 261 non-detached payloads differ between the two serializations, some 262 JWSs using a "b64" value of "false" cannot be syntactically converted 263 between the JWS JSON Serialization and the JWS Compact Serialization. 264 See Section 7 for security considerations on using unencoded 265 payloads. 267 5.1. Unencoded Detached Payload 269 Appendix F of [JWS] describes how to represent JWSs with detached 270 content. A detached payload can contain any octet sequence 271 representable by the application. The payload value will not cause 272 problems parsing the JWS, since it is not represented as part of the 273 JWS. If an application uses a content encoding when representing the 274 payload, then it MUST specify whether the signature or MAC is 275 performed over the content-encoded representation or over the 276 unencoded content. 278 5.2. Unencoded JWS Compact Serialization Payload 280 When using the JWS Compact Serialization, unencoded non-detached 281 payloads using period ('.') characters would cause parsing errors; 282 such payloads MUST NOT be used with the JWS Compact Serialization. 283 Similarly, if a JWS using the JWS Compact Serialization and a non- 284 detached payload is to be transmitted in a context that requires URL 285 safe characters, then the application MUST ensure that the payload 286 contains only the URL-safe characters 'a'-'z', 'A'-'Z', '0'-'9', dash 287 ('-'), underscore ('_'), and tilde ('~'). The ASCII space character 288 and all printable ASCII characters other than period ('.') (those 289 characters in the ranges %x20-2D and %x2F-7E) MAY be included in a 290 non-detached payload using the JWS Compact Serialization, provided 291 that the application can transmit the resulting JWS without 292 modification. 294 No meaning or special semantics are attached to any characters in the 295 payload. For instance, the percent ('%') character represents 296 itself, and is not used by JWS objects for percent-encoding 297 [RFC3986]. Applications, of course, are free to utilize content 298 encoding rules of their choosing, provided that the encoded 299 representations utilize only allowed payload characters. 301 5.3. Unencoded JWS JSON Serialization Payload 303 When using the JWS JSON Serialization, unencoded non-detached 304 payloads must consist of the octets of the UTF-8 encoding of a 305 sequence of Unicode code points that are representable in a JSON 306 string. The payload value is determined after performing any escape 307 processing, per Section 8.3 of RFC 7159 [RFC7159], and UTF-8-encoding 308 the resulting Unicode code points. This means, for instance, that 309 these payloads represented as JSON strings are equivalent ("$.02", 310 "\u0024.02"). Unassigned Unicode code point values MUST NOT be used 311 to represent the payload. 313 6. Intended Use by Applications 315 It is intended that application profiles specify up front whether 316 "b64" with a "false" value is to be used by the application or not, 317 with it then being consistently applied in the application context. 318 For instance, an application that uses detached payloads might 319 specify that "b64" with a "false" value always be used. It is not 320 intended that this parameter value be dynamically varied with 321 different payloads for the same application. 323 JSON Web Tokens (JWTs) [JWT] MUST NOT use "b64" with a "false" value. 325 7. Security Considerations 327 [JWS] base64url-encodes the JWS Payload to restrict the character set 328 used to represent it to characters that are distinct from the 329 delimiters that separate it from other JWS fields. Those delimiters 330 are the period ('.') character for the JWS Compact Serialization and 331 the double-quote ('"') character for the JWS JSON Serialization. 332 This encoding also intentionally excludes characters whose 333 representations may require escaping in some contexts and excludes 334 whitespace and line breaks, as all of these can result in changes to 335 the payload during transmission. 337 When the "b64" (base64url-encode payload) value is "false", these 338 properties are lost. It then becomes the responsibility of the 339 application to ensure that payloads only contain characters that will 340 not cause parsing problems for the serialization used, as described 341 in Section 5, and that the payload will not be modified during 342 transmission. 344 8. IANA Considerations 346 8.1. JWS and JWE Header Parameter Registration 348 This specification registers the "b64" Header Parameter defined in 349 Section 3 in the IANA "JSON Web Signature and Encryption Header 350 Parameters" registry [IANA.JOSE] established by [JWS]. 352 8.1.1. Registry Contents 354 o Header Parameter Name: "b64" 355 o Header Parameter Description: Base64url-Encode Payload 356 o Header Parameter Usage Location(s): JWS 357 o Change Controller: IESG 358 o Specification Document(s): Section 3 of [[ this document ]] 360 9. References 362 9.1. Normative References 364 [IANA.JOSE] 365 IANA, "JSON Object Signing and Encryption (JOSE)", 366 . 368 [JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 369 DOI 10.17487/RFC7518, May 2015, 370 . 372 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 373 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, 374 May 2015, . 376 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 377 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 378 . 380 [RFC20] Cerf, V., "ASCII format for Network Interchange", STD 80, 381 RFC 20, October 1969, 382 . 384 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 385 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 386 RFC2119, March 1997, 387 . 389 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 390 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, 391 November 2003, . 393 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 394 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, 395 March 2014, . 397 [UNICODE] The Unicode Consortium, "The Unicode Standard", 398 . 400 9.2. Informative References 402 [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/ 403 RFC7517, May 2015, 404 . 406 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 407 Resource Identifier (URI): Generic Syntax", STD 66, 408 RFC 3986, DOI 10.17487/RFC3986, January 2005, 409 . 411 Appendix A. Acknowledgements 413 Anders Rundgren, Richard Barnes, Phillip Hallam-Baker, Jim Schaad, 414 Matt Miller, Martin Thomson, and others have all made the case at 415 different times for being able to use a representation of the payload 416 that is not base64url-encoded in contexts in which it safe to do so. 418 Thanks to Sergey Beryozkin, James Manger, Axel Nennker, Anders 419 Rundgren, Nat Sakimura, Jim Schaad, and Matias Woloski for their 420 reviews of the specification. 422 Appendix B. Document History 424 [[ to be removed by the RFC editor before publication as an RFC ]] 426 -03 428 o Allowed the ASCII space character and all printable ASCII 429 characters other than period ('.') in non-detached unencoded 430 payloads using the JWS Compact Serialization. 432 o Updated the abstract to say that that the spec updates RFC 7519. 434 o Removed unused references. 436 o Changed the change controller to IESG. 438 -02 440 o Required that "b64" be integrity protected. 442 o Stated that if the JWS has multiple signatures and/or MACs, the 443 "b64" Header Parameter value MUST be the same for all of them. 445 o Stated that if applications use content encoding, they MUST 446 specify whether the encoded or unencoded payload is used as the 447 JWS Payload value. 449 o Reorganized the Unencoded Payload Content Restrictions section. 451 o Added an "updates" clause for RFC 7519 because this specification 452 prohibits JWTs from using "b64":false. 454 -01 456 o Removed the "sph" (secure protected header) Header Parameter. 458 o Changed the title to "JWS Unencoded Payload Option". 460 o Added the section "Unencoded Payload Content Restrictions". 462 o Added an example using the JWS JSON Serialization. 464 -00 466 o Created the -00 JOSE working group draft from 467 draft-jones-jose-jws-signing-input-options-00 with no normative 468 changes. 470 Author's Address 472 Michael B. Jones 473 Microsoft 475 Email: mbj@microsoft.com 476 URI: http://self-issued.info/