idnits 2.17.1 draft-ietf-jose-json-web-algorithms-13.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 seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (July 15, 2013) is 3937 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 1485 -- Looks like a reference, but probably isn't: '0' on line 1485 -- 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 ** Obsolete normative reference: RFC 2898 (Obsoleted by RFC 8018) ** 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: 6 errors (**), 0 flaws (~~), 4 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 July 15, 2013 5 Expires: January 16, 2014 7 JSON Web Algorithms (JWA) 8 draft-ietf-jose-json-web-algorithms-13 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 January 16, 2014. 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 . . . . . . . . . . . . . . . . . . . . . . . . . 5 52 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 53 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 54 2.1. Terms Incorporated from the JWS Specification . . . . . . 5 55 2.2. Terms Incorporated from the JWE Specification . . . . . . 6 56 2.3. Terms Incorporated from the JWK Specification . . . . . . 9 57 2.4. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 9 58 3. Cryptographic Algorithms for JWS . . . . . . . . . . . . . . . 9 59 3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 9 60 3.2. MAC with HMAC SHA-256, HMAC SHA-384, or HMAC SHA-512 . . . 10 61 3.3. Digital Signature with RSASSA-PKCS1-V1_5 and SHA-256, 62 SHA-384, or SHA-512 . . . . . . . . . . . . . . . . . . . 11 63 3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA 64 P-384 SHA-384, or ECDSA P-521 SHA-512 . . . . . . . . . . 12 65 3.5. Digital Signature with RSASSA-PSS and SHA-256 or 66 SHA-512 . . . . . . . . . . . . . . . . . . . . . . . . . 14 67 3.6. Using the Algorithm "none" . . . . . . . . . . . . . . . . 15 68 3.7. Additional Digital Signature/MAC Algorithms and 69 Parameters . . . . . . . . . . . . . . . . . . . . . . . . 15 70 4. Cryptographic Algorithms for JWE . . . . . . . . . . . . . . . 16 71 4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 16 72 4.2. "enc" (Encryption Method) Header Parameter Values for 73 JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 74 4.3. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 20 75 4.4. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 21 76 4.5. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 21 77 4.6. Direct Encryption with a Shared Symmetric Key . . . . . . 21 78 4.7. Key Agreement with Elliptic Curve Diffie-Hellman 79 Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 21 80 4.7.1. Header Parameters Used for ECDH Key Agreement . . . . 22 81 4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 22 82 4.7.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 22 83 4.7.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 22 84 4.7.2. Key Derivation for ECDH Key Agreement . . . . . . . . 22 85 4.8. Key Encryption with AES GCM . . . . . . . . . . . . . . . 24 86 4.8.1. Header Parameters Used for AES GCM Key Encryption . . 24 87 4.8.1.1. "iv" (Initialization Vector) Header Parameter . . 24 88 4.8.1.2. "tag" (Authentication Tag) Header Parameter . . . 24 89 4.9. Key Encryption with PBES2 . . . . . . . . . . . . . . . . 25 90 4.9.1. PBES2-HS256+A128KW . . . . . . . . . . . . . . . . . . 25 91 4.9.2. PBES2-HS256+A256KW . . . . . . . . . . . . . . . . . . 25 92 4.10. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 25 93 4.10.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 26 94 4.10.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 26 95 4.10.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 26 96 4.10.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 28 98 4.10.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 28 99 4.10.4. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 29 100 4.10.5. Plaintext Encryption with AES_CBC_HMAC_SHA2 . . . . . 29 101 4.11. Plaintext Encryption with AES GCM . . . . . . . . . . . . 29 102 4.12. Additional Encryption Algorithms and Parameters . . . . . 30 103 5. Cryptographic Algorithms for JWK . . . . . . . . . . . . . . . 30 104 5.1. "kty" (Key Type) Parameter Values for JWK . . . . . . . . 30 105 5.2. JWK Parameters for Elliptic Curve Keys . . . . . . . . . . 31 106 5.2.1. JWK Parameters for Elliptic Curve Public Keys . . . . 31 107 5.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 31 108 5.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 32 109 5.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 32 110 5.2.2. JWK Parameters for Elliptic Curve Private Keys . . . . 32 111 5.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 32 112 5.3. JWK Parameters for RSA Keys . . . . . . . . . . . . . . . 32 113 5.3.1. JWK Parameters for RSA Public Keys . . . . . . . . . . 32 114 5.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 33 115 5.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 33 116 5.3.2. JWK Parameters for RSA Private Keys . . . . . . . . . 33 117 5.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 33 118 5.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 33 119 5.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 33 120 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 34 121 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 34 122 5.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 34 123 5.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 34 124 5.3.3. JWK Parameters for Symmetric Keys . . . . . . . . . . 35 125 5.3.3.1. "k" (Key Value) Parameter . . . . . . . . . . . . 35 126 5.3.4. JWK Parameters for PBKDF2 Keys . . . . . . . . . . . . 35 127 5.3.4.1. "s" (salt) Parameter . . . . . . . . . . . . . . . 35 128 5.3.4.2. "c" (count) Parameter . . . . . . . . . . . . . . 35 129 5.3.4.3. "hint" (password hint) Parameter . . . . . . . . . 36 130 5.4. Additional Key Types and Parameters . . . . . . . . . . . 36 131 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 132 6.1. JSON Web Signature and Encryption Algorithms Registry . . 37 133 6.1.1. Template . . . . . . . . . . . . . . . . . . . . . . . 37 134 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 38 135 6.2. JSON Web Key Types Registry . . . . . . . . . . . . . . . 41 136 6.2.1. Registration Template . . . . . . . . . . . . . . . . 42 137 6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 42 138 6.3. JSON Web Key Parameters Registration . . . . . . . . . . . 43 139 6.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 43 140 6.4. Registration of JWE Header Parameter Names . . . . . . . . 45 141 6.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 45 142 7. Security Considerations . . . . . . . . . . . . . . . . . . . 45 143 7.1. Reusing Key Material when Encrypting Keys . . . . . . . . 47 144 7.2. Password Considerations . . . . . . . . . . . . . . . . . 47 145 8. Internationalization Considerations . . . . . . . . . . . . . 47 146 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 48 147 9.1. Normative References . . . . . . . . . . . . . . . . . . . 48 148 9.2. Informative References . . . . . . . . . . . . . . . . . . 49 149 Appendix A. Digital Signature/MAC Algorithm Identifier 150 Cross-Reference . . . . . . . . . . . . . . . . . . . 51 151 Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 53 152 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 55 153 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 56 154 C.2. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 57 155 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 58 156 Appendix E. Document History . . . . . . . . . . . . . . . . . . 58 157 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 64 159 1. Introduction 161 The JSON Web Algorithms (JWA) specification enumerates cryptographic 162 algorithms and identifiers to be used with the JSON Web Signature 163 (JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK) 164 [JWK] specifications. All these specifications utilize JavaScript 165 Object Notation (JSON) [RFC4627] based data structures. This 166 specification also describes the semantics and operations that are 167 specific to these algorithms and key types. 169 Enumerating the algorithms and identifiers for them in this 170 specification, rather than in the JWS, JWE, and JWK specifications, 171 is intended to allow them to remain unchanged in the face of changes 172 in the set of required, recommended, optional, and deprecated 173 algorithms over time. 175 1.1. Notational Conventions 177 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 178 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 179 document are to be interpreted as described in Key words for use in 180 RFCs to Indicate Requirement Levels [RFC2119]. 182 2. Terminology 184 2.1. Terms Incorporated from the JWS Specification 186 These terms defined by the JSON Web Signature (JWS) [JWS] 187 specification are incorporated into this specification: 189 JSON Web Signature (JWS) A data structure representing a digitally 190 signed or MACed message. The structure represents three values: 191 the JWS Header, the JWS Payload, and the JWS Signature. 193 JSON Text Object A UTF-8 [RFC3629] encoded text string representing 194 a JSON object; the syntax of JSON objects is defined in Section 195 2.2 of [RFC4627]. 197 JWS Header A JSON Text Object (or JSON Text Objects, when using the 198 JWS JSON Serialization) that describes the digital signature or 199 MAC operation applied to create the JWS Signature value. The 200 members of the JWS Header object(s) are Header Parameters. 202 JWS Payload The sequence of octets to be secured -- a.k.a., the 203 message. The payload can contain an arbitrary sequence of octets. 205 JWS Signature A sequence of octets containing the cryptographic 206 material that ensures the integrity of the JWS Protected Header 207 and the JWS Payload. The JWS Signature value is a digital 208 signature or MAC value calculated over the JWS Signing Input using 209 the parameters specified in the JWS Header. 211 JWS Protected Header A JSON Text Object that contains the portion of 212 the JWS Header that is integrity protected. For the JWS Compact 213 Serialization, this comprises the entire JWS Header. For the JWS 214 JSON Serialization, this is one component of the JWS Header. 216 Base64url Encoding The URL- and filename-safe Base64 encoding 217 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 218 safe) '=' padding characters omitted, as permitted by Section 3.2. 219 (See Appendix C of [JWS] for notes on implementing base64url 220 encoding without padding.) 222 Encoded JWS Header Base64url encoding of the JWS Protected Header. 224 Encoded JWS Payload Base64url encoding of the JWS Payload. 226 Encoded JWS Signature Base64url encoding of the JWS Signature. 228 JWS Signing Input The concatenation of the Encoded JWS Header, a 229 period ('.') character, and the Encoded JWS Payload. 231 Collision Resistant Namespace A namespace that allows names to be 232 allocated in a manner such that they are highly unlikely to 233 collide with other names. For instance, collision resistance can 234 be achieved through administrative delegation of portions of the 235 namespace or through use of collision-resistant name allocation 236 functions. Examples of Collision Resistant Namespaces include: 237 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 238 X.660 and X.670 Recommendation series, and Universally Unique 239 IDentifiers (UUIDs) [RFC4122]. When using an administratively 240 delegated namespace, the definer of a name needs to take 241 reasonable precautions to ensure they are in control of the 242 portion of the namespace they use to define the name. 244 2.2. Terms Incorporated from the JWE Specification 246 These terms defined by the JSON Web Encryption (JWE) [JWE] 247 specification are incorporated into this specification: 249 JSON Web Encryption (JWE) A data structure representing an encrypted 250 message. The structure represents five values: the JWE Header, 251 the JWE Encrypted Key, the JWE Initialization Vector, the JWE 252 Ciphertext, and the JWE Authentication Tag. 254 Authenticated Encryption An Authenticated Encryption algorithm is 255 one that provides an integrated content integrity check. 256 Authenticated Encryption algorithms accept two inputs, the 257 Plaintext and the Additional Authenticated Data value, and produce 258 two outputs, the Ciphertext and the Authentication Tag value. AES 259 Galois/Counter Mode (GCM) is one such algorithm. 261 Plaintext The sequence of octets to be encrypted -- a.k.a., the 262 message. The plaintext can contain an arbitrary sequence of 263 octets. 265 Ciphertext An encrypted representation of the Plaintext. 267 Additional Authenticated Data (AAD) An input to an Authenticated 268 Encryption operation that is integrity protected but not 269 encrypted. 271 Authentication Tag An output of an Authenticated Encryption 272 operation that ensures the integrity of the Ciphertext and the 273 Additional Authenticated Data. Note that some algorithms may not 274 use an Authentication Tag, in which case this value is the empty 275 octet sequence. 277 Content Encryption Key (CEK) A symmetric key for the Authenticated 278 Encryption algorithm used to encrypt the Plaintext for the 279 recipient to produce the Ciphertext and the Authentication Tag. 281 JWE Header A JSON Text Object (or JSON Text Objects, when using the 282 JWE JSON Serialization) that describes the encryption operations 283 applied to create the JWE Encrypted Key, the JWE Ciphertext, and 284 the JWE Authentication Tag. The members of the JWE Header 285 object(s) are Header Parameters. 287 JWE Encrypted Key The result of encrypting the Content Encryption 288 Key (CEK) with the intended recipient's key using the specified 289 algorithm. Note that for some algorithms, the JWE Encrypted Key 290 value is specified as being the empty octet sequence. 292 JWE Initialization Vector A sequence of octets containing the 293 Initialization Vector used when encrypting the Plaintext. Note 294 that some algorithms may not use an Initialization Vector, in 295 which case this value is the empty octet sequence. 297 JWE Ciphertext A sequence of octets containing the Ciphertext for a 298 JWE. 300 JWE Authentication Tag A sequence of octets containing the 301 Authentication Tag for a JWE. 303 JWE Protected Header A JSON Text Object that contains the portion of 304 the JWE Header that is integrity protected. For the JWE Compact 305 Serialization, this comprises the entire JWE Header. For the JWE 306 JSON Serialization, this is one component of the JWE Header. 308 Encoded JWE Header Base64url encoding of the JWE Protected Header. 310 Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted 311 Key. 313 Encoded JWE Initialization Vector Base64url encoding of the JWE 314 Initialization Vector. 316 Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. 318 Encoded JWE Authentication Tag Base64url encoding of the JWE 319 Authentication Tag. 321 Key Management Mode A method of determining the Content Encryption 322 Key (CEK) value to use. Each algorithm used for determining the 323 CEK value uses a specific Key Management Mode. Key Management 324 Modes employed by this specification are Key Encryption, Key 325 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 326 and Direct Encryption. 328 Key Encryption A Key Management Mode in which the Content Encryption 329 Key (CEK) value is encrypted to the intended recipient using an 330 asymmetric encryption algorithm. 332 Key Wrapping A Key Management Mode in which the Content Encryption 333 Key (CEK) value is encrypted to the intended recipient using a 334 symmetric key wrapping algorithm. 336 Direct Key Agreement A Key Management Mode in which a key agreement 337 algorithm is used to agree upon the Content Encryption Key (CEK) 338 value. 340 Key Agreement with Key Wrapping A Key Management Mode in which a key 341 agreement algorithm is used to agree upon a symmetric key used to 342 encrypt the Content Encryption Key (CEK) value to the intended 343 recipient using a symmetric key wrapping algorithm. 345 Direct Encryption A Key Management Mode in which the Content 346 Encryption Key (CEK) value used is the secret symmetric key value 347 shared between the parties. 349 2.3. Terms Incorporated from the JWK Specification 351 These terms defined by the JSON Web Key (JWK) [JWK] specification are 352 incorporated into this specification: 354 JSON Web Key (JWK) A JSON object that represents a cryptographic 355 key. 357 JSON Web Key Set (JWK Set) A JSON object that contains an array of 358 JWKs as the value of its "keys" member. 360 2.4. Defined Terms 362 These terms are defined for use by this specification: 364 Header Parameter A name/value pair that is member of a JWS Header or 365 JWE Header. 367 Header Parameter Name The name of a member of a JSON object 368 representing a JWS Header or JWE Header. 370 Header Parameter Value The value of a member of a JSON object 371 representing a JWS Header or JWE Header. 373 3. Cryptographic Algorithms for JWS 375 JWS uses cryptographic algorithms to digitally sign or create a 376 Message Authentication Codes (MAC) of the contents of the JWS Header 377 and the JWS Payload. The use of the following algorithms for 378 producing JWSs is defined in this section. 380 3.1. "alg" (Algorithm) Header Parameter Values for JWS 382 The table below is the set of "alg" (algorithm) header parameter 383 values defined by this specification for use with JWS, each of which 384 is explained in more detail in the following sections: 386 +-----------+--------------------------------------+----------------+ 387 | alg | Digital Signature or MAC Algorithm | Implementation | 388 | Parameter | | Requirements | 389 | Value | | | 390 +-----------+--------------------------------------+----------------+ 391 | HS256 | HMAC using SHA-256 hash algorithm | REQUIRED | 392 | HS384 | HMAC using SHA-384 hash algorithm | OPTIONAL | 393 | HS512 | HMAC using SHA-512 hash algorithm | OPTIONAL | 394 | RS256 | RSASSA-PKCS-v1_5 using SHA-256 hash | RECOMMENDED | 395 | | algorithm | | 396 | RS384 | RSASSA-PKCS-v1_5 using SHA-384 hash | OPTIONAL | 397 | | algorithm | | 398 | RS512 | RSASSA-PKCS-v1_5 using SHA-512 hash | OPTIONAL | 399 | | algorithm | | 400 | ES256 | ECDSA using P-256 curve and SHA-256 | RECOMMENDED+ | 401 | | hash algorithm | | 402 | ES384 | ECDSA using P-384 curve and SHA-384 | OPTIONAL | 403 | | hash algorithm | | 404 | ES512 | ECDSA using P-521 curve and SHA-512 | OPTIONAL | 405 | | hash algorithm | | 406 | PS256 | RSASSA-PSS using SHA-256 hash | OPTIONAL | 407 | | algorithm and MGF1 mask generation | | 408 | | function with SHA-256 | | 409 | PS512 | RSASSA-PSS using SHA-512 hash | OPTIONAL | 410 | | algorithm and MGF1 mask generation | | 411 | | function with SHA-512 | | 412 | none | No digital signature or MAC value | REQUIRED | 413 | | included | | 414 +-----------+--------------------------------------+----------------+ 416 All the names are short because a core goal of JWS is for the 417 representations to be compact. However, there is no a priori length 418 restriction on "alg" values. 420 The use of "+" in the Implementation Requirements indicates that the 421 requirement strength is likely to be increased in a future version of 422 the specification. 424 See Appendix A for a table cross-referencing the digital signature 425 and MAC "alg" (algorithm) values used in this specification with the 426 equivalent identifiers used by other standards and software packages. 428 3.2. MAC with HMAC SHA-256, HMAC SHA-384, or HMAC SHA-512 430 Hash-based Message Authentication Codes (HMACs) enable one to use a 431 secret plus a cryptographic hash function to generate a Message 432 Authentication Code (MAC). This can be used to demonstrate that the 433 MAC matches the hashed content, in this case the JWS Signing Input, 434 which therefore demonstrates that whoever generated the MAC was in 435 possession of the secret. The means of exchanging the shared key is 436 outside the scope of this specification. 438 The algorithm for implementing and validating HMACs is provided in 439 RFC 2104 [RFC2104]. This section defines the use of the HMAC SHA- 440 256, HMAC SHA-384, and HMAC SHA-512 functions [SHS]. The "alg" 441 (algorithm) header parameter values "HS256", "HS384", and "HS512" are 442 used in the JWS Header to indicate that the Encoded JWS Signature 443 contains a base64url encoded HMAC value using the respective hash 444 function. 446 A key of the same size as the hash output (for instance, 256 bits for 447 "HS256") or larger MUST be used with this algorithm. 449 The HMAC SHA-256 MAC is generated per RFC 2104, using SHA-256 as the 450 hash algorithm "H", using the octets of the ASCII [USASCII] 451 representation of the JWS Signing Input as the "text" value, and 452 using the shared key. The HMAC output value is the JWS Signature. 453 The JWS signature is base64url encoded to produce the Encoded JWS 454 Signature. 456 The HMAC SHA-256 MAC for a JWS is validated by computing an HMAC 457 value per RFC 2104, using SHA-256 as the hash algorithm "H", using 458 the octets of the ASCII representation of the received JWS Signing 459 Input as the "text" value, and using the shared key. This computed 460 HMAC value is then compared to the result of base64url decoding the 461 received Encoded JWS signature. Alternatively, the computed HMAC 462 value can be base64url encoded and compared to the received Encoded 463 JWS Signature, as this comparison produces the same result as 464 comparing the unencoded values. In either case, if the values match, 465 the HMAC has been validated. If the validation fails, the JWS MUST 466 be rejected. 468 Securing content with the HMAC SHA-384 and HMAC SHA-512 algorithms is 469 performed identically to the procedure for HMAC SHA-256 - just using 470 the corresponding hash algorithm with correspondingly larger minimum 471 key sizes and result values: 384 bits each for HMAC SHA-384 and 512 472 bits each for HMAC SHA-512. 474 An example using this algorithm is shown in Appendix A.1 of [JWS]. 476 3.3. Digital Signature with RSASSA-PKCS1-V1_5 and SHA-256, SHA-384, or 477 SHA-512 479 This section defines the use of the RSASSA-PKCS1-V1_5 digital 480 signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447] 481 (commonly known as PKCS #1), using SHA-256, SHA-384, or SHA-512 [SHS] 482 as the hash functions. The "alg" (algorithm) header parameter values 483 "RS256", "RS384", and "RS512" are used in the JWS Header to indicate 484 that the Encoded JWS Signature contains a base64url encoded RSASSA- 485 PKCS1-V1_5 digital signature using the respective hash function. 487 A key of size 2048 bits or larger MUST be used with these algorithms. 489 The RSASSA-PKCS1-V1_5 SHA-256 digital signature is generated as 490 follows: 492 1. Generate a digital signature of the octets of the ASCII 493 representation of the JWS Signing Input using RSASSA-PKCS1-V1_5- 494 SIGN and the SHA-256 hash function with the desired private key. 495 The output will be an octet sequence. 497 2. Base64url encode the resulting octet sequence. 499 The output is the Encoded JWS Signature for that JWS. 501 The RSASSA-PKCS1-V1_5 SHA-256 digital signature for a JWS is 502 validated as follows: 504 1. Take the Encoded JWS Signature and base64url decode it into an 505 octet sequence. If decoding fails, the JWS MUST be rejected. 507 2. Submit the octets of the ASCII representation of the JWS Signing 508 Input and the public key corresponding to the private key used by 509 the signer to the RSASSA-PKCS1-V1_5-VERIFY algorithm using SHA- 510 256 as the hash function. 512 3. If the validation fails, the JWS MUST be rejected. 514 Signing with the RSASSA-PKCS1-V1_5 SHA-384 and RSASSA-PKCS1-V1_5 SHA- 515 512 algorithms is performed identically to the procedure for RSASSA- 516 PKCS1-V1_5 SHA-256 - just using the corresponding hash algorithm with 517 correspondingly larger result values: 384 bits for RSASSA-PKCS1-V1_5 518 SHA-384 and 512 bits for RSASSA-PKCS1-V1_5 SHA-512. 520 An example using this algorithm is shown in Appendix A.2 of [JWS]. 522 3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA P-384 SHA-384, 523 or ECDSA P-521 SHA-512 525 The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides 526 for the use of Elliptic Curve cryptography, which is able to provide 527 equivalent security to RSA cryptography but using shorter key sizes 528 and with greater processing speed. This means that ECDSA digital 529 signatures will be substantially smaller in terms of length than 530 equivalently strong RSA digital signatures. 532 This specification defines the use of ECDSA with the P-256 curve and 533 the SHA-256 cryptographic hash function, ECDSA with the P-384 curve 534 and the SHA-384 hash function, and ECDSA with the P-521 curve and the 535 SHA-512 hash function. The P-256, P-384, and P-521 curves are 536 defined in [DSS]. The "alg" (algorithm) header parameter values 537 "ES256", "ES384", and "ES512" are used in the JWS Header to indicate 538 that the Encoded JWS Signature contains a base64url encoded ECDSA 539 P-256 SHA-256, ECDSA P-384 SHA-384, or ECDSA P-521 SHA-512 digital 540 signature, respectively. 542 The ECDSA P-256 SHA-256 digital signature is generated as follows: 544 1. Generate a digital signature of the octets of the ASCII 545 representation of the JWS Signing Input using ECDSA P-256 SHA-256 546 with the desired private key. The output will be the pair (R, 547 S), where R and S are 256 bit unsigned integers. 549 2. Turn R and S into octet sequences in big endian order, with each 550 array being be 32 octets long. The array representations MUST 551 NOT be shortened to omit any leading zero octets contained in the 552 values. 554 3. Concatenate the two octet sequences in the order R and then S. 555 (Note that many ECDSA implementations will directly produce this 556 concatenation as their output.) 558 4. Base64url encode the resulting 64 octet sequence. 560 The output is the Encoded JWS Signature for the JWS. 562 The ECDSA P-256 SHA-256 digital signature for a JWS is validated as 563 follows: 565 1. Take the Encoded JWS Signature and base64url decode it into an 566 octet sequence. If decoding fails, the JWS MUST be rejected. 568 2. The output of the base64url decoding MUST be a 64 octet sequence. 569 If decoding does not result in a 64 octet sequence, the JWS MUST 570 be rejected. 572 3. Split the 64 octet sequence into two 32 octet sequences. The 573 first array will be R and the second S (with both being in big 574 endian octet order). 576 4. Submit the octets of the ASCII representation of the JWS Signing 577 Input R, S and the public key (x, y) to the ECDSA P-256 SHA-256 578 validator. 580 5. If the validation fails, the JWS MUST be rejected. 582 Note that ECDSA digital signature contains a value referred to as K, 583 which is a random number generated for each digital signature 584 instance. This means that two ECDSA digital signatures using exactly 585 the same input parameters will output different signature values 586 because their K values will be different. A consequence of this is 587 that one cannot validate an ECDSA signature by recomputing the 588 signature and comparing the results. 590 Signing with the ECDSA P-384 SHA-384 and ECDSA P-521 SHA-512 591 algorithms is performed identically to the procedure for ECDSA P-256 592 SHA-256 - just using the corresponding hash algorithm with 593 correspondingly larger result values. For ECDSA P-384 SHA-384, R and 594 S will be 384 bits each, resulting in a 96 octet sequence. For ECDSA 595 P-521 SHA-512, R and S will be 521 bits each, resulting in a 132 596 octet sequence. 598 Examples using these algorithms are shown in Appendices A.3 and A.4 599 of [JWS]. 601 3.5. Digital Signature with RSASSA-PSS and SHA-256 or SHA-512 603 This section defines the use of the RSASSA-PSS digital signature 604 algorithm as defined in Section 8.1 of RFC 3447 [RFC3447] with the 605 MGF1 mask generation function, always using the same hash function 606 for both the RSASSA-PSS hash function and the MGF1 hash function. 607 Use of both SHA-256 and SHA-512 as these hash functions is defined. 608 All other algorithm parameters use the defaults specified in Section 609 A.2.3 of RFC 3447. The "alg" (algorithm) header parameter values 610 "PS256" and "PS512" is used in the JWS Header to indicate that the 611 Encoded JWS Signature contains a base64url encoded RSASSA-PSS digital 612 signature using the respective hash function in both roles. 614 A key of size 2048 bits or larger MUST be used with this algorithm. 616 The RSASSA-PSS SHA-256 digital signature is generated as follows: 618 1. Generate a digital signature of the octets of the ASCII 619 representation of the JWS Signing Input using RSASSA-PSS-SIGN, 620 the SHA-256 hash function, and the MGF1 mask generation function 621 with SHA-256 with the desired private key. The output will be an 622 octet sequence. 624 2. Base64url encode the resulting octet sequence. 626 The output is the Encoded JWS Signature for that JWS. 628 The RSASSA-PSS SHA-256 digital signature for a JWS is validated as 629 follows: 631 1. Take the Encoded JWS Signature and base64url decode it into an 632 octet sequence. If decoding fails, the JWS MUST be rejected. 634 2. Submit the octets of the ASCII representation of the JWS Signing 635 Input and the public key corresponding to the private key used by 636 the signer to the RSASSA-PSS-VERIFY algorithm using SHA-256 as 637 the hash function and using MGF1 as the mask generation function 638 with SHA-256. 640 3. If the validation fails, the JWS MUST be rejected. 642 Signing with the RSASSA-PSS SHA-512 algorithm is performed 643 identically to the procedure for RSASSA-PSS SHA-256 - just using the 644 alternative hash algorithm in both roles. 646 3.6. Using the Algorithm "none" 648 JWSs MAY also be created that do not provide integrity protection. 649 Such a JWS is called a "Plaintext JWS". Plaintext JWSs MUST use the 650 "alg" value "none", and are formatted identically to other JWSs, but 651 with the empty string for its JWS Signature value. 653 3.7. Additional Digital Signature/MAC Algorithms and Parameters 655 Additional algorithms MAY be used to protect JWSs with corresponding 656 "alg" (algorithm) header parameter values being defined to refer to 657 them. New "alg" header parameter values SHOULD either be registered 658 in the IANA JSON Web Signature and Encryption Algorithms registry 659 Section 6.1 or be a value that contains a Collision Resistant 660 Namespace. In particular, it is permissible to use the algorithm 661 identifiers defined in XML DSIG [RFC3275], XML DSIG 2.0 662 [W3C.CR-xmldsig-core2-20120124], and related specifications as "alg" 663 values. 665 As indicated by the common registry, JWSs and JWEs share a common 666 "alg" value space. The values used by the two specifications MUST be 667 distinct, as the "alg" value can be used to determine whether the 668 object is a JWS or JWE. 670 Likewise, additional reserved Header Parameter Names can be defined 671 via the IANA JSON Web Signature and Encryption Header Parameters 672 registry [JWS]. As indicated by the common registry, JWSs and JWEs 673 share a common header parameter space; when a parameter is used by 674 both specifications, its usage must be compatible between the 675 specifications. 677 4. Cryptographic Algorithms for JWE 679 JWE uses cryptographic algorithms to encrypt the Content Encryption 680 Key (CEK) and the Plaintext. This section specifies a set of 681 specific algorithms for these purposes. 683 4.1. "alg" (Algorithm) Header Parameter Values for JWE 685 The table below is the set of "alg" (algorithm) header parameter 686 values that are defined by this specification for use with JWE. 687 These algorithms are used to encrypt the CEK, producing the JWE 688 Encrypted Key, or to use key agreement to agree upon the CEK. 690 +-------------------+-----------------+------------+----------------+ 691 | alg Parameter | Key Management | Additional | Implementation | 692 | Value | Algorithm | Header | Requirements | 693 | | | Parameters | | 694 +-------------------+-----------------+------------+----------------+ 695 | RSA1_5 | RSAES-PKCS1-V1_ | (none) | REQUIRED | 696 | | 5[RFC3447] | | | 697 | RSA-OAEP | RSAES using | (none) | OPTIONAL | 698 | | Optimal | | | 699 | | Asymmetric | | | 700 | | Encryption | | | 701 | | Padding (OAEP) | | | 702 | | [RFC3447], with | | | 703 | | the default | | | 704 | | parameters | | | 705 | | specified by | | | 706 | | RFC 3447 in | | | 707 | | Section A.2.1 | | | 708 | A128KW | Advanced | (none) | RECOMMENDED | 709 | | Encryption | | | 710 | | Standard (AES) | | | 711 | | Key Wrap | | | 712 | | Algorithm | | | 713 | | [RFC3394] using | | | 714 | | the default | | | 715 | | initial value | | | 716 | | specified in | | | 717 | | Section 2.2.3.1 | | | 718 | | and using 128 | | | 719 | | bit keys | | | 720 | A256KW | AES Key Wrap | (none) | RECOMMENDED | 721 | | Algorithm using | | | 722 | | the default | | | 723 | | initial value | | | 724 | | specified in | | | 725 | | Section 2.2.3.1 | | | 726 | | and using 256 | | | 727 | | bit keys | | | 728 | dir | Direct use of a | (none) | RECOMMENDED | 729 | | shared | | | 730 | | symmetric key | | | 731 | | as the Content | | | 732 | | Encryption Key | | | 733 | | (CEK) for the | | | 734 | | content | | | 735 | | encryption step | | | 736 | | (rather than | | | 737 | | using the | | | 738 | | symmetric key | | | 739 | | to wrap the | | | 740 | | CEK) | | | 741 | ECDH-ES | Elliptic Curve | "epk", | RECOMMENDED+ | 742 | | Diffie-Hellman | "apu", | | 743 | | Ephemeral | "apv" | | 744 | | Static | | | 745 | | [RFC6090] key | | | 746 | | agreement using | | | 747 | | the Concat KDF, | | | 748 | | as defined in | | | 749 | | Section 5.8.1 | | | 750 | | of | | | 751 | | [NIST.800-56A], | | | 752 | | with the | | | 753 | | agreed-upon key | | | 754 | | being used | | | 755 | | directly as the | | | 756 | | Content | | | 757 | | Encryption Key | | | 758 | | (CEK) (rather | | | 759 | | than being used | | | 760 | | to wrap the | | | 761 | | CEK), as | | | 762 | | specified in | | | 763 | | Section 4.7 | | | 764 | ECDH-ES+A128KW | Elliptic Curve | "epk", | RECOMMENDED | 765 | | Diffie-Hellman | "apu", | | 766 | | Ephemeral | "apv" | | 767 | | Static key | | | 768 | | agreement per | | | 769 | | "ECDH-ES" and | | | 770 | | Section 4.7, | | | 771 | | but where the | | | 772 | | agreed-upon key | | | 773 | | is used to wrap | | | 774 | | the Content | | | 775 | | Encryption Key | | | 776 | | (CEK) with the | | | 777 | | "A128KW" | | | 778 | | function | | | 779 | | (rather than | | | 780 | | being used | | | 781 | | directly as the | | | 782 | | CEK) | | | 783 | ECDH-ES+A256KW | Elliptic Curve | "epk", | RECOMMENDED | 784 | | Diffie-Hellman | "apu", | | 785 | | Ephemeral | "apv" | | 786 | | Static key | | | 787 | | agreement, but | | | 788 | | where the | | | 789 | | agreed-upon key | | | 790 | | is used to wrap | | | 791 | | the Content | | | 792 | | Encryption Key | | | 793 | | (CEK) with the | | | 794 | | "A256KW" | | | 795 | | function | | | 796 | | (rather than | | | 797 | | being used | | | 798 | | directly as the | | | 799 | | CEK) | | | 800 | A128GCMKW | AES in | "iv", | OPTIONAL | 801 | | Galois/Counter | "tag" | | 802 | | Mode (GCM) | | | 803 | | [AES] | | | 804 | | [NIST.800-38D] | | | 805 | | using 128 bit | | | 806 | | keys | | | 807 | A256GCMKW | AES GCM using | "iv", | OPTIONAL | 808 | | 256 bit keys | "tag" | | 809 | PBES2-HS256+A128K | PBES2 [RFC2898] | (none) | OPTIONAL | 810 | W | with HMAC | | | 811 | | SHA-256 as the | | | 812 | | PRF and AES Key | | | 813 | | Wrap [RFC3394] | | | 814 | | using 128 bit | | | 815 | | keys for the | | | 816 | | encryption | | | 817 | | scheme | | | 818 | PBES2-HS256+A256K | PBES2 with HMAC | (none) | OPTIONAL | 819 | W | SHA-256 as the | | | 820 | | PRF and AES Key | | | 821 | | Wrap using 256 | | | 822 | | bit keys for | | | 823 | | the encryption | | | 824 | | scheme | | | 825 +-------------------+-----------------+------------+----------------+ 827 All the names are short because a core goal of JWE is for the 828 representations to be compact. However, there is no a priori length 829 restriction on "alg" values. 831 The Additional Header Parameters column indicates what additional 832 Header Parameters are used by the algorithm, beyond "alg", which all 833 use. All but "dir" and "ECDH-ES" also produce a JWE Encrypted Key 834 value. 836 The use of "+" in the Implementation Requirements indicates that the 837 requirement strength is likely to be increased in a future version of 838 the specification. 840 4.2. "enc" (Encryption Method) Header Parameter Values for JWE 842 The table below is the set of "enc" (encryption method) header 843 parameter values that are defined by this specification for use with 844 JWE. These algorithms are used to encrypt the Plaintext, which 845 produces the Ciphertext. 847 +-------------+------------------------+------------+---------------+ 848 | enc | Content Encryption | Additional | Implementatio | 849 | Parameter | Algorithm | Header | nRequirements | 850 | Value | | Parameters | | 851 +-------------+------------------------+------------+---------------+ 852 | A128CBC-HS2 | The | (none) | REQUIRED | 853 | 56 | AES_128_CBC_HMAC_SHA_2 | | | 854 | | 56 authenticated | | | 855 | | encryption algorithm, | | | 856 | | as defined in | | | 857 | | Section 4.10.3. This | | | 858 | | algorithm uses a 256 | | | 859 | | bit key. | | | 860 | A256CBC-HS5 | The | (none) | REQUIRED | 861 | 12 | AES_256_CBC_HMAC_SHA_5 | | | 862 | | 12 authenticated | | | 863 | | encryption algorithm, | | | 864 | | as defined in | | | 865 | | Section 4.10.4. This | | | 866 | | algorithm uses a 512 | | | 867 | | bit key. | | | 868 | A128GCM | AES in Galois/Counter | (none) | RECOMMENDED | 869 | | Mode (GCM) [AES] | | | 870 | | [NIST.800-38D] using | | | 871 | | 128 bit keys | | | 872 | A256GCM | AES GCM using 256 bit | (none) | RECOMMENDED | 873 | | keys | | | 874 +-------------+------------------------+------------+---------------+ 876 The Additional Header Parameters column indicates what additional 877 Header Parameters are used by the algorithm, beyond "enc", which all 878 use. All also use a JWE Initialization Vector value and produce JWE 879 Ciphertext and JWE Authentication Tag values. 881 See Appendix B for a table cross-referencing the encryption "alg" 882 (algorithm) and "enc" (encryption method) values used in this 883 specification with the equivalent identifiers used by other standards 884 and software packages. 886 4.3. Key Encryption with RSAES-PKCS1-V1_5 888 This section defines the specifics of encrypting a JWE CEK with 889 RSAES-PKCS1-V1_5 [RFC3447]. The "alg" header parameter value 890 "RSA1_5" is used in this case. 892 A key of size 2048 bits or larger MUST be used with this algorithm. 894 An example using this algorithm is shown in Appendix A.2 of [JWE]. 896 4.4. Key Encryption with RSAES OAEP 898 This section defines the specifics of encrypting a JWE CEK with RSAES 899 using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447], with 900 the default parameters specified by RFC 3447 in Section A.2.1. The 901 "alg" header parameter value "RSA-OAEP" is used in this case. 903 A key of size 2048 bits or larger MUST be used with this algorithm. 905 An example using this algorithm is shown in Appendix A.1 of [JWE]. 907 4.5. Key Wrapping with AES Key Wrap 909 This section defines the specifics of encrypting a JWE CEK with the 910 Advanced Encryption Standard (AES) Key Wrap Algorithm [RFC3394] using 911 the default initial value specified in Section 2.2.3.1 using 128 or 912 256 bit keys. The "alg" header parameter values "A128KW" or "A256KW" 913 are respectively used in this case. 915 An example using this algorithm is shown in Appendix A.3 of [JWE]. 917 4.6. Direct Encryption with a Shared Symmetric Key 919 This section defines the specifics of directly performing symmetric 920 key encryption without performing a key wrapping step. In this case, 921 the shared symmetric key is used directly as the Content Encryption 922 Key (CEK) value for the "enc" algorithm. An empty octet sequence is 923 used as the JWE Encrypted Key value. The "alg" header parameter 924 value "dir" is used in this case. 926 4.7. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static 927 (ECDH-ES) 929 This section defines the specifics of key agreement with Elliptic 930 Curve Diffie-Hellman Ephemeral Static [RFC6090], and using the Concat 931 KDF, as defined in Section 5.8.1 of [NIST.800-56A]. The key 932 agreement result can be used in one of two ways: 934 1. directly as the Content Encryption Key (CEK) for the "enc" 935 algorithm, in the Direct Key Agreement mode, or 937 2. as a symmetric key used to wrap the CEK with either the "A128KW" 938 or "A256KW" algorithms, in the Key Agreement with Key Wrapping 939 mode. 941 The "alg" header parameter value "ECDH-ES" is used in the Direct Key 942 Agreement mode and the values "ECDH-ES+A128KW" and "ECDH-ES+A256KW" 943 are used in the Key Agreement with Key Wrapping mode. 945 In the Direct Key Agreement case, the output of the Concat KDF MUST 946 be a key of the same length as that used by the "enc" algorithm; in 947 this case, the empty octet sequence is used as the JWE Encrypted Key 948 value. In the Key Agreement with Key Wrapping case, the output of 949 the Concat KDF MUST be a key of the length needed for the specified 950 key wrapping algorithm, either 128 or 256 bits respectively. 952 A new ephemeral public key value MUST be generated for each key 953 agreement transaction. 955 4.7.1. Header Parameters Used for ECDH Key Agreement 957 The following Header Parameter Names are reserved and are used for 958 key agreement as defined below. They MAY also be used for other 959 algorithms if so specified by those algorithm parameter definitions. 961 4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter 963 The "epk" (ephemeral public key) value created by the originator for 964 the use in key agreement algorithms. This key is represented as a 965 JSON Web Key [JWK] bare public key value. This Header Parameter is 966 REQUIRED and MUST be understood and processed by implementations when 967 these algorithms are used. 969 4.7.1.2. "apu" (Agreement PartyUInfo) Header Parameter 971 The "apu" (agreement PartyUInfo) value for key agreement algorithms 972 using it (such as "ECDH-ES"), represented as a base64url encoded 973 string. When used, the PartyUInfo value contains information about 974 the sender. Use of this Header Parameter is OPTIONAL. This Header 975 Parameter MUST be understood and processed by implementations when 976 these algorithms are used. 978 4.7.1.3. "apv" (Agreement PartyVInfo) Header Parameter 980 The "apv" (agreement PartyVInfo) value for key agreement algorithms 981 using it (such as "ECDH-ES"), represented as a base64url encoded 982 string. When used, the PartyVInfo value contains information about 983 the receiver. Use of this Header Parameter is OPTIONAL. This Header 984 Parameter MUST be understood and processed by implementations when 985 these algorithms are used. 987 4.7.2. Key Derivation for ECDH Key Agreement 989 The key derivation process derives the agreed upon key from the 990 shared secret Z established through the ECDH algorithm, per Section 991 6.2.2.2 of [NIST.800-56A]. 993 Key derivation is performed using the Concat KDF, as defined in 994 Section 5.8.1 of [NIST.800-56A], where the Digest Method is SHA-256. 995 The Concat KDF parameters are set as follows: 997 Z This is set to the representation of the shared secret Z as an 998 octet sequence. 1000 keydatalen This is set to the number of bits in the desired output 1001 key. For "ECDH-ES", this is length of the key used by the "enc" 1002 algorithm. For "ECDH-ES+A128KW", and "ECDH-ES+A256KW", this is 1003 128 and 256, respectively. 1005 AlgorithmID In the Direct Key Agreement case, this is set to the 1006 octets of the UTF-8 representation of the "enc" header parameter 1007 value. In the Key Agreement with Key Wrapping case, this is set 1008 to the octets of the UTF-8 representation of the "alg" header 1009 parameter value. 1011 PartyUInfo The PartyUInfo value is of the form Datalen || Data, 1012 where Data is a variable-length string of zero or more octets, and 1013 Datalen is a fixed-length, big endian 32 bit counter that 1014 indicates the length (in octets) of Data, with || being 1015 concatenation. If an "apu" (agreement PartyUInfo) header 1016 parameter is present, Data is set to the result of base64url 1017 decoding the "apu" value and Datalen is set to the number of 1018 octets in Data. Otherwise, Datalen is set to 0 and Data is set to 1019 the empty octet sequence. 1021 PartyVInfo The PartyVInfo value is of the form Datalen || Data, 1022 where Data is a variable-length string of zero or more octets, and 1023 Datalen is a fixed-length, big endian 32 bit counter that 1024 indicates the length (in octets) of Data, with || being 1025 concatenation. If an "apv" (agreement PartyVInfo) header 1026 parameter is present, Data is set to the result of base64url 1027 decoding the "apv" value and Datalen is set to the number of 1028 octets in Data. Otherwise, Datalen is set to 0 and Data is set to 1029 the empty octet sequence. 1031 SuppPubInfo This is set to the keydatalen represented as a 32 bit 1032 big endian integer. 1034 SuppPrivInfo This is set to the empty octet sequence. 1036 Note: The Diffie-Hellman Key Agreement Method [RFC2631] uses a key 1037 derivation function similar to the Concat KDF, but with fewer 1038 parameters. Rather than having separate PartyUInfo and PartyVInfo 1039 parameters, it uses a single PartyAInfo parameter, which is a random 1040 string provided by the sender, that contains 512 bits of information, 1041 when provided. It has no SuppPrivInfo parameter. Should it be 1042 appropriate for the application, key agreement can be performed in a 1043 manner akin to RFC 2631 by using the PartyAInfo value as the "apu" 1044 (Agreement PartyUInfo) header parameter value, when provided, and by 1045 using no "apv" (Agreement PartyVInfo) header parameter. 1047 4.8. Key Encryption with AES GCM 1049 This section defines the specifics of encrypting a JWE Content 1050 Encryption Key (CEK) with Advanced Encryption Standard (AES) in 1051 Galois/Counter Mode (GCM) [AES] [NIST.800-38D] using 128 or 256 bit 1052 keys. The "alg" header parameter values "A128GCMKW" or "A256GCMKW" 1053 are respectively used in this case. 1055 Use of an Initialization Vector of size 96 bits is REQUIRED with this 1056 algorithm. The Initialization Vector is represented in base64url 1057 encoded form as the "iv" (initialization vector) header parameter 1058 value. 1060 The Additional Authenticated Data value used is the empty octet 1061 string. 1063 The requested size of the Authentication Tag output MUST be 128 bits, 1064 regardless of the key size. 1066 The JWE Encrypted Key value is the Ciphertext output. 1068 The Authentication Tag output is represented in base64url encoded 1069 form as the "tag" (authentication tag) header parameter value. 1071 4.8.1. Header Parameters Used for AES GCM Key Encryption 1073 The following Header Parameter Names are used for AES GCM key 1074 encryption. They MAY also be used by other algorithms if so 1075 specified by those algorithm parameter definitions. 1077 4.8.1.1. "iv" (Initialization Vector) Header Parameter 1079 The "iv" (initialization vector) header parameter value is the 1080 base64url encoded representation of the Initialization Vector value 1081 used for the key encryption operation. This Header Parameter is 1082 REQUIRED and MUST be understood and processed by implementations when 1083 these algorithms are used. 1085 4.8.1.2. "tag" (Authentication Tag) Header Parameter 1087 The "tag" (authentication tag) header parameter value is the 1088 base64url encoded representation of the Authentication Tag value 1089 resulting from the key encryption operation. This Header Parameter 1090 is REQUIRED and MUST be understood and processed by implementations 1091 when these algorithms are used. 1093 4.9. Key Encryption with PBES2 1095 The "PBES2-HS256+A128KW" and "PBES2-HS256+A256KW" algorithms defined 1096 below are used to encrypt a JWE Content Master Key using a user- 1097 supplied password to derive the key encryption key. With these 1098 algorithms, the derived key is used to encrypt the JWE Content Master 1099 Key. These algorithms combine a key derivation function with an 1100 encryption scheme to encrypt the JWE Content Master Key according to 1101 PBES2 from Section 6.2 of [RFC2898]. 1103 4.9.1. PBES2-HS256+A128KW 1105 The "PBES2-HS256+A128KW" algorithm uses HMAC SHA-256 as the Pseudo- 1106 Random Function (PRF) and AES Key Wrap [RFC3394] using 128 bit keys 1107 for the encryption scheme. The salt (s) and iteration count (c) MUST 1108 be specified by the "s" and "c" parameters (respectively) in the 1109 applicable PBKDF2 JWK object. The derived-key length (dkLen) is 16 1110 octets. 1112 4.9.2. PBES2-HS256+A256KW 1114 The "PBES2-HS256+A256KW" algorithm uses HMAC SHA-256 as the Pseudo- 1115 Random Function (PRF) and AES Key Wrap using 256 bit keys for the 1116 encryption scheme. The salt (s) and iteration count (c) MUST be 1117 specified by the "s" and "c" parameters (respectively) in the 1118 applicable PBKDF2 JWK object. The derived-key length (dkLen) is 32 1119 octets. 1121 4.10. AES_CBC_HMAC_SHA2 Algorithms 1123 This section defines a family of authenticated encryption algorithms 1124 built using a composition of Advanced Encryption Standard (AES) in 1125 Cipher Block Chaining (CBC) mode with PKCS #5 padding [AES] 1126 [NIST.800-38A] operations and HMAC [RFC2104] [SHS] operations. This 1127 algorithm family is called AES_CBC_HMAC_SHA2. It also defines two 1128 instances of this family, one using 128 bit CBC keys and HMAC SHA-256 1129 and the other using 256 bit CBC keys and HMAC SHA-512. Test cases 1130 for these algorithms can be found in Appendix C. 1132 These algorithms are based upon Authenticated Encryption with AES-CBC 1133 and HMAC-SHA [I-D.mcgrew-aead-aes-cbc-hmac-sha2], performing the same 1134 cryptographic computations, but with the Initialization Vector and 1135 Authentication Tag values remaining separate, rather than being 1136 concatenated with the Ciphertext value in the output representation. 1138 This algorithm family is a generalization of the algorithm family in 1139 [I-D.mcgrew-aead-aes-cbc-hmac-sha2], and can be used to implement 1140 those algorithms. 1142 4.10.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 1144 We use the following notational conventions. 1146 CBC-PKCS5-ENC(X, P) denotes the AES CBC encryption of P using PKCS 1147 #5 padding using the cipher with the key X. 1149 MAC(Y, M) denotes the application of the Message Authentication 1150 Code (MAC) to the message M, using the key Y. 1152 The concatenation of two octet strings A and B is denoted as 1153 A || B. 1155 4.10.2. Generic AES_CBC_HMAC_SHA2 Algorithm 1157 This section defines AES_CBC_HMAC_SHA2 in a manner that is 1158 independent of the AES CBC key size or hash function to be used. 1159 Section 4.10.2.1 and Section 4.10.2.2 define the generic encryption 1160 and decryption algorithms. Section 4.10.3 and Section 4.10.4 define 1161 instances of AES_CBC_HMAC_SHA2 that specify those details. 1163 4.10.2.1. AES_CBC_HMAC_SHA2 Encryption 1165 The authenticated encryption algorithm takes as input four octet 1166 strings: a secret key K, a plaintext P, associated data A, and an 1167 initialization vector IV. The authenticated ciphertext value E and 1168 the authentication tag value T are provided as outputs. The data in 1169 the plaintext are encrypted and authenticated, and the associated 1170 data are authenticated, but not encrypted. 1172 The encryption process is as follows, or uses an equivalent set of 1173 steps: 1175 1. The secondary keys MAC_KEY and ENC_KEY are generated from the 1176 input key K as follows. Each of these two keys is an octet 1177 string. 1179 MAC_KEY consists of the initial MAC_KEY_LEN octets of K, in 1180 order. 1182 ENC_KEY consists of the final ENC_KEY_LEN octets of K, in 1183 order. 1185 Here we denote the number of octets in the MAC_KEY as 1186 MAC_KEY_LEN, and the number of octets in ENC_KEY as ENC_KEY_LEN; 1187 the values of these parameters are specified by the AEAD 1188 algorithms (in Section 4.10.3 and Section 4.10.4). The number of 1189 octets in the input key K is the sum of MAC_KEY_LEN and 1190 ENC_KEY_LEN. When generating the secondary keys from K, MAC_KEY 1191 and ENC_KEY MUST NOT overlap. Note that the MAC key comes before 1192 the encryption key in the input key K; this is in the opposite 1193 order of the algorithm names in the identifier 1194 "AES_CBC_HMAC_SHA2". 1196 2. The Initialization Vector (IV) used is a 128 bit value generated 1197 randomly or pseudorandomly for use in the cipher. 1199 3. The plaintext is CBC encrypted using PKCS #5 padding using 1200 ENC_KEY as the key, and the IV. We denote the ciphertext output 1201 from this step as E. 1203 4. The octet string AL is equal to the number of bits in A expressed 1204 as a 64-bit unsigned integer in network byte order. 1206 5. A message authentication tag T is computed by applying HMAC 1207 [RFC2104] to the following data, in order: 1209 the associated data A, 1211 the initialization vector IV, 1213 the ciphertext E computed in the previous step, and 1215 the octet string AL defined above. 1217 The string MAC_KEY is used as the MAC key. We denote the output 1218 of the MAC computed in this step as M. The first T_LEN bits of M 1219 are used as T. 1221 6. The Ciphertext E and the Authentication Tag T are returned as the 1222 outputs of the authenticated encryption. 1224 The encryption process can be illustrated as follows. Here K, P, A, 1225 IV, and E denote the key, plaintext, associated data, initialization 1226 vector, and ciphertext, respectively. 1228 MAC_KEY = initial MAC_KEY_LEN bytes of K, 1230 ENC_KEY = final ENC_KEY_LEN bytes of K, 1232 E = CBC-PKCS5-ENC(ENC_KEY, P), 1233 M = MAC(MAC_KEY, A || IV || E || AL), 1235 T = initial T_LEN bytes of M. 1237 4.10.2.2. AES_CBC_HMAC_SHA2 Decryption 1239 The authenticated decryption operation has four inputs: K, A, E, and 1240 T as defined above. It has only a single output, either a plaintext 1241 value P or a special symbol FAIL that indicates that the inputs are 1242 not authentic. The authenticated decryption algorithm is as follows, 1243 or uses an equivalent set of steps: 1245 1. The secondary keys MAC_KEY and ENC_KEY are generated from the 1246 input key K as in Step 1 of Section 4.10.2.1. 1248 2. The integrity and authenticity of A and E are checked by 1249 computing an HMAC with the inputs as in Step 5 of 1250 Section 4.10.2.1. The value T, from the previous step, is 1251 compared to the first MAC_KEY length bits of the HMAC output. If 1252 those values are identical, then A and E are considered valid, 1253 and processing is continued. Otherwise, all of the data used in 1254 the MAC validation are discarded, and the AEAD decryption 1255 operation returns an indication that it failed, and the operation 1256 halts. (But see Section 10 of [JWE] for security considerations 1257 on thwarting timing attacks.) 1259 3. The value E is decrypted and the PKCS #5 padding is removed. The 1260 value IV is used as the initialization vector. The value ENC_KEY 1261 is used as the decryption key. 1263 4. The plaintext value is returned. 1265 4.10.3. AES_128_CBC_HMAC_SHA_256 1267 This algorithm is a concrete instantiation of the generic 1268 AES_CBC_HMAC_SHA2 algorithm above. It uses the HMAC message 1269 authentication code [RFC2104] with the SHA-256 hash function [SHS] to 1270 provide message authentication, with the HMAC output truncated to 128 1271 bits, corresponding to the HMAC-SHA-256-128 algorithm defined in 1272 [RFC4868]. For encryption, it uses AES in the Cipher Block Chaining 1273 (CBC) mode of operation as defined in Section 6.2 of [NIST.800-38A], 1274 with PKCS #5 padding. 1276 The input key K is 32 octets long. 1278 The AES CBC IV is 16 octets long. ENC_KEY_LEN is 16 octets. 1280 The SHA-256 hash algorithm is used in HMAC. MAC_KEY_LEN is 16 1281 octets. The HMAC-SHA-256 output is truncated to T_LEN=16 octets, by 1282 stripping off the final 16 octets. 1284 4.10.4. AES_256_CBC_HMAC_SHA_512 1286 AES_256_CBC_HMAC_SHA_512 is based on AES_128_CBC_HMAC_SHA_256, but 1287 with the following differences: 1289 A 256 bit AES CBC key is used instead of 128. 1291 SHA-512 is used in HMAC instead of SHA-256. 1293 ENC_KEY_LEN is 32 octets. 1295 MAC_KEY_LEN is 32 octets. 1297 The length of the input key K is 64 octets. 1299 The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of 1300 16 octets. 1302 4.10.5. Plaintext Encryption with AES_CBC_HMAC_SHA2 1304 The algorithm value "A128CBC-HS256" is used as the "alg" value when 1305 using AES_128_CBC_HMAC_SHA_256 with JWE. The algorithm value 1306 "A256CBC-HS512" is used as the "alg" value when using 1307 AES_256_CBC_HMAC_SHA_512 with JWE. The Additional Authenticated Data 1308 value used is the octets of the ASCII representation of the Encoded 1309 JWE Header value. The JWE Initialization Vector value used is the IV 1310 value. 1312 4.11. Plaintext Encryption with AES GCM 1314 This section defines the specifics of encrypting the JWE Plaintext 1315 with Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) 1316 [AES] [NIST.800-38D] using 128 or 256 bit keys. The "enc" header 1317 parameter values "A128GCM" or "A256GCM" are respectively used in this 1318 case. 1320 The CEK is used as the encryption key. 1322 Use of an initialization vector of size 96 bits is REQUIRED with this 1323 algorithm. 1325 The Additional Authenticated Data value used is the octets of the 1326 ASCII representation of the Encoded JWE Header value. 1328 The requested size of the Authentication Tag output MUST be 128 bits, 1329 regardless of the key size. 1331 The JWE Authentication Tag is set to be the Authentication Tag value 1332 produced by the encryption. During decryption, the received JWE 1333 Authentication Tag is used as the Authentication Tag value. 1335 An example using this algorithm is shown in Appendix A.1 of [JWE]. 1337 4.12. Additional Encryption Algorithms and Parameters 1339 Additional algorithms MAY be used to protect JWEs with corresponding 1340 "alg" (algorithm) and "enc" (encryption method) header parameter 1341 values being defined to refer to them. New "alg" and "enc" header 1342 parameter values SHOULD either be registered in the IANA JSON Web 1343 Signature and Encryption Algorithms registry Section 6.1 or be a 1344 value that contains a Collision Resistant Namespace. In particular, 1345 it is permissible to use the algorithm identifiers defined in XML 1346 Encryption [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 1347 [W3C.CR-xmlenc-core1-20120313], and related specifications as "alg" 1348 and "enc" values. 1350 As indicated by the common registry, JWSs and JWEs share a common 1351 "alg" value space. The values used by the two specifications MUST be 1352 distinct, as the "alg" value can be used to determine whether the 1353 object is a JWS or JWE. 1355 Likewise, additional reserved Header Parameter Names can be defined 1356 via the IANA JSON Web Signature and Encryption Header Parameters 1357 registry [JWS]. As indicated by the common registry, JWSs and JWEs 1358 share a common header parameter space; when a parameter is used by 1359 both specifications, its usage must be compatible between the 1360 specifications. 1362 5. Cryptographic Algorithms for JWK 1364 A JSON Web Key (JWK) [JWK] is a JavaScript Object Notation (JSON) 1365 [RFC4627] data structure that represents a cryptographic key. A JSON 1366 Web Key Set (JWK Set) is a JSON data structure for representing a set 1367 of JWKs. This section specifies a set of key types to be used for 1368 those keys and the key type specific parameters for representing 1369 those keys. Parameters are defined for public, private, and 1370 symmetric keys. 1372 5.1. "kty" (Key Type) Parameter Values for JWK 1374 The table below is the set of "kty" (key type) parameter values that 1375 are defined by this specification for use in JWKs. 1377 +-------------+----------------------------------+------------------+ 1378 | kty | Key Type | Implementation | 1379 | Parameter | | Requirements | 1380 | Value | | | 1381 +-------------+----------------------------------+------------------+ 1382 | EC | Elliptic Curve [DSS] key type | RECOMMENDED+ | 1383 | RSA | RSA [RFC3447] key type | REQUIRED | 1384 | oct | Octet sequence key type (used to | RECOMMENDED+ | 1385 | | represent symmetric keys) | | 1386 | PBKDF2 | Password-Based Key Derivation | OPTIONAL | 1387 | | Function 2 [RFC2898] key type | | 1388 +-------------+----------------------------------+------------------+ 1390 All the names are short because a core goal of JWK is for the 1391 representations to be compact. However, there is no a priori length 1392 restriction on "kty" values. 1394 The use of "+" in the Implementation Requirements indicates that the 1395 requirement strength is likely to be increased in a future version of 1396 the specification. 1398 5.2. JWK Parameters for Elliptic Curve Keys 1400 JWKs can represent Elliptic Curve [DSS] keys. In this case, the 1401 "kty" member value MUST be "EC". 1403 5.2.1. JWK Parameters for Elliptic Curve Public Keys 1405 These members MUST be present for Elliptic Curve public keys: 1407 5.2.1.1. "crv" (Curve) Parameter 1409 The "crv" (curve) member identifies the cryptographic curve used with 1410 the key. Curve values from [DSS] used by this specification are: 1412 o "P-256" 1414 o "P-384" 1416 o "P-521" 1418 Additional "crv" values MAY be used, provided they are understood by 1419 implementations using that Elliptic Curve key. The "crv" value is a 1420 case sensitive string. 1422 5.2.1.2. "x" (X Coordinate) Parameter 1424 The "x" (x coordinate) member contains the x coordinate for the 1425 elliptic curve point. It is represented as the base64url encoding of 1426 the coordinate's big endian representation as an octet sequence. The 1427 array representation MUST NOT be shortened to omit any leading zero 1428 octets contained in the value. For instance, when representing 521 1429 bit integers, the octet sequence to be base64url encoded MUST contain 1430 66 octets, including any leading zero octets. 1432 5.2.1.3. "y" (Y Coordinate) Parameter 1434 The "y" (y coordinate) member contains the y coordinate for the 1435 elliptic curve point. It is represented as the base64url encoding of 1436 the coordinate's big endian representation as an octet sequence. The 1437 array representation MUST NOT be shortened to omit any leading zero 1438 octets contained in the value. For instance, when representing 521 1439 bit integers, the octet sequence to be base64url encoded MUST contain 1440 66 octets, including any leading zero octets. 1442 5.2.2. JWK Parameters for Elliptic Curve Private Keys 1444 In addition to the members used to represent Elliptic Curve public 1445 keys, the following member MUST be present to represent Elliptic 1446 Curve private keys: 1448 5.2.2.1. "d" (ECC Private Key) Parameter 1450 The "d" (ECC private key) member contains the Elliptic Curve private 1451 key value. It is represented as the base64url encoding of the 1452 value's unsigned big endian representation as an octet sequence. The 1453 array representation MUST NOT be shortened to omit any leading zero 1454 octets. For instance, when representing 521 bit integers, the octet 1455 sequence to be base64url encoded MUST contain 66 octets, including 1456 any leading zero octets. 1458 5.3. JWK Parameters for RSA Keys 1460 JWKs can represent RSA [RFC3447] keys. In this case, the "kty" 1461 member value MUST be "RSA". 1463 5.3.1. JWK Parameters for RSA Public Keys 1465 These members MUST be present for RSA public keys: 1467 5.3.1.1. "n" (Modulus) Parameter 1469 The "n" (modulus) member contains the modulus value for the RSA 1470 public key. It is represented as the base64url encoding of the 1471 value's unsigned big endian representation as an octet sequence. The 1472 array representation MUST NOT be shortened to omit any leading zero 1473 octets. For instance, when representing 2048 bit integers, the octet 1474 sequence to be base64url encoded MUST contain 256 octets, including 1475 any leading zero octets. 1477 5.3.1.2. "e" (Exponent) Parameter 1479 The "e" (exponent) member contains the exponent value for the RSA 1480 public key. It is represented as the base64url encoding of the 1481 value's unsigned big endian representation as an octet sequence. The 1482 array representation MUST utilize the minimum number of octets to 1483 represent the value. For instance, when representing the value 1484 65537, the octet sequence to be base64url encoded MUST consist of the 1485 three octets [1, 0, 1]. 1487 5.3.2. JWK Parameters for RSA Private Keys 1489 In addition to the members used to represent RSA public keys, the 1490 following members are used to represent RSA private keys. All are 1491 REQUIRED for RSA private keys except for "oth", which is sometimes 1492 REQUIRED and sometimes MUST NOT be present, as described below. 1494 5.3.2.1. "d" (Private Exponent) Parameter 1496 The "d" (private exponent) member contains the private exponent value 1497 for the RSA private key. It is represented as the base64url encoding 1498 of the value's unsigned big endian representation as an octet 1499 sequence. The array representation MUST NOT be shortened to omit any 1500 leading zero octets. For instance, when representing 2048 bit 1501 integers, the octet sequence to be base64url encoded MUST contain 256 1502 octets, including any leading zero octets. 1504 5.3.2.2. "p" (First Prime Factor) Parameter 1506 The "p" (first prime factor) member contains the first prime factor, 1507 a positive integer. It is represented as the base64url encoding of 1508 the value's unsigned big endian representation as an octet sequence. 1510 5.3.2.3. "q" (Second Prime Factor) Parameter 1512 The "q" (second prime factor) member contains the second prime 1513 factor, a positive integer. It is represented as the base64url 1514 encoding of the value's unsigned big endian representation as an 1515 octet sequence. 1517 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter 1519 The "dp" (first factor CRT exponent) member contains the Chinese 1520 Remainder Theorem (CRT) exponent of the first factor, a positive 1521 integer. It is represented as the base64url encoding of the value's 1522 unsigned big endian representation as an octet sequence. 1524 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter 1526 The "dq" (second factor CRT exponent) member contains the Chinese 1527 Remainder Theorem (CRT) exponent of the second factor, a positive 1528 integer. It is represented as the base64url encoding of the value's 1529 unsigned big endian representation as an octet sequence. 1531 5.3.2.6. "qi" (First CRT Coefficient) Parameter 1533 The "dp" (first CRT coefficient) member contains the Chinese 1534 Remainder Theorem (CRT) coefficient of the second factor, a positive 1535 integer. It is represented as the base64url encoding of the value's 1536 unsigned big endian representation as an octet sequence. 1538 5.3.2.7. "oth" (Other Primes Info) Parameter 1540 The "oth" (other primes info) member contains an array of information 1541 about any third and subsequent primes, should they exist. When only 1542 two primes have been used (the normal case), this parameter MUST be 1543 omitted. When three or more primes have been used, the number of 1544 array elements MUST be the number of primes used minus two. Each 1545 array element MUST be an object with the following members: 1547 5.3.2.7.1. "r" (Prime Factor) 1549 The "r" (prime factor) parameter within an "oth" array member 1550 represents the value of a subsequent prime factor, a positive 1551 integer. It is represented as the base64url encoding of the value's 1552 unsigned big endian representation as an octet sequence. 1554 5.3.2.7.2. "d" (Factor CRT Exponent) 1556 The "d" (Factor CRT Exponent) parameter within an "oth" array member 1557 represents the CRT exponent of the corresponding prime factor, a 1558 positive integer. It is represented as the base64url encoding of the 1559 value's unsigned big endian representation as an octet sequence. 1561 5.3.2.7.3. "t" (Factor CRT Coefficient) 1563 The "t" (factor CRT coefficient) parameter within an "oth" array 1564 member represents the CRT coefficient of the corresponding prime 1565 factor, a positive integer. It is represented as the base64url 1566 encoding of the value's unsigned big endian representation as an 1567 octet sequence. 1569 5.3.3. JWK Parameters for Symmetric Keys 1571 When the JWK "kty" member value is "oct" (octet sequence), the 1572 following member is used to represent a symmetric key (or another key 1573 whose value is a single octet sequence): 1575 5.3.3.1. "k" (Key Value) Parameter 1577 The "k" (key value) member contains the value of the symmetric (or 1578 other single-valued) key. It is represented as the base64url 1579 encoding of the octet sequence containing the key value. 1581 5.3.4. JWK Parameters for PBKDF2 Keys 1583 When the JWK "kty" member value is "PBKDF2", the following members 1584 are used to represent the parameters necessary to derive a cipher key 1585 from a password using the PBKDF2 algorithm [RFC2898]: 1587 5.3.4.1. "s" (salt) Parameter 1589 The REQUIRED "s" parameter contains the PBKDF2 salt value (S) as a 1590 base64url encoded string. This value MUST NOT be the empty string. 1592 The salt expands the possible keys that can be derived from a given 1593 password. [RFC2898] originally recommended a minimum salt length of 1594 8 octets (since there is no concern here of a derived key being re- 1595 used for different purposes). The salt MUST be generated randomly; 1596 see [RFC4086] for considerations on generating random values. 1598 5.3.4.2. "c" (count) Parameter 1600 The REQUIRED "c" parameter contains the PBKDF2 iteration count (c), 1601 as an integer. This value MUST NOT be less than 1, as per [RFC2898]. 1603 The iteration count adds computational expense, ideally compounded by 1604 the possible range of keys introduced by the salt. [RFC2898] 1605 originally recommended a minimum iteration count of 1000. 1607 5.3.4.3. "hint" (password hint) Parameter 1609 The OPTIONAL "hint" parameter contains a description clue to the 1610 password, as a string. If present, this value SHOULD NOT be the 1611 empty string. 1613 The hint is typically displayed to the user as a reminder or mnemonic 1614 for the actual password used. This parameter MUST NOT contain the 1615 actual password, and implementations MAY use various heuristic 1616 algorithms to prohibit hints that are alternate forms of the actual 1617 password. 1619 5.4. Additional Key Types and Parameters 1621 Keys using additional key types can be represented using JWK data 1622 structures with corresponding "kty" (key type) parameter values being 1623 defined to refer to them. New "kty" parameter values SHOULD either 1624 be registered in the IANA JSON Web Key Types registry Section 6.2 or 1625 be a value that contains a Collision Resistant Namespace. 1627 Likewise, parameters for representing keys for additional key types 1628 or additional key properties SHOULD either be registered in the IANA 1629 JSON Web Key Parameters registry [JWK] or be a value that contains a 1630 Collision Resistant Namespace. 1632 6. IANA Considerations 1634 The following registration procedure is used for all the registries 1635 established by this specification. 1637 Values are registered with a Specification Required [RFC5226] after a 1638 two-week review period on the [TBD]@ietf.org mailing list, on the 1639 advice of one or more Designated Experts. However, to allow for the 1640 allocation of values prior to publication, the Designated Expert(s) 1641 may approve registration once they are satisfied that such a 1642 specification will be published. 1644 Registration requests must be sent to the [TBD]@ietf.org mailing list 1645 for review and comment, with an appropriate subject (e.g., "Request 1646 for access token type: example"). [[ Note to RFC-EDITOR: The name of 1647 the mailing list should be determined in consultation with the IESG 1648 and IANA. Suggested name: jose-reg-review. ]] 1650 Within the review period, the Designated Expert(s) will either 1651 approve or deny the registration request, communicating this decision 1652 to the review list and IANA. Denials should include an explanation 1653 and, if applicable, suggestions as to how to make the request 1654 successful. 1656 IANA must only accept registry updates from the Designated Expert(s) 1657 and should direct all requests for registration to the review mailing 1658 list. 1660 6.1. JSON Web Signature and Encryption Algorithms Registry 1662 This specification establishes the IANA JSON Web Signature and 1663 Encryption Algorithms registry for values of the JWS and JWE "alg" 1664 (algorithm) and "enc" (encryption method) header parameters. The 1665 registry records the algorithm name, the algorithm usage locations 1666 from the set "alg" and "enc", implementation requirements, and a 1667 reference to the specification that defines it. The same algorithm 1668 name MAY be registered multiple times, provided that the sets of 1669 usage locations are disjoint. The implementation requirements of an 1670 algorithm MAY be changed over time by the Designated Experts(s) as 1671 the cryptographic landscape evolves, for instance, to change the 1672 status of an algorithm to DEPRECATED, or to change the status of an 1673 algorithm from OPTIONAL to RECOMMENDED or REQUIRED. 1675 6.1.1. Template 1677 Algorithm Name: 1678 The name requested (e.g., "example"). This name is case 1679 sensitive. Names that match other registered names in a case 1680 insensitive manner SHOULD NOT be accepted. 1682 Algorithm Usage Location(s): 1683 The algorithm usage, which must be one or more of the values "alg" 1684 or "enc". 1686 Implementation Requirements: 1687 The algorithm implementation requirements, which must be one the 1688 words REQUIRED, RECOMMENDED, OPTIONAL, or DEPRECATED. Optionally, 1689 the word can be followed by a "+" or "-". The use of "+" 1690 indicates that the requirement strength is likely to be increased 1691 in a future version of the specification. The use of "-" 1692 indicates that the requirement strength is likely to be decreased 1693 in a future version of the specification. 1695 Change Controller: 1696 For Standards Track RFCs, state "IETF". For others, give the name 1697 of the responsible party. Other details (e.g., postal address, 1698 email address, home page URI) may also be included. 1700 Specification Document(s): 1701 Reference to the document(s) that specify the parameter, 1702 preferably including URI(s) that can be used to retrieve copies of 1703 the document(s). An indication of the relevant sections may also 1704 be included but is not required. 1706 6.1.2. Initial Registry Contents 1708 o Algorithm Name: "HS256" 1709 o Algorithm Usage Location(s): "alg" 1710 o Implementation Requirements: REQUIRED 1711 o Change Controller: IETF 1712 o Specification Document(s): Section 3.1 of [[ this document ]] 1714 o Algorithm Name: "HS384" 1715 o Algorithm Usage Location(s): "alg" 1716 o Implementation Requirements: OPTIONAL 1717 o Change Controller: IETF 1718 o Specification Document(s): Section 3.1 of [[ this document ]] 1720 o Algorithm Name: "HS512" 1721 o Algorithm Usage Location(s): "alg" 1722 o Implementation Requirements: OPTIONAL 1723 o Change Controller: IETF 1724 o Specification Document(s): Section 3.1 of [[ this document ]] 1726 o Algorithm Name: "RS256" 1727 o Algorithm Usage Location(s): "alg" 1728 o Implementation Requirements: RECOMMENDED 1729 o Change Controller: IETF 1730 o Specification Document(s): Section 3.1 of [[ this document ]] 1732 o Algorithm Name: "RS384" 1733 o Algorithm Usage Location(s): "alg" 1734 o Implementation Requirements: OPTIONAL 1735 o Change Controller: IETF 1736 o Specification Document(s): Section 3.1 of [[ this document ]] 1738 o Algorithm Name: "RS512" 1739 o Algorithm Usage Location(s): "alg" 1740 o Implementation Requirements: OPTIONAL 1741 o Change Controller: IETF 1742 o Specification Document(s): Section 3.1 of [[ this document ]] 1744 o Algorithm Name: "ES256" 1745 o Algorithm Usage Location(s): "alg" 1746 o Implementation Requirements: RECOMMENDED+ 1747 o Change Controller: IETF 1748 o Specification Document(s): Section 3.1 of [[ this document ]] 1750 o Algorithm Name: "ES384" 1751 o Algorithm Usage Location(s): "alg" 1752 o Implementation Requirements: OPTIONAL 1753 o Change Controller: IETF 1754 o Specification Document(s): Section 3.1 of [[ this document ]] 1756 o Algorithm Name: "ES512" 1757 o Algorithm Usage Location(s): "alg" 1758 o Implementation Requirements: OPTIONAL 1759 o Change Controller: IETF 1760 o Specification Document(s): Section 3.1 of [[ this document ]] 1762 o Algorithm Name: "PS256" 1763 o Algorithm Usage Location(s): "alg" 1764 o Implementation Requirements: RECOMMENDED 1765 o Change Controller: IETF 1766 o Specification Document(s): Section 3.1 of [[ this document ]] 1768 o Algorithm Name: "PS512" 1769 o Algorithm Usage Location(s): "alg" 1770 o Implementation Requirements: RECOMMENDED 1771 o Change Controller: IETF 1772 o Specification Document(s): Section 3.1 of [[ this document ]] 1774 o Algorithm Name: "none" 1775 o Algorithm Usage Location(s): "alg" 1776 o Implementation Requirements: REQUIRED 1777 o Change Controller: IETF 1778 o Specification Document(s): Section 3.1 of [[ this document ]] 1780 o Algorithm Name: "RSA1_5" 1781 o Algorithm Usage Location(s): "alg" 1782 o Implementation Requirements: REQUIRED 1783 o Change Controller: IETF 1784 o Specification Document(s): Section 4.1 of [[ this document ]] 1786 o Algorithm Name: "RSA-OAEP" 1787 o Algorithm Usage Location(s): "alg" 1788 o Implementation Requirements: OPTIONAL 1789 o Change Controller: IETF 1790 o Specification Document(s): Section 4.1 of [[ this document ]] 1791 o Algorithm Name: "A128KW" 1792 o Algorithm Usage Location(s): "alg" 1793 o Implementation Requirements: RECOMMENDED 1794 o Change Controller: IETF 1795 o Specification Document(s): Section 4.1 of [[ this document ]] 1797 o Algorithm Name: "A256KW" 1798 o Algorithm Usage Location(s): "alg" 1799 o Implementation Requirements: RECOMMENDED 1800 o Change Controller: IETF 1801 o Specification Document(s): Section 4.1 of [[ this document ]] 1803 o Algorithm Name: "dir" 1804 o Algorithm Usage Location(s): "alg" 1805 o Implementation Requirements: RECOMMENDED 1806 o Change Controller: IETF 1807 o Specification Document(s): Section 4.1 of [[ this document ]] 1809 o Algorithm Name: "ECDH-ES" 1810 o Algorithm Usage Location(s): "alg" 1811 o Implementation Requirements: RECOMMENDED+ 1812 o Change Controller: IETF 1813 o Specification Document(s): Section 4.1 of [[ this document ]] 1815 o Algorithm Name: "ECDH-ES+A128KW" 1816 o Algorithm Usage Location(s): "alg" 1817 o Implementation Requirements: RECOMMENDED 1818 o Change Controller: IETF 1819 o Specification Document(s): Section 4.1 of [[ this document ]] 1821 o Algorithm Name: "ECDH-ES+A256KW" 1822 o Algorithm Usage Location(s): "alg" 1823 o Implementation Requirements: RECOMMENDED 1824 o Change Controller: IETF 1825 o Specification Document(s): Section 4.1 of [[ this document ]] 1827 o Algorithm Name: "A128GCMKW" 1828 o Algorithm Usage Location(s): "alg" 1829 o Implementation Requirements: OPTIONAL 1830 o Change Controller: IETF 1831 o Specification Document(s): Section 4.8 of [[ this document ]] 1833 o Algorithm Name: "A256GCMKW" 1834 o Algorithm Usage Location(s): "alg" 1835 o Implementation Requirements: OPTIONAL 1836 o Change Controller: IETF 1837 o Specification Document(s): Section 4.8 of [[ this document ]] 1839 o Algorithm Name: "PBES2-HS256+A128KW" 1840 o Algorithm Usage Location(s): "alg" 1841 o Implementation Requirements: OPTIONAL 1842 o Change Controller: IETF 1843 o Specification Document(s): Section 4.9.1 of [[ this document ]] 1845 o Algorithm Name: "PBES2-HS256+A256KW" 1846 o Algorithm Usage Location(s): "alg" 1847 o Implementation Requirements: OPTIONAL 1848 o Change Controller: IETF 1849 o Specification Document(s): Section 4.9.2 of [[ this document ]] 1851 o Algorithm Name: "A128CBC-HS256" 1852 o Algorithm Usage Location(s): "enc" 1853 o Implementation Requirements: REQUIRED 1854 o Change Controller: IETF 1855 o Specification Document(s): Section 4.2 of [[ this document ]] 1857 o Algorithm Name: "A256CBC-HS512" 1858 o Algorithm Usage Location(s): "enc" 1859 o Implementation Requirements: REQUIRED 1860 o Change Controller: IETF 1861 o Specification Document(s): Section 4.2 of [[ this document ]] 1863 o Algorithm Name: "A128GCM" 1864 o Algorithm Usage Location(s): "enc" 1865 o Implementation Requirements: RECOMMENDED 1866 o Change Controller: IETF 1867 o Specification Document(s): Section 4.2 of [[ this document ]] 1869 o Algorithm Name: "A256GCM" 1870 o Algorithm Usage Location(s): "enc" 1871 o Implementation Requirements: RECOMMENDED 1872 o Change Controller: IETF 1873 o Specification Document(s): Section 4.2 of [[ this document ]] 1875 6.2. JSON Web Key Types Registry 1877 This specification establishes the IANA JSON Web Key Types registry 1878 for values of the JWK "kty" (key type) parameter. The registry 1879 records the "kty" value and a reference to the specification that 1880 defines it. This specification registers the values defined in 1881 Section 5.1. 1883 6.2.1. Registration Template 1885 "kty" Parameter Value: 1886 The name requested (e.g., "example"). This name is case 1887 sensitive. Names that match other registered names in a case 1888 insensitive manner SHOULD NOT be accepted. 1890 Change Controller: 1891 For Standards Track RFCs, state "IETF". For others, give the name 1892 of the responsible party. Other details (e.g., postal address, 1893 email address, home page URI) may also be included. 1895 Implementation Requirements: 1896 The algorithm implementation requirements, which must be one the 1897 words REQUIRED, RECOMMENDED, OPTIONAL, or DEPRECATED. Optionally, 1898 the word can be followed by a "+" or "-". The use of "+" 1899 indicates that the requirement strength is likely to be increased 1900 in a future version of the specification. The use of "-" 1901 indicates that the requirement strength is likely to be decreased 1902 in a future version of the specification. 1904 Specification Document(s): 1905 Reference to the document(s) that specify the parameter, 1906 preferably including URI(s) that can be used to retrieve copies of 1907 the document(s). An indication of the relevant sections may also 1908 be included but is not required. 1910 6.2.2. Initial Registry Contents 1912 o "kty" Parameter Value: "EC" 1913 o Implementation Requirements: RECOMMENDED+ 1914 o Change Controller: IETF 1915 o Specification Document(s): Section 5.2 of [[ this document ]] 1917 o "kty" Parameter Value: "RSA" 1918 o Implementation Requirements: REQUIRED 1919 o Change Controller: IETF 1920 o Specification Document(s): Section 5.3 of [[ this document ]] 1922 o "kty" Parameter Value: "oct" 1923 o Implementation Requirements: RECOMMENDED+ 1924 o Change Controller: IETF 1925 o Specification Document(s): Section 5.3.3 of [[ this document ]] 1927 o "kty" Paramater value: "PBKDF2" 1928 o Implementation Requirements: OPTIONAL 1929 o Change Controller: IETF 1930 o Specification Document(s): Section 5.3.4 of [[ this document ]] 1932 6.3. JSON Web Key Parameters Registration 1934 This specification registers the parameter names defined in Sections 1935 5.2, 5.3, and 5.3.3 in the IANA JSON Web Key Parameters registry 1936 [JWK]. 1938 6.3.1. Registry Contents 1940 o Parameter Name: "crv" 1941 o Parameter Information Class: Public 1942 o Change Controller: IETF 1943 o Specification Document(s): Section 5.2.1.1 of [[ this document ]] 1945 o Parameter Name: "x" 1946 o Parameter Information Class: Public 1947 o Change Controller: IETF 1948 o Specification Document(s): Section 5.2.1.2 of [[ this document ]] 1950 o Parameter Name: "y" 1951 o Parameter Information Class: Public 1952 o Change Controller: IETF 1953 o Specification Document(s): Section 5.2.1.3 of [[ this document ]] 1955 o Parameter Name: "d" 1956 o Parameter Information Class: Private 1957 o Change Controller: IETF 1958 o Specification Document(s): Section 5.2.2.1 of [[ this document ]] 1960 o Parameter Name: "n" 1961 o Parameter Information Class: Public 1962 o Change Controller: IETF 1963 o Specification Document(s): Section 5.3.1.1 of [[ this document ]] 1965 o Parameter Name: "e" 1966 o Parameter Information Class: Public 1967 o Change Controller: IETF 1968 o Specification Document(s): Section 5.3.1.2 of [[ this document ]] 1970 o Parameter Name: "d" 1971 o Parameter Information Class: Private 1972 o Change Controller: IETF 1973 o Specification Document(s): Section 5.3.2.1 of [[ this document ]] 1974 o Parameter Name: "p" 1975 o Parameter Information Class: Private 1976 o Change Controller: IETF 1977 o Specification Document(s): Section 5.3.2.2 of [[ this document ]] 1979 o Parameter Name: "q" 1980 o Parameter Information Class: Private 1981 o Change Controller: IETF 1982 o Specification Document(s): Section 5.3.2.3 of [[ this document ]] 1984 o Parameter Name: "dp" 1985 o Parameter Information Class: Private 1986 o Change Controller: IETF 1987 o Specification Document(s): Section 5.3.2.4 of [[ this document ]] 1989 o Parameter Name: "dq" 1990 o Parameter Information Class: Private 1991 o Change Controller: IETF 1992 o Specification Document(s): Section 5.3.2.5 of [[ this document ]] 1994 o Parameter Name: "qi" 1995 o Parameter Information Class: Private 1996 o Change Controller: IETF 1997 o Specification Document(s): Section 5.3.2.6 of [[ this document ]] 1999 o Parameter Name: "oth" 2000 o Parameter Information Class: Private 2001 o Change Controller: IETF 2002 o Specification Document(s): Section 5.3.2.7 of [[ this document ]] 2004 o Parameter Name: "k" 2005 o Parameter Information Class: Private 2006 o Change Controller: IETF 2007 o Specification Document(s): Section 5.3.3.1 of [[ this document ]] 2009 o Parameter Name: "s" 2010 o Parameter Information Class: Public 2011 o Change Controller: IETF 2012 o Specification Document(s): Section 5.3.4.1 of [[ this document ]] 2014 o Parameter Name: "c" 2015 o Parameter Information Class: Public 2016 o Change Controller: IETF 2017 o Specification Document(s): Section 5.3.4.2 of [[ this document ]] 2019 o Parameter Name: "hint" 2020 o Parameter Information Class: Public 2021 o Change Controller: IETF 2022 o Specification Document(s): Section 5.3.4.3 of [[ this document ]] 2024 6.4. Registration of JWE Header Parameter Names 2026 This specification registers the Header Parameter Names defined in 2027 Section 4.7.1 and Section 4.8.1 in the IANA JSON Web Signature and 2028 Encryption Header Parameters registry [JWS]. 2030 6.4.1. Registry Contents 2032 o Header Parameter Name: "epk" 2033 o Header Parameter Usage Location(s): JWE 2034 o Change Controller: IETF 2035 o Specification Document(s): Section 4.7.1.1 of [[ this document ]] 2037 o Header Parameter Name: "apu" 2038 o Header Parameter Usage Location(s): JWE 2039 o Change Controller: IETF 2040 o Specification Document(s): Section 4.7.1.2 of [[ this document ]] 2042 o Header Parameter Name: "apv" 2043 o Header Parameter Usage Location(s): JWE 2044 o Change Controller: IETF 2045 o Specification Document(s): Section 4.7.1.3 of [[ this document ]] 2047 o Header Parameter Name: "iv" 2048 o Header Parameter Usage Location(s): JWE 2049 o Change Controller: IETF 2050 o Specification Document(s): Section 4.8.1.1 of [[ this document ]] 2052 o Header Parameter Name: "tag" 2053 o Header Parameter Usage Location(s): JWE 2054 o Change Controller: IETF 2055 o Specification Document(s): Section 4.8.1.2 of [[ this document ]] 2057 7. Security Considerations 2059 All of the security issues faced by any cryptographic application 2060 must be faced by a JWS/JWE/JWK agent. Among these issues are 2061 protecting the user's private and symmetric keys, preventing various 2062 attacks, and helping the user avoid mistakes such as inadvertently 2063 encrypting a message for the wrong recipient. The entire list of 2064 security considerations is beyond the scope of this document, but 2065 some significant considerations are listed here. 2067 The security considerations in [AES], [DSS], [JWE], [JWK], [JWS], 2068 [NIST.800-38A], [NIST.800-38D], [NIST.800-56A], [RFC2104], [RFC3394], 2069 [RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this 2070 specification. 2072 Eventually the algorithms and/or key sizes currently described in 2073 this specification will no longer be considered sufficiently secure 2074 and will be removed. Therefore, implementers and deployments must be 2075 prepared for this eventuality. 2077 Algorithms of matching strengths should be used together whenever 2078 possible. For instance, when AES Key Wrap is used with a given key 2079 size, using the same key size is recommended when AES GCM is also 2080 used. 2082 While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not 2083 to adopt RSASSA-PKCS-v1_5 for new applications and instead requests 2084 that people transition to RSASSA-PSS, this specification does include 2085 RSASSA-PKCS-v1_5, for interoperability reasons, because it commonly 2086 implemented. 2088 Keys used with RSAES-PKCS1-v1_5 must follow the constraints in 2089 Section 7.2 of RFC 3447 [RFC3447]. In particular, keys with a low 2090 public key exponent value must not be used. 2092 Keys used with AES GCM must follow the constraints in Section 8.3 of 2093 [NIST.800-38D], which states: "The total number of invocations of the 2094 authenticated encryption function shall not exceed 2^32, including 2095 all IV lengths and all instances of the authenticated encryption 2096 function with the given key". In accordance with this rule, AES GCM 2097 MUST NOT be used with the same key encryption key or with the same 2098 direct encryption key more than 2^32 times. 2100 Plaintext JWSs (JWSs that use the "alg" value "none") provide no 2101 integrity protection. Thus, they must only be used in contexts where 2102 the payload is secured by means other than a digital signature or MAC 2103 value, or need not be secured. 2105 Receiving agents that validate signatures and sending agents that 2106 encrypt messages need to be cautious of cryptographic processing 2107 usage when validating signatures and encrypting messages using keys 2108 larger than those mandated in this specification. An attacker could 2109 send certificates with keys that would result in excessive 2110 cryptographic processing, for example, keys larger than those 2111 mandated in this specification, which could swamp the processing 2112 element. Agents that use such keys without first validating the 2113 certificate to a trust anchor are advised to have some sort of 2114 cryptographic resource management system to prevent such attacks. 2116 7.1. Reusing Key Material when Encrypting Keys 2118 It is NOT RECOMMENDED to reuse the same key material (Key Encryption 2119 Key, Content Master Key, Initialization Vector, etc.) to encrypt 2120 multiple JWK or JWK Set objects, or to encrypt the same JWK or JWK 2121 Set object multiple times. One suggestion for preventing re-use is 2122 to always generate a new set key material for each encryption 2123 operation, based on the considerations noted in this document as well 2124 as from [RFC4086]. 2126 7.2. Password Considerations 2128 While convenient for end users, passwords are vulnerable to a number 2129 of attacks. To help mitigate some of these limitations, this 2130 document applies principles from [RFC2898] to derive cryptographic 2131 keys from user-supplied passwords. 2133 However, the strength of the password still has a significant impact. 2134 A high-entry password has greater resistance to dictionary attacks. 2135 [NIST-800-63-1] contains guidelines for estimating password entropy, 2136 which can help applications and users generate stronger passwords. 2138 An ideal password is one that is as large (or larger) than the 2139 derived key length but less than the PRF's block size. Passwords 2140 larger than the PRF's block size are first hashed, which reduces an 2141 attacker's effective search space to the length of the hash algorithm 2142 (32 octets for HMAC SHA-256). It is RECOMMENDED that the password be 2143 no longer than 64 octets long for "PBES2-HS256+A256KW". 2145 Still, care needs to be taken in where and how password-based 2146 encryption is used. Such algorithms MUST NOT be used where the 2147 attacker can make an indefinite number of attempts to circumvent the 2148 protection. 2150 8. Internationalization Considerations 2152 Passwords obtained from users are likely to require preparation and 2153 normalization to account for differences of octet sequences generated 2154 by different input devices, locales, etc. It is RECOMMENDED that 2155 applications to perform the steps outlined in 2156 [I-D.melnikov-precis-saslprepbis] to prepare a password supplied 2157 directly by a user before performing key derivation and encryption. 2159 9. References 2160 9.1. Normative References 2162 [AES] National Institute of Standards and Technology (NIST), 2163 "Advanced Encryption Standard (AES)", FIPS PUB 197, 2164 November 2001. 2166 [DSS] National Institute of Standards and Technology, "Digital 2167 Signature Standard (DSS)", FIPS PUB 186-3, June 2009. 2169 [I-D.melnikov-precis-saslprepbis] 2170 Saint-Andre, P. and A. Melnikov, "Preparation and 2171 Comparison of Internationalized Strings Representing 2172 Simple User Names and Passwords", 2173 draft-melnikov-precis-saslprepbis-04 (work in progress), 2174 September 2012. 2176 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 2177 Encryption (JWE)", draft-ietf-jose-json-web-encryption 2178 (work in progress), July 2013. 2180 [JWK] Jones, M., "JSON Web Key (JWK)", 2181 draft-ietf-jose-json-web-key (work in progress), 2182 July 2013. 2184 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2185 Signature (JWS)", draft-ietf-jose-json-web-signature (work 2186 in progress), July 2013. 2188 [NIST.800-38A] 2189 National Institute of Standards and Technology (NIST), 2190 "Recommendation for Block Cipher Modes of Operation", 2191 NIST PUB 800-38A, December 2001. 2193 [NIST.800-38D] 2194 National Institute of Standards and Technology (NIST), 2195 "Recommendation for Block Cipher Modes of Operation: 2196 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 2197 December 2001. 2199 [NIST.800-56A] 2200 National Institute of Standards and Technology (NIST), 2201 "Recommendation for Pair-Wise Key Establishment Schemes 2202 Using Discrete Logarithm Cryptography", NIST Special 2203 Publication 800-56A, Revision 2, May 2013. 2205 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 2206 Hashing for Message Authentication", RFC 2104, 2207 February 1997. 2209 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2210 Requirement Levels", BCP 14, RFC 2119, March 1997. 2212 [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography 2213 Specification Version 2.0", RFC 2898, September 2000. 2215 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 2216 (AES) Key Wrap Algorithm", RFC 3394, September 2002. 2218 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2219 10646", STD 63, RFC 3629, November 2003. 2221 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 2222 Requirements for Security", BCP 106, RFC 4086, June 2005. 2224 [RFC4627] Crockford, D., "The application/json Media Type for 2225 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2227 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2228 Encodings", RFC 4648, October 2006. 2230 [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA- 2231 384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007. 2233 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 2234 Encryption", RFC 5116, January 2008. 2236 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2237 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2238 May 2008. 2240 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 2241 Curve Cryptography Algorithms", RFC 6090, February 2011. 2243 [SHS] National Institute of Standards and Technology, "Secure 2244 Hash Standard (SHS)", FIPS PUB 180-3, October 2008. 2246 [USASCII] American National Standards Institute, "Coded Character 2247 Set -- 7-bit American Standard Code for Information 2248 Interchange", ANSI X3.4, 1986. 2250 9.2. Informative References 2252 [CanvasApp] 2253 Facebook, "Canvas Applications", 2010. 2255 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 2256 McGrew, D. and K. Paterson, "Authenticated Encryption with 2257 AES-CBC and HMAC-SHA", 2258 draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), 2259 October 2012. 2261 [I-D.miller-jose-jwe-protected-jwk] 2262 Miller, M., "Using JavaScript Object Notation (JSON) Web 2263 Encryption (JWE) for Protecting JSON Web Key (JWK) 2264 Objects", draft-miller-jose-jwe-protected-jwk-02 (work in 2265 progress), June 2013. 2267 [I-D.rescorla-jsms] 2268 Rescorla, E. and J. Hildebrand, "JavaScript Message 2269 Security Format", draft-rescorla-jsms-00 (work in 2270 progress), March 2011. 2272 [JCA] Oracle, "Java Cryptography Architecture", 2011. 2274 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 2275 Encryption", September 2010. 2277 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 2278 September 2010. 2280 [MagicSignatures] 2281 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 2282 Signatures", January 2011. 2284 [NIST-800-63-1] 2285 National Institute of Standards and Technology (NIST), 2286 "Electronic Authentication Guideline", NIST 800-63-1, 2287 December 2011. 2289 [RFC2631] Rescorla, E., "Diffie-Hellman Key Agreement Method", 2290 RFC 2631, June 1999. 2292 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 2293 Language) XML-Signature Syntax and Processing", RFC 3275, 2294 March 2002. 2296 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 2297 Standards (PKCS) #1: RSA Cryptography Specifications 2298 Version 2.1", RFC 3447, February 2003. 2300 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2301 Unique IDentifier (UUID) URN Namespace", RFC 4122, 2302 July 2005. 2304 [W3C.CR-xmldsig-core2-20120124] 2305 Eastlake, D., Reagle, J., Yiu, K., Solo, D., Datta, P., 2306 Hirsch, F., Cantor, S., and T. Roessler, "XML Signature 2307 Syntax and Processing Version 2.0", World Wide Web 2308 Consortium CR CR-xmldsig-core2-20120124, January 2012, 2309 . 2311 [W3C.CR-xmlenc-core1-20120313] 2312 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 2313 "XML Encryption Syntax and Processing Version 1.1", World 2314 Wide Web Consortium CR CR-xmlenc-core1-20120313, 2315 March 2012, 2316 . 2318 [W3C.REC-xmlenc-core-20021210] 2319 Eastlake, D. and J. Reagle, "XML Encryption Syntax and 2320 Processing", World Wide Web Consortium Recommendation REC- 2321 xmlenc-core-20021210, December 2002, 2322 . 2324 Appendix A. Digital Signature/MAC Algorithm Identifier Cross-Reference 2326 This appendix contains a table cross-referencing the digital 2327 signature and MAC "alg" (algorithm) values used in this specification 2328 with the equivalent identifiers used by other standards and software 2329 packages. See XML DSIG [RFC3275], XML DSIG 2.0 2330 [W3C.CR-xmldsig-core2-20120124], and Java Cryptography Architecture 2331 [JCA] for more information about the names defined by those 2332 documents. 2334 +---------+----+---------------------------+----------+-------------+ 2335 | Algorit | JW | XML DSIG | JCA | OID | 2336 | hm | S | | | | 2337 +---------+----+---------------------------+----------+-------------+ 2338 | HMAC | HS | http://www.w3.org/2001/04 | HmacSHA2 | 1.2.840.113 | 2339 | using | 25 | /xmldsig-more#hmac-sha256 | 56 | 549.2.9 | 2340 | SHA-256 | 6 | | | | 2341 | hash | | | | | 2342 | algorit | | | | | 2343 | hm | | | | | 2344 | HMAC | HS | http://www.w3.org/2001/04 | HmacSHA3 | 1.2.840.113 | 2345 | using | 38 | /xmldsig-more#hmac-sha384 | 84 | 549.2.10 | 2346 | SHA-384 | 4 | | | | 2347 | hash | | | | | 2348 | algorit | | | | | 2349 | hm | | | | | 2350 | HMAC | HS | http://www.w3.org/2001/04 | HmacSHA5 | 1.2.840.113 | 2351 | using | 51 | /xmldsig-more#hmac-sha512 | 12 | 549.2.11 | 2352 | SHA-512 | 2 | | | | 2353 | hash | | | | | 2354 | algorit | | | | | 2355 | hm | | | | | 2356 | RSASSA- | RS | http://www.w3.org/2001/04 | SHA256wi | 1.2.840.113 | 2357 | PKCS-v1 | 25 | /xmldsig-more#rsa-sha256 | thRSA | 549.1.1.11 | 2358 | _5using | 6 | | | | 2359 | SHA-2 | | | | | 2360 | 56hash | | | | | 2361 | algor | | | | | 2362 | ithm | | | | | 2363 | RSASSA- | RS | http://www.w3.org/2001/04 | SHA384wi | 1.2.840.113 | 2364 | PKCS-v1 | 38 | /xmldsig-more#rsa-sha384 | thRSA | 549.1.1.12 | 2365 | _5using | 4 | | | | 2366 | SHA-3 | | | | | 2367 | 84hash | | | | | 2368 | algor | | | | | 2369 | ithm | | | | | 2370 | RSASSA- | RS | http://www.w3.org/2001/04 | SHA512wi | 1.2.840.113 | 2371 | PKCS-v1 | 51 | /xmldsig-more#rsa-sha512 | thRSA | 549.1.1.13 | 2372 | _5using | 2 | | | | 2373 | SHA-5 | | | | | 2374 | 12hash | | | | | 2375 | algor | | | | | 2376 | ithm | | | | | 2377 | ECDSA | ES | http://www.w3.org/2001/04 | SHA256wi | 1.2.840.100 | 2378 | using | 25 | /xmldsig-more#ecdsa-sha25 | thECDSA | 45.4.3.2 | 2379 | P-256 | 6 | 6 | | | 2380 | curve | | | | | 2381 | and | | | | | 2382 | SHA-256 | | | | | 2383 | hash | | | | | 2384 | algorit | | | | | 2385 | hm | | | | | 2386 | ECDSA | ES | http://www.w3.org/2001/04 | SHA384wi | 1.2.840.100 | 2387 | using | 38 | /xmldsig-more#ecdsa-sha38 | thECDSA | 45.4.3.3 | 2388 | P-384 | 4 | 4 | | | 2389 | curve | | | | | 2390 | and | | | | | 2391 | SHA-384 | | | | | 2392 | hash | | | | | 2393 | algorit | | | | | 2394 | hm | | | | | 2395 | ECDSA | ES | http://www.w3.org/2001/04 | SHA512wi | 1.2.840.100 | 2396 | using | 51 | /xmldsig-more#ecdsa-sha51 | thECDSA | 45.4.3.4 | 2397 | P-521 | 2 | 2 | | | 2398 | curve | | | | | 2399 | and | | | | | 2400 | SHA-512 | | | | | 2401 | hash | | | | | 2402 | algorit | | | | | 2403 | hm | | | | | 2404 | RSASSA- | PS | | | | 2405 | PSS | 25 | | | | 2406 | using | 6 | | | | 2407 | SHA-25 | | | | | 2408 | 6hash | | | | | 2409 | algori | | | | | 2410 | thm and | | | | | 2411 | MGF1 | | | | | 2412 | mask | | | | | 2413 | gener | | | | | 2414 | ation | | | | | 2415 | func | | | | | 2416 | tionwit | | | | | 2417 | h SHA | | | | | 2418 | -256 | | | | | 2419 | RSASSA- | PS | | | | 2420 | PSS | 51 | | | | 2421 | using | 2 | | | | 2422 | SHA-51 | | | | | 2423 | 2hash | | | | | 2424 | algori | | | | | 2425 | thm and | | | | | 2426 | MGF1 | | | | | 2427 | mask | | | | | 2428 | gener | | | | | 2429 | ation | | | | | 2430 | func | | | | | 2431 | tionwit | | | | | 2432 | h SHA | | | | | 2433 | -512 | | | | | 2434 +---------+----+---------------------------+----------+-------------+ 2436 Appendix B. Encryption Algorithm Identifier Cross-Reference 2438 This appendix contains a table cross-referencing the "alg" 2439 (algorithm) and "enc" (encryption method) values used in this 2440 specification with the equivalent identifiers used by other standards 2441 and software packages. See XML Encryption 2443 [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 2444 [W3C.CR-xmlenc-core1-20120313], and Java Cryptography Architecture 2445 [JCA] for more information about the names defined by those 2446 documents. 2448 For the composite algorithms "A128CBC-HS256" and "A256CBC-HS512", the 2449 corresponding AES CBC algorithm identifiers are listed. 2451 +----------+--------+--------------------------+--------------------+ 2452 | Algorith | JWE | XML ENC | JCA | 2453 | m | | | | 2454 +----------+--------+--------------------------+--------------------+ 2455 | RSAES-PK | RSA1_5 | http://www.w3.org/2001/0 | RSA/ECB/PKCS1Paddi | 2456 | CS1-V1_5 | | 4/xmlenc#rsa-1_5 | ng | 2457 | RSAES | RSA-OA | http://www.w3.org/2001/0 | RSA/ECB/OAEPWithSH | 2458 | using | EP | 4/xmlenc#rsa-oaep-mgf1p | A-1AndMGF1Padding | 2459 | Optimal | | | | 2460 | Asymmetr | | | | 2461 | ic | | | | 2462 | Encrypt | | | | 2463 | ion | | | | 2464 | Paddin | | | | 2465 | g (OAEP) | | | | 2466 | Elliptic | ECDH-E | http://www.w3.org/2009/x | | 2467 | Curve | S | mlenc11#ECDH-ES | | 2468 | Diffie-H | | | | 2469 | ellman | | | | 2470 | Ephemer | | | | 2471 | alStatic | | | | 2472 | Advanced | A128KW | http://www.w3.org/2001/0 | | 2473 | Encrypti | | 4/xmlenc#kw-aes128 | | 2474 | on | | | | 2475 | Standar | | | | 2476 | d(AES) | | | | 2477 | Key Wra | | | | 2478 | pAlgorit | | | | 2479 | hmusing | | | | 2480 | 128 bi | | | | 2481 | t keys | | | | 2482 | AES Key | A256KW | http://www.w3.org/2001/0 | | 2483 | Wrap | | 4/xmlenc#kw-aes256 | | 2484 | Algorith | | | | 2485 | musing | | | | 2486 | 256 bit | | | | 2487 | keys | | | | 2488 | AES in | A128CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 2489 | Cipher | C-HS25 | 4/xmlenc#aes128-cbc | ng | 2490 | Block | 6 | | | 2491 | Chaining | | | | 2492 | (CBC) | | | | 2493 | mode | | | | 2494 | with | | | | 2495 | PKCS #5 | | | | 2496 | padding | | | | 2497 | using | | | | 2498 | 128 bit | | | | 2499 | keys | | | | 2500 | AES in | A256CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 2501 | CBC mode | C-HS51 | 4/xmlenc#aes256-cbc | ng | 2502 | with | 2 | | | 2503 | PKCS #5 | | | | 2504 | padding | | | | 2505 | using | | | | 2506 | 256 bit | | | | 2507 | keys | | | | 2508 | AES in | A128GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 2509 | Galois/C | M | mlenc11#aes128-gcm | | 2510 | ounter | | | | 2511 | Mode | | | | 2512 | (GCM) | | | | 2513 | using | | | | 2514 | 128 bit | | | | 2515 | keys | | | | 2516 | AES GCM | A256GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 2517 | using | M | mlenc11#aes256-gcm | | 2518 | 256 bit | | | | 2519 | keys | | | | 2520 +----------+--------+--------------------------+--------------------+ 2522 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms 2524 The following test cases can be used to validate implementations of 2525 the AES_CBC_HMAC_SHA2 algorithms defined in Section 4.10. They are 2526 also intended to correspond to test cases that may appear in a future 2527 version of [I-D.mcgrew-aead-aes-cbc-hmac-sha2], demonstrating that 2528 the cryptographic computations performed are the same. 2530 The variable names are those defined in Section 4.10. All values are 2531 hexadecimal. 2533 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 2535 AES_128_CBC_HMAC_SHA_256 2537 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2538 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2540 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2542 ENC_KEY = 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2544 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2545 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2546 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2547 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2548 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2549 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2550 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2551 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2553 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2555 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2556 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2557 4b 65 72 63 6b 68 6f 66 66 73 2559 AL = 00 00 00 00 00 00 01 50 2561 E = c8 0e df a3 2d df 39 d5 ef 00 c0 b4 68 83 42 79 2562 a2 e4 6a 1b 80 49 f7 92 f7 6b fe 54 b9 03 a9 c9 2563 a9 4a c9 b4 7a d2 65 5c 5f 10 f9 ae f7 14 27 e2 2564 fc 6f 9b 3f 39 9a 22 14 89 f1 63 62 c7 03 23 36 2565 09 d4 5a c6 98 64 e3 32 1c f8 29 35 ac 40 96 c8 2566 6e 13 33 14 c5 40 19 e8 ca 79 80 df a4 b9 cf 1b 2567 38 4c 48 6f 3a 54 c5 10 78 15 8e e5 d7 9d e5 9f 2568 bd 34 d8 48 b3 d6 95 50 a6 76 46 34 44 27 ad e5 2569 4b 88 51 ff b5 98 f7 f8 00 74 b9 47 3c 82 e2 db 2571 M = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2572 e6 e5 45 82 47 65 15 f0 ad 9f 75 a2 b7 1c 73 ef 2574 T = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2576 C.2. Test Cases for AES_256_CBC_HMAC_SHA_512 2578 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2579 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2580 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2581 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2583 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2584 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2586 ENC_KEY = 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2587 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2589 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2590 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2591 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2592 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2593 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2594 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2595 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2596 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2598 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2600 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2601 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2602 4b 65 72 63 6b 68 6f 66 66 73 2604 AL = 00 00 00 00 00 00 01 50 2606 E = 4a ff aa ad b7 8c 31 c5 da 4b 1b 59 0d 10 ff bd 2607 3d d8 d5 d3 02 42 35 26 91 2d a0 37 ec bc c7 bd 2608 82 2c 30 1d d6 7c 37 3b cc b5 84 ad 3e 92 79 c2 2609 e6 d1 2a 13 74 b7 7f 07 75 53 df 82 94 10 44 6b 2610 36 eb d9 70 66 29 6a e6 42 7e a7 5c 2e 08 46 a1 2611 1a 09 cc f5 37 0d c8 0b fe cb ad 28 c7 3f 09 b3 2612 a3 b7 5e 66 2a 25 94 41 0a e4 96 b2 e2 e6 60 9e 2613 31 e6 e0 2c c8 37 f0 53 d2 1f 37 ff 4f 51 95 0b 2614 be 26 38 d0 9d d7 a4 93 09 30 80 6d 07 03 b1 f6 2616 M = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2617 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2618 fd 30 a5 65 c6 16 ff b2 f3 64 ba ec e6 8f c4 07 2619 53 bc fc 02 5d de 36 93 75 4a a1 f5 c3 37 3b 9c 2621 T = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2622 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2624 Appendix D. Acknowledgements 2626 Solutions for signing and encrypting JSON content were previously 2627 explored by Magic Signatures [MagicSignatures], JSON Simple Sign 2628 [JSS], Canvas Applications [CanvasApp], JSON Simple Encryption [JSE], 2629 and JavaScript Message Security Format [I-D.rescorla-jsms], all of 2630 which influenced this draft. 2632 The Authenticated Encryption with AES-CBC and HMAC-SHA 2633 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] specification, upon which the 2634 AES_CBC_HMAC_SHA2 algorithms are based, was written by David A. 2635 McGrew and Kenny Paterson. The test cases for AES_CBC_HMAC_SHA2 are 2636 based upon those for [I-D.mcgrew-aead-aes-cbc-hmac-sha2] by John 2637 Foley. 2639 Matt Miller wrote Using JavaScript Object Notation (JSON) Web 2640 Encryption (JWE) for Protecting JSON Web Key (JWK) Objects 2641 [I-D.miller-jose-jwe-protected-jwk], which the password-based 2642 encryption content of this draft is based upon. 2644 This specification is the work of the JOSE Working Group, which 2645 includes dozens of active and dedicated participants. In particular, 2646 the following individuals contributed ideas, feedback, and wording 2647 that influenced this specification: 2649 Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de 2650 Medeiros, Yaron Y. Goland, Dick Hardt, Jeff Hodges, Edmund Jay, James 2651 Manger, Matt Miller, Tony Nadalin, Axel Nennker, John Panzer, 2652 Emmanuel Raviart, Nat Sakimura, Jim Schaad, Hannes Tschofenig, and 2653 Sean Turner. 2655 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2656 Sean Turner and Stephen Farrell served as Security area directors 2657 during the creation of this specification. 2659 Appendix E. Document History 2661 [[ to be removed by the RFC editor before publication as an RFC ]] 2663 -13 2665 o Added key encryption with AES GCM as specified in 2666 draft-jones-jose-aes-gcm-key-wrap-01, addressing issue #13. 2668 o Added security considerations text limiting the number of times 2669 that an AES GCM key can be used for key encryption or direct 2670 encryption, per Section 8.3 of NIST SP 800-38D, addressing issue 2671 #28. 2673 o Added password-based key encryption as specified in 2674 draft-miller-jose-jwe-protected-jwk-02. 2676 -12 2678 o In the Direct Key Agreement case, the Concat KDF AlgorithmID is 2679 set to the octets of the UTF-8 representation of the "enc" header 2680 parameter value. 2682 o Restored the "apv" (agreement PartyVInfo) parameter. 2684 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2685 be with the algorithm descriptions that use them. 2687 o Changed terminology from "block encryption" to "content 2688 encryption". 2690 -11 2692 o Removed the Encrypted Key value from the AAD computation since it 2693 is already effectively integrity protected by the encryption 2694 process. The AAD value now only contains the representation of 2695 the JWE Encrypted Header. 2697 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2699 o Added more information about the use of PartyUInfo during key 2700 agreement. 2702 o Use the keydatalen as the SuppPubInfo value for the Concat KDF 2703 when doing key agreement, as RFC 2631 does. 2705 o Added algorithm identifiers for RSASSA-PSS with SHA-256 and SHA- 2706 512. 2708 o Added a Parameter Information Class value to the JSON Web Key 2709 Parameters registry, which registers whether the parameter conveys 2710 public or private information. 2712 -10 2714 o Changed the JWE processing rules for multiple recipients so that a 2715 single AAD value contains the header parameters and encrypted key 2716 values for all the recipients, enabling AES GCM to be safely used 2717 for multiple recipients. 2719 -09 2721 o Expanded the scope of the JWK parameters to include private and 2722 symmetric key representations, as specified by 2723 draft-jones-jose-json-private-and-symmetric-key-00. 2725 o Changed term "JWS Secured Input" to "JWS Signing Input". 2727 o Changed from using the term "byte" to "octet" when referring to 8 2728 bit values. 2730 o Specified that AES Key Wrap uses the default initial value 2731 specified in Section 2.2.3.1 of RFC 3394. This addressed issue 2732 #19. 2734 o Added Key Management Mode definitions to terminology section and 2735 used the defined terms to provide clearer key management 2736 instructions. This addressed issue #5. 2738 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2739 and "A256CBC-HS512". The new algorithms perform the same 2740 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2741 but with the Initialization Vector and Authentication Tag values 2742 remaining separate from the Ciphertext value in the output 2743 representation. Also deleted the header parameters "epu" 2744 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2745 they are no longer used. 2747 o Changed from using the term "Integrity Value" to "Authentication 2748 Tag". 2750 -08 2752 o Changed the name of the JWK key type parameter from "alg" to 2753 "kty". 2755 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2756 since the term AEAD in the RFC 5116 sense implied the use of a 2757 particular data representation, rather than just referring to the 2758 class of algorithms that perform authenticated encryption with 2759 associated data. 2761 o Applied editorial improvements suggested by Jeff Hodges. Many of 2762 these simplified the terminology used. 2764 o Added seriesInfo information to Internet Draft references. 2766 -07 2767 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2769 o Changed the name of the JWK RSA modulus parameter from "mod" to 2770 "n" and the name of the JWK RSA exponent parameter from "xpo" to 2771 "e", so that the identifiers are the same as those used in RFC 2772 3447. 2774 o Made several local editorial changes to clean up loose ends left 2775 over from to the decision to only support block encryption methods 2776 providing integrity. 2778 -06 2780 o Removed the "int" and "kdf" parameters and defined the new 2781 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2782 "A256CBC+HS512" to replace the former uses of AES CBC, which 2783 required the use of separate integrity and key derivation 2784 functions. 2786 o Included additional values in the Concat KDF calculation -- the 2787 desired output size and the algorithm value, and optionally 2788 PartyUInfo and PartyVInfo values. Added the optional header 2789 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2790 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2791 PartyVInfo). 2793 o Changed the name of the JWK RSA exponent parameter from "exp" to 2794 "xpo" so as to allow the potential use of the name "exp" for a 2795 future extension that might define an expiration parameter for 2796 keys. (The "exp" name is already used for this purpose in the JWT 2797 specification.) 2799 o Applied changes made by the RFC Editor to RFC 6749's registry 2800 language to this specification. 2802 -05 2804 o Support both direct encryption using a shared or agreed upon 2805 symmetric key, and the use of a shared or agreed upon symmetric 2806 key to key wrap the CMK. Specifically, added the "alg" values 2807 "dir", "ECDH-ES+A128KW", and "ECDH-ES+A256KW" to finish filling in 2808 this set of capabilities. 2810 o Updated open issues. 2812 -04 2813 o Added text requiring that any leading zero bytes be retained in 2814 base64url encoded key value representations for fixed-length 2815 values. 2817 o Added this language to Registration Templates: "This name is case 2818 sensitive. Names that match other registered names in a case 2819 insensitive manner SHOULD NOT be accepted." 2821 o Described additional open issues. 2823 o Applied editorial suggestions. 2825 -03 2827 o Always use a 128 bit "authentication tag" size for AES GCM, 2828 regardless of the key size. 2830 o Specified that use of a 128 bit IV is REQUIRED with AES CBC. It 2831 was previously RECOMMENDED. 2833 o Removed key size language for ECDSA algorithms, since the key size 2834 is implied by the algorithm being used. 2836 o Stated that the "int" key size must be the same as the hash output 2837 size (and not larger, as was previously allowed) so that its size 2838 is defined for key generation purposes. 2840 o Added the "kdf" (key derivation function) header parameter to 2841 provide crypto agility for key derivation. The default KDF 2842 remains the Concat KDF with the SHA-256 digest function. 2844 o Clarified that the "mod" and "exp" values are unsigned. 2846 o Added Implementation Requirements columns to algorithm tables and 2847 Implementation Requirements entries to algorithm registries. 2849 o Changed AES Key Wrap to RECOMMENDED. 2851 o Moved registries JSON Web Signature and Encryption Header 2852 Parameters and JSON Web Signature and Encryption Type Values to 2853 the JWS specification. 2855 o Moved JSON Web Key Parameters registry to the JWK specification. 2857 o Changed registration requirements from RFC Required to 2858 Specification Required with Expert Review. 2860 o Added Registration Template sections for defined registries. 2862 o Added Registry Contents sections to populate registry values. 2864 o No longer say "the UTF-8 representation of the JWS Secured Input 2865 (which is the same as the ASCII representation)". Just call it 2866 "the ASCII representation of the JWS Secured Input". 2868 o Added "Collision Resistant Namespace" to the terminology section. 2870 o Numerous editorial improvements. 2872 -02 2874 o For AES GCM, use the "additional authenticated data" parameter to 2875 provide integrity for the header, encrypted key, and ciphertext 2876 and use the resulting "authentication tag" value as the JWE 2877 Authentication Tag. 2879 o Defined minimum required key sizes for algorithms without 2880 specified key sizes. 2882 o Defined KDF output key sizes. 2884 o Specified the use of PKCS #5 padding with AES CBC. 2886 o Generalized text to allow key agreement to be employed as an 2887 alternative to key wrapping or key encryption. 2889 o Clarified that ECDH-ES is a key agreement algorithm. 2891 o Required implementation of AES-128-KW and AES-256-KW. 2893 o Removed the use of "A128GCM" and "A256GCM" for key wrapping. 2895 o Removed "A512KW" since it turns out that it's not a standard 2896 algorithm. 2898 o Clarified the relationship between "typ" header parameter values 2899 and MIME types. 2901 o Generalized language to refer to Message Authentication Codes 2902 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2903 unless in a context specific to HMAC algorithms. 2905 o Established registries: JSON Web Signature and Encryption Header 2906 Parameters, JSON Web Signature and Encryption Algorithms, JSON Web 2907 Signature and Encryption "typ" Values, JSON Web Key Parameters, 2908 and JSON Web Key Algorithm Families. 2910 o Moved algorithm-specific definitions from JWK to JWA. 2912 o Reformatted to give each member definition its own section 2913 heading. 2915 -01 2917 o Moved definition of "alg":"none" for JWSs here from the JWT 2918 specification since this functionality is likely to be useful in 2919 more contexts that just for JWTs. 2921 o Added Advanced Encryption Standard (AES) Key Wrap Algorithm using 2922 512 bit keys ("A512KW"). 2924 o Added text "Alternatively, the Encoded JWS Signature MAY be 2925 base64url decoded to produce the JWS Signature and this value can 2926 be compared with the computed HMAC value, as this comparison 2927 produces the same result as comparing the encoded values". 2929 o Corrected the Magic Signatures reference. 2931 o Made other editorial improvements suggested by JOSE working group 2932 participants. 2934 -00 2936 o Created the initial IETF draft based upon 2937 draft-jones-json-web-signature-04 and 2938 draft-jones-json-web-encryption-02 with no normative changes. 2940 o Changed terminology to no longer call both digital signatures and 2941 HMACs "signatures". 2943 Author's Address 2945 Michael B. Jones 2946 Microsoft 2948 Email: mbj@microsoft.com 2949 URI: http://self-issued.info/