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