idnits 2.17.1 draft-jones-jose-jws-signing-input-options-00.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 doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (May 27, 2015) is 3255 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 207 -- Looks like a reference, but probably isn't: '46' on line 207 -- Looks like a reference, but probably isn't: '48' on line 207 -- Looks like a reference, but probably isn't: '50' on line 207 == Unused Reference: 'RFC2104' is defined on line 399, but no explicit reference was found in the text == Unused Reference: 'RFC3447' is defined on line 403, but no explicit reference was found in the text == Unused Reference: 'SHS' is defined on line 407, 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 (~~), 5 warnings (==), 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 Intended status: Standards Track May 27, 2015 5 Expires: November 28, 2015 7 JWS Signing Input Options 8 draft-jones-jose-jws-signing-input-options-00 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. 22 Also, JWS includes a representation of the JWS Protected Header and a 23 period ('.') character in the JWS Signature computation. While this 24 cryptographically binds the protected Header Parameters to the 25 integrity protected payload, some of have described use cases in 26 which this binding is unnecessary and/or an impediment to adoption, 27 especially when the payload is large and/or detached. This 28 specification defines a means of accommodating these use cases by 29 defining an option to change the JWS Signing Input computation to not 30 include a representation of the JWS Protected Header and a period 31 ('.') character in the JWS Signing Input. 33 These options are intended to broaden the set of use cases for which 34 the use of JWS is a good fit. 36 Status of this Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at http://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on November 28, 2015. 53 Copyright Notice 55 Copyright (c) 2015 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents 60 (http://trustee.ietf.org/license-info) in effect on the date of 61 publication of this document. Please review these documents 62 carefully, as they describe your rights and restrictions with respect 63 to this document. Code Components extracted from this document must 64 include Simplified BSD License text as described in Section 4.e of 65 the Trust Legal Provisions and are provided without warranty as 66 described in the Simplified BSD License. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 71 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 72 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 73 3. Header Parameters Defined . . . . . . . . . . . . . . . . . . 5 74 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 75 4.1. Example with {"alg":"HS256"} . . . . . . . . . . . . . . . 7 76 4.2. Example with {"alg":"HS256","sph":false} . . . . . . . . . 7 77 4.3. Example with {"alg":"HS256","b64":false} . . . . . . . . . 7 78 4.4. Example with {"alg":"HS256","sph":false,"b64":false} . . . 8 79 5. Intended Use by Applications . . . . . . . . . . . . . . . . . 8 80 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 81 6.1. JWS and JWE Header Parameter Registration . . . . . . . . 8 82 6.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 8 83 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9 84 7.1. Unsecured Header Parameters . . . . . . . . . . . . . . . 9 85 7.2. Unencoded Payloads . . . . . . . . . . . . . . . . . . . . 9 86 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 87 8.1. Normative References . . . . . . . . . . . . . . . . . . . 9 88 8.2. Informative References . . . . . . . . . . . . . . . . . . 10 89 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10 90 Appendix B. Document History . . . . . . . . . . . . . . . . . . 11 91 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11 93 1. Introduction 95 The "JSON Web Signature (JWS)" [JWS] specification defines the JWS 96 Signing Input as the input to the digital signature or MAC 97 computation, with the value ASCII(BASE64URL(UTF8(JWS Protected 98 Header)) || '.' || BASE64URL(JWS Payload)). While this works well in 99 practice for many use cases, including those accommodating arbitrary 100 payload values, other use cases have been described in which either 101 the base64url encoding of the payload or the addition of information 102 beyond the payload itself to the JWS Signing Input present a burden 103 to implementation and adoption, particularly when the payload is 104 large and/or detached. 106 This specification introduces two new JWS Header Parameter values 107 that generalize the JWS Signing Input computation in a manner that 108 makes these two behaviors selectable and optional. 110 The primary set of use cases where these enhancements may be helpful 111 are those in which the payload may be very large and where means are 112 already in place to enable the payload to be communicated between 113 parties without modifications. Appendix F of [JWS] describes how to 114 represent JWSs with detached content, which would typically be used 115 for these use cases. 117 The advantages of not having to base64url-encode a large payload are 118 that allocation of the additional storage to hold the base64url- 119 encoded form is avoided and the base64url-encoding computation never 120 has to be performed. 122 The advantages of not having to add a representation of the JWS 123 Protected Header and a period ('.') character as a prefix to the 124 payload representation in JWS Signing Input are similar. If the 125 prefix is present in the JWS Signing Input, then space has to be 126 allocated to hold the JWS Signing Input that includes a copy of the 127 (large) payload representation. This is necessary because most 128 cryptographic libraries underlying the JWS implementation will 129 require that the JWS Signing Input be represented as a contiguous 130 octet sequence. 132 In summary, these options can help avoid unnecessary copying and 133 transformations of the potentially large payload, resulting in 134 sometimes significant space and time improvements for deployments. 136 1.1. Notational Conventions 138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 140 "OPTIONAL" in this document are to be interpreted as described in 141 "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119]. 142 The interpretation should only be applied when the terms appear in 143 all capital letters. 145 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 146 of STRING, where STRING is a sequence of zero or more Unicode 147 [UNICODE] characters. 149 ASCII(STRING) denotes the octets of the ASCII [RFC20] representation 150 of STRING, where STRING is a sequence of zero or more ASCII 151 characters. 153 The concatenation of two values A and B is denoted as A || B. 155 2. Terminology 157 This specification uses the same terminology as the "JSON Web 158 Signature (JWS)" [JWS] and "JSON Web Algorithms (JWA)" [JWA] 159 specifications. 161 3. Header Parameters Defined 163 [JWS] defines the JWS Signing Input value to be 164 ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS 165 Payload)). The following Header Parameters are defined that modify 166 the JWS Signing Input computation in the following ways: 168 sph 169 The "sph" (secure protected header) Header Parameter determines 170 whether the octet sequence ASCII(BASE64URL(UTF8(JWS Protected 171 Header)) || '.') is included in the JWS Signing Input or not. 172 When the "sph" value is "false", it is not included. The "sph" 173 value is a JSON [RFC7159] boolean, with a default value of "true". 175 b64 176 The "b64" (base64url-encode payload) Header Parameter determines 177 whether the payload is represented in the JWS and the JWS Signing 178 Input as ASCII(BASE64URL(JWS Payload)) or as the payload itself 179 with no encoding performed. When the "b64" value is "false", the 180 payload is represented simply as the JWS Payload value; otherwise, 181 it is represented as ASCII(BASE64URL(JWS Payload)). The "b64" 182 value is a JSON boolean, with a default value of "true". Note 183 that unless the payload is detached, as described in Appendix F of 184 [JWS], many payload values (such as those including period ('.') 185 characters) would cause errors parsing the resulting JWSs, 186 depending upon the serialization used. See Section 7.2 for 187 limitations on using unencoded payloads. 189 The following table shows the JWS Signing Input computation, 190 depending upon the values of these parameters: 192 +-------+-------+---------------------------------------------------+ 193 | "sph" | "b64" | JWS Signing Input Formula | 194 +-------+-------+---------------------------------------------------+ 195 | true | true | ASCII(BASE64URL(UTF8(JWS Protected Header)) || | 196 | | | '.' || BASE64URL(JWS Payload)) | 197 | false | true | ASCII(BASE64URL(JWS Payload)) | 198 | true | false | ASCII(BASE64URL(UTF8(JWS Protected Header)) || | 199 | | | '.') || JWS Payload | 200 | false | false | JWS Payload | 201 +-------+-------+---------------------------------------------------+ 203 4. Examples 205 This section gives some examples of possible uses of these Header 206 Parameters and resulting JWSs using the JWS Compact Serialization. 207 All these examples use the JWS Payload value [36, 46, 48, 50]. This 208 octet sequence represents the ASCII characters "$.02". Its 209 base64url-encoded representation is "JC4wMg". 211 The following table shows different sets of Header Parameter values 212 and the resulting JWS Signing Input values represented as ASCII 213 characters: 215 +--------------------------------+----------------------------------+ 216 | JWS Protected Header | JWS Signing Input Value | 217 +--------------------------------+----------------------------------+ 218 | {"alg":"HS256"} | eyJhbGciOiJIUzI1NiJ9.JC4wMg | 219 | {"alg":"HS256","sph":false} | JC4wMg | 220 | {"alg":"HS256","b64":false} | eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFs | 221 | | c2V9.$.02 | 222 | {"alg":"HS256","sph":false,"b6 | $.02 | 223 | 4":false} | | 224 +--------------------------------+----------------------------------+ 226 All these examples use this HMAC key from Appendix A.1 of [JWS], 227 which is represented as a JWK [JWK] (with line breaks within values 228 for display purposes only): 230 {"kty":"oct", 231 "k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75 232 aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow" 233 } 235 The rest of this section shows complete representations using the JWS 236 Compact Serialization for the four JWSs with the sets of Header 237 Parameters listed above. 239 4.1. Example with {"alg":"HS256"} 241 The complete JWS representation for this example using the JWS 242 Compact Serialization (with line breaks for display purposes only) 243 is: 245 eyJhbGciOiJIUzI1NiJ9 246 . 247 JC4wMg 248 . 249 5mvfOroL-g7HyqJoozehmsaqmvTYGEq5jTI1gVvoEoQ 251 Note that this JWS uses only features defined by [JWS] and uses 252 neither of the new Header Parameters defined in Section 3. It is the 253 "control", so that differences from it when the new Header Parameters 254 are used can be easily seen. 256 4.2. Example with {"alg":"HS256","sph":false} 258 The complete JWS representation for this example using the JWS 259 Compact Serialization (with line breaks for display purposes only) 260 is: 262 eyJhbGciOiJIUzI1NiIsInNwaCI6ZmFsc2V9 263 . 264 JC4wMg 265 . 266 ojui4Wd9BM62Ag1zcfUAPHZGj_nWl2oHEJN1QIVH4IM 268 4.3. Example with {"alg":"HS256","b64":false} 270 The complete JWS representation for this example using the JWS 271 Compact Serialization (with line breaks for display purposes only) 272 is: 274 eyJhbGciOiJIUzI1NiIsImI2NCI6ZmFsc2V9 275 . 276 . 277 GsyM6AQJbQHY8aQKCbZSPJHzMRWo3HKIlcDuXof7nqs 279 Note that the payload "$.02" cannot be represented in this JWS in its 280 unencoded form because it contains a period ('.') character, which 281 would cause parsing problems. This JWS is therefore shown with a 282 detached payload. 284 4.4. Example with {"alg":"HS256","sph":false,"b64":false} 286 The complete JWS representation for this example using the JWS 287 Compact Serialization (with line breaks for display purposes only) 288 is: 290 eyJhbGciOiJIUzI1NiIsInNwaCI6ZmFsc2UsImI2NCI6ZmFsc2V9 291 . 292 . 293 diN05PDK8714HY7InlOPYcJ8dIBpr-JVNA_20hkfnSc 295 Note that the payload "$.02" cannot be represented in this JWS in its 296 unencoded form because it contains a period ('.') character, which 297 would cause parsing problems. This JWS is therefore shown with a 298 detached payload. 300 5. Intended Use by Applications 302 It is intended that application profiles specify up front whether the 303 "sph" and/or "b64" are to be used by the application, with them then 304 being consistently applied in the application context. For instance, 305 an application using potentially large detached payloads might 306 specify that both "sph" and "b64" always be used. Another 307 application that always uses alphanumeric payloads might specify that 308 "b64" always be used. It is not intended that these parameter values 309 be dynamically varied with different payloads for the same 310 application. 312 6. IANA Considerations 314 6.1. JWS and JWE Header Parameter Registration 316 This specification registers the "mac" (MAC algorithm) Header 317 Parameter defined in Section 3 in the IANA JSON Web Signature and 318 Encryption Header Parameters registry defined in [JWS]. 320 6.1.1. Registry Contents 322 o Header Parameter Name: "sph" 323 o Header Parameter Description: Secure Protected Header 324 o Header Parameter Usage Location(s): JWS 325 o Change Controller: IETF 326 o Specification Document(s): Section 3 of [[ this document ]] 327 o Header Parameter Name: "b64" 328 o Header Parameter Description: Base64url-Encode Payload 329 o Header Parameter Usage Location(s): JWS 330 o Change Controller: IETF 331 o Specification Document(s): Section 3 of [[ this document ]] 333 7. Security Considerations 335 7.1. Unsecured Header Parameters 337 The same security considerations apply to the case when the "sph" 338 (secure protected header) value is "false" as apply when Header 339 Parameters are carried in the JWS Unprotected Header. These are 340 described in Section 10.7 of [JWS]. 342 7.2. Unencoded Payloads 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. 349 This encoding also intentionally excludes characters whose 350 representations may require escaping in some contexts and excludes 351 whitespace and line breaks, as all of these can result in changes to 352 the payload during transmission. 354 When the "b64" (secure protected header) value is "false", these 355 properties are lost. It then becomes the responsibility of the 356 application to ensure that payloads only contain characters that will 357 not cause parsing problems for the serialization used and that the 358 payload will not be modified during transmission. For instance, this 359 means that payloads cannot contain period ('.') characters when using 360 the JWS Compact Serialization, unless the payload is detached. 361 Similarly, if the JWS is to be transmitted in a context that requires 362 URL safe characters, then the application must ensure that the 363 payload contains only the URL-safe characters 'a'-'z', 'A'-'Z', 364 '0'-'9', dash ('-'), underscore ('_'), and tilde ('~'), unless it is 365 detached. 367 8. References 369 8.1. Normative References 371 [JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 372 May 2015, . 374 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 375 Signature (JWS)", RFC 7515, May 2015, 376 . 378 [RFC20] Cerf, V., "ASCII format for Network Interchange", STD 80, 379 RFC 20, October 1969, 380 . 382 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 383 Requirement Levels", BCP 14, RFC 2119, March 1997. 385 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 386 10646", STD 63, RFC 3629, November 2003. 388 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 389 Interchange Format", RFC 7159, March 2014. 391 [UNICODE] The Unicode Consortium, "The Unicode Standard", 392 . 394 8.2. Informative References 396 [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517, May 2015, 397 . 399 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 400 Hashing for Message Authentication", RFC 2104, 401 February 1997. 403 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 404 Standards (PKCS) #1: RSA Cryptography Specifications 405 Version 2.1", RFC 3447, February 2003. 407 [SHS] National Institute of Standards and Technology, "Secure 408 Hash Standard (SHS)", FIPS PUB 180-4, March 2012, . 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 using a representation of the payload that is not 416 base64url-encoded and/or not cryptographically binding the Header 417 Parameter values to the integrity protected payload in contexts in 418 which it safe to do so. 420 Appendix B. Document History 422 [[ to be removed by the RFC editor before publication as an RFC ]] 424 -00 426 o Created draft-jones-jose-jws-signing-input-options. 428 Author's Address 430 Michael B. Jones 431 Microsoft 433 Email: mbj@microsoft.com 434 URI: http://self-issued.info/