idnits 2.17.1 draft-ietf-jose-json-web-algorithms-10.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 25, 2013) is 4019 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 1169 -- Looks like a reference, but probably isn't: '0' on line 1169 -- 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 25, 2013 5 Expires: October 27, 2013 7 JSON Web Algorithms (JWA) 8 draft-ietf-jose-json-web-algorithms-10 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 27, 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 . . . . . . . . 23 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 . . . . . . . . . . . 24 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 . . . . . . . . . . . . . 25 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 . . . . 26 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 4.10. Additional Encryption Algorithms and Parameters 1025 Additional algorithms MAY be used to protect JWEs with corresponding 1026 "alg" (algorithm) and "enc" (encryption method) header parameter 1027 values being defined to refer to them. New "alg" and "enc" header 1028 parameter values SHOULD either be registered in the IANA JSON Web 1029 Signature and Encryption Algorithms registry Section 6.1 or be a 1030 value that contains a Collision Resistant Namespace. In particular, 1031 it is permissible to use the algorithm identifiers defined in XML 1032 Encryption [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 1033 [W3C.CR-xmlenc-core1-20120313], and related specifications as "alg" 1034 and "enc" values. 1036 As indicated by the common registry, JWSs and JWEs share a common 1037 "alg" value space. The values used by the two specifications MUST be 1038 distinct, as the "alg" value can be used to determine whether the 1039 object is a JWS or JWE. 1041 Likewise, additional reserved Header Parameter Names MAY be defined 1042 via the IANA JSON Web Signature and Encryption Header Parameters 1043 registry [JWS]. As indicated by the common registry, JWSs and JWEs 1044 share a common header parameter space; when a parameter is used by 1045 both specifications, its usage must be compatible between the 1046 specifications. 1048 5. Cryptographic Algorithms for JWK 1050 A JSON Web Key (JWK) [JWK] is a JavaScript Object Notation (JSON) 1051 [RFC4627] data structure that represents a cryptographic key. A JSON 1052 Web Key Set (JWK Set) is a JSON data structure for representing a set 1053 of JWKs. This section specifies a set of key types to be used for 1054 those keys and the key type specific parameters for representing 1055 those keys. Parameters are defined for public, private, and 1056 symmetric keys. 1058 5.1. "kty" (Key Type) Parameter Values for JWK 1060 The table below is the set of "kty" (key type) parameter values that 1061 are defined by this specification for use in JWKs. 1063 +-------------+----------------------------------+------------------+ 1064 | kty | Key Type | Implementation | 1065 | Parameter | | Requirements | 1066 | Value | | | 1067 +-------------+----------------------------------+------------------+ 1068 | EC | Elliptic Curve [DSS] key type | RECOMMENDED+ | 1069 | RSA | RSA [RFC3447] key type | REQUIRED | 1070 | oct | Octet sequence key type (used to | RECOMMENDED+ | 1071 | | represent symmetric keys) | | 1072 +-------------+----------------------------------+------------------+ 1074 All the names are short because a core goal of JWK is for the 1075 representations to be compact. However, there is no a priori length 1076 restriction on "kty" values. 1078 The use of "+" in the Implementation Requirements indicates that the 1079 requirement strength is likely to be increased in a future version of 1080 the specification. 1082 5.2. JWK Parameters for Elliptic Curve Keys 1084 JWKs can represent Elliptic Curve [DSS] keys. In this case, the 1085 "kty" member value MUST be "EC". 1087 5.2.1. JWK Parameters for Elliptic Curve Public Keys 1089 These members MUST be present for Elliptic Curve public keys: 1091 5.2.1.1. "crv" (Curve) Parameter 1093 The "crv" (curve) member identifies the cryptographic curve used with 1094 the key. Curve values from [DSS] used by this specification are: 1096 o "P-256" 1098 o "P-384" 1100 o "P-521" 1102 Additional "crv" values MAY be used, provided they are understood by 1103 implementations using that Elliptic Curve key. The "crv" value is a 1104 case sensitive string. 1106 5.2.1.2. "x" (X Coordinate) Parameter 1108 The "x" (x coordinate) member contains the x coordinate for the 1109 elliptic curve point. It is represented as the base64url encoding of 1110 the coordinate's big endian representation as an octet sequence. The 1111 array representation MUST NOT be shortened to omit any leading zero 1112 octets contained in the value. For instance, when representing 521 1113 bit integers, the octet sequence to be base64url encoded MUST contain 1114 66 octets, including any leading zero octets. 1116 5.2.1.3. "y" (Y Coordinate) Parameter 1118 The "y" (y coordinate) member contains the y coordinate for the 1119 elliptic curve point. It is represented as the base64url encoding of 1120 the coordinate's big endian representation as an octet sequence. The 1121 array representation MUST NOT be shortened to omit any leading zero 1122 octets contained in the value. For instance, when representing 521 1123 bit integers, the octet sequence to be base64url encoded MUST contain 1124 66 octets, including any leading zero octets. 1126 5.2.2. JWK Parameters for Elliptic Curve Private Keys 1128 In addition to the members used to represent Elliptic Curve public 1129 keys, the following member MUST be present to represent Elliptic 1130 Curve private keys: 1132 5.2.2.1. "d" (ECC Private Key) Parameter 1134 The "d" (ECC private key) member contains the Elliptic Curve private 1135 key value. It is represented as the base64url encoding of the 1136 value's unsigned big endian representation as an octet sequence. The 1137 array representation MUST NOT be shortened to omit any leading zero 1138 octets. For instance, when representing 521 bit integers, the octet 1139 sequence to be base64url encoded MUST contain 66 octets, including 1140 any leading zero octets. 1142 5.3. JWK Parameters for RSA Keys 1144 JWKs can represent RSA [RFC3447] keys. In this case, the "kty" 1145 member value MUST be "RSA". 1147 5.3.1. JWK Parameters for RSA Public Keys 1149 These members MUST be present for RSA public keys: 1151 5.3.1.1. "n" (Modulus) Parameter 1153 The "n" (modulus) member contains the modulus value for the RSA 1154 public key. It is represented as the base64url encoding of the 1155 value's unsigned big endian representation as an octet sequence. The 1156 array representation MUST NOT be shortened to omit any leading zero 1157 octets. For instance, when representing 2048 bit integers, the octet 1158 sequence to be base64url encoded MUST contain 256 octets, including 1159 any leading zero octets. 1161 5.3.1.2. "e" (Exponent) Parameter 1163 The "e" (exponent) member contains the exponent value for the RSA 1164 public key. It is represented as the base64url encoding of the 1165 value's unsigned big endian representation as an octet sequence. The 1166 array representation MUST utilize the minimum number of octets to 1167 represent the value. For instance, when representing the value 1168 65537, the octet sequence to be base64url encoded MUST consist of the 1169 three octets [1, 0, 1]. 1171 5.3.2. JWK Parameters for RSA Private Keys 1173 In addition to the members used to represent RSA public keys, the 1174 following members are used to represent RSA private keys. All are 1175 REQUIRED for RSA private keys except for "oth", which is sometimes 1176 REQUIRED and sometimes MUST NOT be present, as described below. 1178 5.3.2.1. "d" (Private Exponent) Parameter 1180 The "d" (private exponent) member contains the private exponent value 1181 for the RSA private key. It is represented as the base64url encoding 1182 of the value's unsigned big endian representation as an octet 1183 sequence. The array representation MUST NOT be shortened to omit any 1184 leading zero octets. For instance, when representing 2048 bit 1185 integers, the octet sequence to be base64url encoded MUST contain 256 1186 octets, including any leading zero octets. 1188 5.3.2.2. "p" (First Prime Factor) Parameter 1190 The "p" (first prime factor) member contains the first prime factor, 1191 a positive integer. It is represented as the base64url encoding of 1192 the value's unsigned big endian representation as an octet sequence. 1194 5.3.2.3. "q" (Second Prime Factor) Parameter 1196 The "q" (second prime factor) member contains the second prime 1197 factor, a positive integer. It is represented as the base64url 1198 encoding of the value's unsigned big endian representation as an 1199 octet sequence. 1201 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter 1203 The "dp" (first factor CRT exponent) member contains the Chinese 1204 Remainder Theorem (CRT) exponent of the first factor, a positive 1205 integer. It is represented as the base64url encoding of the value's 1206 unsigned big endian representation as an octet sequence. 1208 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter 1210 The "dq" (second factor CRT exponent) member contains the Chinese 1211 Remainder Theorem (CRT) exponent of the second 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.6. "qi" (First CRT Coefficient) Parameter 1217 The "dp" (first CRT coefficient) member contains the Chinese 1218 Remainder Theorem (CRT) coefficient 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.7. "oth" (Other Primes Info) Parameter 1224 The "oth" (other primes info) member contains an array of information 1225 about any third and subsequent primes, should they exist. When only 1226 two primes have been used (the normal case), this parameter MUST be 1227 omitted. When three or more primes have been used, the number of 1228 array elements MUST be the number of primes used minus two. Each 1229 array element MUST be an object with the following members: 1231 5.3.2.7.1. "r" (Prime Factor) 1233 The "r" (prime factor) parameter within an "oth" array member 1234 represents the value of a subsequent prime factor, a positive 1235 integer. It is represented as the base64url encoding of the value's 1236 unsigned big endian representation as an octet sequence. 1238 5.3.2.7.2. "d" (Factor CRT Exponent) 1240 The "d" (Factor CRT Exponent) parameter within an "oth" array member 1241 represents the CRT exponent of the corresponding prime factor, a 1242 positive integer. It is represented as the base64url encoding of the 1243 value's unsigned big endian representation as an octet sequence. 1245 5.3.2.7.3. "t" (Factor CRT Coefficient) 1247 The "t" (factor CRT coefficient) parameter within an "oth" array 1248 member represents the CRT coefficient of the corresponding prime 1249 factor, a positive integer. It is represented as the base64url 1250 encoding of the value's unsigned big endian representation as an 1251 octet sequence. 1253 5.3.3. JWK Parameters for Symmetric Keys 1255 When the JWK "kty" member value is "oct" (octet sequence), the 1256 following member is used to represent a symmetric key (or another key 1257 whose value is a single octet sequence): 1259 5.3.3.1. "k" (Key Value) Parameter 1261 The "k" (key value) member contains the value of the symmetric (or 1262 other single-valued) key. It is represented as the base64url 1263 encoding of the octet sequence containing the key value. 1265 5.4. Additional Key Types and Parameters 1267 Keys using additional key types can be represented using JWK data 1268 structures with corresponding "kty" (key type) parameter values being 1269 defined to refer to them. New "kty" parameter values SHOULD either 1270 be registered in the IANA JSON Web Key Types registry Section 6.2 or 1271 be a value that contains a Collision Resistant Namespace. 1273 Likewise, parameters for representing keys for additional key types 1274 or additional key properties SHOULD either be registered in the IANA 1275 JSON Web Key Parameters registry [JWK] or be a value that contains a 1276 Collision Resistant Namespace. 1278 6. IANA Considerations 1280 The following registration procedure is used for all the registries 1281 established by this specification. 1283 Values are registered with a Specification Required [RFC5226] after a 1284 two-week review period on the [TBD]@ietf.org mailing list, on the 1285 advice of one or more Designated Experts. However, to allow for the 1286 allocation of values prior to publication, the Designated Expert(s) 1287 may approve registration once they are satisfied that such a 1288 specification will be published. 1290 Registration requests must be sent to the [TBD]@ietf.org mailing list 1291 for review and comment, with an appropriate subject (e.g., "Request 1292 for access token type: example"). [[ Note to RFC-EDITOR: The name of 1293 the mailing list should be determined in consultation with the IESG 1294 and IANA. Suggested name: jose-reg-review. ]] 1296 Within the review period, the Designated Expert(s) will either 1297 approve or deny the registration request, communicating this decision 1298 to the review list and IANA. Denials should include an explanation 1299 and, if applicable, suggestions as to how to make the request 1300 successful. 1302 IANA must only accept registry updates from the Designated Expert(s) 1303 and should direct all requests for registration to the review mailing 1304 list. 1306 6.1. JSON Web Signature and Encryption Algorithms Registry 1308 This specification establishes the IANA JSON Web Signature and 1309 Encryption Algorithms registry for values of the JWS and JWE "alg" 1310 (algorithm) and "enc" (encryption method) header parameters. The 1311 registry records the algorithm name, the algorithm usage locations 1312 from the set "alg" and "enc", implementation requirements, and a 1313 reference to the specification that defines it. The same algorithm 1314 name MAY be registered multiple times, provided that the sets of 1315 usage locations are disjoint. The implementation requirements of an 1316 algorithm MAY be changed over time by the Designated Experts(s) as 1317 the cryptographic landscape evolves, for instance, to change the 1318 status of an algorithm to DEPRECATED, or to change the status of an 1319 algorithm from OPTIONAL to RECOMMENDED or REQUIRED. 1321 6.1.1. Template 1323 Algorithm Name: 1324 The name requested (e.g., "example"). This name is case 1325 sensitive. Names that match other registered names in a case 1326 insensitive manner SHOULD NOT be accepted. 1328 Algorithm Usage Location(s): 1329 The algorithm usage, which must be one or more of the values "alg" 1330 or "enc". 1332 Implementation Requirements: 1333 The algorithm implementation requirements, which must be one the 1334 words REQUIRED, RECOMMENDED, OPTIONAL, or DEPRECATED. Optionally, 1335 the word can be followed by a "+" or "-". The use of "+" 1336 indicates that the requirement strength is likely to be increased 1337 in a future version of the specification. The use of "-" 1338 indicates that the requirement strength is likely to be decreased 1339 in a future version of the specification. 1341 Change Controller: 1342 For Standards Track RFCs, state "IETF". For others, give the name 1343 of the responsible party. Other details (e.g., postal address, 1344 email address, home page URI) may also be included. 1346 Specification Document(s): 1347 Reference to the document(s) that specify the parameter, 1348 preferably including URI(s) that can be used to retrieve copies of 1349 the document(s). An indication of the relevant sections may also 1350 be included but is not required. 1352 6.1.2. Initial Registry Contents 1354 o Algorithm Name: "HS256" 1355 o Algorithm Usage Location(s): "alg" 1356 o Implementation Requirements: REQUIRED 1357 o Change Controller: IETF 1358 o Specification Document(s): Section 3.1 of [[ this document ]] 1360 o Algorithm Name: "HS384" 1361 o Algorithm Usage Location(s): "alg" 1362 o Implementation Requirements: OPTIONAL 1363 o Change Controller: IETF 1364 o Specification Document(s): Section 3.1 of [[ this document ]] 1366 o Algorithm Name: "HS512" 1367 o Algorithm Usage Location(s): "alg" 1368 o Implementation Requirements: OPTIONAL 1369 o Change Controller: IETF 1370 o Specification Document(s): Section 3.1 of [[ this document ]] 1372 o Algorithm Name: "RS256" 1373 o Algorithm Usage Location(s): "alg" 1374 o Implementation Requirements: RECOMMENDED 1375 o Change Controller: IETF 1376 o Specification Document(s): Section 3.1 of [[ this document ]] 1378 o Algorithm Name: "RS384" 1379 o Algorithm Usage Location(s): "alg" 1380 o Implementation Requirements: OPTIONAL 1381 o Change Controller: IETF 1382 o Specification Document(s): Section 3.1 of [[ this document ]] 1384 o Algorithm Name: "RS512" 1385 o Algorithm Usage Location(s): "alg" 1386 o Implementation Requirements: OPTIONAL 1387 o Change Controller: IETF 1388 o Specification Document(s): Section 3.1 of [[ this document ]] 1390 o Algorithm Name: "ES256" 1391 o Algorithm Usage Location(s): "alg" 1392 o Implementation Requirements: RECOMMENDED+ 1393 o Change Controller: IETF 1394 o Specification Document(s): Section 3.1 of [[ this document ]] 1396 o Algorithm Name: "ES384" 1397 o Algorithm Usage Location(s): "alg" 1398 o Implementation Requirements: OPTIONAL 1399 o Change Controller: IETF 1400 o Specification Document(s): Section 3.1 of [[ this document ]] 1402 o Algorithm Name: "ES512" 1403 o Algorithm Usage Location(s): "alg" 1404 o Implementation Requirements: OPTIONAL 1405 o Change Controller: IETF 1406 o Specification Document(s): Section 3.1 of [[ this document ]] 1408 o Algorithm Name: "none" 1409 o Algorithm Usage Location(s): "alg" 1410 o Implementation Requirements: REQUIRED 1411 o Change Controller: IETF 1412 o Specification Document(s): Section 3.1 of [[ this document ]] 1414 o Algorithm Name: "RSA1_5" 1415 o Algorithm Usage Location(s): "alg" 1416 o Implementation Requirements: REQUIRED 1417 o Change Controller: IETF 1418 o Specification Document(s): Section 4.1 of [[ this document ]] 1420 o Algorithm Name: "RSA-OAEP" 1421 o Algorithm Usage Location(s): "alg" 1422 o Implementation Requirements: OPTIONAL 1423 o Change Controller: IETF 1424 o Specification Document(s): Section 4.1 of [[ this document ]] 1426 o Algorithm Name: "A128KW" 1427 o Algorithm Usage Location(s): "alg" 1428 o Implementation Requirements: RECOMMENDED 1429 o Change Controller: IETF 1430 o Specification Document(s): Section 4.1 of [[ this document ]] 1432 o Algorithm Name: "A256KW" 1433 o Algorithm Usage Location(s): "alg" 1434 o Implementation Requirements: RECOMMENDED 1435 o Change Controller: IETF 1436 o Specification Document(s): Section 4.1 of [[ this document ]] 1437 o Algorithm Name: "dir" 1438 o Algorithm Usage Location(s): "alg" 1439 o Implementation Requirements: RECOMMENDED 1440 o Change Controller: IETF 1441 o Specification Document(s): Section 4.1 of [[ this document ]] 1443 o Algorithm Name: "ECDH-ES" 1444 o Algorithm Usage Location(s): "alg" 1445 o Implementation Requirements: RECOMMENDED+ 1446 o Change Controller: IETF 1447 o Specification Document(s): Section 4.1 of [[ this document ]] 1449 o Algorithm Name: "ECDH-ES+A128KW" 1450 o Algorithm Usage Location(s): "alg" 1451 o Implementation Requirements: RECOMMENDED 1452 o Change Controller: IETF 1453 o Specification Document(s): Section 4.1 of [[ this document ]] 1455 o Algorithm Name: "ECDH-ES+A256KW" 1456 o Algorithm Usage Location(s): "alg" 1457 o Implementation Requirements: RECOMMENDED 1458 o Change Controller: IETF 1459 o Specification Document(s): Section 4.1 of [[ this document ]] 1461 o Algorithm Name: "A128CBC-HS256" 1462 o Algorithm Usage Location(s): "enc" 1463 o Implementation Requirements: REQUIRED 1464 o Change Controller: IETF 1465 o Specification Document(s): Section 4.2 of [[ this document ]] 1467 o Algorithm Name: "A256CBC-HS512" 1468 o Algorithm Usage Location(s): "enc" 1469 o Implementation Requirements: REQUIRED 1470 o Change Controller: IETF 1471 o Specification Document(s): Section 4.2 of [[ this document ]] 1473 o Algorithm Name: "A128GCM" 1474 o Algorithm Usage Location(s): "enc" 1475 o Implementation Requirements: RECOMMENDED 1476 o Change Controller: IETF 1477 o Specification Document(s): Section 4.2 of [[ this document ]] 1479 o Algorithm Name: "A256GCM" 1480 o Algorithm Usage Location(s): "enc" 1481 o Implementation Requirements: RECOMMENDED 1482 o Change Controller: IETF 1483 o Specification Document(s): Section 4.2 of [[ this document ]] 1485 6.2. JSON Web Key Types Registry 1487 This specification establishes the IANA JSON Web Key Types registry 1488 for values of the JWK "kty" (key type) parameter. The registry 1489 records the "kty" value and a reference to the specification that 1490 defines it. This specification registers the values defined in 1491 Section 5.1. 1493 6.2.1. Registration Template 1495 "kty" Parameter Value: 1496 The name requested (e.g., "example"). This name is case 1497 sensitive. Names that match other registered names in a case 1498 insensitive manner SHOULD NOT be accepted. 1500 Change Controller: 1501 For Standards Track RFCs, state "IETF". For others, give the name 1502 of the responsible party. Other details (e.g., postal address, 1503 email address, home page URI) may also be included. 1505 Implementation Requirements: 1506 The algorithm implementation requirements, which must be one the 1507 words REQUIRED, RECOMMENDED, OPTIONAL, or DEPRECATED. Optionally, 1508 the word can be followed by a "+" or "-". The use of "+" 1509 indicates that the requirement strength is likely to be increased 1510 in a future version of the specification. The use of "-" 1511 indicates that the requirement strength is likely to be decreased 1512 in a future version of the specification. 1514 Specification Document(s): 1515 Reference to the document(s) that specify the parameter, 1516 preferably including URI(s) that can be used to retrieve copies of 1517 the document(s). An indication of the relevant sections may also 1518 be included but is not required. 1520 6.2.2. Initial Registry Contents 1522 o "kty" Parameter Value: "EC" 1523 o Implementation Requirements: RECOMMENDED+ 1524 o Change Controller: IETF 1525 o Specification Document(s): Section 5.1 of [[ this document ]] 1527 o "kty" Parameter Value: "RSA" 1528 o Implementation Requirements: REQUIRED 1529 o Change Controller: IETF 1530 o Specification Document(s): Section 5.1 of [[ this document ]] 1532 o "kty" Parameter Value: "oct" 1533 o Implementation Requirements: RECOMMENDED+ 1534 o Change Controller: IETF 1535 o Specification Document(s): Section 5.1 of [[ this document ]] 1537 6.3. JSON Web Key Parameters Registration 1539 This specification registers the parameter names defined in Sections 1540 5.2, 5.3, and 5.3.3 in the IANA JSON Web Key Parameters registry 1541 [JWK]. 1543 6.3.1. Registry Contents 1545 o Parameter Name: "crv" 1546 o Change Controller: IETF 1547 o Specification Document(s): Section 5.2.1.1 of [[ this document ]] 1549 o Parameter Name: "x" 1550 o Change Controller: IETF 1551 o Specification Document(s): Section 5.2.1.2 of [[ this document ]] 1553 o Parameter Name: "y" 1554 o Change Controller: IETF 1555 o Specification Document(s): Section 5.2.1.3 of [[ this document ]] 1557 o Parameter Name: "d" 1558 o Change Controller: IETF 1559 o Specification Document(s): Section 5.2.2.1 of [[ this document ]] 1561 o Parameter Name: "n" 1562 o Change Controller: IETF 1563 o Specification Document(s): Section 5.3.1.1 of [[ this document ]] 1565 o Parameter Name: "e" 1566 o Change Controller: IETF 1567 o Specification Document(s): Section 5.3.1.2 of [[ this document ]] 1569 o Parameter Name: "d" 1570 o Change Controller: IETF 1571 o Specification Document(s): Section 5.3.2.1 of [[ this document ]] 1573 o Parameter Name: "p" 1574 o Change Controller: IETF 1575 o Specification Document(s): Section 5.3.2.2 of [[ this document ]] 1577 o Parameter Name: "q" 1578 o Change Controller: IETF 1579 o Specification Document(s): Section 5.3.2.3 of [[ this document ]] 1581 o Parameter Name: "dp" 1582 o Change Controller: IETF 1583 o Specification Document(s): Section 5.3.2.4 of [[ this document ]] 1585 o Parameter Name: "dq" 1586 o Change Controller: IETF 1587 o Specification Document(s): Section 5.3.2.5 of [[ this document ]] 1589 o Parameter Name: "qi" 1590 o Change Controller: IETF 1591 o Specification Document(s): Section 5.3.2.6 of [[ this document ]] 1593 o Parameter Name: "oth" 1594 o Change Controller: IETF 1595 o Specification Document(s): Section 5.3.2.7 of [[ this document ]] 1597 o Parameter Name: "k" 1598 o Change Controller: IETF 1599 o Specification Document(s): Section 5.3.3.1 of [[ this document ]] 1601 7. Security Considerations 1603 All of the security issues faced by any cryptographic application 1604 must be faced by a JWS/JWE/JWK agent. Among these issues are 1605 protecting the user's private and symmetric keys, preventing various 1606 attacks, and helping the user avoid mistakes such as inadvertently 1607 encrypting a message for the wrong recipient. The entire list of 1608 security considerations is beyond the scope of this document, but 1609 some significant considerations are listed here. 1611 The security considerations in [AES], [DSS], [JWE], [JWK], [JWS], 1612 [NIST.800-38A], [NIST.800-38D], [NIST.800-56A], [RFC2104], [RFC3394], 1613 [RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this 1614 specification. 1616 Eventually the algorithms and/or key sizes currently described in 1617 this specification will no longer be considered sufficiently secure 1618 and will be removed. Therefore, implementers and deployments must be 1619 prepared for this eventuality. 1621 Algorithms of matching strengths should be used together whenever 1622 possible. For instance, when AES Key Wrap is used with a given key 1623 size, using the same key size is recommended when AES GCM is also 1624 used. 1626 While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not 1627 to adopt RSASSA-PKCS1 for new applications and instead requests that 1628 people transition to RSASSA-PSS, this specification does include 1629 RSASSA-PKCS1, for interoperability reasons, because it commonly 1630 implemented. 1632 Keys used with RSAES-PKCS1-v1_5 must follow the constraints in 1633 Section 7.2 of RFC 3447 [RFC3447]. In particular, keys with a low 1634 public key exponent value must not be used. 1636 Plaintext JWSs (JWSs that use the "alg" value "none") provide no 1637 integrity protection. Thus, they must only be used in contexts where 1638 the payload is secured by means other than a digital signature or MAC 1639 value, or need not be secured. 1641 Receiving agents that validate signatures and sending agents that 1642 encrypt messages need to be cautious of cryptographic processing 1643 usage when validating signatures and encrypting messages using keys 1644 larger than those mandated in this specification. An attacker could 1645 send certificates with keys that would result in excessive 1646 cryptographic processing, for example, keys larger than those 1647 mandated in this specification, which could swamp the processing 1648 element. Agents that use such keys without first validating the 1649 certificate to a trust anchor are advised to have some sort of 1650 cryptographic resource management system to prevent such attacks. 1652 8. References 1654 8.1. Normative References 1656 [AES] National Institute of Standards and Technology (NIST), 1657 "Advanced Encryption Standard (AES)", FIPS PUB 197, 1658 November 2001. 1660 [DSS] National Institute of Standards and Technology, "Digital 1661 Signature Standard (DSS)", FIPS PUB 186-3, June 2009. 1663 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 1664 Encryption (JWE)", draft-ietf-jose-json-web-encryption 1665 (work in progress), April 2013. 1667 [JWK] Jones, M., "JSON Web Key (JWK)", 1668 draft-ietf-jose-json-web-key (work in progress), 1669 April 2013. 1671 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1672 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1673 in progress), April 2013. 1675 [NIST.800-38A] 1676 National Institute of Standards and Technology (NIST), 1677 "Recommendation for Block Cipher Modes of Operation", 1678 NIST PUB 800-38A, December 2001. 1680 [NIST.800-38D] 1681 National Institute of Standards and Technology (NIST), 1682 "Recommendation for Block Cipher Modes of Operation: 1683 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 1684 December 2001. 1686 [NIST.800-56A] 1687 National Institute of Standards and Technology (NIST), 1688 "Recommendation for Pair-Wise Key Establishment Schemes 1689 Using Discrete Logarithm Cryptography (Revised)", NIST PUB 1690 800-56A, March 2007. 1692 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1693 Hashing for Message Authentication", RFC 2104, 1694 February 1997. 1696 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1697 Requirement Levels", BCP 14, RFC 2119, March 1997. 1699 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 1700 (AES) Key Wrap Algorithm", RFC 3394, September 2002. 1702 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1703 10646", STD 63, RFC 3629, November 2003. 1705 [RFC4627] Crockford, D., "The application/json Media Type for 1706 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1708 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1709 Encodings", RFC 4648, October 2006. 1711 [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA- 1712 384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007. 1714 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 1715 Encryption", RFC 5116, January 2008. 1717 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1718 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1719 May 2008. 1721 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 1722 Curve Cryptography Algorithms", RFC 6090, February 2011. 1724 [SHS] National Institute of Standards and Technology, "Secure 1725 Hash Standard (SHS)", FIPS PUB 180-3, October 2008. 1727 [USASCII] American National Standards Institute, "Coded Character 1728 Set -- 7-bit American Standard Code for Information 1729 Interchange", ANSI X3.4, 1986. 1731 8.2. Informative References 1733 [CanvasApp] 1734 Facebook, "Canvas Applications", 2010. 1736 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1737 McGrew, D. and K. Paterson, "Authenticated Encryption with 1738 AES-CBC and HMAC-SHA", 1739 draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), 1740 October 2012. 1742 [I-D.rescorla-jsms] 1743 Rescorla, E. and J. Hildebrand, "JavaScript Message 1744 Security Format", draft-rescorla-jsms-00 (work in 1745 progress), March 2011. 1747 [JCA] Oracle, "Java Cryptography Architecture", 2011. 1749 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1750 Encryption", September 2010. 1752 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 1753 September 2010. 1755 [MagicSignatures] 1756 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 1757 Signatures", January 2011. 1759 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 1760 Language) XML-Signature Syntax and Processing", RFC 3275, 1761 March 2002. 1763 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1764 Standards (PKCS) #1: RSA Cryptography Specifications 1765 Version 2.1", RFC 3447, February 2003. 1767 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1768 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1769 July 2005. 1771 [W3C.CR-xmldsig-core2-20120124] 1772 Eastlake, D., Reagle, J., Yiu, K., Solo, D., Datta, P., 1773 Hirsch, F., Cantor, S., and T. Roessler, "XML Signature 1774 Syntax and Processing Version 2.0", World Wide Web 1775 Consortium CR CR-xmldsig-core2-20120124, January 2012, 1776 . 1778 [W3C.CR-xmlenc-core1-20120313] 1779 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 1780 "XML Encryption Syntax and Processing Version 1.1", World 1781 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1782 March 2012, 1783 . 1785 [W3C.REC-xmlenc-core-20021210] 1786 Eastlake, D. and J. Reagle, "XML Encryption Syntax and 1787 Processing", World Wide Web Consortium Recommendation REC- 1788 xmlenc-core-20021210, December 2002, 1789 . 1791 Appendix A. Digital Signature/MAC Algorithm Identifier Cross-Reference 1793 This appendix contains a table cross-referencing the digital 1794 signature and MAC "alg" (algorithm) values used in this specification 1795 with the equivalent identifiers used by other standards and software 1796 packages. See XML DSIG [RFC3275], XML DSIG 2.0 1797 [W3C.CR-xmldsig-core2-20120124], and Java Cryptography Architecture 1798 [JCA] for more information about the names defined by those 1799 documents. 1801 +-------+-----+----------------------------+----------+-------------+ 1802 | Algor | JWS | XML DSIG | JCA | OID | 1803 | ithm | | | | | 1804 +-------+-----+----------------------------+----------+-------------+ 1805 | HMAC | HS2 | http://www.w3.org/2001/04/ | HmacSHA2 | 1.2.840.113 | 1806 | using | 56 | xmldsig-more#hmac-sha256 | 56 | 549.2.9 | 1807 | SHA-2 | | | | | 1808 | 56 | | | | | 1809 | hash | | | | | 1810 | algo | | | | | 1811 | rithm | | | | | 1812 | HMAC | HS3 | http://www.w3.org/2001/04/ | HmacSHA3 | 1.2.840.113 | 1813 | using | 84 | xmldsig-more#hmac-sha384 | 84 | 549.2.10 | 1814 | SHA-3 | | | | | 1815 | 84 | | | | | 1816 | hash | | | | | 1817 | algo | | | | | 1818 | rithm | | | | | 1819 | HMAC | HS5 | http://www.w3.org/2001/04/ | HmacSHA5 | 1.2.840.113 | 1820 | using | 12 | xmldsig-more#hmac-sha512 | 12 | 549.2.11 | 1821 | SHA-5 | | | | | 1822 | 12 | | | | | 1823 | hash | | | | | 1824 | algo | | | | | 1825 | rithm | | | | | 1826 | RSASS | RS2 | http://www.w3.org/2001/04/ | SHA256wi | 1.2.840.113 | 1827 | A | 56 | xmldsig-more#rsa-sha256 | thRSA | 549.1.1.11 | 1828 | usin | | | | | 1829 | gSHA- | | | | | 1830 | 256 | | | | | 1831 | has | | | | | 1832 | h alg | | | | | 1833 | orith | | | | | 1834 | m | | | | | 1835 | RSASS | RS3 | http://www.w3.org/2001/04/ | SHA384wi | 1.2.840.113 | 1836 | A | 84 | xmldsig-more#rsa-sha384 | thRSA | 549.1.1.12 | 1837 | usin | | | | | 1838 | gSHA- | | | | | 1839 | 384 | | | | | 1840 | has | | | | | 1841 | h alg | | | | | 1842 | orith | | | | | 1843 | m | | | | | 1844 | RSASS | RS5 | http://www.w3.org/2001/04/ | SHA512wi | 1.2.840.113 | 1845 | A | 12 | xmldsig-more#rsa-sha512 | thRSA | 549.1.1.13 | 1846 | usin | | | | | 1847 | gSHA- | | | | | 1848 | 512 | | | | | 1849 | has | | | | | 1850 | h alg | | | | | 1851 | orith | | | | | 1852 | m | | | | | 1853 | ECDSA | ES2 | http://www.w3.org/2001/04/ | SHA256wi | 1.2.840.100 | 1854 | using | 56 | xmldsig-more#ecdsa-sha256 | thECDSA | 45.4.3.2 | 1855 | P-256 | | | | | 1856 | curve | | | | | 1857 | and | | | | | 1858 | SHA-2 | | | | | 1859 | 56 | | | | | 1860 | hash | | | | | 1861 | algo | | | | | 1862 | rithm | | | | | 1863 | ECDSA | ES3 | http://www.w3.org/2001/04/ | SHA384wi | 1.2.840.100 | 1864 | using | 84 | xmldsig-more#ecdsa-sha384 | thECDSA | 45.4.3.3 | 1865 | P-384 | | | | | 1866 | curve | | | | | 1867 | and | | | | | 1868 | SHA-3 | | | | | 1869 | 84 | | | | | 1870 | hash | | | | | 1871 | algo | | | | | 1872 | rithm | | | | | 1873 | ECDSA | ES5 | http://www.w3.org/2001/04/ | SHA512wi | 1.2.840.100 | 1874 | using | 12 | xmldsig-more#ecdsa-sha512 | thECDSA | 45.4.3.4 | 1875 | P-521 | | | | | 1876 | curve | | | | | 1877 | and | | | | | 1878 | SHA-5 | | | | | 1879 | 12 | | | | | 1880 | hash | | | | | 1881 | algo | | | | | 1882 | rithm | | | | | 1883 +-------+-----+----------------------------+----------+-------------+ 1885 Appendix B. Encryption Algorithm Identifier Cross-Reference 1887 This appendix contains a table cross-referencing the "alg" 1888 (algorithm) and "enc" (encryption method) values used in this 1889 specification with the equivalent identifiers used by other standards 1890 and software packages. See XML Encryption 1892 [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 1893 [W3C.CR-xmlenc-core1-20120313], and Java Cryptography Architecture 1894 [JCA] for more information about the names defined by those 1895 documents. 1897 For the composite algorithms "A128CBC-HS256" and "A256CBC-HS512", the 1898 corresponding AES CBC algorithm identifiers are listed. 1900 +----------+--------+--------------------------+--------------------+ 1901 | Algorith | JWE | XML ENC | JCA | 1902 | m | | | | 1903 +----------+--------+--------------------------+--------------------+ 1904 | RSAES-PK | RSA1_5 | http://www.w3.org/2001/0 | RSA/ECB/PKCS1Paddi | 1905 | CS1-V1_5 | | 4/xmlenc#rsa-1_5 | ng | 1906 | RSAES | RSA-OA | http://www.w3.org/2001/0 | RSA/ECB/OAEPWithSH | 1907 | using | EP | 4/xmlenc#rsa-oaep-mgf1p | A-1AndMGF1Padding | 1908 | Optimal | | | | 1909 | Asymmetr | | | | 1910 | ic | | | | 1911 | Encrypt | | | | 1912 | ion | | | | 1913 | Paddin | | | | 1914 | g (OAEP) | | | | 1915 | Elliptic | ECDH-E | http://www.w3.org/2009/x | | 1916 | Curve | S | mlenc11#ECDH-ES | | 1917 | Diffie-H | | | | 1918 | ellman | | | | 1919 | Ephemer | | | | 1920 | alStatic | | | | 1921 | Advanced | A128KW | http://www.w3.org/2001/0 | | 1922 | Encrypti | | 4/xmlenc#kw-aes128 | | 1923 | on | | | | 1924 | Standar | | | | 1925 | d(AES) | | | | 1926 | Key Wra | | | | 1927 | pAlgorit | | | | 1928 | hmusing | | | | 1929 | 128 bi | | | | 1930 | t keys | | | | 1931 | AES Key | A256KW | http://www.w3.org/2001/0 | | 1932 | Wrap | | 4/xmlenc#kw-aes256 | | 1933 | Algorith | | | | 1934 | musing | | | | 1935 | 256 bit | | | | 1936 | keys | | | | 1937 | AES in | A128CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 1938 | Cipher | C-HS25 | 4/xmlenc#aes128-cbc | ng | 1939 | Block | 6 | | | 1940 | Chaining | | | | 1941 | (CBC) | | | | 1942 | mode | | | | 1943 | with | | | | 1944 | PKCS #5 | | | | 1945 | padding | | | | 1946 | using | | | | 1947 | 128 bit | | | | 1948 | keys | | | | 1949 | AES in | A256CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 1950 | CBC mode | C-HS51 | 4/xmlenc#aes256-cbc | ng | 1951 | with | 2 | | | 1952 | PKCS #5 | | | | 1953 | padding | | | | 1954 | using | | | | 1955 | 256 bit | | | | 1956 | keys | | | | 1957 | AES in | A128GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 1958 | Galois/C | M | mlenc11#aes128-gcm | | 1959 | ounter | | | | 1960 | Mode | | | | 1961 | (GCM) | | | | 1962 | using | | | | 1963 | 128 bit | | | | 1964 | keys | | | | 1965 | AES GCM | A256GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 1966 | using | M | mlenc11#aes256-gcm | | 1967 | 256 bit | | | | 1968 | keys | | | | 1969 +----------+--------+--------------------------+--------------------+ 1971 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms 1973 The following test cases can be used to validate implementations of 1974 the AES_CBC_HMAC_SHA2 algorithms defined in Section 4.8. They are 1975 also intended to correspond to test cases that may appear in a future 1976 version of [I-D.mcgrew-aead-aes-cbc-hmac-sha2], demonstrating that 1977 the cryptographic computations performed are the same. 1979 The variable names are those defined in Section 4.8. All values are 1980 hexadecimal. 1982 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 1984 AES_128_CBC_HMAC_SHA_256 1986 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 1987 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 1989 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 1991 ENC_KEY = 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 1993 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 1994 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 1995 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 1996 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 1997 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 1998 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 1999 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2000 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2002 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2004 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2005 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2006 4b 65 72 63 6b 68 6f 66 66 73 2008 AL = 00 00 00 00 00 00 01 50 2010 E = c8 0e df a3 2d df 39 d5 ef 00 c0 b4 68 83 42 79 2011 a2 e4 6a 1b 80 49 f7 92 f7 6b fe 54 b9 03 a9 c9 2012 a9 4a c9 b4 7a d2 65 5c 5f 10 f9 ae f7 14 27 e2 2013 fc 6f 9b 3f 39 9a 22 14 89 f1 63 62 c7 03 23 36 2014 09 d4 5a c6 98 64 e3 32 1c f8 29 35 ac 40 96 c8 2015 6e 13 33 14 c5 40 19 e8 ca 79 80 df a4 b9 cf 1b 2016 38 4c 48 6f 3a 54 c5 10 78 15 8e e5 d7 9d e5 9f 2017 bd 34 d8 48 b3 d6 95 50 a6 76 46 34 44 27 ad e5 2018 4b 88 51 ff b5 98 f7 f8 00 74 b9 47 3c 82 e2 db 2020 M = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2021 e6 e5 45 82 47 65 15 f0 ad 9f 75 a2 b7 1c 73 ef 2023 T = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2025 C.2. Test Cases for AES_256_CBC_HMAC_SHA_512 2027 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2028 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2029 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2030 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2032 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2033 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2035 ENC_KEY = 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2036 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2038 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2039 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2040 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2041 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2042 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2043 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2044 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2045 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2047 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2049 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2050 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2051 4b 65 72 63 6b 68 6f 66 66 73 2053 AL = 00 00 00 00 00 00 01 50 2055 E = 4a ff aa ad b7 8c 31 c5 da 4b 1b 59 0d 10 ff bd 2056 3d d8 d5 d3 02 42 35 26 91 2d a0 37 ec bc c7 bd 2057 82 2c 30 1d d6 7c 37 3b cc b5 84 ad 3e 92 79 c2 2058 e6 d1 2a 13 74 b7 7f 07 75 53 df 82 94 10 44 6b 2059 36 eb d9 70 66 29 6a e6 42 7e a7 5c 2e 08 46 a1 2060 1a 09 cc f5 37 0d c8 0b fe cb ad 28 c7 3f 09 b3 2061 a3 b7 5e 66 2a 25 94 41 0a e4 96 b2 e2 e6 60 9e 2062 31 e6 e0 2c c8 37 f0 53 d2 1f 37 ff 4f 51 95 0b 2063 be 26 38 d0 9d d7 a4 93 09 30 80 6d 07 03 b1 f6 2065 M = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2066 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2067 fd 30 a5 65 c6 16 ff b2 f3 64 ba ec e6 8f c4 07 2068 53 bc fc 02 5d de 36 93 75 4a a1 f5 c3 37 3b 9c 2070 T = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2071 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2073 Appendix D. Acknowledgements 2075 Solutions for signing and encrypting JSON content were previously 2076 explored by Magic Signatures [MagicSignatures], JSON Simple Sign 2077 [JSS], Canvas Applications [CanvasApp], JSON Simple Encryption [JSE], 2078 and JavaScript Message Security Format [I-D.rescorla-jsms], all of 2079 which influenced this draft. 2081 The Authenticated Encryption with AES-CBC and HMAC-SHA 2082 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] specification, upon which the 2083 AES_CBC_HMAC_SHA2 algorithms are based, was written by David A. 2084 McGrew and Kenny Paterson. The test cases for AES_CBC_HMAC_SHA2 are 2085 based upon those for [I-D.mcgrew-aead-aes-cbc-hmac-sha2] by John 2086 Foley. 2088 This specification is the work of the JOSE Working Group, which 2089 includes dozens of active and dedicated participants. In particular, 2090 the following individuals contributed ideas, feedback, and wording 2091 that influenced this specification: 2093 Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de 2094 Medeiros, Yaron Y. Goland, Dick Hardt, Jeff Hodges, Edmund Jay, James 2095 Manger, Tony Nadalin, Axel Nennker, John Panzer, Emmanuel Raviart, 2096 Nat Sakimura, Jim Schaad, Hannes Tschofenig, and Sean Turner. 2098 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2099 Sean Turner and Stephen Farrell served as Security area directors 2100 during the creation of this specification. 2102 Appendix E. Document History 2104 [[ to be removed by the RFC editor before publication as an RFC ]] 2106 -10 2108 o Changed the JWE processing rules for multiple recipients so that a 2109 single AAD value contains the header parameters and encrypted key 2110 values for all the recipients, enabling AES GCM to be safely used 2111 for multiple recipients. 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 2175 o Removed the "int" and "kdf" parameters and defined the new 2176 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2177 "A256CBC+HS512" to replace the former uses of AES CBC, which 2178 required the use of separate integrity and key derivation 2179 functions. 2181 o Included additional values in the Concat KDF calculation -- the 2182 desired output size and the algorithm value, and optionally 2183 PartyUInfo and PartyVInfo values. Added the optional header 2184 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2185 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2186 PartyVInfo). 2188 o Changed the name of the JWK RSA exponent parameter from "exp" to 2189 "xpo" so as to allow the potential use of the name "exp" for a 2190 future extension that might define an expiration parameter for 2191 keys. (The "exp" name is already used for this purpose in the JWT 2192 specification.) 2194 o Applied changes made by the RFC Editor to RFC 6749's registry 2195 language to this specification. 2197 -05 2199 o Support both direct encryption using a shared or agreed upon 2200 symmetric key, and the use of a shared or agreed upon symmetric 2201 key to key wrap the CMK. Specifically, added the "alg" values 2202 "dir", "ECDH-ES+A128KW", and "ECDH-ES+A256KW" to finish filling in 2203 this set of capabilities. 2205 o Updated open issues. 2207 -04 2209 o Added text requiring that any leading zero bytes be retained in 2210 base64url encoded key value representations for fixed-length 2211 values. 2213 o Added this language to Registration Templates: "This name is case 2214 sensitive. Names that match other registered names in a case 2215 insensitive manner SHOULD NOT be accepted." 2217 o Described additional open issues. 2219 o Applied editorial suggestions. 2221 -03 2223 o Always use a 128 bit "authentication tag" size for AES GCM, 2224 regardless of the key size. 2226 o Specified that use of a 128 bit IV is REQUIRED with AES CBC. It 2227 was previously RECOMMENDED. 2229 o Removed key size language for ECDSA algorithms, since the key size 2230 is implied by the algorithm being used. 2232 o Stated that the "int" key size must be the same as the hash output 2233 size (and not larger, as was previously allowed) so that its size 2234 is defined for key generation purposes. 2236 o Added the "kdf" (key derivation function) header parameter to 2237 provide crypto agility for key derivation. The default KDF 2238 remains the Concat KDF with the SHA-256 digest function. 2240 o Clarified that the "mod" and "exp" values are unsigned. 2242 o Added Implementation Requirements columns to algorithm tables and 2243 Implementation Requirements entries to algorithm registries. 2245 o Changed AES Key Wrap to RECOMMENDED. 2247 o Moved registries JSON Web Signature and Encryption Header 2248 Parameters and JSON Web Signature and Encryption Type Values to 2249 the JWS specification. 2251 o Moved JSON Web Key Parameters registry to the JWK specification. 2253 o Changed registration requirements from RFC Required to 2254 Specification Required with Expert Review. 2256 o Added Registration Template sections for defined registries. 2258 o Added Registry Contents sections to populate registry values. 2260 o No longer say "the UTF-8 representation of the JWS Secured Input 2261 (which is the same as the ASCII representation)". Just call it 2262 "the ASCII representation of the JWS Secured Input". 2264 o Added "Collision Resistant Namespace" to the terminology section. 2266 o Numerous editorial improvements. 2268 -02 2270 o For AES GCM, use the "additional authenticated data" parameter to 2271 provide integrity for the header, encrypted key, and ciphertext 2272 and use the resulting "authentication tag" value as the JWE 2273 Authentication Tag. 2275 o Defined minimum required key sizes for algorithms without 2276 specified key sizes. 2278 o Defined KDF output key sizes. 2280 o Specified the use of PKCS #5 padding with AES CBC. 2282 o Generalized text to allow key agreement to be employed as an 2283 alternative to key wrapping or key encryption. 2285 o Clarified that ECDH-ES is a key agreement algorithm. 2287 o Required implementation of AES-128-KW and AES-256-KW. 2289 o Removed the use of "A128GCM" and "A256GCM" for key wrapping. 2291 o Removed "A512KW" since it turns out that it's not a standard 2292 algorithm. 2294 o Clarified the relationship between "typ" header parameter values 2295 and MIME types. 2297 o Generalized language to refer to Message Authentication Codes 2298 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2299 unless in a context specific to HMAC algorithms. 2301 o Established registries: JSON Web Signature and Encryption Header 2302 Parameters, JSON Web Signature and Encryption Algorithms, JSON Web 2303 Signature and Encryption "typ" Values, JSON Web Key Parameters, 2304 and JSON Web Key Algorithm Families. 2306 o Moved algorithm-specific definitions from JWK to JWA. 2308 o Reformatted to give each member definition its own section 2309 heading. 2311 -01 2312 o Moved definition of "alg":"none" for JWSs here from the JWT 2313 specification since this functionality is likely to be useful in 2314 more contexts that just for JWTs. 2316 o Added Advanced Encryption Standard (AES) Key Wrap Algorithm using 2317 512 bit keys ("A512KW"). 2319 o Added text "Alternatively, the Encoded JWS Signature MAY be 2320 base64url decoded to produce the JWS Signature and this value can 2321 be compared with the computed HMAC value, as this comparison 2322 produces the same result as comparing the encoded values". 2324 o Corrected the Magic Signatures reference. 2326 o Made other editorial improvements suggested by JOSE working group 2327 participants. 2329 -00 2331 o Created the initial IETF draft based upon 2332 draft-jones-json-web-signature-04 and 2333 draft-jones-json-web-encryption-02 with no normative changes. 2335 o Changed terminology to no longer call both digital signatures and 2336 HMACs "signatures". 2338 Author's Address 2340 Michael B. Jones 2341 Microsoft 2343 Email: mbj@microsoft.com 2344 URI: http://self-issued.info/