idnits 2.17.1 draft-ietf-jose-jws-signing-input-options-02.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 : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC7519, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 13, 2015) is 3148 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) == Unused Reference: 'RFC2104' is defined on line 392, but no explicit reference was found in the text == Unused Reference: 'RFC3447' is defined on line 397, but no explicit reference was found in the text == Unused Reference: 'SHS' is defined on line 402, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE' -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 4 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) September 13, 2015 5 Intended status: Standards Track 6 Expires: March 16, 2016 8 JWS Unencoded Payload Option 9 draft-ietf-jose-jws-signing-input-options-02 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 Status of this Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on March 16, 2016. 41 Copyright Notice 43 Copyright (c) 2015 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 60 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 3. The "b64" Header Parameter . . . . . . . . . . . . . . . . . . 4 62 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 4.1. Example with {"alg":"HS256"} . . . . . . . . . . . . . . . 5 64 4.2. Example with {"alg":"HS256","b64":false} . . . . . . . . . 5 65 5. Unencoded Payload Content Restrictions . . . . . . . . . . . . 6 66 5.1. Unencoded Detached Payload . . . . . . . . . . . . . . . . 6 67 5.2. Unencoded JWS Compact Serialization Payload . . . . . . . 7 68 5.3. Unencoded JWS JSON Serialization Payload . . . . . . . . . 7 69 6. Intended Use by Applications . . . . . . . . . . . . . . . . . 7 70 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7 71 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 72 8.1. JWS and JWE Header Parameter Registration . . . . . . . . 8 73 8.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 8 74 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 75 9.1. Normative References . . . . . . . . . . . . . . . . . . . 8 76 9.2. Informative References . . . . . . . . . . . . . . . . . . 9 77 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 78 Appendix B. Document History . . . . . . . . . . . . . . . . . . 10 79 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10 81 1. Introduction 83 The "JSON Web Signature (JWS)" [JWS] specification defines the JWS 84 Signing Input as the input to the digital signature or MAC 85 computation, with the value ASCII(BASE64URL(UTF8(JWS Protected 86 Header)) || '.' || BASE64URL(JWS Payload)). While this works well in 87 practice for many use cases, including those accommodating arbitrary 88 payload values, other use cases have been described in which 89 base64url encoding the payload is unnecessary and/or an impediment to 90 adoption, particularly when the payload is large and/or detached. 92 This specification introduces a new JWS Header Parameter value that 93 generalizes the JWS Signing Input computation in a manner that makes 94 base64url encoding the payload selectable and optional. The primary 95 set of use cases where this enhancement may be helpful are those in 96 which the payload may be very large and where means are already in 97 place to enable the payload to be communicated between the parties 98 without modifications. Appendix F of [JWS] describes how to 99 represent JWSs with detached content, which would typically be used 100 for these use cases. 102 The advantages of not having to base64url-encode a large payload are 103 that allocation of the additional storage to hold the base64url- 104 encoded form is avoided and the base64url-encoding computation never 105 has to be performed. In summary, this option can help avoid 106 unnecessary copying and transformations of the potentially large 107 payload, resulting in sometimes significant space and time 108 improvements for deployments. 110 1.1. Notational Conventions 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 114 "OPTIONAL" in this document are to be interpreted as described in 115 "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. 116 The interpretation should only be applied when the terms appear in 117 all capital letters. 119 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 120 of STRING, where STRING is a sequence of zero or more Unicode 121 [UNICODE] characters. 123 ASCII(STRING) denotes the octets of the ASCII [RFC20] representation 124 of STRING, where STRING is a sequence of zero or more ASCII 125 characters. 127 The concatenation of two values A and B is denoted as A || B. 129 2. Terminology 131 This specification uses the same terminology as the "JSON Web 132 Signature (JWS)" [JWS] and "JSON Web Algorithms (JWA)" [JWA] 133 specifications. 135 3. The "b64" Header Parameter 137 This Header Parameter modifies the JWS Payload representation and the 138 JWS Signing Input computation in the following way: 140 b64 141 The "b64" (base64url-encode payload) Header Parameter determines 142 whether the payload is represented in the JWS and the JWS Signing 143 Input as ASCII(BASE64URL(JWS Payload)) or as the JWS Payload value 144 itself with no encoding performed. When the "b64" value is 145 "false", the payload is represented simply as the JWS Payload 146 value; otherwise, it is represented as ASCII(BASE64URL(JWS 147 Payload)). The "b64" value is a JSON boolean, with a default 148 value of "true". When used, this Header Parameter MUST be 149 integrity protected; therefore, it MUST occur only within the JWS 150 Protected Header. Use of this Header Parameter is OPTIONAL. If 151 the JWS has multiple signatures and/or MACs, the "b64" Header 152 Parameter value MUST be the same for all of them. Note that 153 unless the payload is detached, many payload values would cause 154 errors parsing the resulting JWSs, as described in Section 5. 156 The following table shows the JWS Signing Input computation, 157 depending upon the value of this parameter: 159 +-------+-----------------------------------------------------------+ 160 | "b64" | JWS Signing Input Formula | 161 +-------+-----------------------------------------------------------+ 162 | true | ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || | 163 | | BASE64URL(JWS Payload)) | 164 | false | ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.') || | 165 | | JWS Payload | 166 +-------+-----------------------------------------------------------+ 168 4. Examples 170 This section gives examples of JWSs showing the difference that using 171 the "b64" Header Parameter makes. The resulting JWSs both use the 172 JWS Compact Serialization and both use the JWS Payload value [36, 46, 173 48, 50]. This octet sequence represents the ASCII characters "$.02"; 174 its base64url-encoded representation is "JC4wMg". 176 The following table shows a set of Header Parameter values without 177 using a false "b64" Header Parameter value and a set using it, with 178 the resulting JWS Signing Input values represented as ASCII 179 characters: 181 +-----------------------------+-------------------------------------+ 182 | JWS Protected Header | JWS Signing Input Value | 183 +-----------------------------+-------------------------------------+ 184 | {"alg":"HS256"} | eyJhbGciOiJIUzI1NiJ9.JC4wMg | 185 | {"alg":"HS256","b64":false} | eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2V | 186 | | 9.$.02 | 187 +-----------------------------+-------------------------------------+ 189 These examples use the HMAC key from Appendix A.1 of [JWS], which is 190 represented below as a JWK [JWK] (with line breaks within values for 191 display purposes only): 193 { 194 "kty":"oct", 195 "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75 196 aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow" 197 } 199 The rest of this section shows complete representations for the two 200 JWSs above. 202 4.1. Example with {"alg":"HS256"} 204 The complete JWS representation for this example using the JWS 205 Compact Serialization (with line breaks for display purposes only) 206 is: 208 eyJhbGciOiJIUzI1NiJ9 209 . 210 JC4wMg 211 . 212 5mvfOroL-g7HyqJoozehmsaqmvTYGEq5jTI1gVvoEoQ 214 Note that this JWS uses only features defined by [JWS] and does not 215 use the new "b64" Header Parameter. It is the "control", so that 216 differences when it is used can be easily seen. 218 4.2. Example with {"alg":"HS256","b64":false} 220 The complete JWS representation for this example using the JWS 221 Compact Serialization (with line breaks for display purposes only) 222 is: 224 eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2V9 225 . 226 . 227 GsyM6AQJbQHY8aQKCbZSPJHzMRWo3HKIlcDuXof7nqs 229 Note that the payload "$.02" cannot be represented in this JWS in its 230 unencoded form because it contains a period ('.') character, which 231 would cause parsing problems. This JWS is therefore shown with a 232 detached payload. 234 The complete JWS representation for this example using the flattened 235 JWS JSON Serialization is: 237 { 238 "protected": 239 "eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2V9", 240 "payload": 241 "$.02", 242 "signature", 243 "GsyM6AQJbQHY8aQKCbZSPJHzMRWo3HKIlcDuXof7nqs" 244 } 246 If using a detached payload with the JWS JSON Serialization, the 247 "payload" element would be omitted. 249 5. Unencoded Payload Content Restrictions 251 When the "b64" value is "false", different restrictions on the 252 payload content apply, depending upon the circumstances, as described 253 in this section. The restrictions prevent the use of payload values 254 that would cause errors parsing the resulting JWSs. 256 Note that because the character sets that can be used for unencoded 257 non-detached payloads differ between the two serializations, some 258 JWSs using a "b64" value of "false" cannot be syntactically converted 259 between the JWS JSON Serialization and the JWS Compact Serialization. 260 See Section 7 for security considerations on using unencoded 261 payloads. 263 5.1. Unencoded Detached Payload 265 Appendix F of [JWS] describes how to represent JWSs with detached 266 content. A detached payload can contain any octet sequence 267 representable by the application. The payload value will not cause 268 problems parsing the JWS, since it is not represented as part of the 269 JWS. If an application uses a content encoding when representing the 270 payload, then it MUST specify whether the signature or MAC is 271 performed over the content-encoded representation or over the 272 unencoded content. 274 5.2. Unencoded JWS Compact Serialization Payload 276 When using the JWS Compact Serialization, unencoded non-detached 277 payloads including period ('.') characters would cause parsing 278 errors; such payloads MUST NOT be used with the JWS Compact 279 Serialization. Similarly, if a JWS using the JWS Compact 280 Serialization and a non-detached payload is to be transmitted in a 281 context that requires URL safe characters, then the application must 282 ensure that the payload contains only the URL-safe characters 283 'a'-'z', 'A'-'Z', '0'-'9', dash ('-'), underscore ('_'), and tilde 284 ('~'); non-detached payloads using characters outside this set SHOULD 285 NOT be used. 287 5.3. Unencoded JWS JSON Serialization Payload 289 When using the JWS JSON Serialization, unencoded non-detached 290 payloads must consist of the octets of the UTF-8 encoding of a 291 sequence of Unicode code points that are representable in a JSON 292 string. The payload value is determined after performing any escape 293 processing, per Section 8.3 of RFC 7159 [RFC7159], and UTF-8-encoding 294 the resulting Unicode code points. This means, for instance, that 295 these payloads represented as JSON strings are equivalent ("$.02", 296 "\u0024.02"). Unassigned Unicode code point values MUST NOT be used 297 to represent the payload. 299 6. Intended Use by Applications 301 It is intended that application profiles specify up front whether 302 "b64" with a "false" value is to be used by the application or not, 303 with it then being consistently applied in the application context. 304 For instance, an application that uses detached payloads might 305 specify that "b64" with a "false" value always be used. It is not 306 intended that this parameter value be dynamically varied with 307 different payloads for the same application. 309 JSON Web Tokens (JWTs) [JWT] MUST NOT use "b64" with a "false" value. 311 7. Security Considerations 313 [JWS] base64url-encodes the JWS Payload to restrict the character set 314 used to represent it to characters that are distinct from the 315 delimiters that separate it from other JWS fields. Those delimiters 316 are the period ('.') character for the JWS Compact Serialization and 317 the double-quote ('"') character for the JWS JSON Serialization. 318 This encoding also intentionally excludes characters whose 319 representations may require escaping in some contexts and excludes 320 whitespace and line breaks, as all of these can result in changes to 321 the payload during transmission. 323 When the "b64" (base64url-encode payload) value is "false", these 324 properties are lost. It then becomes the responsibility of the 325 application to ensure that payloads only contain characters that will 326 not cause parsing problems for the serialization used, as described 327 in Section 5, and that the payload will not be modified during 328 transmission. 330 8. IANA Considerations 332 8.1. JWS and JWE Header Parameter Registration 334 This specification registers the "b64" Header Parameter defined in 335 Section 3 in the IANA "JSON Web Signature and Encryption Header 336 Parameters" registry [IANA.JOSE] established by [JWS]. 338 8.1.1. Registry Contents 340 o Header Parameter Name: "b64" 341 o Header Parameter Description: Base64url-Encode Payload 342 o Header Parameter Usage Location(s): JWS 343 o Change Controller: IETF 344 o Specification Document(s): Section 3 of [[ this document ]] 346 9. References 348 9.1. Normative References 350 [IANA.JOSE] 351 IANA, "JSON Object Signing and Encryption (JOSE)", 352 . 354 [JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 355 DOI 10.17487/RFC7518, May 2015, 356 . 358 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 359 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, 360 May 2015, . 362 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 363 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 364 . 366 [RFC20] Cerf, V., "ASCII format for Network Interchange", STD 80, 367 RFC 20, October 1969, 368 . 370 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 371 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 372 RFC2119, March 1997, 373 . 375 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 376 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, 377 November 2003, . 379 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 380 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, 381 March 2014, . 383 [UNICODE] The Unicode Consortium, "The Unicode Standard", 384 . 386 9.2. Informative References 388 [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/ 389 RFC7517, May 2015, 390 . 392 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 393 Hashing for Message Authentication", RFC 2104, 394 DOI 10.17487/RFC2104, February 1997, 395 . 397 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 398 Standards (PKCS) #1: RSA Cryptography Specifications 399 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, 400 February 2003, . 402 [SHS] National Institute of Standards and Technology, "Secure 403 Hash Standard (SHS)", FIPS PUB 180-4, March 2012, . 406 Appendix A. Acknowledgements 408 Anders Rundgren, Richard Barnes, Phillip Hallam-Baker, Jim Schaad, 409 Matt Miller, Martin Thomson, and others have all made the case at 410 different times for being able to use a representation of the payload 411 that is not base64url-encoded in contexts in which it safe to do so. 413 Thanks to Sergey Beryozkin, James Manger, Axel Nennker, Anders 414 Rundgren, Nat Sakimura, Jim Schaad, and Matias Woloski for their 415 reviews of the specification. 417 Appendix B. Document History 419 [[ to be removed by the RFC editor before publication as an RFC ]] 421 -02 423 o Required that "b64" be integrity protected. 425 o Stated that if the JWS has multiple signatures and/or MACs, the 426 "b64" Header Parameter value MUST be the same for all of them. 428 o Stated that if applications use content encoding, they MUST 429 specify whether the encoded or unencoded payload is used as the 430 JWS Payload value. 432 o Reorganized the Unencoded Payload Content Restrictions section. 434 o Added an "updates" clause for RFC 7519 because this specification 435 prohibits JWTs from using "b64":false. 437 -01 439 o Removed the "sph" (secure protected header) Header Parameter. 441 o Changed the title to "JWS Unencoded Payload Option". 443 o Added the section "Unencoded Payload Content Restrictions". 445 o Added an example using the JWS JSON Serialization. 447 -00 449 o Created the -00 JOSE working group draft from 450 draft-jones-jose-jws-signing-input-options-00 with no normative 451 changes. 453 Author's Address 455 Michael B. Jones 456 Microsoft 458 Email: mbj@microsoft.com 459 URI: http://self-issued.info/