idnits 2.17.1 draft-ietf-jose-json-web-algorithms-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 : ---------------------------------------------------------------------------- == There are 5 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 23, 2013) is 4021 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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: '1' on line 1176 -- Looks like a reference, but probably isn't: '0' on line 1176 -- Possible downref: Non-RFC (?) normative reference: ref. 'AES' -- Possible downref: Non-RFC (?) normative reference: ref. 'DSS' ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Downref: Normative reference to an Informational RFC: RFC 3394 ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Downref: Normative reference to an Informational RFC: RFC 6090 -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' == Outdated reference: A later version (-05) exists of draft-mcgrew-aead-aes-cbc-hmac-sha2-01 -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) Summary: 5 errors (**), 0 flaws (~~), 3 warnings (==), 9 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 April 23, 2013 5 Expires: October 25, 2013 7 JSON Web Algorithms (JWA) 8 draft-ietf-jose-json-web-algorithms-09 10 Abstract 12 The JSON Web Algorithms (JWA) specification enumerates cryptographic 13 algorithms and identifiers to be used with the JSON Web Signature 14 (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) 15 specifications. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on October 25, 2013. 34 Copyright Notice 36 Copyright (c) 2013 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 52 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 53 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 2.1. Terms Incorporated from the JWS Specification . . . . . . 4 55 2.2. Terms Incorporated from the JWE Specification . . . . . . 5 56 2.3. Terms Incorporated from the JWK Specification . . . . . . 7 57 2.4. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 8 58 3. Cryptographic Algorithms for JWS . . . . . . . . . . . . . . . 8 59 3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 8 60 3.2. MAC with HMAC SHA-256, HMAC SHA-384, or HMAC SHA-512 . . . 9 61 3.3. Digital Signature with RSA SHA-256, RSA SHA-384, or 62 RSA SHA-512 . . . . . . . . . . . . . . . . . . . . . . . 10 63 3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA 64 P-384 SHA-384, or ECDSA P-521 SHA-512 . . . . . . . . . . 11 65 3.5. Using the Algorithm "none" . . . . . . . . . . . . . . . . 12 66 3.6. Additional Digital Signature/MAC Algorithms and 67 Parameters . . . . . . . . . . . . . . . . . . . . . . . . 13 68 4. Cryptographic Algorithms for JWE . . . . . . . . . . . . . . . 13 69 4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 13 70 4.2. "enc" (Encryption Method) Header Parameter Values for 71 JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 72 4.3. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 16 73 4.4. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 16 74 4.5. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 16 75 4.6. Direct Encryption with a Shared Symmetric Key . . . . . . 16 76 4.7. Key Agreement with Elliptic Curve Diffie-Hellman 77 Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 16 78 4.7.1. Key Derivation for "ECDH-ES" . . . . . . . . . . . . . 17 79 4.8. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 18 80 4.8.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 18 81 4.8.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 19 82 4.8.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 19 83 4.8.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 21 84 4.8.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 21 85 4.8.4. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 22 86 4.8.5. Plaintext Encryption with AES_CBC_HMAC_SHA2 . . . . . 22 87 4.9. Plaintext Encryption with AES GCM . . . . . . . . . . . . 22 88 4.10. Additional Encryption Algorithms and Parameters . . . . . 23 89 5. Cryptographic Algorithms for JWK . . . . . . . . . . . . . . . 23 90 5.1. "kty" (Key Type) Parameter Values for JWK . . . . . . . . 24 91 5.2. JWK Parameters for Elliptic Curve Keys . . . . . . . . . . 24 92 5.2.1. JWK Parameters for Elliptic Curve Public Keys . . . . 24 93 5.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 24 94 5.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 25 95 5.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 25 96 5.2.2. JWK Parameters for Elliptic Curve Private Keys . . . . 25 97 5.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 25 98 5.3. JWK Parameters for RSA Keys . . . . . . . . . . . . . . . 25 99 5.3.1. JWK Parameters for RSA Public Keys . . . . . . . . . . 25 100 5.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 26 101 5.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 26 102 5.3.2. JWK Parameters for RSA Private Keys . . . . . . . . . 26 103 5.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 26 104 5.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 26 105 5.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 26 106 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 27 107 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 27 108 5.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 27 109 5.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 27 110 5.3.3. JWK Parameters for Symmetric Keys . . . . . . . . . . 28 111 5.3.3.1. "k" (Key Value) Parameter . . . . . . . . . . . . 28 112 5.4. Additional Key Types and Parameters . . . . . . . . . . . 28 113 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 114 6.1. JSON Web Signature and Encryption Algorithms Registry . . 29 115 6.1.1. Template . . . . . . . . . . . . . . . . . . . . . . . 29 116 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 30 117 6.2. JSON Web Key Types Registry . . . . . . . . . . . . . . . 33 118 6.2.1. Registration Template . . . . . . . . . . . . . . . . 33 119 6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 33 120 6.3. JSON Web Key Parameters Registration . . . . . . . . . . . 34 121 6.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 34 122 7. Security Considerations . . . . . . . . . . . . . . . . . . . 35 123 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 36 124 8.1. Normative References . . . . . . . . . . . . . . . . . . . 36 125 8.2. Informative References . . . . . . . . . . . . . . . . . . 38 126 Appendix A. Digital Signature/MAC Algorithm Identifier 127 Cross-Reference . . . . . . . . . . . . . . . . . . . 39 128 Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 41 129 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 43 130 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 44 131 C.2. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 45 132 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 46 133 Appendix E. Document History . . . . . . . . . . . . . . . . . . 46 134 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 51 136 1. Introduction 138 The JSON Web Algorithms (JWA) specification enumerates cryptographic 139 algorithms and identifiers to be used with the JSON Web Signature 140 (JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK) 141 [JWK] specifications. All these specifications utilize JavaScript 142 Object Notation (JSON) [RFC4627] based data structures. This 143 specification also describes the semantics and operations that are 144 specific to these algorithms and key types. 146 Enumerating the algorithms and identifiers for them in this 147 specification, rather than in the JWS, JWE, and JWK specifications, 148 is intended to allow them to remain unchanged in the face of changes 149 in the set of required, recommended, optional, and deprecated 150 algorithms over time. 152 1.1. Notational Conventions 154 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 155 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 156 document are to be interpreted as described in Key words for use in 157 RFCs to Indicate Requirement Levels [RFC2119]. 159 2. Terminology 161 2.1. Terms Incorporated from the JWS Specification 163 These terms defined by the JSON Web Signature (JWS) [JWS] 164 specification are incorporated into this specification: 166 JSON Web Signature (JWS) A data structure representing a digitally 167 signed or MACed message. The structure represents three values: 168 the JWS Header, the JWS Payload, and the JWS Signature. 170 JSON Text Object A UTF-8 [RFC3629] encoded text string representing 171 a JSON object; the syntax of JSON objects is defined in Section 172 2.2 of [RFC4627]. 174 JWS Header A JSON Text Object that describes the digital signature 175 or MAC operation applied to create the JWS Signature value. 177 JWS Payload The sequence of octets to be secured -- a.k.a., the 178 message. The payload can contain an arbitrary sequence of octets. 180 JWS Signature A sequence of octets containing the cryptographic 181 material that ensures the integrity of the JWS Header and the JWS 182 Payload. The JWS Signature value is a digital signature or MAC 183 value calculated over the JWS Signing Input using the parameters 184 specified in the JWS Header. 186 Base64url Encoding The URL- and filename-safe Base64 encoding 187 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 188 safe) '=' padding characters omitted, as permitted by Section 3.2. 189 (See Appendix C of [JWS] for notes on implementing base64url 190 encoding without padding.) 192 Encoded JWS Header Base64url encoding of the JWS Header. 194 Encoded JWS Payload Base64url encoding of the JWS Payload. 196 Encoded JWS Signature Base64url encoding of the JWS Signature. 198 JWS Signing Input The concatenation of the Encoded JWS Header, a 199 period ('.') character, and the Encoded JWS Payload. 201 Collision Resistant Namespace A namespace that allows names to be 202 allocated in a manner such that they are highly unlikely to 203 collide with other names. For instance, collision resistance can 204 be achieved through administrative delegation of portions of the 205 namespace or through use of collision-resistant name allocation 206 functions. Examples of Collision Resistant Namespaces include: 207 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 208 X.660 and X.670 Recommendation series, and Universally Unique 209 IDentifiers (UUIDs) [RFC4122]. When using an administratively 210 delegated namespace, the definer of a name needs to take 211 reasonable precautions to ensure they are in control of the 212 portion of the namespace they use to define the name. 214 2.2. Terms Incorporated from the JWE Specification 216 These terms defined by the JSON Web Encryption (JWE) [JWE] 217 specification are incorporated into this specification: 219 JSON Web Encryption (JWE) A data structure representing an encrypted 220 message. The structure represents five values: the JWE Header, 221 the JWE Encrypted Key, the JWE Initialization Vector, the JWE 222 Ciphertext, and the JWE Authentication Tag. 224 Authenticated Encryption An Authenticated Encryption algorithm is 225 one that provides an integrated content integrity check. 226 Authenticated Encryption algorithms accept two inputs, the 227 Plaintext and the Additional Authenticated Data value, and produce 228 two outputs, the Ciphertext and the Authentication Tag value. AES 229 Galois/Counter Mode (GCM) is one such algorithm. 231 Plaintext The sequence of octets to be encrypted -- a.k.a., the 232 message. The plaintext can contain an arbitrary sequence of 233 octets. 235 Ciphertext An encrypted representation of the Plaintext. 237 Additional Associated Data (AAD) An input to an Authenticated 238 Encryption operation that is integrity protected but not 239 encrypted. 241 Authentication Tag An output of an Authenticated Encryption 242 operation that ensures the integrity of the Ciphertext and the 243 Additional Associated Data. 245 Content Encryption Key (CEK) A symmetric key for the Authenticated 246 Encryption algorithm used to encrypt the Plaintext for the 247 recipient to produce the Ciphertext and the Authentication Tag. 249 JWE Header A JSON Text Object that describes the encryption 250 operations applied to create the JWE Encrypted Key, the JWE 251 Ciphertext, and the JWE Authentication Tag. 253 JWE Encrypted Key The result of encrypting the Content Encryption 254 Key (CEK) with the intended recipient's key using the specified 255 algorithm. Note that for some algorithms, the JWE Encrypted Key 256 value is specified as being the empty octet sequence. 258 JWE Initialization Vector A sequence of octets containing the 259 Initialization Vector used when encrypting the Plaintext. 261 JWE Ciphertext A sequence of octets containing the Ciphertext for a 262 JWE. 264 JWE Authentication Tag A sequence of octets containing the 265 Authentication Tag for a JWE. 267 Encoded JWE Header Base64url encoding of the JWE Header. 269 Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted 270 Key. 272 Encoded JWE Initialization Vector Base64url encoding of the JWE 273 Initialization Vector. 275 Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. 277 Encoded JWE Authentication Tag Base64url encoding of the JWE 278 Authentication Tag. 280 Key Management Mode A method of determining the Content Encryption 281 Key (CEK) value to use. Each algorithm used for determining the 282 CEK value uses a specific Key Management Mode. Key Management 283 Modes employed by this specification are Key Encryption, Key 284 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 285 and Direct Encryption. 287 Key Encryption A Key Management Mode in which the Content Encryption 288 Key (CEK) value is encrypted to the intended recipient using an 289 asymmetric encryption algorithm. 291 Key Wrapping A Key Management Mode in which the Content Encryption 292 Key (CEK) value is encrypted to the intended recipient using a 293 symmetric key wrapping algorithm. 295 Direct Key Agreement A Key Management Mode in which a key agreement 296 algorithm is used to agree upon the Content Encryption Key (CEK) 297 value. 299 Key Agreement with Key Wrapping A Key Management Mode in which a key 300 agreement algorithm is used to agree upon a symmetric key used to 301 encrypt the Content Encryption Key (CEK) value to the intended 302 recipient using a symmetric key wrapping algorithm. 304 Direct Encryption A Key Management Mode in which the Content 305 Encryption Key (CEK) value used is the secret symmetric key value 306 shared between the parties. 308 2.3. Terms Incorporated from the JWK Specification 310 These terms defined by the JSON Web Key (JWK) [JWK] specification are 311 incorporated into this specification: 313 JSON Web Key (JWK) A JSON object that represents a cryptographic 314 key. 316 JSON Web Key Set (JWK Set) A JSON object that contains an array of 317 JWKs as the value of its "keys" member. 319 2.4. Defined Terms 321 These terms are defined for use by this specification: 323 Header Parameter Name The name of a member of the JSON object 324 representing a JWS Header or JWE Header. 326 Header Parameter Value The value of a member of the JSON object 327 representing a JWS Header or JWE Header. 329 3. Cryptographic Algorithms for JWS 331 JWS uses cryptographic algorithms to digitally sign or create a 332 Message Authentication Codes (MAC) of the contents of the JWS Header 333 and the JWS Payload. The use of the following algorithms for 334 producing JWSs is defined in this section. 336 3.1. "alg" (Algorithm) Header Parameter Values for JWS 338 The table below is the set of "alg" (algorithm) header parameter 339 values defined by this specification for use with JWS, each of which 340 is explained in more detail in the following sections: 342 +--------------+--------------------------------+-------------------+ 343 | alg | Digital Signature or MAC | Implementation | 344 | Parameter | Algorithm | Requirements | 345 | Value | | | 346 +--------------+--------------------------------+-------------------+ 347 | HS256 | HMAC using SHA-256 hash | REQUIRED | 348 | | algorithm | | 349 | HS384 | HMAC using SHA-384 hash | OPTIONAL | 350 | | algorithm | | 351 | HS512 | HMAC using SHA-512 hash | OPTIONAL | 352 | | algorithm | | 353 | RS256 | RSASSA using SHA-256 hash | RECOMMENDED | 354 | | algorithm | | 355 | RS384 | RSASSA using SHA-384 hash | OPTIONAL | 356 | | algorithm | | 357 | RS512 | RSASSA using SHA-512 hash | OPTIONAL | 358 | | algorithm | | 359 | ES256 | ECDSA using P-256 curve and | RECOMMENDED+ | 360 | | SHA-256 hash algorithm | | 361 | ES384 | ECDSA using P-384 curve and | OPTIONAL | 362 | | SHA-384 hash algorithm | | 363 | ES512 | ECDSA using P-521 curve and | OPTIONAL | 364 | | SHA-512 hash algorithm | | 365 | none | No digital signature or MAC | REQUIRED | 366 | | value included | | 367 +--------------+--------------------------------+-------------------+ 369 All the names are short because a core goal of JWS is for the 370 representations to be compact. However, there is no a priori length 371 restriction on "alg" values. 373 The use of "+" in the Implementation Requirements indicates that the 374 requirement strength is likely to be increased in a future version of 375 the specification. 377 See Appendix A for a table cross-referencing the digital signature 378 and MAC "alg" (algorithm) values used in this specification with the 379 equivalent identifiers used by other standards and software packages. 381 3.2. MAC with HMAC SHA-256, HMAC SHA-384, or HMAC SHA-512 383 Hash-based Message Authentication Codes (HMACs) enable one to use a 384 secret plus a cryptographic hash function to generate a Message 385 Authentication Code (MAC). This can be used to demonstrate that the 386 MAC matches the hashed content, in this case the JWS Signing Input, 387 which therefore demonstrates that whoever generated the MAC was in 388 possession of the secret. The means of exchanging the shared key is 389 outside the scope of this specification. 391 The algorithm for implementing and validating HMACs is provided in 392 RFC 2104 [RFC2104]. This section defines the use of the HMAC SHA- 393 256, HMAC SHA-384, and HMAC SHA-512 functions [SHS]. The "alg" 394 (algorithm) header parameter values "HS256", "HS384", and "HS512" are 395 used in the JWS Header to indicate that the Encoded JWS Signature 396 contains a base64url encoded HMAC value using the respective hash 397 function. 399 A key of the same size as the hash output (for instance, 256 bits for 400 "HS256") or larger MUST be used with this algorithm. 402 The HMAC SHA-256 MAC is generated per RFC 2104, using SHA-256 as the 403 hash algorithm "H", using the octets of the ASCII [USASCII] 404 representation of the JWS Signing Input as the "text" value, and 405 using the shared key. The HMAC output value is the JWS Signature. 406 The JWS signature is base64url encoded to produce the Encoded JWS 407 Signature. 409 The HMAC SHA-256 MAC for a JWS is validated by computing an HMAC 410 value per RFC 2104, using SHA-256 as the hash algorithm "H", using 411 the octets of the ASCII representation of the received JWS Signing 412 Input as the "text" value, and using the shared key. This computed 413 HMAC value is then compared to the result of base64url decoding the 414 received Encoded JWS signature. Alternatively, the computed HMAC 415 value can be base64url encoded and compared to the received Encoded 416 JWS Signature, as this comparison produces the same result as 417 comparing the unencoded values. In either case, if the values match, 418 the HMAC has been validated. If the validation fails, the JWS MUST 419 be rejected. 421 Securing content with the HMAC SHA-384 and HMAC SHA-512 algorithms is 422 performed identically to the procedure for HMAC SHA-256 - just using 423 the corresponding hash algorithm with correspondingly larger minimum 424 key sizes and result values: 384 bits each for HMAC SHA-384 and 512 425 bits each for HMAC SHA-512. 427 An example using this algorithm is shown in Appendix A.1 of [JWS]. 429 3.3. Digital Signature with RSA SHA-256, RSA SHA-384, or RSA SHA-512 431 This section defines the use of the RSASSA-PKCS1-V1_5 digital 432 signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447], 433 (commonly known as PKCS #1), using SHA-256, SHA-384, or SHA-512 [SHS] 434 as the hash functions. The "alg" (algorithm) header parameter values 435 "RS256", "RS384", and "RS512" are used in the JWS Header to indicate 436 that the Encoded JWS Signature contains a base64url encoded RSA 437 digital signature using the respective hash function. 439 A key of size 2048 bits or larger MUST be used with these algorithms. 441 The RSA SHA-256 digital signature is generated as follows: 443 1. Generate a digital signature of the octets of the ASCII 444 representation of the JWS Signing Input using RSASSA-PKCS1-V1_5- 445 SIGN and the SHA-256 hash function with the desired private key. 446 The output will be an octet sequence. 448 2. Base64url encode the resulting octet sequence. 450 The output is the Encoded JWS Signature for that JWS. 452 The RSA SHA-256 digital signature for a JWS is validated as follows: 454 1. Take the Encoded JWS Signature and base64url decode it into an 455 octet sequence. If decoding fails, the JWS MUST be rejected. 457 2. Submit the octets of the ASCII representation of the JWS Signing 458 Input and the public key corresponding to the private key used by 459 the signer to the RSASSA-PKCS1-V1_5-VERIFY algorithm using SHA- 460 256 as the hash function. 462 3. If the validation fails, the JWS MUST be rejected. 464 Signing with the RSA SHA-384 and RSA SHA-512 algorithms is performed 465 identically to the procedure for RSA SHA-256 - just using the 466 corresponding hash algorithm with correspondingly larger result 467 values: 384 bits for RSA SHA-384 and 512 bits for RSA SHA-512. 469 An example using this algorithm is shown in Appendix A.2 of [JWS]. 471 3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA P-384 SHA-384, 472 or ECDSA P-521 SHA-512 474 The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides 475 for the use of Elliptic Curve cryptography, which is able to provide 476 equivalent security to RSA cryptography but using shorter key sizes 477 and with greater processing speed. This means that ECDSA digital 478 signatures will be substantially smaller in terms of length than 479 equivalently strong RSA digital signatures. 481 This specification defines the use of ECDSA with the P-256 curve and 482 the SHA-256 cryptographic hash function, ECDSA with the P-384 curve 483 and the SHA-384 hash function, and ECDSA with the P-521 curve and the 484 SHA-512 hash function. The P-256, P-384, and P-521 curves are 485 defined in [DSS]. The "alg" (algorithm) header parameter values 486 "ES256", "ES384", and "ES512" are used in the JWS Header to indicate 487 that the Encoded JWS Signature contains a base64url encoded ECDSA 488 P-256 SHA-256, ECDSA P-384 SHA-384, or ECDSA P-521 SHA-512 digital 489 signature, respectively. 491 The ECDSA P-256 SHA-256 digital signature is generated as follows: 493 1. Generate a digital signature of the octets of the ASCII 494 representation of the JWS Signing Input using ECDSA P-256 SHA-256 495 with the desired private key. The output will be the pair (R, 496 S), where R and S are 256 bit unsigned integers. 498 2. Turn R and S into octet sequences in big endian order, with each 499 array being be 32 octets long. The array representations MUST 500 NOT be shortened to omit any leading zero octets contained in the 501 values. 503 3. Concatenate the two octet sequences in the order R and then S. 504 (Note that many ECDSA implementations will directly produce this 505 concatenation as their output.) 507 4. Base64url encode the resulting 64 octet sequence. 509 The output is the Encoded JWS Signature for the JWS. 511 The ECDSA P-256 SHA-256 digital signature for a JWS is validated as 512 follows: 514 1. Take the Encoded JWS Signature and base64url decode it into an 515 octet sequence. If decoding fails, the JWS MUST be rejected. 517 2. The output of the base64url decoding MUST be a 64 octet sequence. 518 If decoding does not result in a 64 octet sequence, the JWS MUST 519 be rejected. 521 3. Split the 64 octet sequence into two 32 octet sequences. The 522 first array will be R and the second S (with both being in big 523 endian octet order). 525 4. Submit the octets of the ASCII representation of the JWS Signing 526 Input R, S and the public key (x, y) to the ECDSA P-256 SHA-256 527 validator. 529 5. If the validation fails, the JWS MUST be rejected. 531 Note that ECDSA digital signature contains a value referred to as K, 532 which is a random number generated for each digital signature 533 instance. This means that two ECDSA digital signatures using exactly 534 the same input parameters will output different signature values 535 because their K values will be different. A consequence of this is 536 that one cannot validate an ECDSA signature by recomputing the 537 signature and comparing the results. 539 Signing with the ECDSA P-384 SHA-384 and ECDSA P-521 SHA-512 540 algorithms is performed identically to the procedure for ECDSA P-256 541 SHA-256 - just using the corresponding hash algorithm with 542 correspondingly larger result values. For ECDSA P-384 SHA-384, R and 543 S will be 384 bits each, resulting in a 96 octet sequence. For ECDSA 544 P-521 SHA-512, R and S will be 521 bits each, resulting in a 132 545 octet sequence. 547 Examples using these algorithms are shown in Appendices A.3 and A.4 548 of [JWS]. 550 3.5. Using the Algorithm "none" 552 JWSs MAY also be created that do not provide integrity protection. 553 Such a JWS is called a "Plaintext JWS". Plaintext JWSs MUST use the 554 "alg" value "none", and are formatted identically to other JWSs, but 555 with the empty string for its JWS Signature value. 557 3.6. Additional Digital Signature/MAC Algorithms and Parameters 559 Additional algorithms MAY be used to protect JWSs with corresponding 560 "alg" (algorithm) header parameter values being defined to refer to 561 them. New "alg" header parameter values SHOULD either be registered 562 in the IANA JSON Web Signature and Encryption Algorithms registry 563 Section 6.1 or be a value that contains a Collision Resistant 564 Namespace. In particular, it is permissible to use the algorithm 565 identifiers defined in XML DSIG [RFC3275], XML DSIG 2.0 566 [W3C.CR-xmldsig-core2-20120124], and related specifications as "alg" 567 values. 569 As indicated by the common registry, JWSs and JWEs share a common 570 "alg" value space. The values used by the two specifications MUST be 571 distinct, as the "alg" value can be used to determine whether the 572 object is a JWS or JWE. 574 Likewise, additional reserved Header Parameter Names MAY be defined 575 via the IANA JSON Web Signature and Encryption Header Parameters 576 registry [JWS]. As indicated by the common registry, JWSs and JWEs 577 share a common header parameter space; when a parameter is used by 578 both specifications, its usage must be compatible between the 579 specifications. 581 4. Cryptographic Algorithms for JWE 583 JWE uses cryptographic algorithms to encrypt the Content Encryption 584 Key (CEK) and the Plaintext. This section specifies a set of 585 specific algorithms for these purposes. 587 4.1. "alg" (Algorithm) Header Parameter Values for JWE 589 The table below is the set of "alg" (algorithm) header parameter 590 values that are defined by this specification for use with JWE. 591 These algorithms are used to encrypt the CEK, producing the JWE 592 Encrypted Key, or to use key agreement to agree upon the CEK. 594 +----------------+---------------------------------+----------------+ 595 | alg Parameter | Key Management Algorithm | Implementation | 596 | Value | | Requirements | 597 +----------------+---------------------------------+----------------+ 598 | RSA1_5 | RSAES-PKCS1-V1_5 [RFC3447] | REQUIRED | 599 | RSA-OAEP | RSAES using Optimal Asymmetric | OPTIONAL | 600 | | Encryption Padding (OAEP) | | 601 | | [RFC3447], with the default | | 602 | | parameters specified by RFC | | 603 | | 3447 in Section A.2.1 | | 604 | A128KW | Advanced Encryption Standard | RECOMMENDED | 605 | | (AES) Key Wrap Algorithm | | 606 | | [RFC3394] using the default | | 607 | | initial value specified in | | 608 | | Section 2.2.3.1 and using 128 | | 609 | | bit keys | | 610 | A256KW | AES Key Wrap Algorithm using | RECOMMENDED | 611 | | the default initial value | | 612 | | specified in Section 2.2.3.1 | | 613 | | and using 256 bit keys | | 614 | dir | Direct use of a shared | RECOMMENDED | 615 | | symmetric key as the Content | | 616 | | Encryption Key (CEK) for the | | 617 | | block encryption step (rather | | 618 | | than using the symmetric key to | | 619 | | wrap the CEK) | | 620 | ECDH-ES | Elliptic Curve Diffie-Hellman | RECOMMENDED+ | 621 | | Ephemeral Static [RFC6090] key | | 622 | | agreement using the Concat KDF, | | 623 | | as defined in Section 5.8.1 of | | 624 | | [NIST.800-56A], with the | | 625 | | agreed-upon key being used | | 626 | | directly as the Content | | 627 | | Encryption Key (CEK) (rather | | 628 | | than being used to wrap the | | 629 | | CEK), as specified in | | 630 | | Section 4.7 | | 631 | ECDH-ES+A128KW | Elliptic Curve Diffie-Hellman | RECOMMENDED | 632 | | Ephemeral Static key agreement | | 633 | | per "ECDH-ES" and Section 4.7, | | 634 | | but where the agreed-upon key | | 635 | | is used to wrap the Content | | 636 | | Encryption Key (CEK) with the | | 637 | | "A128KW" function (rather than | | 638 | | being used directly as the CEK) | | 639 | ECDH-ES+A256KW | Elliptic Curve Diffie-Hellman | RECOMMENDED | 640 | | Ephemeral Static key agreement | | 641 | | per "ECDH-ES" and Section 4.7, | | 642 | | but where the agreed-upon key | | 643 | | is used to wrap the Content | | 644 | | Encryption Key (CEK) with the | | 645 | | "A256KW" function (rather than | | 646 | | being used directly as the CEK) | | 647 +----------------+---------------------------------+----------------+ 649 The use of "+" in the Implementation Requirements indicates that the 650 requirement strength is likely to be increased in a future version of 651 the specification. 653 4.2. "enc" (Encryption Method) Header Parameter Values for JWE 655 The table below is the set of "enc" (encryption method) header 656 parameter values that are defined by this specification for use with 657 JWE. These algorithms are used to encrypt the Plaintext, which 658 produces the Ciphertext. 660 +---------------+----------------------------------+----------------+ 661 | enc Parameter | Block Encryption Algorithm | Implementation | 662 | Value | | Requirements | 663 +---------------+----------------------------------+----------------+ 664 | A128CBC-HS256 | The AES_128_CBC_HMAC_SHA_256 | REQUIRED | 665 | | authenticated encryption | | 666 | | algorithm, as defined in | | 667 | | Section 4.8.3. This algorithm | | 668 | | uses a 256 bit key. | | 669 | A256CBC-HS512 | The AES_256_CBC_HMAC_SHA_512 | REQUIRED | 670 | | authenticated encryption | | 671 | | algorithm, as defined in | | 672 | | Section 4.8.4. This algorithm | | 673 | | uses a 512 bit key. | | 674 | A128GCM | AES in Galois/Counter Mode (GCM) | RECOMMENDED | 675 | | [AES] [NIST.800-38D] using 128 | | 676 | | bit keys | | 677 | A256GCM | AES GCM using 256 bit keys | RECOMMENDED | 678 +---------------+----------------------------------+----------------+ 680 All the names are short because a core goal of JWE is for the 681 representations to be compact. However, there is no a priori length 682 restriction on "alg" values. 684 See Appendix B for a table cross-referencing the encryption "alg" 685 (algorithm) and "enc" (encryption method) values used in this 686 specification with the equivalent identifiers used by other standards 687 and software packages. 689 4.3. Key Encryption with RSAES-PKCS1-V1_5 691 This section defines the specifics of encrypting a JWE CEK with 692 RSAES-PKCS1-V1_5 [RFC3447]. The "alg" header parameter value 693 "RSA1_5" is used in this case. 695 A key of size 2048 bits or larger MUST be used with this algorithm. 697 An example using this algorithm is shown in Appendix A.2 of [JWE]. 699 4.4. Key Encryption with RSAES OAEP 701 This section defines the specifics of encrypting a JWE CEK with RSAES 702 using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447], with 703 the default parameters specified by RFC 3447 in Section A.2.1. The 704 "alg" header parameter value "RSA-OAEP" is used in this case. 706 A key of size 2048 bits or larger MUST be used with this algorithm. 708 An example using this algorithm is shown in Appendix A.1 of [JWE]. 710 4.5. Key Wrapping with AES Key Wrap 712 This section defines the specifics of encrypting a JWE CEK with the 713 Advanced Encryption Standard (AES) Key Wrap Algorithm [RFC3394] using 714 the default initial value specified in Section 2.2.3.1 using 128 or 715 256 bit keys. The "alg" header parameter values "A128KW" or "A256KW" 716 are used in this case. 718 An example using this algorithm is shown in Appendix A.3 of [JWE]. 720 4.6. Direct Encryption with a Shared Symmetric Key 722 This section defines the specifics of directly performing symmetric 723 key encryption without performing a key wrapping step. In this case, 724 the shared symmetric key is used directly as the Content Encryption 725 Key (CEK) value for the "enc" algorithm. An empty octet sequence is 726 used as the JWE Encrypted Key value. The "alg" header parameter 727 value "dir" is used in this case. 729 4.7. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static 730 (ECDH-ES) 732 This section defines the specifics of key agreement with Elliptic 733 Curve Diffie-Hellman Ephemeral Static [RFC6090], and using the Concat 734 KDF, as defined in Section 5.8.1 of [NIST.800-56A]. The key 735 agreement result can be used in one of two ways: 737 1. directly as the Content Encryption Key (CEK) for the "enc" 738 algorithm, in the Direct Key Agreement mode, or 740 2. as a symmetric key used to wrap the CEK with either the "A128KW" 741 or "A256KW" algorithms, in the Key Agreement with Key Wrapping 742 mode. 744 The "alg" header parameter value "ECDH-ES" is used in the Direct Key 745 Agreement mode and the values "ECDH-ES+A128KW" and "ECDH-ES+A256KW" 746 are used in the Key Agreement with Key Wrapping mode. 748 In the Direct Key Agreement case, the output of the Concat KDF MUST 749 be a key of the same length as that used by the "enc" algorithm; in 750 this case, the empty octet sequence is used as the JWE Encrypted Key 751 value. In the Key Agreement with Key Wrapping case, the output of 752 the Concat KDF MUST be a key of the length needed for the specified 753 key wrapping algorithm, either 128 or 256 bits respectively. 755 A new "epk" (ephemeral public key) value MUST be generated for each 756 key agreement transaction. 758 4.7.1. Key Derivation for "ECDH-ES" 760 The key derivation process derives the agreed upon key from the 761 shared secret Z established through the ECDH algorithm, per Section 762 6.2.2.2 of [NIST.800-56A]. 764 Key derivation is performed using the Concat KDF, as defined in 765 Section 5.8.1 of [NIST.800-56A], where the Digest Method is SHA-256. 766 The Concat KDF parameters are set as follows: 768 Z This is set to the representation of the shared secret Z as an 769 octet sequence. 771 keydatalen This is set to the number of bits in the desired output 772 key. For "ECDH-ES", this is length of the key used by the "enc" 773 algorithm. For "ECDH-ES+A128KW", and "ECDH-ES+A256KW", this is 774 128 and 256, respectively. 776 AlgorithmID This is set to the concatenation of keydatalen 777 represented as a 32 bit big endian integer and the octets of the 778 UTF-8 representation of the "alg" header parameter value. 780 PartyUInfo The PartyUInfo value is of the form Datalen || Data, 781 where Data is a variable-length string of zero or more octets, and 782 Datalen is a fixed-length, big endian 32 bit counter that 783 indicates the length (in octets) of Data, with || being 784 concatenation. If an "apu" (agreement PartyUInfo) header 785 parameter is present, Data is set to the result of base64url 786 decoding the "apu" value and Datalen is set to the number of 787 octets in Data. Otherwise, Datalen is set to 0 and Data is set to 788 the empty octet sequence. 790 PartyVInfo The PartyVInfo value is of the form Datalen || Data, 791 where Data is a variable-length string of zero or more octets, and 792 Datalen is a fixed-length, big endian 32 bit counter that 793 indicates the length (in octets) of Data, with || being 794 concatenation. If an "apv" (agreement PartyVInfo) header 795 parameter is present, Data is set to the result of base64url 796 decoding the "apv" value and Datalen is set to the number of 797 octets in Data. Otherwise, Datalen is set to 0 and Data is set to 798 the empty octet sequence. 800 SuppPubInfo This is set to the empty octet sequence. 802 SuppPrivInfo This is set to the empty octet sequence. 804 4.8. AES_CBC_HMAC_SHA2 Algorithms 806 This section defines a family of authenticated encryption algorithms 807 built using a composition of Advanced Encryption Standard (AES) in 808 Cipher Block Chaining (CBC) mode with PKCS #5 padding [AES] 809 [NIST.800-38A] operations and HMAC [RFC2104] [SHS] operations. This 810 algorithm family is called AES_CBC_HMAC_SHA2. It also defines two 811 instances of this family, one using 128 bit CBC keys and HMAC SHA-256 812 and the other using 256 bit CBC keys and HMAC SHA-512. Test cases 813 for these algorithms can be found in Appendix C. 815 These algorithms are based upon Authenticated Encryption with AES-CBC 816 and HMAC-SHA [I-D.mcgrew-aead-aes-cbc-hmac-sha2], performing the same 817 cryptographic computations, but with the Initialization Vector and 818 Authentication Tag values remaining separate, rather than being 819 concatenated with the Ciphertext value in the output representation. 820 This algorithm family is a generalization of the algorithm family in 821 [I-D.mcgrew-aead-aes-cbc-hmac-sha2], and can be used to implement 822 those algorithms. 824 4.8.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 826 We use the following notational conventions. 828 CBC-PKCS5-ENC(X,P) denotes the AES CBC encryption of P using PKCS 829 #5 padding using the cipher with the key X. 831 MAC(Y, M) denotes the application of the Message Authentication 832 Code (MAC) to the message M, using the key Y. 834 The concatenation of two octet strings A and B is denoted as 835 A || B. 837 4.8.2. Generic AES_CBC_HMAC_SHA2 Algorithm 839 This section defines AES_CBC_HMAC_SHA2 in a manner that is 840 independent of the AES CBC key size or hash function to be used. 841 Section 4.8.2.1 and Section 4.8.2.2 define the generic encryption and 842 decryption algorithms. Section 4.8.3 and Section 4.8.4 define 843 instances of AES_CBC_HMAC_SHA2 that specify those details. 845 4.8.2.1. AES_CBC_HMAC_SHA2 Encryption 847 The authenticated encryption algorithm takes as input four octet 848 strings: a secret key K, a plaintext P, associated data A, and an 849 initialization vector IV. The authenticated ciphertext value E and 850 the authentication tag value T are provided as outputs. The data in 851 the plaintext are encrypted and authenticated, and the associated 852 data are authenticated, but not encrypted. 854 The encryption process is as follows, or uses an equivalent set of 855 steps: 857 1. The secondary keys MAC_KEY and ENC_KEY are generated from the 858 input key K as follows. Each of these two keys is an octet 859 string. 861 MAC_KEY consists of the initial MAC_KEY_LEN octets of K, in 862 order. 864 ENC_KEY consists of the final ENC_KEY_LEN octets of K, in 865 order. 867 Here we denote the number of octets in the MAC_KEY as 868 MAC_KEY_LEN, and the number of octets in ENC_KEY as ENC_KEY_LEN; 869 the values of these parameters are specified by the AEAD 870 algorithms (in Section 4.8.3 and Section 4.8.4). The number of 871 octets in the input key K is the sum of MAC_KEY_LEN and 872 ENC_KEY_LEN. When generating the secondary keys from K, MAC_KEY 873 and ENC_KEY MUST NOT overlap. Note that the MAC key comes before 874 the encryption key in the input key K; this is in the opposite 875 order of the algorithm names in the identifier 876 "AES_CBC_HMAC_SHA2". 878 2. The Initialization Vector (IV) used is a 128 bit value generated 879 randomly or pseudorandomly for use in the cipher. 881 3. The plaintext is CBC encrypted using PKCS #5 padding using 882 ENC_KEY as the key, and the IV. We denote the ciphertext output 883 from this step as E. 885 4. The octet string AL is equal to the number of bits in A expressed 886 as a 64-bit unsigned integer in network byte order. 888 5. A message authentication tag T is computed by applying HMAC 889 [RFC2104] to the following data, in order: 891 the associated data A, 893 the initialization vector IV, 895 the ciphertext E computed in the previous step, and 897 the octet string AL defined above. 899 The string MAC_KEY is used as the MAC key. We denote the output 900 of the MAC computed in this step as M. The first T_LEN bits of M 901 are used as T. 903 6. The Ciphertext E and the Authentication Tag T are returned as the 904 outputs of the authenticated encryption. 906 The encryption process can be illustrated as follows. Here K, P, A, 907 IV, and E denote the key, plaintext, associated data, initialization 908 vector, and ciphertext, respectively. 910 MAC_KEY = initial MAC_KEY_LEN bytes of K, 912 ENC_KEY = final ENC_KEY_LEN bytes of K, 914 E = CBC-PKCS5-ENC(ENC_KEY, P), 916 M = MAC(MAC_KEY, A || IV || E || AL), 918 T = initial T_LEN bytes of M. 920 4.8.2.2. AES_CBC_HMAC_SHA2 Decryption 922 The authenticated decryption operation has four inputs: K, A, E, and 923 T as defined above. It has only a single output, either a plaintext 924 value P or a special symbol FAIL that indicates that the inputs are 925 not authentic. The authenticated decryption algorithm is as follows, 926 or uses an equivalent set of steps: 928 1. The secondary keys MAC_KEY and ENC_KEY are generated from the 929 input key K as in Step 1 of Section 4.8.2.1. 931 2. The integrity and authenticity of A and E are checked by 932 computing an HMAC with the inputs as in Step 5 of 933 Section 4.8.2.1. The value T, from the previous step, is 934 compared to the first MAC_KEY length bits of the HMAC output. If 935 those values are identical, then A and E are considered valid, 936 and processing is continued. Otherwise, all of the data used in 937 the MAC validation are discarded, and the AEAD decryption 938 operation returns an indication that it failed, and the operation 939 halts. (But see Section 10 of [JWE] for security considerations 940 on thwarting timing attacks.) 942 3. The value E is decrypted and the PKCS #5 padding is removed. The 943 value IV is used as the initialization vector. The value ENC_KEY 944 is used as the decryption key. 946 4. The plaintext value is returned. 948 4.8.3. AES_128_CBC_HMAC_SHA_256 950 This algorithm is a concrete instantiation of the generic 951 AES_CBC_HMAC_SHA2 algorithm above. It uses the HMAC message 952 authentication code [RFC2104] with the SHA-256 hash function [SHS] to 953 provide message authentication, with the HMAC output truncated to 128 954 bits, corresponding to the HMAC-SHA-256-128 algorithm defined in 955 [RFC4868]. For encryption, it uses AES in the cipher block chaining 956 (CBC) mode of operation as defined in Section 6.2 of [NIST.800-38A], 957 with PKCS #5 padding. 959 The input key K is 32 octets long. 961 The AES CBC IV is 16 octets long. ENC_KEY_LEN is 16 octets. 963 The SHA-256 hash algorithm is used in HMAC. MAC_KEY_LEN is 16 964 octets. The HMAC-SHA-256 output is truncated to T_LEN=16 octets, by 965 stripping off the final 16 octets. 967 4.8.4. AES_256_CBC_HMAC_SHA_512 969 AES_256_CBC_HMAC_SHA_512 is based on AES_128_CBC_HMAC_SHA_256, but 970 with the following differences: 972 A 256 bit AES CBC key is used instead of 128. 974 SHA-512 is used in HMAC instead of SHA-256. 976 ENC_KEY_LEN is 32 octets. 978 MAC_KEY_LEN is 32 octets. 980 The length of the input key K is 64 octets. 982 The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of 983 16 octets. 985 4.8.5. Plaintext Encryption with AES_CBC_HMAC_SHA2 987 The algorithm value "A128CBC-HS256" is used as the "alg" value when 988 using AES_128_CBC_HMAC_SHA_256 with JWE. The algorithm value 989 "A256CBC-HS512" is used as the "alg" value when using 990 AES_256_CBC_HMAC_SHA_512 with JWE. In both cases, the Additional 991 Authenticated Data value used is the concatenation of the Encoded JWE 992 Header value, a period ('.') character, and the Encoded JWE Encrypted 993 Key. The JWE Initialization Vector value used is the IV value. 995 4.9. Plaintext Encryption with AES GCM 997 This section defines the specifics of encrypting the JWE Plaintext 998 with Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) 999 [AES] [NIST.800-38D] using 128 or 256 bit keys. The "enc" header 1000 parameter values "A128GCM" or "A256GCM" are used in this case. 1002 The CEK is used as the encryption key. 1004 Use of an initialization vector of size 96 bits is REQUIRED with this 1005 algorithm. 1007 The Additional Authenticated Data parameter is used to secure the 1008 header and key values. (The Additional Authenticated Data value used 1009 is the octets of the ASCII representation of the concatenation of the 1010 Encoded JWE Header, a period ('.') character, and the Encoded JWE 1011 Encrypted Key per Section 5 of the JWE specification.) This same 1012 Additional Authenticated Data value is used when decrypting as well. 1014 The requested size of the Authentication Tag output MUST be 128 bits, 1015 regardless of the key size. 1017 The JWE Authentication Tag is set to be the Authentication Tag value 1018 produced by the encryption. During decryption, the received JWE 1019 Authentication Tag is used as the Authentication Tag value. 1021 An example using this algorithm is shown in Appendix A.1 of [JWE]. 1023 Note: AES GCM MUST NOT be used when using the JWE JSON Serialization 1024 for multiple recipients, since this would result in the same 1025 Initialization Vector and Plaintext values being used for multiple 1026 GCM encryptions. This is prohibited by the GCM specification because 1027 of severe security vulnerabilities that would result, were GCM used 1028 in this way. 1030 4.10. Additional Encryption Algorithms and Parameters 1032 Additional algorithms MAY be used to protect JWEs with corresponding 1033 "alg" (algorithm) and "enc" (encryption method) header parameter 1034 values being defined to refer to them. New "alg" and "enc" header 1035 parameter values SHOULD either be registered in the IANA JSON Web 1036 Signature and Encryption Algorithms registry Section 6.1 or be a 1037 value that contains a Collision Resistant Namespace. In particular, 1038 it is permissible to use the algorithm identifiers defined in XML 1039 Encryption [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 1040 [W3C.CR-xmlenc-core1-20120313], and related specifications as "alg" 1041 and "enc" values. 1043 As indicated by the common registry, JWSs and JWEs share a common 1044 "alg" value space. The values used by the two specifications MUST be 1045 distinct, as the "alg" value can be used to determine whether the 1046 object is a JWS or JWE. 1048 Likewise, additional reserved Header Parameter Names MAY be defined 1049 via the IANA JSON Web Signature and Encryption Header Parameters 1050 registry [JWS]. As indicated by the common registry, JWSs and JWEs 1051 share a common header parameter space; when a parameter is used by 1052 both specifications, its usage must be compatible between the 1053 specifications. 1055 5. Cryptographic Algorithms for JWK 1057 A JSON Web Key (JWK) [JWK] is a JavaScript Object Notation (JSON) 1058 [RFC4627] data structure that represents a cryptographic key. A JSON 1059 Web Key Set (JWK Set) is a JSON data structure for representing a set 1060 of JWKs. This section specifies a set of key types to be used for 1061 those keys and the key type specific parameters for representing 1062 those keys. Parameters are defined for public, private, and 1063 symmetric keys. 1065 5.1. "kty" (Key Type) Parameter Values for JWK 1067 The table below is the set of "kty" (key type) parameter values that 1068 are defined by this specification for use in JWKs. 1070 +-------------+----------------------------------+------------------+ 1071 | kty | Key Type | Implementation | 1072 | Parameter | | Requirements | 1073 | Value | | | 1074 +-------------+----------------------------------+------------------+ 1075 | EC | Elliptic Curve [DSS] key type | RECOMMENDED+ | 1076 | RSA | RSA [RFC3447] key type | REQUIRED | 1077 | oct | Octet sequence key type (used to | RECOMMENDED+ | 1078 | | represent symmetric keys) | | 1079 +-------------+----------------------------------+------------------+ 1081 All the names are short because a core goal of JWK is for the 1082 representations to be compact. However, there is no a priori length 1083 restriction on "kty" values. 1085 The use of "+" in the Implementation Requirements indicates that the 1086 requirement strength is likely to be increased in a future version of 1087 the specification. 1089 5.2. JWK Parameters for Elliptic Curve Keys 1091 JWKs can represent Elliptic Curve [DSS] keys. In this case, the 1092 "kty" member value MUST be "EC". 1094 5.2.1. JWK Parameters for Elliptic Curve Public Keys 1096 These members MUST be present for Elliptic Curve public keys: 1098 5.2.1.1. "crv" (Curve) Parameter 1100 The "crv" (curve) member identifies the cryptographic curve used with 1101 the key. Curve values from [DSS] used by this specification are: 1103 o "P-256" 1105 o "P-384" 1107 o "P-521" 1109 Additional "crv" values MAY be used, provided they are understood by 1110 implementations using that Elliptic Curve key. The "crv" value is a 1111 case sensitive string. 1113 5.2.1.2. "x" (X Coordinate) Parameter 1115 The "x" (x coordinate) member contains the x coordinate for the 1116 elliptic curve point. It is represented as the base64url encoding of 1117 the coordinate's big endian representation as an octet sequence. The 1118 array representation MUST NOT be shortened to omit any leading zero 1119 octets contained in the value. For instance, when representing 521 1120 bit integers, the octet sequence to be base64url encoded MUST contain 1121 66 octets, including any leading zero octets. 1123 5.2.1.3. "y" (Y Coordinate) Parameter 1125 The "y" (y coordinate) member contains the y coordinate for the 1126 elliptic curve point. It is represented as the base64url encoding of 1127 the coordinate's big endian representation as an octet sequence. The 1128 array representation MUST NOT be shortened to omit any leading zero 1129 octets contained in the value. For instance, when representing 521 1130 bit integers, the octet sequence to be base64url encoded MUST contain 1131 66 octets, including any leading zero octets. 1133 5.2.2. JWK Parameters for Elliptic Curve Private Keys 1135 In addition to the members used to represent Elliptic Curve public 1136 keys, the following member MUST be present to represent Elliptic 1137 Curve private keys: 1139 5.2.2.1. "d" (ECC Private Key) Parameter 1141 The "d" (ECC private key) member contains the Elliptic Curve private 1142 key value. It is represented as the base64url encoding of the 1143 value's unsigned big endian representation as an octet sequence. The 1144 array representation MUST NOT be shortened to omit any leading zero 1145 octets. For instance, when representing 521 bit integers, the octet 1146 sequence to be base64url encoded MUST contain 66 octets, including 1147 any leading zero octets. 1149 5.3. JWK Parameters for RSA Keys 1151 JWKs can represent RSA [RFC3447] keys. In this case, the "kty" 1152 member value MUST be "RSA". 1154 5.3.1. JWK Parameters for RSA Public Keys 1156 These members MUST be present for RSA public keys: 1158 5.3.1.1. "n" (Modulus) Parameter 1160 The "n" (modulus) member contains the modulus value for the RSA 1161 public key. It is represented as the base64url encoding of the 1162 value's unsigned big endian representation as an octet sequence. The 1163 array representation MUST NOT be shortened to omit any leading zero 1164 octets. For instance, when representing 2048 bit integers, the octet 1165 sequence to be base64url encoded MUST contain 256 octets, including 1166 any leading zero octets. 1168 5.3.1.2. "e" (Exponent) Parameter 1170 The "e" (exponent) member contains the exponent value for the RSA 1171 public key. It is represented as the base64url encoding of the 1172 value's unsigned big endian representation as an octet sequence. The 1173 array representation MUST utilize the minimum number of octets to 1174 represent the value. For instance, when representing the value 1175 65537, the octet sequence to be base64url encoded MUST consist of the 1176 three octets [1, 0, 1]. 1178 5.3.2. JWK Parameters for RSA Private Keys 1180 In addition to the members used to represent RSA public keys, the 1181 following members are used to represent RSA private keys. All are 1182 REQUIRED for RSA private keys except for "oth", which is sometimes 1183 REQUIRED and sometimes MUST NOT be present, as described below. 1185 5.3.2.1. "d" (Private Exponent) Parameter 1187 The "d" (private exponent) member contains the private exponent value 1188 for the RSA private key. It is represented as the base64url encoding 1189 of the value's unsigned big endian representation as an octet 1190 sequence. The array representation MUST NOT be shortened to omit any 1191 leading zero octets. For instance, when representing 2048 bit 1192 integers, the octet sequence to be base64url encoded MUST contain 256 1193 octets, including any leading zero octets. 1195 5.3.2.2. "p" (First Prime Factor) Parameter 1197 The "p" (first prime factor) member contains the first prime factor, 1198 a positive integer. It is represented as the base64url encoding of 1199 the value's unsigned big endian representation as an octet sequence. 1201 5.3.2.3. "q" (Second Prime Factor) Parameter 1203 The "q" (second prime factor) member contains the second prime 1204 factor, a positive integer. It is represented as the base64url 1205 encoding of the value's unsigned big endian representation as an 1206 octet sequence. 1208 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter 1210 The "dp" (first factor CRT exponent) member contains the Chinese 1211 Remainder Theorem (CRT) exponent of the first factor, a positive 1212 integer. It is represented as the base64url encoding of the value's 1213 unsigned big endian representation as an octet sequence. 1215 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter 1217 The "dq" (second factor CRT exponent) member contains the Chinese 1218 Remainder Theorem (CRT) exponent of the second factor, a positive 1219 integer. It is represented as the base64url encoding of the value's 1220 unsigned big endian representation as an octet sequence. 1222 5.3.2.6. "qi" (First CRT Coefficient) Parameter 1224 The "dp" (first CRT coefficient) member contains the Chinese 1225 Remainder Theorem (CRT) coefficient of the second factor, a positive 1226 integer. It is represented as the base64url encoding of the value's 1227 unsigned big endian representation as an octet sequence. 1229 5.3.2.7. "oth" (Other Primes Info) Parameter 1231 The "oth" (other primes info) member contains an array of information 1232 about any third and subsequent primes, should they exist. When only 1233 two primes have been used (the normal case), this parameter MUST be 1234 omitted. When three or more primes have been used, the number of 1235 array elements MUST be the number of primes used minus two. Each 1236 array element MUST be an object with the following members: 1238 5.3.2.7.1. "r" (Prime Factor) 1240 The "r" (prime factor) parameter within an "oth" array member 1241 represents the value of a subsequent prime factor, a positive 1242 integer. It is represented as the base64url encoding of the value's 1243 unsigned big endian representation as an octet sequence. 1245 5.3.2.7.2. "d" (Factor CRT Exponent) 1247 The "d" (Factor CRT Exponent) parameter within an "oth" array member 1248 represents the CRT exponent of the corresponding prime factor, a 1249 positive integer. It is represented as the base64url encoding of the 1250 value's unsigned big endian representation as an octet sequence. 1252 5.3.2.7.3. "t" (Factor CRT Coefficient) 1254 The "t" (factor CRT coefficient) parameter within an "oth" array 1255 member represents the CRT coefficient of the corresponding prime 1256 factor, a positive integer. It is represented as the base64url 1257 encoding of the value's unsigned big endian representation as an 1258 octet sequence. 1260 5.3.3. JWK Parameters for Symmetric Keys 1262 When the JWK "kty" member value is "oct" (octet sequence), the 1263 following member is used to represent a symmetric key (or another key 1264 whose value is a single octet sequence): 1266 5.3.3.1. "k" (Key Value) Parameter 1268 The "k" (key value) member contains the value of the symmetric (or 1269 other single-valued) key. It is represented as the base64url 1270 encoding of the octet sequence containing the key value. 1272 5.4. Additional Key Types and Parameters 1274 Keys using additional key types can be represented using JWK data 1275 structures with corresponding "kty" (key type) parameter values being 1276 defined to refer to them. New "kty" parameter values SHOULD either 1277 be registered in the IANA JSON Web Key Types registry Section 6.2 or 1278 be a value that contains a Collision Resistant Namespace. 1280 Likewise, parameters for representing keys for additional key types 1281 or additional key properties SHOULD either be registered in the IANA 1282 JSON Web Key Parameters registry [JWK] or be a value that contains a 1283 Collision Resistant Namespace. 1285 6. IANA Considerations 1287 The following registration procedure is used for all the registries 1288 established by this specification. 1290 Values are registered with a Specification Required [RFC5226] after a 1291 two-week review period on the [TBD]@ietf.org mailing list, on the 1292 advice of one or more Designated Experts. However, to allow for the 1293 allocation of values prior to publication, the Designated Expert(s) 1294 may approve registration once they are satisfied that such a 1295 specification will be published. 1297 Registration requests must be sent to the [TBD]@ietf.org mailing list 1298 for review and comment, with an appropriate subject (e.g., "Request 1299 for access token type: example"). [[ Note to RFC-EDITOR: The name of 1300 the mailing list should be determined in consultation with the IESG 1301 and IANA. Suggested name: jose-reg-review. ]] 1303 Within the review period, the Designated Expert(s) will either 1304 approve or deny the registration request, communicating this decision 1305 to the review list and IANA. Denials should include an explanation 1306 and, if applicable, suggestions as to how to make the request 1307 successful. 1309 IANA must only accept registry updates from the Designated Expert(s) 1310 and should direct all requests for registration to the review mailing 1311 list. 1313 6.1. JSON Web Signature and Encryption Algorithms Registry 1315 This specification establishes the IANA JSON Web Signature and 1316 Encryption Algorithms registry for values of the JWS and JWE "alg" 1317 (algorithm) and "enc" (encryption method) header parameters. The 1318 registry records the algorithm name, the algorithm usage locations 1319 from the set "alg" and "enc", implementation requirements, and a 1320 reference to the specification that defines it. The same algorithm 1321 name MAY be registered multiple times, provided that the sets of 1322 usage locations are disjoint. The implementation requirements of an 1323 algorithm MAY be changed over time by the Designated Experts(s) as 1324 the cryptographic landscape evolves, for instance, to change the 1325 status of an algorithm to DEPRECATED, or to change the status of an 1326 algorithm from OPTIONAL to RECOMMENDED or REQUIRED. 1328 6.1.1. Template 1330 Algorithm Name: 1331 The name requested (e.g., "example"). This name is case 1332 sensitive. Names that match other registered names in a case 1333 insensitive manner SHOULD NOT be accepted. 1335 Algorithm Usage Location(s): 1336 The algorithm usage, which must be one or more of the values "alg" 1337 or "enc". 1339 Implementation Requirements: 1340 The algorithm implementation requirements, which must be one the 1341 words REQUIRED, RECOMMENDED, OPTIONAL, or DEPRECATED. Optionally, 1342 the word can be followed by a "+" or "-". The use of "+" 1343 indicates that the requirement strength is likely to be increased 1344 in a future version of the specification. The use of "-" 1345 indicates that the requirement strength is likely to be decreased 1346 in a future version of the specification. 1348 Change Controller: 1349 For Standards Track RFCs, state "IETF". For others, give the name 1350 of the responsible party. Other details (e.g., postal address, 1351 email address, home page URI) may also be included. 1353 Specification Document(s): 1354 Reference to the document(s) that specify the parameter, 1355 preferably including URI(s) that can be used to retrieve copies of 1356 the document(s). An indication of the relevant sections may also 1357 be included but is not required. 1359 6.1.2. Initial Registry Contents 1361 o Algorithm Name: "HS256" 1362 o Algorithm Usage Location(s): "alg" 1363 o Implementation Requirements: REQUIRED 1364 o Change Controller: IETF 1365 o Specification Document(s): Section 3.1 of [[ this document ]] 1367 o Algorithm Name: "HS384" 1368 o Algorithm Usage Location(s): "alg" 1369 o Implementation Requirements: OPTIONAL 1370 o Change Controller: IETF 1371 o Specification Document(s): Section 3.1 of [[ this document ]] 1373 o Algorithm Name: "HS512" 1374 o Algorithm Usage Location(s): "alg" 1375 o Implementation Requirements: OPTIONAL 1376 o Change Controller: IETF 1377 o Specification Document(s): Section 3.1 of [[ this document ]] 1379 o Algorithm Name: "RS256" 1380 o Algorithm Usage Location(s): "alg" 1381 o Implementation Requirements: RECOMMENDED 1382 o Change Controller: IETF 1383 o Specification Document(s): Section 3.1 of [[ this document ]] 1385 o Algorithm Name: "RS384" 1386 o Algorithm Usage Location(s): "alg" 1387 o Implementation Requirements: OPTIONAL 1388 o Change Controller: IETF 1389 o Specification Document(s): Section 3.1 of [[ this document ]] 1391 o Algorithm Name: "RS512" 1392 o Algorithm Usage Location(s): "alg" 1393 o Implementation Requirements: OPTIONAL 1394 o Change Controller: IETF 1395 o Specification Document(s): Section 3.1 of [[ this document ]] 1397 o Algorithm Name: "ES256" 1398 o Algorithm Usage Location(s): "alg" 1399 o Implementation Requirements: RECOMMENDED+ 1400 o Change Controller: IETF 1401 o Specification Document(s): Section 3.1 of [[ this document ]] 1403 o Algorithm Name: "ES384" 1404 o Algorithm Usage Location(s): "alg" 1405 o Implementation Requirements: OPTIONAL 1406 o Change Controller: IETF 1407 o Specification Document(s): Section 3.1 of [[ this document ]] 1409 o Algorithm Name: "ES512" 1410 o Algorithm Usage Location(s): "alg" 1411 o Implementation Requirements: OPTIONAL 1412 o Change Controller: IETF 1413 o Specification Document(s): Section 3.1 of [[ this document ]] 1415 o Algorithm Name: "none" 1416 o Algorithm Usage Location(s): "alg" 1417 o Implementation Requirements: REQUIRED 1418 o Change Controller: IETF 1419 o Specification Document(s): Section 3.1 of [[ this document ]] 1421 o Algorithm Name: "RSA1_5" 1422 o Algorithm Usage Location(s): "alg" 1423 o Implementation Requirements: REQUIRED 1424 o Change Controller: IETF 1425 o Specification Document(s): Section 4.1 of [[ this document ]] 1427 o Algorithm Name: "RSA-OAEP" 1428 o Algorithm Usage Location(s): "alg" 1429 o Implementation Requirements: OPTIONAL 1430 o Change Controller: IETF 1431 o Specification Document(s): Section 4.1 of [[ this document ]] 1433 o Algorithm Name: "A128KW" 1434 o Algorithm Usage Location(s): "alg" 1435 o Implementation Requirements: RECOMMENDED 1436 o Change Controller: IETF 1437 o Specification Document(s): Section 4.1 of [[ this document ]] 1439 o Algorithm Name: "A256KW" 1440 o Algorithm Usage Location(s): "alg" 1441 o Implementation Requirements: RECOMMENDED 1442 o Change Controller: IETF 1443 o Specification Document(s): Section 4.1 of [[ this document ]] 1445 o Algorithm Name: "dir" 1446 o Algorithm Usage Location(s): "alg" 1447 o Implementation Requirements: RECOMMENDED 1448 o Change Controller: IETF 1449 o Specification Document(s): Section 4.1 of [[ this document ]] 1451 o Algorithm Name: "ECDH-ES" 1452 o Algorithm Usage Location(s): "alg" 1453 o Implementation Requirements: RECOMMENDED+ 1454 o Change Controller: IETF 1455 o Specification Document(s): Section 4.1 of [[ this document ]] 1457 o Algorithm Name: "ECDH-ES+A128KW" 1458 o Algorithm Usage Location(s): "alg" 1459 o Implementation Requirements: RECOMMENDED 1460 o Change Controller: IETF 1461 o Specification Document(s): Section 4.1 of [[ this document ]] 1463 o Algorithm Name: "ECDH-ES+A256KW" 1464 o Algorithm Usage Location(s): "alg" 1465 o Implementation Requirements: RECOMMENDED 1466 o Change Controller: IETF 1467 o Specification Document(s): Section 4.1 of [[ this document ]] 1469 o Algorithm Name: "A128CBC-HS256" 1470 o Algorithm Usage Location(s): "enc" 1471 o Implementation Requirements: REQUIRED 1472 o Change Controller: IETF 1473 o Specification Document(s): Section 4.2 of [[ this document ]] 1475 o Algorithm Name: "A256CBC-HS512" 1476 o Algorithm Usage Location(s): "enc" 1477 o Implementation Requirements: REQUIRED 1478 o Change Controller: IETF 1479 o Specification Document(s): Section 4.2 of [[ this document ]] 1481 o Algorithm Name: "A128GCM" 1482 o Algorithm Usage Location(s): "enc" 1483 o Implementation Requirements: RECOMMENDED 1484 o Change Controller: IETF 1485 o Specification Document(s): Section 4.2 of [[ this document ]] 1486 o Algorithm Name: "A256GCM" 1487 o Algorithm Usage Location(s): "enc" 1488 o Implementation Requirements: RECOMMENDED 1489 o Change Controller: IETF 1490 o Specification Document(s): Section 4.2 of [[ this document ]] 1492 6.2. JSON Web Key Types Registry 1494 This specification establishes the IANA JSON Web Key Types registry 1495 for values of the JWK "kty" (key type) parameter. The registry 1496 records the "kty" value and a reference to the specification that 1497 defines it. This specification registers the values defined in 1498 Section 5.1. 1500 6.2.1. Registration Template 1502 "kty" Parameter Value: 1503 The name requested (e.g., "example"). This name is case 1504 sensitive. Names that match other registered names in a case 1505 insensitive manner SHOULD NOT be accepted. 1507 Change Controller: 1508 For Standards Track RFCs, state "IETF". For others, give the name 1509 of the responsible party. Other details (e.g., postal address, 1510 email address, home page URI) may also be included. 1512 Implementation Requirements: 1513 The algorithm implementation requirements, which must be one the 1514 words REQUIRED, RECOMMENDED, OPTIONAL, or DEPRECATED. Optionally, 1515 the word can be followed by a "+" or "-". The use of "+" 1516 indicates that the requirement strength is likely to be increased 1517 in a future version of the specification. The use of "-" 1518 indicates that the requirement strength is likely to be decreased 1519 in a future version of the specification. 1521 Specification Document(s): 1522 Reference to the document(s) that specify the parameter, 1523 preferably including URI(s) that can be used to retrieve copies of 1524 the document(s). An indication of the relevant sections may also 1525 be included but is not required. 1527 6.2.2. Initial Registry Contents 1529 o "kty" Parameter Value: "EC" 1530 o Implementation Requirements: RECOMMENDED+ 1531 o Change Controller: IETF 1532 o Specification Document(s): Section 5.1 of [[ this document ]] 1534 o "kty" Parameter Value: "RSA" 1535 o Implementation Requirements: REQUIRED 1536 o Change Controller: IETF 1537 o Specification Document(s): Section 5.1 of [[ this document ]] 1539 o "kty" Parameter Value: "oct" 1540 o Implementation Requirements: RECOMMENDED+ 1541 o Change Controller: IETF 1542 o Specification Document(s): Section 5.1 of [[ this document ]] 1544 6.3. JSON Web Key Parameters Registration 1546 This specification registers the parameter names defined in Sections 1547 5.2, 5.3, and 5.3.3 in the IANA JSON Web Key Parameters registry 1548 [JWK]. 1550 6.3.1. Registry Contents 1552 o Parameter Name: "crv" 1553 o Change Controller: IETF 1554 o Specification Document(s): Section 5.2.1.1 of [[ this document ]] 1556 o Parameter Name: "x" 1557 o Change Controller: IETF 1558 o Specification Document(s): Section 5.2.1.2 of [[ this document ]] 1560 o Parameter Name: "y" 1561 o Change Controller: IETF 1562 o Specification Document(s): Section 5.2.1.3 of [[ this document ]] 1564 o Parameter Name: "d" 1565 o Change Controller: IETF 1566 o Specification Document(s): Section 5.2.2.1 of [[ this document ]] 1568 o Parameter Name: "n" 1569 o Change Controller: IETF 1570 o Specification Document(s): Section 5.3.1.1 of [[ this document ]] 1572 o Parameter Name: "e" 1573 o Change Controller: IETF 1574 o Specification Document(s): Section 5.3.1.2 of [[ this document ]] 1576 o Parameter Name: "d" 1577 o Change Controller: IETF 1578 o Specification Document(s): Section 5.3.2.1 of [[ this document ]] 1580 o Parameter Name: "p" 1581 o Change Controller: IETF 1582 o Specification Document(s): Section 5.3.2.2 of [[ this document ]] 1584 o Parameter Name: "q" 1585 o Change Controller: IETF 1586 o Specification Document(s): Section 5.3.2.3 of [[ this document ]] 1588 o Parameter Name: "dp" 1589 o Change Controller: IETF 1590 o Specification Document(s): Section 5.3.2.4 of [[ this document ]] 1592 o Parameter Name: "dq" 1593 o Change Controller: IETF 1594 o Specification Document(s): Section 5.3.2.5 of [[ this document ]] 1596 o Parameter Name: "qi" 1597 o Change Controller: IETF 1598 o Specification Document(s): Section 5.3.2.6 of [[ this document ]] 1600 o Parameter Name: "oth" 1601 o Change Controller: IETF 1602 o Specification Document(s): Section 5.3.2.7 of [[ this document ]] 1604 o Parameter Name: "k" 1605 o Change Controller: IETF 1606 o Specification Document(s): Section 5.3.3.1 of [[ this document ]] 1608 7. Security Considerations 1610 All of the security issues faced by any cryptographic application 1611 must be faced by a JWS/JWE/JWK agent. Among these issues are 1612 protecting the user's private and symmetric keys, preventing various 1613 attacks, and helping the user avoid mistakes such as inadvertently 1614 encrypting a message for the wrong recipient. The entire list of 1615 security considerations is beyond the scope of this document, but 1616 some significant considerations are listed here. 1618 The security considerations in [AES], [DSS], [JWE], [JWK], [JWS], 1619 [NIST.800-38A], [NIST.800-38D], [NIST.800-56A], [RFC2104], [RFC3394], 1620 [RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this 1621 specification. 1623 Eventually the algorithms and/or key sizes currently described in 1624 this specification will no longer be considered sufficiently secure 1625 and will be removed. Therefore, implementers and deployments must be 1626 prepared for this eventuality. 1628 Algorithms of matching strengths should be used together whenever 1629 possible. For instance, when AES Key Wrap is used with a given key 1630 size, using the same key size is recommended when AES GCM is also 1631 used. 1633 While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not 1634 to adopt RSASSA-PKCS1 for new applications and instead requests that 1635 people transition to RSASSA-PSS, this specification does include 1636 RSASSA-PKCS1, for interoperability reasons, because it commonly 1637 implemented. 1639 Keys used with RSAES-PKCS1-v1_5 must follow the constraints in 1640 Section 7.2 of RFC 3447 [RFC3447]. In particular, keys with a low 1641 public key exponent value must not be used. 1643 Plaintext JWSs (JWSs that use the "alg" value "none") provide no 1644 integrity protection. Thus, they must only be used in contexts where 1645 the payload is secured by means other than a digital signature or MAC 1646 value, or need not be secured. 1648 Receiving agents that validate signatures and sending agents that 1649 encrypt messages need to be cautious of cryptographic processing 1650 usage when validating signatures and encrypting messages using keys 1651 larger than those mandated in this specification. An attacker could 1652 send certificates with keys that would result in excessive 1653 cryptographic processing, for example, keys larger than those 1654 mandated in this specification, which could swamp the processing 1655 element. Agents that use such keys without first validating the 1656 certificate to a trust anchor are advised to have some sort of 1657 cryptographic resource management system to prevent such attacks. 1659 8. References 1661 8.1. Normative References 1663 [AES] National Institute of Standards and Technology (NIST), 1664 "Advanced Encryption Standard (AES)", FIPS PUB 197, 1665 November 2001. 1667 [DSS] National Institute of Standards and Technology, "Digital 1668 Signature Standard (DSS)", FIPS PUB 186-3, June 2009. 1670 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 1671 Encryption (JWE)", draft-ietf-jose-json-web-encryption 1672 (work in progress), April 2013. 1674 [JWK] Jones, M., "JSON Web Key (JWK)", 1675 draft-ietf-jose-json-web-key (work in progress), 1676 April 2013. 1678 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1679 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1680 in progress), April 2013. 1682 [NIST.800-38A] 1683 National Institute of Standards and Technology (NIST), 1684 "Recommendation for Block Cipher Modes of Operation", 1685 NIST PUB 800-38A, December 2001. 1687 [NIST.800-38D] 1688 National Institute of Standards and Technology (NIST), 1689 "Recommendation for Block Cipher Modes of Operation: 1690 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 1691 December 2001. 1693 [NIST.800-56A] 1694 National Institute of Standards and Technology (NIST), 1695 "Recommendation for Pair-Wise Key Establishment Schemes 1696 Using Discrete Logarithm Cryptography (Revised)", NIST PUB 1697 800-56A, March 2007. 1699 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1700 Hashing for Message Authentication", RFC 2104, 1701 February 1997. 1703 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1704 Requirement Levels", BCP 14, RFC 2119, March 1997. 1706 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 1707 (AES) Key Wrap Algorithm", RFC 3394, September 2002. 1709 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1710 10646", STD 63, RFC 3629, November 2003. 1712 [RFC4627] Crockford, D., "The application/json Media Type for 1713 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1715 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1716 Encodings", RFC 4648, October 2006. 1718 [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA- 1719 384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007. 1721 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 1722 Encryption", RFC 5116, January 2008. 1724 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1725 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1726 May 2008. 1728 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 1729 Curve Cryptography Algorithms", RFC 6090, February 2011. 1731 [SHS] National Institute of Standards and Technology, "Secure 1732 Hash Standard (SHS)", FIPS PUB 180-3, October 2008. 1734 [USASCII] American National Standards Institute, "Coded Character 1735 Set -- 7-bit American Standard Code for Information 1736 Interchange", ANSI X3.4, 1986. 1738 8.2. Informative References 1740 [CanvasApp] 1741 Facebook, "Canvas Applications", 2010. 1743 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1744 McGrew, D. and K. Paterson, "Authenticated Encryption with 1745 AES-CBC and HMAC-SHA", 1746 draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), 1747 October 2012. 1749 [I-D.rescorla-jsms] 1750 Rescorla, E. and J. Hildebrand, "JavaScript Message 1751 Security Format", draft-rescorla-jsms-00 (work in 1752 progress), March 2011. 1754 [JCA] Oracle, "Java Cryptography Architecture", 2011. 1756 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1757 Encryption", September 2010. 1759 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 1760 September 2010. 1762 [MagicSignatures] 1763 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 1764 Signatures", January 2011. 1766 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 1767 Language) XML-Signature Syntax and Processing", RFC 3275, 1768 March 2002. 1770 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1771 Standards (PKCS) #1: RSA Cryptography Specifications 1772 Version 2.1", RFC 3447, February 2003. 1774 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1775 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1776 July 2005. 1778 [W3C.CR-xmldsig-core2-20120124] 1779 Eastlake, D., Reagle, J., Yiu, K., Solo, D., Datta, P., 1780 Hirsch, F., Cantor, S., and T. Roessler, "XML Signature 1781 Syntax and Processing Version 2.0", World Wide Web 1782 Consortium CR CR-xmldsig-core2-20120124, January 2012, 1783 . 1785 [W3C.CR-xmlenc-core1-20120313] 1786 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 1787 "XML Encryption Syntax and Processing Version 1.1", World 1788 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1789 March 2012, 1790 . 1792 [W3C.REC-xmlenc-core-20021210] 1793 Eastlake, D. and J. Reagle, "XML Encryption Syntax and 1794 Processing", World Wide Web Consortium Recommendation REC- 1795 xmlenc-core-20021210, December 2002, 1796 . 1798 Appendix A. Digital Signature/MAC Algorithm Identifier Cross-Reference 1800 This appendix contains a table cross-referencing the digital 1801 signature and MAC "alg" (algorithm) values used in this specification 1802 with the equivalent identifiers used by other standards and software 1803 packages. See XML DSIG [RFC3275], XML DSIG 2.0 1804 [W3C.CR-xmldsig-core2-20120124], and Java Cryptography Architecture 1805 [JCA] for more information about the names defined by those 1806 documents. 1808 +-------+-----+----------------------------+----------+-------------+ 1809 | Algor | JWS | XML DSIG | JCA | OID | 1810 | ithm | | | | | 1811 +-------+-----+----------------------------+----------+-------------+ 1812 | HMAC | HS2 | http://www.w3.org/2001/04/ | HmacSHA2 | 1.2.840.113 | 1813 | using | 56 | xmldsig-more#hmac-sha256 | 56 | 549.2.9 | 1814 | SHA-2 | | | | | 1815 | 56 | | | | | 1816 | hash | | | | | 1817 | algo | | | | | 1818 | rithm | | | | | 1819 | HMAC | HS3 | http://www.w3.org/2001/04/ | HmacSHA3 | 1.2.840.113 | 1820 | using | 84 | xmldsig-more#hmac-sha384 | 84 | 549.2.10 | 1821 | SHA-3 | | | | | 1822 | 84 | | | | | 1823 | hash | | | | | 1824 | algo | | | | | 1825 | rithm | | | | | 1826 | HMAC | HS5 | http://www.w3.org/2001/04/ | HmacSHA5 | 1.2.840.113 | 1827 | using | 12 | xmldsig-more#hmac-sha512 | 12 | 549.2.11 | 1828 | SHA-5 | | | | | 1829 | 12 | | | | | 1830 | hash | | | | | 1831 | algo | | | | | 1832 | rithm | | | | | 1833 | RSASS | RS2 | http://www.w3.org/2001/04/ | SHA256wi | 1.2.840.113 | 1834 | A | 56 | xmldsig-more#rsa-sha256 | thRSA | 549.1.1.11 | 1835 | usin | | | | | 1836 | gSHA- | | | | | 1837 | 256 | | | | | 1838 | has | | | | | 1839 | h alg | | | | | 1840 | orith | | | | | 1841 | m | | | | | 1842 | RSASS | RS3 | http://www.w3.org/2001/04/ | SHA384wi | 1.2.840.113 | 1843 | A | 84 | xmldsig-more#rsa-sha384 | thRSA | 549.1.1.12 | 1844 | usin | | | | | 1845 | gSHA- | | | | | 1846 | 384 | | | | | 1847 | has | | | | | 1848 | h alg | | | | | 1849 | orith | | | | | 1850 | m | | | | | 1851 | RSASS | RS5 | http://www.w3.org/2001/04/ | SHA512wi | 1.2.840.113 | 1852 | A | 12 | xmldsig-more#rsa-sha512 | thRSA | 549.1.1.13 | 1853 | usin | | | | | 1854 | gSHA- | | | | | 1855 | 512 | | | | | 1856 | has | | | | | 1857 | h alg | | | | | 1858 | orith | | | | | 1859 | m | | | | | 1860 | ECDSA | ES2 | http://www.w3.org/2001/04/ | SHA256wi | 1.2.840.100 | 1861 | using | 56 | xmldsig-more#ecdsa-sha256 | thECDSA | 45.4.3.2 | 1862 | P-256 | | | | | 1863 | curve | | | | | 1864 | and | | | | | 1865 | SHA-2 | | | | | 1866 | 56 | | | | | 1867 | hash | | | | | 1868 | algo | | | | | 1869 | rithm | | | | | 1870 | ECDSA | ES3 | http://www.w3.org/2001/04/ | SHA384wi | 1.2.840.100 | 1871 | using | 84 | xmldsig-more#ecdsa-sha384 | thECDSA | 45.4.3.3 | 1872 | P-384 | | | | | 1873 | curve | | | | | 1874 | and | | | | | 1875 | SHA-3 | | | | | 1876 | 84 | | | | | 1877 | hash | | | | | 1878 | algo | | | | | 1879 | rithm | | | | | 1880 | ECDSA | ES5 | http://www.w3.org/2001/04/ | SHA512wi | 1.2.840.100 | 1881 | using | 12 | xmldsig-more#ecdsa-sha512 | thECDSA | 45.4.3.4 | 1882 | P-521 | | | | | 1883 | curve | | | | | 1884 | and | | | | | 1885 | SHA-5 | | | | | 1886 | 12 | | | | | 1887 | hash | | | | | 1888 | algo | | | | | 1889 | rithm | | | | | 1890 +-------+-----+----------------------------+----------+-------------+ 1892 Appendix B. Encryption Algorithm Identifier Cross-Reference 1894 This appendix contains a table cross-referencing the "alg" 1895 (algorithm) and "enc" (encryption method) values used in this 1896 specification with the equivalent identifiers used by other standards 1897 and software packages. See XML Encryption 1899 [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 1900 [W3C.CR-xmlenc-core1-20120313], and Java Cryptography Architecture 1901 [JCA] for more information about the names defined by those 1902 documents. 1904 For the composite algorithms "A128CBC-HS256" and "A256CBC-HS512", the 1905 corresponding AES CBC algorithm identifiers are listed. 1907 +----------+--------+--------------------------+--------------------+ 1908 | Algorith | JWE | XML ENC | JCA | 1909 | m | | | | 1910 +----------+--------+--------------------------+--------------------+ 1911 | RSAES-PK | RSA1_5 | http://www.w3.org/2001/0 | RSA/ECB/PKCS1Paddi | 1912 | CS1-V1_5 | | 4/xmlenc#rsa-1_5 | ng | 1913 | RSAES | RSA-OA | http://www.w3.org/2001/0 | RSA/ECB/OAEPWithSH | 1914 | using | EP | 4/xmlenc#rsa-oaep-mgf1p | A-1AndMGF1Padding | 1915 | Optimal | | | | 1916 | Asymmetr | | | | 1917 | ic | | | | 1918 | Encrypt | | | | 1919 | ion | | | | 1920 | Paddin | | | | 1921 | g (OAEP) | | | | 1922 | Elliptic | ECDH-E | http://www.w3.org/2009/x | | 1923 | Curve | S | mlenc11#ECDH-ES | | 1924 | Diffie-H | | | | 1925 | ellman | | | | 1926 | Ephemer | | | | 1927 | alStatic | | | | 1928 | Advanced | A128KW | http://www.w3.org/2001/0 | | 1929 | Encrypti | | 4/xmlenc#kw-aes128 | | 1930 | on | | | | 1931 | Standar | | | | 1932 | d(AES) | | | | 1933 | Key Wra | | | | 1934 | pAlgorit | | | | 1935 | hmusing | | | | 1936 | 128 bi | | | | 1937 | t keys | | | | 1938 | AES Key | A256KW | http://www.w3.org/2001/0 | | 1939 | Wrap | | 4/xmlenc#kw-aes256 | | 1940 | Algorith | | | | 1941 | musing | | | | 1942 | 256 bit | | | | 1943 | keys | | | | 1944 | AES in | A128CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 1945 | Cipher | C-HS25 | 4/xmlenc#aes128-cbc | ng | 1946 | Block | 6 | | | 1947 | Chaining | | | | 1948 | (CBC) | | | | 1949 | mode | | | | 1950 | with | | | | 1951 | PKCS #5 | | | | 1952 | padding | | | | 1953 | using | | | | 1954 | 128 bit | | | | 1955 | keys | | | | 1956 | AES in | A256CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 1957 | CBC mode | C-HS51 | 4/xmlenc#aes256-cbc | ng | 1958 | with | 2 | | | 1959 | PKCS #5 | | | | 1960 | padding | | | | 1961 | using | | | | 1962 | 256 bit | | | | 1963 | keys | | | | 1964 | AES in | A128GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 1965 | Galois/C | M | mlenc11#aes128-gcm | | 1966 | ounter | | | | 1967 | Mode | | | | 1968 | (GCM) | | | | 1969 | using | | | | 1970 | 128 bit | | | | 1971 | keys | | | | 1972 | AES GCM | A256GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 1973 | using | M | mlenc11#aes256-gcm | | 1974 | 256 bit | | | | 1975 | keys | | | | 1976 +----------+--------+--------------------------+--------------------+ 1978 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms 1980 The following test cases can be used to validate implementations of 1981 the AES_CBC_HMAC_SHA2 algorithms defined in Section 4.8. They are 1982 also intended to correspond to test cases that may appear in a future 1983 version of [I-D.mcgrew-aead-aes-cbc-hmac-sha2], demonstrating that 1984 the cryptographic computations performed are the same. 1986 The variable names are those defined in Section 4.8. All values are 1987 hexadecimal. 1989 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 1991 AES_128_CBC_HMAC_SHA_256 1993 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 1994 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 1996 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 1998 ENC_KEY = 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2000 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2001 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2002 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2003 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2004 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2005 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2006 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2007 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2009 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2011 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2012 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2013 4b 65 72 63 6b 68 6f 66 66 73 2015 AL = 00 00 00 00 00 00 01 50 2017 E = c8 0e df a3 2d df 39 d5 ef 00 c0 b4 68 83 42 79 2018 a2 e4 6a 1b 80 49 f7 92 f7 6b fe 54 b9 03 a9 c9 2019 a9 4a c9 b4 7a d2 65 5c 5f 10 f9 ae f7 14 27 e2 2020 fc 6f 9b 3f 39 9a 22 14 89 f1 63 62 c7 03 23 36 2021 09 d4 5a c6 98 64 e3 32 1c f8 29 35 ac 40 96 c8 2022 6e 13 33 14 c5 40 19 e8 ca 79 80 df a4 b9 cf 1b 2023 38 4c 48 6f 3a 54 c5 10 78 15 8e e5 d7 9d e5 9f 2024 bd 34 d8 48 b3 d6 95 50 a6 76 46 34 44 27 ad e5 2025 4b 88 51 ff b5 98 f7 f8 00 74 b9 47 3c 82 e2 db 2027 M = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2028 e6 e5 45 82 47 65 15 f0 ad 9f 75 a2 b7 1c 73 ef 2030 T = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2032 C.2. Test Cases for AES_256_CBC_HMAC_SHA_512 2034 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2035 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2036 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2037 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2039 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2040 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2042 ENC_KEY = 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2043 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2045 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2046 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2047 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2048 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2049 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2050 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2051 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2052 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2054 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2056 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2057 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2058 4b 65 72 63 6b 68 6f 66 66 73 2060 AL = 00 00 00 00 00 00 01 50 2062 E = 4a ff aa ad b7 8c 31 c5 da 4b 1b 59 0d 10 ff bd 2063 3d d8 d5 d3 02 42 35 26 91 2d a0 37 ec bc c7 bd 2064 82 2c 30 1d d6 7c 37 3b cc b5 84 ad 3e 92 79 c2 2065 e6 d1 2a 13 74 b7 7f 07 75 53 df 82 94 10 44 6b 2066 36 eb d9 70 66 29 6a e6 42 7e a7 5c 2e 08 46 a1 2067 1a 09 cc f5 37 0d c8 0b fe cb ad 28 c7 3f 09 b3 2068 a3 b7 5e 66 2a 25 94 41 0a e4 96 b2 e2 e6 60 9e 2069 31 e6 e0 2c c8 37 f0 53 d2 1f 37 ff 4f 51 95 0b 2070 be 26 38 d0 9d d7 a4 93 09 30 80 6d 07 03 b1 f6 2072 M = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2073 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2074 fd 30 a5 65 c6 16 ff b2 f3 64 ba ec e6 8f c4 07 2075 53 bc fc 02 5d de 36 93 75 4a a1 f5 c3 37 3b 9c 2077 T = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2078 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2080 Appendix D. Acknowledgements 2082 Solutions for signing and encrypting JSON content were previously 2083 explored by Magic Signatures [MagicSignatures], JSON Simple Sign 2084 [JSS], Canvas Applications [CanvasApp], JSON Simple Encryption [JSE], 2085 and JavaScript Message Security Format [I-D.rescorla-jsms], all of 2086 which influenced this draft. 2088 The Authenticated Encryption with AES-CBC and HMAC-SHA 2089 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] specification, upon which the 2090 AES_CBC_HMAC_SHA2 algorithms are based, was written by David A. 2091 McGrew and Kenny Paterson. The test cases for AES_CBC_HMAC_SHA2 are 2092 based upon those for [I-D.mcgrew-aead-aes-cbc-hmac-sha2] by John 2093 Foley. 2095 This specification is the work of the JOSE Working Group, which 2096 includes dozens of active and dedicated participants. In particular, 2097 the following individuals contributed ideas, feedback, and wording 2098 that influenced this specification: 2100 Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de 2101 Medeiros, Yaron Y. Goland, Dick Hardt, Jeff Hodges, Edmund Jay, James 2102 Manger, Tony Nadalin, Axel Nennker, John Panzer, Emmanuel Raviart, 2103 Nat Sakimura, Jim Schaad, Hannes Tschofenig, and Sean Turner. 2105 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2106 Sean Turner and Stephen Farrell served as Security area directors 2107 during the creation of this specification. 2109 Appendix E. Document History 2111 [[ to be removed by the RFC editor before publication as an RFC ]] 2113 -09 2115 o Expanded the scope of the JWK parameters to include private and 2116 symmetric key representations, as specified by 2117 draft-jones-jose-json-private-and-symmetric-key-00. 2119 o Changed term "JWS Secured Input" to "JWS Signing Input". 2121 o Changed from using the term "byte" to "octet" when referring to 8 2122 bit values. 2124 o Specified that AES Key Wrap uses the default initial value 2125 specified in Section 2.2.3.1 of RFC 3394. This addressed issue 2126 #19. 2128 o Added Key Management Mode definitions to terminology section and 2129 used the defined terms to provide clearer key management 2130 instructions. This addressed issue #5. 2132 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2133 and "A256CBC-HS512". The new algorithms perform the same 2134 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2135 but with the Initialization Vector and Authentication Tag values 2136 remaining separate from the Ciphertext value in the output 2137 representation. Also deleted the header parameters "epu" 2138 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2139 they are no longer used. 2141 o Changed from using the term "Integrity Value" to "Authentication 2142 Tag". 2144 -08 2146 o Changed the name of the JWK key type parameter from "alg" to 2147 "kty". 2149 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2150 since the term AEAD in the RFC 5116 sense implied the use of a 2151 particular data representation, rather than just referring to the 2152 class of algorithms that perform authenticated encryption with 2153 associated data. 2155 o Applied editorial improvements suggested by Jeff Hodges. Many of 2156 these simplified the terminology used. 2158 o Added seriesInfo information to Internet Draft references. 2160 -07 2162 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2164 o Changed the name of the JWK RSA modulus parameter from "mod" to 2165 "n" and the name of the JWK RSA exponent parameter from "xpo" to 2166 "e", so that the identifiers are the same as those used in RFC 2167 3447. 2169 o Made several local editorial changes to clean up loose ends left 2170 over from to the decision to only support block encryption methods 2171 providing integrity. 2173 -06 2174 o Removed the "int" and "kdf" parameters and defined the new 2175 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2176 "A256CBC+HS512" to replace the former uses of AES CBC, which 2177 required the use of separate integrity and key derivation 2178 functions. 2180 o Included additional values in the Concat KDF calculation -- the 2181 desired output size and the algorithm value, and optionally 2182 PartyUInfo and PartyVInfo values. Added the optional header 2183 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2184 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2185 PartyVInfo). 2187 o Changed the name of the JWK RSA exponent parameter from "exp" to 2188 "xpo" so as to allow the potential use of the name "exp" for a 2189 future extension that might define an expiration parameter for 2190 keys. (The "exp" name is already used for this purpose in the JWT 2191 specification.) 2193 o Applied changes made by the RFC Editor to RFC 6749's registry 2194 language to this specification. 2196 -05 2198 o Support both direct encryption using a shared or agreed upon 2199 symmetric key, and the use of a shared or agreed upon symmetric 2200 key to key wrap the CMK. Specifically, added the "alg" values 2201 "dir", "ECDH-ES+A128KW", and "ECDH-ES+A256KW" to finish filling in 2202 this set of capabilities. 2204 o Updated open issues. 2206 -04 2208 o Added text requiring that any leading zero bytes be retained in 2209 base64url encoded key value representations for fixed-length 2210 values. 2212 o Added this language to Registration Templates: "This name is case 2213 sensitive. Names that match other registered names in a case 2214 insensitive manner SHOULD NOT be accepted." 2216 o Described additional open issues. 2218 o Applied editorial suggestions. 2220 -03 2221 o Always use a 128 bit "authentication tag" size for AES GCM, 2222 regardless of the key size. 2224 o Specified that use of a 128 bit IV is REQUIRED with AES CBC. It 2225 was previously RECOMMENDED. 2227 o Removed key size language for ECDSA algorithms, since the key size 2228 is implied by the algorithm being used. 2230 o Stated that the "int" key size must be the same as the hash output 2231 size (and not larger, as was previously allowed) so that its size 2232 is defined for key generation purposes. 2234 o Added the "kdf" (key derivation function) header parameter to 2235 provide crypto agility for key derivation. The default KDF 2236 remains the Concat KDF with the SHA-256 digest function. 2238 o Clarified that the "mod" and "exp" values are unsigned. 2240 o Added Implementation Requirements columns to algorithm tables and 2241 Implementation Requirements entries to algorithm registries. 2243 o Changed AES Key Wrap to RECOMMENDED. 2245 o Moved registries JSON Web Signature and Encryption Header 2246 Parameters and JSON Web Signature and Encryption Type Values to 2247 the JWS specification. 2249 o Moved JSON Web Key Parameters registry to the JWK specification. 2251 o Changed registration requirements from RFC Required to 2252 Specification Required with Expert Review. 2254 o Added Registration Template sections for defined registries. 2256 o Added Registry Contents sections to populate registry values. 2258 o No longer say "the UTF-8 representation of the JWS Secured Input 2259 (which is the same as the ASCII representation)". Just call it 2260 "the ASCII representation of the JWS Secured Input". 2262 o Added "Collision Resistant Namespace" to the terminology section. 2264 o Numerous editorial improvements. 2266 -02 2267 o For AES GCM, use the "additional authenticated data" parameter to 2268 provide integrity for the header, encrypted key, and ciphertext 2269 and use the resulting "authentication tag" value as the JWE 2270 Authentication Tag. 2272 o Defined minimum required key sizes for algorithms without 2273 specified key sizes. 2275 o Defined KDF output key sizes. 2277 o Specified the use of PKCS #5 padding with AES CBC. 2279 o Generalized text to allow key agreement to be employed as an 2280 alternative to key wrapping or key encryption. 2282 o Clarified that ECDH-ES is a key agreement algorithm. 2284 o Required implementation of AES-128-KW and AES-256-KW. 2286 o Removed the use of "A128GCM" and "A256GCM" for key wrapping. 2288 o Removed "A512KW" since it turns out that it's not a standard 2289 algorithm. 2291 o Clarified the relationship between "typ" header parameter values 2292 and MIME types. 2294 o Generalized language to refer to Message Authentication Codes 2295 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2296 unless in a context specific to HMAC algorithms. 2298 o Established registries: JSON Web Signature and Encryption Header 2299 Parameters, JSON Web Signature and Encryption Algorithms, JSON Web 2300 Signature and Encryption "typ" Values, JSON Web Key Parameters, 2301 and JSON Web Key Algorithm Families. 2303 o Moved algorithm-specific definitions from JWK to JWA. 2305 o Reformatted to give each member definition its own section 2306 heading. 2308 -01 2310 o Moved definition of "alg":"none" for JWSs here from the JWT 2311 specification since this functionality is likely to be useful in 2312 more contexts that just for JWTs. 2314 o Added Advanced Encryption Standard (AES) Key Wrap Algorithm using 2315 512 bit keys ("A512KW"). 2317 o Added text "Alternatively, the Encoded JWS Signature MAY be 2318 base64url decoded to produce the JWS Signature and this value can 2319 be compared with the computed HMAC value, as this comparison 2320 produces the same result as comparing the encoded values". 2322 o Corrected the Magic Signatures reference. 2324 o Made other editorial improvements suggested by JOSE working group 2325 participants. 2327 -00 2329 o Created the initial IETF draft based upon 2330 draft-jones-json-web-signature-04 and 2331 draft-jones-json-web-encryption-02 with no normative changes. 2333 o Changed terminology to no longer call both digital signatures and 2334 HMACs "signatures". 2336 Author's Address 2338 Michael B. Jones 2339 Microsoft 2341 Email: mbj@microsoft.com 2342 URI: http://self-issued.info/