idnits 2.17.1 draft-ietf-jose-json-web-algorithms-15.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 (September 3, 2013) is 3889 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 2793 -- Looks like a reference, but probably isn't: '0' on line 2793 -- Looks like a reference, but probably isn't: '65' on line 2777 -- Looks like a reference, but probably isn't: '49' on line 2772 -- Looks like a reference, but probably isn't: '50' on line 2772 -- Looks like a reference, but probably isn't: '56' on line 2772 -- Looks like a reference, but probably isn't: '71' on line 2772 -- Looks like a reference, but probably isn't: '67' on line 2772 -- Looks like a reference, but probably isn't: '77' on line 2772 -- Looks like a reference, but probably isn't: '5' on line 2775 -- Looks like a reference, but probably isn't: '108' on line 2777 -- Looks like a reference, but probably isn't: '105' on line 2777 -- Looks like a reference, but probably isn't: '99' on line 2777 -- Looks like a reference, but probably isn't: '101' on line 2777 -- Looks like a reference, but probably isn't: '3' on line 2780 -- Looks like a reference, but probably isn't: '66' on line 2782 -- Looks like a reference, but probably isn't: '111' on line 2782 -- Looks like a reference, but probably isn't: '98' on line 2782 -- Looks like a reference, but probably isn't: '128' on line 2785 -- 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-02 -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) Summary: 6 errors (**), 0 flaws (~~), 4 warnings (==), 26 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 September 3, 2013 5 Expires: March 7, 2014 7 JSON Web Algorithms (JWA) 8 draft-ietf-jose-json-web-algorithms-15 10 Abstract 12 The JSON Web Algorithms (JWA) specification registers 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. It defines several IANA registries for these 16 identifiers. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on March 7, 2014. 35 Copyright Notice 37 Copyright (c) 2013 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 53 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 54 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 2.1. Terms Incorporated from the JWS Specification . . . . . . 5 56 2.2. Terms Incorporated from the JWE Specification . . . . . . 6 57 2.3. Terms Incorporated from the JWK Specification . . . . . . 9 58 2.4. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 9 59 3. Cryptographic Algorithms for JWS . . . . . . . . . . . . . . . 9 60 3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 9 61 3.2. HMAC with SHA-2 Functions . . . . . . . . . . . . . . . . 10 62 3.3. Digital Signature with RSASSA-PKCS1-V1_5 . . . . . . . . . 11 63 3.4. Digital Signature with ECDSA . . . . . . . . . . . . . . . 12 64 3.5. Digital Signature with RSASSA-PSS . . . . . . . . . . . . 14 65 3.6. Using the Algorithm "none" . . . . . . . . . . . . . . . . 15 66 4. Cryptographic Algorithms for JWE . . . . . . . . . . . . . . . 15 67 4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 15 68 4.2. "enc" (Encryption Method) Header Parameter Values for 69 JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 70 4.3. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 21 71 4.4. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 21 72 4.5. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 21 73 4.6. Direct Encryption with a Shared Symmetric Key . . . . . . 21 74 4.7. Key Agreement with Elliptic Curve Diffie-Hellman 75 Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 21 76 4.7.1. Header Parameters Used for ECDH Key Agreement . . . . 22 77 4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 22 78 4.7.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 22 79 4.7.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 23 80 4.7.2. Key Derivation for ECDH Key Agreement . . . . . . . . 23 81 4.8. Key Encryption with AES GCM . . . . . . . . . . . . . . . 24 82 4.8.1. Header Parameters Used for AES GCM Key Encryption . . 25 83 4.8.1.1. "iv" (Initialization Vector) Header Parameter . . 25 84 4.8.1.2. "tag" (Authentication Tag) Header Parameter . . . 25 85 4.9. Key Encryption with PBES2 . . . . . . . . . . . . . . . . 25 86 4.9.1. Header Parameters Used for PBES2 Key Encryption . . . 25 87 4.9.1.1. "p2s" (PBES2 salt) Parameter . . . . . . . . . . . 25 88 4.9.1.2. "p2c" (PBES2 count) Parameter . . . . . . . . . . 26 89 4.10. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 26 90 4.10.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 26 91 4.10.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 27 92 4.10.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 27 93 4.10.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 28 94 4.10.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 29 95 4.10.4. AES_192_CBC_HMAC_SHA_384 . . . . . . . . . . . . . . . 29 96 4.10.5. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 30 97 4.10.6. Plaintext Encryption with AES_CBC_HMAC_SHA2 . . . . . 30 99 4.11. Plaintext Encryption with AES GCM . . . . . . . . . . . . 30 100 5. Cryptographic Algorithms for JWK . . . . . . . . . . . . . . . 31 101 5.1. "kty" (Key Type) Parameter Values . . . . . . . . . . . . 31 102 5.2. JWK Parameters for Elliptic Curve Keys . . . . . . . . . . 32 103 5.2.1. JWK Parameters for Elliptic Curve Public Keys . . . . 32 104 5.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 32 105 5.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 32 106 5.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 32 107 5.2.2. JWK Parameters for Elliptic Curve Private Keys . . . . 32 108 5.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 33 109 5.3. JWK Parameters for RSA Keys . . . . . . . . . . . . . . . 33 110 5.3.1. JWK Parameters for RSA Public Keys . . . . . . . . . . 33 111 5.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 33 112 5.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 33 113 5.3.2. JWK Parameters for RSA Private Keys . . . . . . . . . 33 114 5.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 34 115 5.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 34 116 5.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 34 117 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 34 118 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 34 119 5.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 34 120 5.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 35 121 5.4. JWK Parameters for Symmetric Keys . . . . . . . . . . . . 35 122 5.4.1. "k" (Key Value) Parameter . . . . . . . . . . . . . . 35 123 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 124 6.1. JSON Web Signature and Encryption Algorithms Registry . . 36 125 6.1.1. Template . . . . . . . . . . . . . . . . . . . . . . . 36 126 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 37 127 6.2. JSON Web Key Types Registry . . . . . . . . . . . . . . . 42 128 6.2.1. Registration Template . . . . . . . . . . . . . . . . 42 129 6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 43 130 6.3. JSON Web Key Parameters Registration . . . . . . . . . . . 43 131 6.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 43 132 6.4. Registration of JWE Header Parameter Names . . . . . . . . 45 133 6.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 45 134 7. Security Considerations . . . . . . . . . . . . . . . . . . . 46 135 7.1. Reusing Key Material when Encrypting Keys . . . . . . . . 47 136 7.2. Password Considerations . . . . . . . . . . . . . . . . . 47 137 8. Internationalization Considerations . . . . . . . . . . . . . 48 138 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 48 139 9.1. Normative References . . . . . . . . . . . . . . . . . . . 48 140 9.2. Informative References . . . . . . . . . . . . . . . . . . 50 141 Appendix A. Digital Signature/MAC Algorithm Identifier 142 Cross-Reference . . . . . . . . . . . . . . . . . . . 51 143 Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 54 144 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 57 145 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 58 146 C.2. Test Cases for AES_192_CBC_HMAC_SHA_384 . . . . . . . . . 59 147 C.3. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 60 148 Appendix D. Example ECDH-ES Key Agreement Computation . . . . . . 61 149 Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 63 150 Appendix F. Document History . . . . . . . . . . . . . . . . . . 64 151 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 70 153 1. Introduction 155 The JSON Web Algorithms (JWA) specification registers cryptographic 156 algorithms and identifiers to be used with the JSON Web Signature 157 (JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK) 158 [JWK] specifications. It defines several IANA registries for these 159 identifiers. All these specifications utilize JavaScript Object 160 Notation (JSON) [RFC4627] based data structures. This specification 161 also describes the semantics and operations that are specific to 162 these algorithms and key types. 164 Registering the algorithms and identifiers here, rather than in the 165 JWS, JWE, and JWK specifications, is intended to allow them to remain 166 unchanged in the face of changes in the set of Required, Recommended, 167 Optional, and Deprecated algorithms over time. This also allows 168 changes to the JWS, JWE, and JWK specifications without changing this 169 document. 171 Names defined by this specification are short because a core goal is 172 for the resulting representations to be compact. 174 1.1. Notational Conventions 176 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 177 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 178 document are to be interpreted as described in Key words for use in 179 RFCs to Indicate Requirement Levels [RFC2119]. 181 2. Terminology 183 2.1. Terms Incorporated from the JWS Specification 185 These terms defined by the JSON Web Signature (JWS) [JWS] 186 specification are incorporated into this specification: 188 JSON Web Signature (JWS) A data structure representing a digitally 189 signed or MACed message. The structure represents three values: 190 the JWS Header, the JWS Payload, and the JWS Signature. 192 JSON Text Object A UTF-8 [RFC3629] encoded text string representing 193 a JSON object; the syntax of JSON objects is defined in Section 194 2.2 of [RFC4627]. 196 JWS Header A JSON Text Object (or JSON Text Objects, when using the 197 JWS JSON Serialization) that describes the digital signature or 198 MAC operation applied to create the JWS Signature value. The 199 members of the JWS Header object(s) are Header Parameters. 201 JWS Payload The sequence of octets to be secured -- a.k.a., the 202 message. The payload can contain an arbitrary sequence of octets. 204 JWS Signature A sequence of octets containing the cryptographic 205 material that ensures the integrity of the JWS Protected Header 206 and the JWS Payload. The JWS Signature value is a digital 207 signature or MAC value calculated over the JWS Signing Input using 208 the parameters specified in the JWS Header. 210 JWS Protected Header A JSON Text Object that contains the portion of 211 the JWS Header that is integrity protected. For the JWS Compact 212 Serialization, this comprises the entire JWS Header. For the JWS 213 JSON Serialization, this is one component of the JWS Header. 215 Base64url Encoding Base64 encoding using the URL- and filename-safe 216 character set defined in Section 5 of RFC 4648 [RFC4648], with all 217 trailing '=' characters omitted (as permitted by Section 3.2). 218 (See Appendix C of [JWS] for notes on implementing base64url 219 encoding without padding.) 221 Encoded JWS Header Base64url encoding of the JWS Protected Header. 223 Encoded JWS Payload Base64url encoding of the JWS Payload. 225 Encoded JWS Signature Base64url encoding of the JWS Signature. 227 JWS Signing Input The concatenation of the Encoded JWS Header, a 228 period ('.') character, and the Encoded JWS Payload. 230 Collision Resistant Namespace A namespace that allows names to be 231 allocated in a manner such that they are highly unlikely to 232 collide with other names. Examples of Collision Resistant 233 Namespaces include: Domain Names, Object Identifiers (OIDs) as 234 defined in the ITU-T X.660 and X.670 Recommendation series, and 235 Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an 236 administratively delegated namespace, the definer of a name needs 237 to take reasonable precautions to ensure they are in control of 238 the portion of the namespace they use to define the name. 240 2.2. Terms Incorporated from the JWE Specification 242 These terms defined by the JSON Web Encryption (JWE) [JWE] 243 specification are incorporated into this specification: 245 JSON Web Encryption (JWE) A data structure representing an encrypted 246 message. The structure represents five values: the JWE Header, 247 the JWE Encrypted Key, the JWE Initialization Vector, the JWE 248 Ciphertext, and the JWE Authentication Tag. 250 Authenticated Encryption An Authenticated Encryption algorithm is 251 one that provides an integrated content integrity check. 252 Authenticated Encryption algorithms accept two inputs, the 253 Plaintext and the Additional Authenticated Data value, and produce 254 two outputs, the Ciphertext and the Authentication Tag value. AES 255 Galois/Counter Mode (GCM) is one such algorithm. 257 Plaintext The sequence of octets to be encrypted -- a.k.a., the 258 message. The plaintext can contain an arbitrary sequence of 259 octets. 261 Ciphertext An encrypted representation of the Plaintext. 263 Additional Authenticated Data (AAD) An input to an Authenticated 264 Encryption operation that is integrity protected but not 265 encrypted. 267 Authentication Tag An output of an Authenticated Encryption 268 operation that ensures the integrity of the Ciphertext and the 269 Additional Authenticated Data. Note that some algorithms may not 270 use an Authentication Tag, in which case this value is the empty 271 octet sequence. 273 Content Encryption Key (CEK) A symmetric key for the Authenticated 274 Encryption algorithm used to encrypt the Plaintext for the 275 recipient to produce the Ciphertext and the Authentication Tag. 277 JWE Header A JSON Text Object (or JSON Text Objects, when using the 278 JWE JSON Serialization) that describes the encryption operations 279 applied to create the JWE Encrypted Key, the JWE Ciphertext, and 280 the JWE Authentication Tag. The members of the JWE Header 281 object(s) are Header Parameters. 283 JWE Encrypted Key The result of encrypting the Content Encryption 284 Key (CEK) with the intended recipient's key using the specified 285 algorithm. Note that for some algorithms, the JWE Encrypted Key 286 value is specified as being the empty octet sequence. 288 JWE Initialization Vector A sequence of octets containing the 289 Initialization Vector used when encrypting the Plaintext. Note 290 that some algorithms may not use an Initialization Vector, in 291 which case this value is the empty octet sequence. 293 JWE Ciphertext A sequence of octets containing the Ciphertext for a 294 JWE. 296 JWE Authentication Tag A sequence of octets containing the 297 Authentication Tag for a JWE. 299 JWE Protected Header A JSON Text Object that contains the portion of 300 the JWE Header that is integrity protected. For the JWE Compact 301 Serialization, this comprises the entire JWE Header. For the JWE 302 JSON Serialization, this is one component of the JWE Header. 304 Encoded JWE Header Base64url encoding of the JWE Protected Header. 306 Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted 307 Key. 309 Encoded JWE Initialization Vector Base64url encoding of the JWE 310 Initialization Vector. 312 Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. 314 Encoded JWE Authentication Tag Base64url encoding of the JWE 315 Authentication Tag. 317 Key Management Mode A method of determining the Content Encryption 318 Key (CEK) value to use. Each algorithm used for determining the 319 CEK value uses a specific Key Management Mode. Key Management 320 Modes employed by this specification are Key Encryption, Key 321 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 322 and Direct Encryption. 324 Key Encryption A Key Management Mode in which the Content Encryption 325 Key (CEK) value is encrypted to the intended recipient using an 326 asymmetric encryption algorithm. 328 Key Wrapping A Key Management Mode in which the Content Encryption 329 Key (CEK) value is encrypted to the intended recipient using a 330 symmetric key wrapping algorithm. 332 Direct Key Agreement A Key Management Mode in which a key agreement 333 algorithm is used to agree upon the Content Encryption Key (CEK) 334 value. 336 Key Agreement with Key Wrapping A Key Management Mode in which a key 337 agreement algorithm is used to agree upon a symmetric key used to 338 encrypt the Content Encryption Key (CEK) value to the intended 339 recipient using a symmetric key wrapping algorithm. 341 Direct Encryption A Key Management Mode in which the Content 342 Encryption Key (CEK) value used is the secret symmetric key value 343 shared between the parties. 345 2.3. Terms Incorporated from the JWK Specification 347 These terms defined by the JSON Web Key (JWK) [JWK] specification are 348 incorporated into this specification: 350 JSON Web Key (JWK) A JSON object that represents a cryptographic 351 key. 353 JSON Web Key Set (JWK Set) A JSON object that contains an array of 354 JWKs as the value of its "keys" member. 356 2.4. Defined Terms 358 These terms are defined for use by this specification: 360 Header Parameter A name/value pair that is member of a JWS Header or 361 JWE Header. 363 Header Parameter Name The name of a member of a JSON object 364 representing a JWS Header or JWE Header. 366 Header Parameter Value The value of a member of a JSON object 367 representing a JWS Header or JWE Header. 369 3. Cryptographic Algorithms for JWS 371 JWS uses cryptographic algorithms to digitally sign or create a 372 Message Authentication Codes (MAC) of the contents of the JWS Header 373 and the JWS Payload. 375 3.1. "alg" (Algorithm) Header Parameter Values for JWS 377 The table below is the set of "alg" (algorithm) header parameter 378 values defined by this specification for use with JWS, each of which 379 is explained in more detail in the following sections: 381 +-----------+--------------------------------------+----------------+ 382 | alg | Digital Signature or MAC Algorithm | Implementation | 383 | Parameter | | Requirements | 384 | Value | | | 385 +-----------+--------------------------------------+----------------+ 386 | HS256 | HMAC using SHA-256 hash algorithm | Required | 387 | HS384 | HMAC using SHA-384 hash algorithm | Optional | 388 | HS512 | HMAC using SHA-512 hash algorithm | Optional | 389 | RS256 | RSASSA-PKCS-v1_5 using SHA-256 hash | Recommended | 390 | | algorithm | | 391 | RS384 | RSASSA-PKCS-v1_5 using SHA-384 hash | Optional | 392 | | algorithm | | 393 | RS512 | RSASSA-PKCS-v1_5 using SHA-512 hash | Optional | 394 | | algorithm | | 395 | ES256 | ECDSA using P-256 curve and SHA-256 | Recommended+ | 396 | | hash algorithm | | 397 | ES384 | ECDSA using P-384 curve and SHA-384 | Optional | 398 | | hash algorithm | | 399 | ES512 | ECDSA using P-521 curve and SHA-512 | Optional | 400 | | hash algorithm | | 401 | PS256 | RSASSA-PSS using SHA-256 hash | Optional | 402 | | algorithm and MGF1 mask generation | | 403 | | function with SHA-256 | | 404 | PS384 | RSASSA-PSS using SHA-384 hash | Optional | 405 | | algorithm and MGF1 mask generation | | 406 | | function with SHA-384 | | 407 | PS512 | RSASSA-PSS using SHA-512 hash | Optional | 408 | | algorithm and MGF1 mask generation | | 409 | | function with SHA-512 | | 410 | none | No digital signature or MAC value | Required | 411 | | included | | 412 +-----------+--------------------------------------+----------------+ 414 The use of "+" in the Implementation Requirements indicates that the 415 requirement strength is likely to be increased in a future version of 416 the specification. 418 See Appendix A for a table cross-referencing the digital signature 419 and MAC "alg" (algorithm) values used in this specification with the 420 equivalent identifiers used by other standards and software packages. 422 3.2. HMAC with SHA-2 Functions 424 Hash-based Message Authentication Codes (HMACs) enable one to use a 425 secret plus a cryptographic hash function to generate a Message 426 Authentication Code (MAC). This can be used to demonstrate that 427 whoever generated the MAC was in possession of the MAC key. 429 The algorithm for implementing and validating HMACs is provided in 430 RFC 2104 [RFC2104]. This section defines the use of the HMAC SHA- 431 256, HMAC SHA-384, and HMAC SHA-512 functions [SHS]. The "alg" 432 (algorithm) header parameter values "HS256", "HS384", and "HS512" are 433 used in the JWS Header to indicate that the Encoded JWS Signature 434 contains a base64url encoded HMAC value using the respective hash 435 function. 437 A key of the same size as the hash output (for instance, 256 bits for 438 "HS256") or larger MUST be used with this algorithm. 440 The HMAC SHA-256 MAC is generated per RFC 2104, using SHA-256 as the 441 hash algorithm "H", using the octets of the ASCII [USASCII] 442 representation of the JWS Signing Input as the "text" value, and 443 using the shared key. The HMAC output value is the JWS Signature. 444 The JWS signature is base64url encoded to produce the Encoded JWS 445 Signature. 447 The HMAC SHA-256 MAC for a JWS is validated by computing an HMAC 448 value per RFC 2104, using SHA-256 as the hash algorithm "H", using 449 the octets of the ASCII representation of the received JWS Signing 450 Input as the "text" value, and using the shared key. This computed 451 HMAC value is then compared to the result of base64url decoding the 452 received Encoded JWS signature. Alternatively, the computed HMAC 453 value can be base64url encoded and compared to the received Encoded 454 JWS Signature, as this comparison produces the same result as 455 comparing the unencoded values. In either case, if the values match, 456 the HMAC has been validated. 458 Securing content with the HMAC SHA-384 and HMAC SHA-512 algorithms is 459 performed identically to the procedure for HMAC SHA-256 - just using 460 the corresponding hash algorithms with correspondingly larger minimum 461 key sizes and result values: 384 bits each for HMAC SHA-384 and 512 462 bits each for HMAC SHA-512. 464 An example using this algorithm is shown in Appendix A.1 of [JWS]. 466 3.3. Digital Signature with RSASSA-PKCS1-V1_5 468 This section defines the use of the RSASSA-PKCS1-V1_5 digital 469 signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447] 470 (commonly known as PKCS #1), using SHA-256, SHA-384, or SHA-512 [SHS] 471 as the hash functions. The "alg" (algorithm) header parameter values 472 "RS256", "RS384", and "RS512" are used in the JWS Header to indicate 473 that the Encoded JWS Signature contains a base64url encoded RSASSA- 474 PKCS1-V1_5 digital signature using the respective hash function. 476 A key of size 2048 bits or larger MUST be used with these algorithms. 478 The RSASSA-PKCS1-V1_5 SHA-256 digital signature is generated as 479 follows: 481 1. Generate a digital signature of the octets of the ASCII 482 representation of the JWS Signing Input using RSASSA-PKCS1-V1_5- 483 SIGN and the SHA-256 hash function with the desired private key. 484 The output will be an octet sequence. 486 2. Base64url encode the resulting octet sequence. 488 The output is the Encoded JWS Signature for that JWS. 490 The RSASSA-PKCS1-V1_5 SHA-256 digital signature for a JWS is 491 validated as follows: 493 1. Take the Encoded JWS Signature and base64url decode it into an 494 octet sequence. If decoding fails, the validation has failed. 496 2. Submit the octets of the ASCII representation of the JWS Signing 497 Input and the public key corresponding to the private key used by 498 the signer to the RSASSA-PKCS1-V1_5-VERIFY algorithm using SHA- 499 256 as the hash function. 501 Signing with the RSASSA-PKCS1-V1_5 SHA-384 and RSASSA-PKCS1-V1_5 SHA- 502 512 algorithms is performed identically to the procedure for RSASSA- 503 PKCS1-V1_5 SHA-256 - just using the corresponding hash algorithms 504 instead of SHA-256. 506 An example using this algorithm is shown in Appendix A.2 of [JWS]. 508 3.4. Digital Signature with ECDSA 510 The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides 511 for the use of Elliptic Curve cryptography, which is able to provide 512 equivalent security to RSA cryptography but using shorter key sizes 513 and with greater processing speed. This means that ECDSA digital 514 signatures will be substantially smaller in terms of length than 515 equivalently strong RSA digital signatures. 517 This specification defines the use of ECDSA with the P-256 curve and 518 the SHA-256 cryptographic hash function, ECDSA with the P-384 curve 519 and the SHA-384 hash function, and ECDSA with the P-521 curve and the 520 SHA-512 hash function. The P-256, P-384, and P-521 curves are 521 defined in [DSS]. The "alg" (algorithm) header parameter values 522 "ES256", "ES384", and "ES512" are used in the JWS Header to indicate 523 that the Encoded JWS Signature contains a base64url encoded ECDSA 524 P-256 SHA-256, ECDSA P-384 SHA-384, or ECDSA P-521 SHA-512 digital 525 signature, respectively. 527 The ECDSA P-256 SHA-256 digital signature is generated as follows: 529 1. Generate a digital signature of the octets of the ASCII 530 representation of the JWS Signing Input using ECDSA P-256 SHA-256 531 with the desired private key. The output will be the pair (R, 532 S), where R and S are 256 bit unsigned integers. 534 2. Turn R and S into octet sequences in big endian order, with each 535 array being be 32 octets long. The array representations MUST 536 NOT be shortened to omit any leading zero octets contained in the 537 values. 539 3. Concatenate the two octet sequences in the order R and then S. 540 (Note that many ECDSA implementations will directly produce this 541 concatenation as their output.) 543 4. Base64url encode the resulting 64 octet sequence. 545 The output is the Encoded JWS Signature for the JWS. 547 The ECDSA P-256 SHA-256 digital signature for a JWS is validated as 548 follows: 550 1. Take the Encoded JWS Signature and base64url decode it into an 551 octet sequence. If decoding fails, the validation has failed. 553 2. The output of the base64url decoding MUST be a 64 octet sequence. 554 If decoding does not result in a 64 octet sequence, the 555 validation has failed. 557 3. Split the 64 octet sequence into two 32 octet sequences. The 558 first array will be R and the second S (with both being in big 559 endian octet order). 561 4. Submit the octets of the ASCII representation of the JWS Signing 562 Input R, S and the public key (x, y) to the ECDSA P-256 SHA-256 563 validator. 565 Signing with the ECDSA P-384 SHA-384 and ECDSA P-521 SHA-512 566 algorithms is performed identically to the procedure for ECDSA P-256 567 SHA-256 - just using the corresponding hash algorithms with 568 correspondingly larger result values. For ECDSA P-384 SHA-384, R and 569 S will be 384 bits each, resulting in a 96 octet sequence. For ECDSA 570 P-521 SHA-512, R and S will be 521 bits each, resulting in a 132 571 octet sequence. 573 Examples using these algorithms are shown in Appendices A.3 and A.4 574 of [JWS]. 576 3.5. Digital Signature with RSASSA-PSS 578 This section defines the use of the RSASSA-PSS digital signature 579 algorithm as defined in Section 8.1 of RFC 3447 [RFC3447] with the 580 MGF1 mask generation function, always using the same hash function 581 for both the RSASSA-PSS hash function and the MGF1 hash function. 582 Use of SHA-256, SHA-384, and SHA-512 as these hash functions is 583 defined. The size of the salt value is the same size as the hash 584 function output. All other algorithm parameters use the defaults 585 specified in Section A.2.3 of RFC 3447. The "alg" (algorithm) header 586 parameter values "PS256", "PS384", and "PS512" are used in the JWS 587 Header to indicate that the Encoded JWS Signature contains a 588 base64url encoded RSASSA-PSS digital signature using the respective 589 hash function in both roles. 591 A key of size 2048 bits or larger MUST be used with this algorithm. 593 The RSASSA-PSS SHA-256 digital signature is generated as follows: 595 1. Generate a digital signature of the octets of the ASCII 596 representation of the JWS Signing Input using RSASSA-PSS-SIGN, 597 the SHA-256 hash function, and the MGF1 mask generation function 598 with SHA-256 with the desired private key. The output will be an 599 octet sequence. 601 2. Base64url encode the resulting octet sequence. 603 The output is the Encoded JWS Signature for that JWS. 605 The RSASSA-PSS SHA-256 digital signature for a JWS is validated as 606 follows: 608 1. Take the Encoded JWS Signature and base64url decode it into an 609 octet sequence. If decoding fails, the validation has failed. 611 2. Submit the octets of the ASCII representation of the JWS Signing 612 Input and the public key corresponding to the private key used by 613 the signer to the RSASSA-PSS-VERIFY algorithm using SHA-256 as 614 the hash function and using MGF1 as the mask generation function 615 with SHA-256. 617 Signing with the RSASSA-PSS SHA-384 and RSASSA-PSS SHA-512 algorithms 618 is performed identically to the procedure for RSASSA-PSS SHA-256 - 619 just using the alternative hash algorithm in both roles. 621 3.6. Using the Algorithm "none" 623 JWSs MAY also be created that do not provide integrity protection. 624 Such a JWS is called a "Plaintext JWS". Plaintext JWSs MUST use the 625 "alg" value "none", and are formatted identically to other JWSs, but 626 with the empty string for its JWS Signature value. 628 4. Cryptographic Algorithms for JWE 630 JWE uses cryptographic algorithms to encrypt the Content Encryption 631 Key (CEK) and the Plaintext. 633 4.1. "alg" (Algorithm) Header Parameter Values for JWE 635 The table below is the set of "alg" (algorithm) header parameter 636 values that are defined by this specification for use with JWE. 637 These algorithms are used to encrypt the CEK, producing the JWE 638 Encrypted Key, or to use key agreement to agree upon the CEK. 640 +-------------------+-----------------+------------+----------------+ 641 | alg Parameter | Key Management | Additional | Implementation | 642 | Value | Algorithm | Header | Requirements | 643 | | | Parameters | | 644 +-------------------+-----------------+------------+----------------+ 645 | RSA1_5 | RSAES-PKCS1-V1_ | (none) | Required | 646 | | 5[RFC3447] | | | 647 | RSA-OAEP | RSAES using | (none) | Optional | 648 | | Optimal | | | 649 | | Asymmetric | | | 650 | | Encryption | | | 651 | | Padding (OAEP) | | | 652 | | [RFC3447], with | | | 653 | | the default | | | 654 | | parameters | | | 655 | | specified by | | | 656 | | RFC 3447 in | | | 657 | | Section A.2.1 | | | 658 | A128KW | Advanced | (none) | Recommended | 659 | | Encryption | | | 660 | | Standard (AES) | | | 661 | | Key Wrap | | | 662 | | Algorithm | | | 663 | | [RFC3394] using | | | 664 | | the default | | | 665 | | initial value | | | 666 | | specified in | | | 667 | | Section 2.2.3.1 | | | 668 | | and using 128 | | | 669 | | bit keys | | | 670 | A192KW | AES Key Wrap | (none) | Optional | 671 | | Algorithm using | | | 672 | | the default | | | 673 | | initial value | | | 674 | | specified in | | | 675 | | Section 2.2.3.1 | | | 676 | | and using 192 | | | 677 | | bit keys | | | 678 | A256KW | AES Key Wrap | (none) | Recommended | 679 | | Algorithm using | | | 680 | | the default | | | 681 | | initial value | | | 682 | | specified in | | | 683 | | Section 2.2.3.1 | | | 684 | | and using 256 | | | 685 | | bit keys | | | 686 | dir | Direct use of a | (none) | Recommended | 687 | | shared | | | 688 | | symmetric key | | | 689 | | as the Content | | | 690 | | Encryption Key | | | 691 | | (CEK) for the | | | 692 | | content | | | 693 | | encryption step | | | 694 | | (rather than | | | 695 | | using the | | | 696 | | symmetric key | | | 697 | | to wrap the | | | 698 | | CEK) | | | 699 | ECDH-ES | Elliptic Curve | "epk", | Recommended+ | 700 | | Diffie-Hellman | "apu", | | 701 | | Ephemeral | "apv" | | 702 | | Static | | | 703 | | [RFC6090] key | | | 704 | | agreement using | | | 705 | | the Concat KDF, | | | 706 | | as defined in | | | 707 | | Section 5.8.1 | | | 708 | | of | | | 709 | | [NIST.800-56A], | | | 710 | | with the | | | 711 | | agreed-upon key | | | 712 | | being used | | | 713 | | directly as the | | | 714 | | Content | | | 715 | | Encryption Key | | | 716 | | (CEK) (rather | | | 717 | | than being used | | | 718 | | to wrap the | | | 719 | | CEK), as | | | 720 | | specified in | | | 721 | | Section 4.7 | | | 722 | ECDH-ES+A128KW | Elliptic Curve | "epk", | Recommended | 723 | | Diffie-Hellman | "apu", | | 724 | | Ephemeral | "apv" | | 725 | | Static key | | | 726 | | agreement per | | | 727 | | "ECDH-ES" and | | | 728 | | Section 4.7, | | | 729 | | where the | | | 730 | | agreed-upon key | | | 731 | | is used to wrap | | | 732 | | the Content | | | 733 | | Encryption Key | | | 734 | | (CEK) with the | | | 735 | | "A128KW" | | | 736 | | function | | | 737 | | (rather than | | | 738 | | being used | | | 739 | | directly as the | | | 740 | | CEK) | | | 741 | ECDH-ES+A192KW | Elliptic Curve | "epk", | Optional | 742 | | Diffie-Hellman | "apu", | | 743 | | Ephemeral | "apv" | | 744 | | Static key | | | 745 | | agreement, | | | 746 | | where the | | | 747 | | agreed-upon key | | | 748 | | is used to wrap | | | 749 | | the Content | | | 750 | | Encryption Key | | | 751 | | (CEK) with the | | | 752 | | "A192KW" | | | 753 | | function | | | 754 | | (rather than | | | 755 | | being used | | | 756 | | directly as the | | | 757 | | CEK) | | | 758 | ECDH-ES+A256KW | Elliptic Curve | "epk", | Recommended | 759 | | Diffie-Hellman | "apu", | | 760 | | Ephemeral | "apv" | | 761 | | Static key | | | 762 | | agreement, | | | 763 | | where the | | | 764 | | agreed-upon key | | | 765 | | is used to wrap | | | 766 | | the Content | | | 767 | | Encryption Key | | | 768 | | (CEK) with the | | | 769 | | "A256KW" | | | 770 | | function | | | 771 | | (rather than | | | 772 | | being used | | | 773 | | directly as the | | | 774 | | CEK) | | | 775 | A128GCMKW | AES in | "iv", | Optional | 776 | | Galois/Counter | "tag" | | 777 | | Mode (GCM) | | | 778 | | [AES] | | | 779 | | [NIST.800-38D] | | | 780 | | using 128 bit | | | 781 | | keys | | | 782 | A192GCMKW | AES GCM using | "iv", | Optional | 783 | | 192 bit keys | "tag" | | 784 | A256GCMKW | AES GCM using | "iv", | Optional | 785 | | 256 bit keys | "tag" | | 786 | PBES2-HS256+A128K | PBES2 [RFC2898] | "p2s", | Optional | 787 | W | with HMAC | "p2c" | | 788 | | SHA-256 as the | | | 789 | | PRF and AES Key | | | 790 | | Wrap [RFC3394] | | | 791 | | using 128 bit | | | 792 | | keys for the | | | 793 | | encryption | | | 794 | | scheme | | | 795 | PBES2-HS384+A192K | PBES2 with HMAC | "p2s", | Optional | 796 | W | SHA-256 as the | "p2c" | | 797 | | PRF and AES Key | | | 798 | | Wrap using 192 | | | 799 | | bit keys for | | | 800 | | the encryption | | | 801 | | scheme | | | 802 | PBES2-HS512+A256K | PBES2 with HMAC | "p2s", | Optional | 803 | W | SHA-256 as the | "p2c" | | 804 | | PRF and AES Key | | | 805 | | Wrap using 256 | | | 806 | | bit keys for | | | 807 | | the encryption | | | 808 | | scheme | | | 809 +-------------------+-----------------+------------+----------------+ 811 The Additional Header Parameters column indicates what additional 812 Header Parameters are used by the algorithm, beyond "alg", which all 813 use. All but "dir" and "ECDH-ES" also produce a JWE Encrypted Key 814 value. 816 The use of "+" in the Implementation Requirements indicates that the 817 requirement strength is likely to be increased in a future version of 818 the specification. 820 4.2. "enc" (Encryption Method) Header Parameter Values for JWE 822 The table below is the set of "enc" (encryption method) header 823 parameter values that are defined by this specification for use with 824 JWE. These algorithms are used to encrypt the Plaintext, which 825 produces the Ciphertext. 827 +-------------+------------------------+------------+---------------+ 828 | enc | Content Encryption | Additional | Implementatio | 829 | Parameter | Algorithm | Header | nRequirements | 830 | Value | | Parameters | | 831 +-------------+------------------------+------------+---------------+ 832 | A128CBC-HS2 | The | (none) | Required | 833 | 56 | AES_128_CBC_HMAC_SHA_2 | | | 834 | | 56 authenticated | | | 835 | | encryption algorithm, | | | 836 | | as defined in | | | 837 | | Section 4.10.3. This | | | 838 | | algorithm uses a 256 | | | 839 | | bit key. | | | 840 | A192CBC-HS3 | The | (none) | Optional | 841 | 84 | AES_192_CBC_HMAC_SHA_3 | | | 842 | | 84 authenticated | | | 843 | | encryption algorithm, | | | 844 | | as defined in | | | 845 | | Section 4.10.4. This | | | 846 | | algorithm uses a 384 | | | 847 | | bit key. | | | 848 | A256CBC-HS5 | The | (none) | Required | 849 | 12 | AES_256_CBC_HMAC_SHA_5 | | | 850 | | 12 authenticated | | | 851 | | encryption algorithm, | | | 852 | | as defined in | | | 853 | | Section 4.10.5. This | | | 854 | | algorithm uses a 512 | | | 855 | | bit key. | | | 856 | A128GCM | AES in Galois/Counter | (none) | Recommended | 857 | | Mode (GCM) [AES] | | | 858 | | [NIST.800-38D] using | | | 859 | | 128 bit keys | | | 860 | A192GCM | AES GCM using 192 bit | (none) | Optional | 861 | | keys | | | 862 | A256GCM | AES GCM using 256 bit | (none) | Recommended | 863 | | keys | | | 864 +-------------+------------------------+------------+---------------+ 866 The Additional Header Parameters column indicates what additional 867 Header Parameters are used by the algorithm, beyond "enc", which all 868 use. All also use a JWE Initialization Vector value and produce JWE 869 Ciphertext and JWE Authentication Tag values. 871 See Appendix B for a table cross-referencing the encryption "alg" 872 (algorithm) and "enc" (encryption method) values used in this 873 specification with the equivalent identifiers used by other standards 874 and software packages. 876 4.3. Key Encryption with RSAES-PKCS1-V1_5 878 This section defines the specifics of encrypting a JWE CEK with 879 RSAES-PKCS1-V1_5 [RFC3447]. The "alg" header parameter value 880 "RSA1_5" is used in this case. 882 A key of size 2048 bits or larger MUST be used with this algorithm. 884 An example using this algorithm is shown in Appendix A.2 of [JWE]. 886 4.4. Key Encryption with RSAES OAEP 888 This section defines the specifics of encrypting a JWE CEK with RSAES 889 using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447], with 890 the default parameters specified by RFC 3447 in Section A.2.1. The 891 "alg" header parameter value "RSA-OAEP" is used in this case. 893 A key of size 2048 bits or larger MUST be used with this algorithm. 895 An example using this algorithm is shown in Appendix A.1 of [JWE]. 897 4.5. Key Wrapping with AES Key Wrap 899 This section defines the specifics of encrypting a JWE CEK with the 900 Advanced Encryption Standard (AES) Key Wrap Algorithm [RFC3394] using 901 the default initial value specified in Section 2.2.3.1 using 128, 902 192, or 256 bit keys. The "alg" header parameter values "A128KW", 903 "A192KW", or "A256KW" are respectively used in this case. 905 An example using this algorithm is shown in Appendix A.3 of [JWE]. 907 4.6. Direct Encryption with a Shared Symmetric Key 909 This section defines the specifics of directly performing symmetric 910 key encryption without performing a key wrapping step. In this case, 911 the shared symmetric key is used directly as the Content Encryption 912 Key (CEK) value for the "enc" algorithm. An empty octet sequence is 913 used as the JWE Encrypted Key value. The "alg" header parameter 914 value "dir" is used in this case. 916 4.7. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static 917 (ECDH-ES) 919 This section defines the specifics of key agreement with Elliptic 920 Curve Diffie-Hellman Ephemeral Static [RFC6090], in combination with 921 the Concat KDF, as defined in Section 5.8.1 of [NIST.800-56A]. The 922 key agreement result can be used in one of two ways: 924 1. directly as the Content Encryption Key (CEK) for the "enc" 925 algorithm, in the Direct Key Agreement mode, or 927 2. as a symmetric key used to wrap the CEK with the "A128KW", 928 "A192KW", or "A256KW" algorithms, in the Key Agreement with Key 929 Wrapping mode. 931 The "alg" header parameter value "ECDH-ES" is used in the Direct Key 932 Agreement mode and the values "ECDH-ES+A128KW", "ECDH-ES+A192KW", or 933 "ECDH-ES+A256KW" are used in the Key Agreement with Key Wrapping 934 mode. 936 In the Direct Key Agreement case, the output of the Concat KDF MUST 937 be a key of the same length as that used by the "enc" algorithm; in 938 this case, the empty octet sequence is used as the JWE Encrypted Key 939 value. In the Key Agreement with Key Wrapping case, the output of 940 the Concat KDF MUST be a key of the length needed for the specified 941 key wrapping algorithm, one of 128, 192, or 256 bits respectively. 943 A new ephemeral public key value MUST be generated for each key 944 agreement operation. 946 4.7.1. Header Parameters Used for ECDH Key Agreement 948 The following Header Parameter Names are reserved and are used for 949 key agreement as defined below. 951 4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter 953 The "epk" (ephemeral public key) value created by the originator for 954 the use in key agreement algorithms. This key is represented as a 955 JSON Web Key [JWK] public key value. It MUST contain only public key 956 parameters and SHOULD contain only the minimum JWK parameters 957 necessary to represent the key; other JWK parameters included can be 958 checked for consistency and honored or can be ignored. This Header 959 Parameter is REQUIRED and MUST be understood and processed by 960 implementations when these algorithms are used. 962 4.7.1.2. "apu" (Agreement PartyUInfo) Header Parameter 964 The "apu" (agreement PartyUInfo) value for key agreement algorithms 965 using it (such as "ECDH-ES"), represented as a base64url encoded 966 string. When used, the PartyUInfo value contains information about 967 the sender. Use of this Header Parameter is OPTIONAL. This Header 968 Parameter MUST be understood and processed by implementations when 969 these algorithms are used. 971 4.7.1.3. "apv" (Agreement PartyVInfo) Header Parameter 973 The "apv" (agreement PartyVInfo) value for key agreement algorithms 974 using it (such as "ECDH-ES"), represented as a base64url encoded 975 string. When used, the PartyVInfo value contains information about 976 the receiver. Use of this Header Parameter is OPTIONAL. This Header 977 Parameter MUST be understood and processed by implementations when 978 these algorithms are used. 980 4.7.2. Key Derivation for ECDH Key Agreement 982 The key derivation process derives the agreed upon key from the 983 shared secret Z established through the ECDH algorithm, per Section 984 6.2.2.2 of [NIST.800-56A]. 986 Key derivation is performed using the Concat KDF, as defined in 987 Section 5.8.1 of [NIST.800-56A], where the Digest Method is SHA-256. 988 The Concat KDF parameters are set as follows: 990 Z This is set to the representation of the shared secret Z as an 991 octet sequence. 993 keydatalen This is set to the number of bits in the desired output 994 key. For "ECDH-ES", this is length of the key used by the "enc" 995 algorithm. For "ECDH-ES+A128KW", "ECDH-ES+A192KW", and 996 "ECDH-ES+A256KW", this is 128, 192, and 256, respectively. 998 AlgorithmID In the Direct Key Agreement case, this is set to the 999 octets of the UTF-8 representation of the "enc" header parameter 1000 value. In the Key Agreement with Key Wrapping case, this is set 1001 to the octets of the UTF-8 representation of the "alg" header 1002 parameter value. 1004 PartyUInfo The PartyUInfo value is of the form Datalen || Data, 1005 where Data is a variable-length string of zero or more octets, and 1006 Datalen is a fixed-length, big endian 32 bit counter that 1007 indicates the length (in octets) of Data, with || being 1008 concatenation. If an "apu" (agreement PartyUInfo) header 1009 parameter is present, Data is set to the result of base64url 1010 decoding the "apu" value and Datalen is set to the number of 1011 octets in Data. Otherwise, Datalen is set to 0 and Data is set to 1012 the empty octet sequence. 1014 PartyVInfo The PartyVInfo value is of the form Datalen || Data, 1015 where Data is a variable-length string of zero or more octets, and 1016 Datalen is a fixed-length, big endian 32 bit counter that 1017 indicates the length (in octets) of Data, with || being 1018 concatenation. If an "apv" (agreement PartyVInfo) header 1019 parameter is present, Data is set to the result of base64url 1020 decoding the "apv" value and Datalen is set to the number of 1021 octets in Data. Otherwise, Datalen is set to 0 and Data is set to 1022 the empty octet sequence. 1024 SuppPubInfo This is set to the keydatalen represented as a 32 bit 1025 big endian integer. 1027 SuppPrivInfo This is set to the empty octet sequence. 1029 See Appendix D for an example key agreement computation using this 1030 method. 1032 Note: The Diffie-Hellman Key Agreement Method [RFC2631] uses a key 1033 derivation function similar to the Concat KDF, but with fewer 1034 parameters. Rather than having separate PartyUInfo and PartyVInfo 1035 parameters, it uses a single PartyAInfo parameter, which is a random 1036 string provided by the sender, that contains 512 bits of information, 1037 when provided. It has no SuppPrivInfo parameter. Should it be 1038 appropriate for the application, key agreement can be performed in a 1039 manner akin to RFC 2631 by using the PartyAInfo value as the "apu" 1040 (Agreement PartyUInfo) header parameter value, when provided, and by 1041 using no "apv" (Agreement PartyVInfo) header parameter. 1043 4.8. Key Encryption with AES GCM 1045 This section defines the specifics of encrypting a JWE Content 1046 Encryption Key (CEK) with Advanced Encryption Standard (AES) in 1047 Galois/Counter Mode (GCM) [AES] [NIST.800-38D] using 128, 192, or 256 1048 bit keys. The "alg" header parameter values "A128GCMKW", 1049 "A192GCMKW", or "A256GCMKW" are respectively used in this case. 1051 Use of an Initialization Vector of size 96 bits is REQUIRED with this 1052 algorithm. The Initialization Vector is represented in base64url 1053 encoded form as the "iv" (initialization vector) header parameter 1054 value. 1056 The Additional Authenticated Data value used is the empty octet 1057 string. 1059 The requested size of the Authentication Tag output MUST be 128 bits, 1060 regardless of the key size. 1062 The JWE Encrypted Key value is the Ciphertext output. 1064 The Authentication Tag output is represented in base64url encoded 1065 form as the "tag" (authentication tag) header parameter value. 1067 4.8.1. Header Parameters Used for AES GCM Key Encryption 1069 The following Header Parameters are used for AES GCM key encryption. 1071 4.8.1.1. "iv" (Initialization Vector) Header Parameter 1073 The "iv" (initialization vector) header parameter value is the 1074 base64url encoded representation of the Initialization Vector value 1075 used for the key encryption operation. This Header Parameter is 1076 REQUIRED and MUST be understood and processed by implementations when 1077 these algorithms are used. 1079 4.8.1.2. "tag" (Authentication Tag) Header Parameter 1081 The "tag" (authentication tag) header parameter value is the 1082 base64url encoded representation of the Authentication Tag value 1083 resulting from the key encryption operation. This Header Parameter 1084 is REQUIRED and MUST be understood and processed by implementations 1085 when these algorithms are used. 1087 4.9. Key Encryption with PBES2 1089 The "PBES2-HS256+A128KW", "PBES2-HS384+A192KW", and 1090 "PBES2-HS512+A256KW" composite algorithms are used to perform 1091 password-based encryption of a JWE CEK, by first deriving a key 1092 encryption key from a user-supplied password, then encrypting the JWE 1093 CEK using the derived key. These algorithms are PBES2 schemes as 1094 specified in Section 6.2 of [RFC2898]. 1096 These algorithms use HMAC SHA-2 algorithms as the Pseudo-Random 1097 Function (PRF) for the PBKDF2 key derivation and AES Key Wrap 1098 [RFC3394] for the encryption scheme. The salt MUST be provided as 1099 the "p2s" header parameter value, and MUST be base64url decoded to 1100 obtain the value. The iteration count parameter MUST be provided as 1101 the "p2c" header parameter value. The algorithms respectively use 1102 HMAC SHA-256, HMAC SHA-384, and HMAC SHA-512 as the PRF and use 128, 1103 192, and 256 bit AES Key Wrap keys. Their derived-key lengths 1104 (dkLen) respectively are 16, 24, and 32 octets. 1106 4.9.1. Header Parameters Used for PBES2 Key Encryption 1108 The following Header Parameters are used for Key Encryption with 1109 PBES2. 1111 4.9.1.1. "p2s" (PBES2 salt) Parameter 1113 The "p2s" (PBES2 salt) header parameter contains the PBKDF2 salt 1114 value, encoded using base64url. This Header Parameter is REQUIRED 1115 and MUST be understood and processed by implementations when these 1116 algorithms are used. 1118 The salt expands the possible keys that can be derived from a given 1119 password. A salt value containing 8 or more octets MUST be used. A 1120 new salt value MUST be generated randomly for every encryption 1121 operation; see [RFC4086] for considerations on generating random 1122 values. 1124 4.9.1.2. "p2c" (PBES2 count) Parameter 1126 The "p2c" (PBES2 count) header parameter contains the PBKDF2 1127 iteration count, represented as a positive integer. This Header 1128 Parameter is REQUIRED and MUST be understood and processed by 1129 implementations when these algorithms are used. 1131 The iteration count adds computational expense, ideally compounded by 1132 the possible range of keys introduced by the salt. A minimum 1133 iteration count of 1000 is RECOMMENDED. 1135 4.10. AES_CBC_HMAC_SHA2 Algorithms 1137 This section defines a family of authenticated encryption algorithms 1138 built using a composition of Advanced Encryption Standard (AES) in 1139 Cipher Block Chaining (CBC) mode with PKCS #5 padding [AES] 1140 [NIST.800-38A] operations and HMAC [RFC2104] [SHS] operations. This 1141 algorithm family is called AES_CBC_HMAC_SHA2. It also defines three 1142 instances of this family, the first using 128 bit CBC keys and HMAC 1143 SHA-256, the second using 192 bit CBC keys and HMAC SHA-384, and the 1144 third using 256 bit CBC keys and HMAC SHA-512. Test cases for these 1145 algorithms can be found in Appendix C. 1147 These algorithms are based upon Authenticated Encryption with AES-CBC 1148 and HMAC-SHA [I-D.mcgrew-aead-aes-cbc-hmac-sha2], performing the same 1149 cryptographic computations, but with the Initialization Vector and 1150 Authentication Tag values remaining separate, rather than being 1151 concatenated with the Ciphertext value in the output representation. 1152 This option is discussed in Appendix B of that specification. This 1153 algorithm family is a generalization of the algorithm family in 1154 [I-D.mcgrew-aead-aes-cbc-hmac-sha2], and can be used to implement 1155 those algorithms. 1157 4.10.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 1159 We use the following notational conventions. 1161 CBC-PKCS5-ENC(X, P) denotes the AES CBC encryption of P using PKCS 1162 #5 padding using the cipher with the key X. 1164 MAC(Y, M) denotes the application of the Message Authentication 1165 Code (MAC) to the message M, using the key Y. 1167 The concatenation of two octet strings A and B is denoted as 1168 A || B. 1170 4.10.2. Generic AES_CBC_HMAC_SHA2 Algorithm 1172 This section defines AES_CBC_HMAC_SHA2 in a manner that is 1173 independent of the AES CBC key size or hash function to be used. 1174 Section 4.10.2.1 and Section 4.10.2.2 define the generic encryption 1175 and decryption algorithms. Section 4.10.3 and Section 4.10.5 define 1176 instances of AES_CBC_HMAC_SHA2 that specify those details. 1178 4.10.2.1. AES_CBC_HMAC_SHA2 Encryption 1180 The authenticated encryption algorithm takes as input four octet 1181 strings: a secret key K, a plaintext P, associated data A, and an 1182 initialization vector IV. The authenticated ciphertext value E and 1183 the authentication tag value T are provided as outputs. The data in 1184 the plaintext are encrypted and authenticated, and the associated 1185 data are authenticated, but not encrypted. 1187 The encryption process is as follows, or uses an equivalent set of 1188 steps: 1190 1. The secondary keys MAC_KEY and ENC_KEY are generated from the 1191 input key K as follows. Each of these two keys is an octet 1192 string. 1194 MAC_KEY consists of the initial MAC_KEY_LEN octets of K, in 1195 order. 1197 ENC_KEY consists of the final ENC_KEY_LEN octets of K, in 1198 order. 1200 Here we denote the number of octets in the MAC_KEY as 1201 MAC_KEY_LEN, and the number of octets in ENC_KEY as ENC_KEY_LEN; 1202 the values of these parameters are specified by the AEAD 1203 algorithms (in Section 4.10.3 and Section 4.10.5). The number of 1204 octets in the input key K is the sum of MAC_KEY_LEN and 1205 ENC_KEY_LEN. When generating the secondary keys from K, MAC_KEY 1206 and ENC_KEY MUST NOT overlap. Note that the MAC key comes before 1207 the encryption key in the input key K; this is in the opposite 1208 order of the algorithm names in the identifier 1209 "AES_CBC_HMAC_SHA2". 1211 2. The Initialization Vector (IV) used is a 128 bit value generated 1212 randomly or pseudorandomly for use in the cipher. 1214 3. The plaintext is CBC encrypted using PKCS #5 padding using 1215 ENC_KEY as the key, and the IV. We denote the ciphertext output 1216 from this step as E. 1218 4. The octet string AL is equal to the number of bits in A expressed 1219 as a 64-bit unsigned integer in network byte order. 1221 5. A message authentication tag T is computed by applying HMAC 1222 [RFC2104] to the following data, in order: 1224 the associated data A, 1226 the initialization vector IV, 1228 the ciphertext E computed in the previous step, and 1230 the octet string AL defined above. 1232 The string MAC_KEY is used as the MAC key. We denote the output 1233 of the MAC computed in this step as M. The first T_LEN bits of M 1234 are used as T. 1236 6. The Ciphertext E and the Authentication Tag T are returned as the 1237 outputs of the authenticated encryption. 1239 The encryption process can be illustrated as follows. Here K, P, A, 1240 IV, and E denote the key, plaintext, associated data, initialization 1241 vector, and ciphertext, respectively. 1243 MAC_KEY = initial MAC_KEY_LEN bytes of K, 1245 ENC_KEY = final ENC_KEY_LEN bytes of K, 1247 E = CBC-PKCS5-ENC(ENC_KEY, P), 1249 M = MAC(MAC_KEY, A || IV || E || AL), 1251 T = initial T_LEN bytes of M. 1253 4.10.2.2. AES_CBC_HMAC_SHA2 Decryption 1255 The authenticated decryption operation has four inputs: K, A, E, and 1256 T as defined above. It has only a single output, either a plaintext 1257 value P or a special symbol FAIL that indicates that the inputs are 1258 not authentic. The authenticated decryption algorithm is as follows, 1259 or uses an equivalent set of steps: 1261 1. The secondary keys MAC_KEY and ENC_KEY are generated from the 1262 input key K as in Step 1 of Section 4.10.2.1. 1264 2. The integrity and authenticity of A and E are checked by 1265 computing an HMAC with the inputs as in Step 5 of 1266 Section 4.10.2.1. The value T, from the previous step, is 1267 compared to the first MAC_KEY length bits of the HMAC output. If 1268 those values are identical, then A and E are considered valid, 1269 and processing is continued. Otherwise, all of the data used in 1270 the MAC validation are discarded, and the AEAD decryption 1271 operation returns an indication that it failed, and the operation 1272 halts. (But see Section 10 of [JWE] for security considerations 1273 on thwarting timing attacks.) 1275 3. The value E is decrypted and the PKCS #5 padding is removed. The 1276 value IV is used as the initialization vector. The value ENC_KEY 1277 is used as the decryption key. 1279 4. The plaintext value is returned. 1281 4.10.3. AES_128_CBC_HMAC_SHA_256 1283 This algorithm is a concrete instantiation of the generic 1284 AES_CBC_HMAC_SHA2 algorithm above. It uses the HMAC message 1285 authentication code [RFC2104] with the SHA-256 hash function [SHS] to 1286 provide message authentication, with the HMAC output truncated to 128 1287 bits, corresponding to the HMAC-SHA-256-128 algorithm defined in 1288 [RFC4868]. For encryption, it uses AES in the Cipher Block Chaining 1289 (CBC) mode of operation as defined in Section 6.2 of [NIST.800-38A], 1290 with PKCS #5 padding. 1292 The input key K is 32 octets long. 1294 The AES CBC IV is 16 octets long. ENC_KEY_LEN is 16 octets. 1296 The SHA-256 hash algorithm is used in HMAC. MAC_KEY_LEN is 16 1297 octets. The HMAC-SHA-256 output is truncated to T_LEN=16 octets, by 1298 stripping off the final 16 octets. 1300 4.10.4. AES_192_CBC_HMAC_SHA_384 1302 AES_192_CBC_HMAC_SHA_384 is based on AES_128_CBC_HMAC_SHA_256, but 1303 with the following differences: 1305 A 192 bit AES CBC key is used instead of 128. 1307 SHA-384 is used in HMAC instead of SHA-256. 1309 ENC_KEY_LEN is 24 octets instead of 16. 1311 MAC_KEY_LEN is 24 octets instead of 16. 1313 The length of the input key K is 48 octets instead of 32. 1315 The HMAC SHA-384 value is truncated to T_LEN=24 octets instead of 1316 16. 1318 4.10.5. AES_256_CBC_HMAC_SHA_512 1320 AES_256_CBC_HMAC_SHA_512 is based on AES_128_CBC_HMAC_SHA_256, but 1321 with the following differences: 1323 A 256 bit AES CBC key is used instead of 128. 1325 SHA-512 is used in HMAC instead of SHA-256. 1327 ENC_KEY_LEN is 32 octets instead of 16. 1329 MAC_KEY_LEN is 32 octets instead of 16. 1331 The length of the input key K is 64 octets instead of 32. 1333 The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of 1334 16. 1336 4.10.6. Plaintext Encryption with AES_CBC_HMAC_SHA2 1338 The algorithm value "A128CBC-HS256" is used as the "alg" value when 1339 using AES_128_CBC_HMAC_SHA_256 with JWE. The algorithm value 1340 "A192CBC-HS384" is used as the "alg" value when using 1341 AES_192_CBC_HMAC_SHA_384 with JWE. The algorithm value 1342 "A256CBC-HS512" is used as the "alg" value when using 1343 AES_256_CBC_HMAC_SHA_512 with JWE. The Additional Authenticated Data 1344 value used is the octets of the ASCII representation of the Encoded 1345 JWE Header value. The JWE Initialization Vector value used is the IV 1346 value. 1348 4.11. Plaintext Encryption with AES GCM 1350 This section defines the specifics of encrypting the JWE Plaintext 1351 with Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) 1352 [AES] [NIST.800-38D] using 128, 192, or 256 bit keys. The "enc" 1353 header parameter values "A128GCM", "A192GCM", or "A256GCM" are 1354 respectively used in this case. 1356 The CEK is used as the encryption key. 1358 Use of an initialization vector of size 96 bits is REQUIRED with this 1359 algorithm. 1361 The Additional Authenticated Data value used is the octets of the 1362 ASCII representation of the Encoded JWE Header value. 1364 The requested size of the Authentication Tag output MUST be 128 bits, 1365 regardless of the key size. 1367 The JWE Authentication Tag is set to be the Authentication Tag value 1368 produced by the encryption. During decryption, the received JWE 1369 Authentication Tag is used as the Authentication Tag value. 1371 An example using this algorithm is shown in Appendix A.1 of [JWE]. 1373 5. Cryptographic Algorithms for JWK 1375 A JSON Web Key (JWK) [JWK] is a JSON data structure that represents a 1376 cryptographic key. These keys can be either asymmetric or symmetric. 1377 They can hold both public and private information about the key. 1378 This section defines the parameters for keys using the algorithms 1379 specified by this document. 1381 5.1. "kty" (Key Type) Parameter Values 1383 The table below is the set of "kty" (key type) parameter values that 1384 are defined by this specification for use in JWKs. 1386 +--------------+--------------------------------+-------------------+ 1387 | kty | Key Type | Implementation | 1388 | Parameter | | Requirements | 1389 | Value | | | 1390 +--------------+--------------------------------+-------------------+ 1391 | EC | Elliptic Curve [DSS] | Recommended+ | 1392 | RSA | RSA [RFC3447] | Required | 1393 | oct | Octet sequence (used to | Required | 1394 | | represent symmetric keys) | | 1395 +--------------+--------------------------------+-------------------+ 1397 The use of "+" in the Implementation Requirements indicates that the 1398 requirement strength is likely to be increased in a future version of 1399 the specification. 1401 5.2. JWK Parameters for Elliptic Curve Keys 1403 JWKs can represent Elliptic Curve [DSS] keys. In this case, the 1404 "kty" member value MUST be "EC". 1406 5.2.1. JWK Parameters for Elliptic Curve Public Keys 1408 The following members MUST be present for Elliptic Curve public keys. 1410 5.2.1.1. "crv" (Curve) Parameter 1412 The "crv" (curve) member identifies the cryptographic curve used with 1413 the key. Curve values from [DSS] used by this specification are: 1415 o "P-256" 1417 o "P-384" 1419 o "P-521" 1421 Additional "crv" values MAY be used, provided they are understood by 1422 implementations using that Elliptic Curve key. The "crv" value is a 1423 case sensitive string. 1425 5.2.1.2. "x" (X Coordinate) Parameter 1427 The "x" (x coordinate) member contains the x coordinate for the 1428 elliptic curve point. It is represented as the base64url encoding of 1429 the coordinate's big endian representation as an octet sequence. The 1430 array representation MUST NOT be shortened to omit any leading zero 1431 octets contained in the value. For instance, when representing 521 1432 bit integers, the octet sequence to be base64url encoded MUST contain 1433 66 octets, including any leading zero octets. 1435 5.2.1.3. "y" (Y Coordinate) Parameter 1437 The "y" (y coordinate) member contains the y coordinate for the 1438 elliptic curve point. It is represented as the base64url encoding of 1439 the coordinate's big endian representation as an octet sequence. The 1440 array representation MUST NOT be shortened to omit any leading zero 1441 octets contained in the value. For instance, when representing 521 1442 bit integers, the octet sequence to be base64url encoded MUST contain 1443 66 octets, including any leading zero octets. 1445 5.2.2. JWK Parameters for Elliptic Curve Private Keys 1447 In addition to the members used to represent Elliptic Curve public 1448 keys, the following member MUST be present to represent Elliptic 1449 Curve private keys. 1451 5.2.2.1. "d" (ECC Private Key) Parameter 1453 The "d" (ECC private key) member contains the Elliptic Curve private 1454 key value. It is represented as the base64url encoding of the 1455 value's unsigned big endian representation as an octet sequence. The 1456 array representation MUST NOT be shortened to omit any leading zero 1457 octets. For instance, when representing 521 bit integers, the octet 1458 sequence to be base64url encoded MUST contain 66 octets, including 1459 any leading zero octets. 1461 5.3. JWK Parameters for RSA Keys 1463 JWKs can represent RSA [RFC3447] keys. In this case, the "kty" 1464 member value MUST be "RSA". 1466 5.3.1. JWK Parameters for RSA Public Keys 1468 The following members MUST be present for RSA public keys. 1470 5.3.1.1. "n" (Modulus) Parameter 1472 The "n" (modulus) member contains the modulus value for the RSA 1473 public key. It is represented as the base64url encoding of the 1474 value's unsigned big endian representation as an octet sequence. The 1475 array representation MUST NOT be shortened to omit any leading zero 1476 octets. For instance, when representing 2048 bit integers, the octet 1477 sequence to be base64url encoded MUST contain 256 octets, including 1478 any leading zero octets. 1480 5.3.1.2. "e" (Exponent) Parameter 1482 The "e" (exponent) member contains the exponent value for the RSA 1483 public key. It is represented as the base64url encoding of the 1484 value's unsigned big endian representation as an octet sequence. The 1485 array representation MUST utilize the minimum number of octets to 1486 represent the value. For instance, when representing the value 1487 65537, the octet sequence to be base64url encoded MUST consist of the 1488 three octets [1, 0, 1]. 1490 5.3.2. JWK Parameters for RSA Private Keys 1492 In addition to the members used to represent RSA public keys, the 1493 following members are used to represent RSA private keys. The 1494 parameter "d" is REQUIRED for RSA private keys. The others enable 1495 optimizations and are RECOMMENDED. If any of the others are present 1496 then all MUST be present, with the exception of "oth", which MUST 1497 only be present when more than two prime factors were used. 1499 5.3.2.1. "d" (Private Exponent) Parameter 1501 The "d" (private exponent) member contains the private exponent value 1502 for the RSA private key. It is represented as the base64url encoding 1503 of the value's unsigned big endian representation as an octet 1504 sequence. The array representation MUST NOT be shortened to omit any 1505 leading zero octets. For instance, when representing 2048 bit 1506 integers, the octet sequence to be base64url encoded MUST contain 256 1507 octets, including any leading zero octets. 1509 5.3.2.2. "p" (First Prime Factor) Parameter 1511 The "p" (first prime factor) member contains the first prime factor, 1512 a positive integer. It is represented as the base64url encoding of 1513 the value's unsigned big endian representation as an octet sequence. 1515 5.3.2.3. "q" (Second Prime Factor) Parameter 1517 The "q" (second prime factor) member contains the second prime 1518 factor, a positive integer. It is represented as the base64url 1519 encoding of the value's unsigned big endian representation as an 1520 octet sequence. 1522 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter 1524 The "dp" (first factor CRT exponent) member contains the Chinese 1525 Remainder Theorem (CRT) exponent of the first factor, a positive 1526 integer. It is represented as the base64url encoding of the value's 1527 unsigned big endian representation as an octet sequence. 1529 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter 1531 The "dq" (second factor CRT exponent) member contains the Chinese 1532 Remainder Theorem (CRT) exponent of the second factor, a positive 1533 integer. It is represented as the base64url encoding of the value's 1534 unsigned big endian representation as an octet sequence. 1536 5.3.2.6. "qi" (First CRT Coefficient) Parameter 1538 The "dp" (first CRT coefficient) member contains the Chinese 1539 Remainder Theorem (CRT) coefficient of the second factor, a positive 1540 integer. It is represented as the base64url encoding of the value's 1541 unsigned big endian representation as an octet sequence. 1543 5.3.2.7. "oth" (Other Primes Info) Parameter 1545 The "oth" (other primes info) member contains an array of information 1546 about any third and subsequent primes, should they exist. When only 1547 two primes have been used (the normal case), this parameter MUST be 1548 omitted. When three or more primes have been used, the number of 1549 array elements MUST be the number of primes used minus two. Each 1550 array element MUST be an object with the following members: 1552 5.3.2.7.1. "r" (Prime Factor) 1554 The "r" (prime factor) parameter within an "oth" array member 1555 represents the value of a subsequent prime factor, a positive 1556 integer. It is represented as the base64url encoding of the value's 1557 unsigned big endian representation as an octet sequence. 1559 5.3.2.7.2. "d" (Factor CRT Exponent) 1561 The "d" (Factor CRT Exponent) parameter within an "oth" array member 1562 represents the CRT exponent of the corresponding prime factor, a 1563 positive integer. It is represented as the base64url encoding of the 1564 value's unsigned big endian representation as an octet sequence. 1566 5.3.2.7.3. "t" (Factor CRT Coefficient) 1568 The "t" (factor CRT coefficient) parameter within an "oth" array 1569 member represents the CRT coefficient of the corresponding prime 1570 factor, a positive integer. It is represented as the base64url 1571 encoding of the value's unsigned big endian representation as an 1572 octet sequence. 1574 5.4. JWK Parameters for Symmetric Keys 1576 When the JWK "kty" member value is "oct" (octet sequence), the 1577 following member is used to represent a symmetric key (or another key 1578 whose value is a single octet sequence): 1580 5.4.1. "k" (Key Value) Parameter 1582 The "k" (key value) member contains the value of the symmetric (or 1583 other single-valued) key. It is represented as the base64url 1584 encoding of the octet sequence containing the key value. 1586 6. IANA Considerations 1588 The following registration procedure is used for all the registries 1589 established by this specification. 1591 Values are registered with a Specification Required [RFC5226] after a 1592 two-week review period on the [TBD]@ietf.org mailing list, on the 1593 advice of one or more Designated Experts. However, to allow for the 1594 allocation of values prior to publication, the Designated Expert(s) 1595 may approve registration once they are satisfied that such a 1596 specification will be published. 1598 Registration requests must be sent to the [TBD]@ietf.org mailing list 1599 for review and comment, with an appropriate subject (e.g., "Request 1600 for access token type: example"). [[ Note to RFC-EDITOR: The name of 1601 the mailing list should be determined in consultation with the IESG 1602 and IANA. Suggested name: jose-reg-review. ]] 1604 Within the review period, the Designated Expert(s) will either 1605 approve or deny the registration request, communicating this decision 1606 to the review list and IANA. Denials should include an explanation 1607 and, if applicable, suggestions as to how to make the request 1608 successful. 1610 IANA must only accept registry updates from the Designated Expert(s) 1611 and should direct all requests for registration to the review mailing 1612 list. 1614 6.1. JSON Web Signature and Encryption Algorithms Registry 1616 This specification establishes the IANA JSON Web Signature and 1617 Encryption Algorithms registry for values of the JWS and JWE "alg" 1618 (algorithm) and "enc" (encryption method) header parameters. The 1619 registry records the algorithm name, the algorithm usage locations 1620 from the set "alg" and "enc", implementation requirements, and a 1621 reference to the specification that defines it. The same algorithm 1622 name MAY be registered multiple times, provided that the sets of 1623 usage locations are disjoint. 1625 The implementation requirements of an algorithm MAY be changed over 1626 time by the Designated Experts(s) as the cryptographic landscape 1627 evolves, for instance, to change the status of an algorithm to 1628 Deprecated, or to change the status of an algorithm from Optional to 1629 Recommended+ or Required. Changes of implementation requirements are 1630 only permitted on a Specification Required basis, with the new 1631 specification defining the revised implementation requirements level. 1633 6.1.1. Template 1634 Algorithm Name: 1635 The name requested (e.g., "example"). This name is case 1636 sensitive. Names that match other registered names in a case 1637 insensitive manner SHOULD NOT be accepted. 1639 Algorithm Usage Location(s): 1640 The algorithm usage, which must be one or more of the values "alg" 1641 or "enc". 1643 Implementation Requirements: 1644 The algorithm implementation requirements, which must be one the 1645 words Required, Recommended, Optional, or Deprecated. Optionally, 1646 the word can be followed by a "+" or "-". The use of "+" 1647 indicates that the requirement strength is likely to be increased 1648 in a future version of the specification. The use of "-" 1649 indicates that the requirement strength is likely to be decreased 1650 in a future version of the specification. 1652 Change Controller: 1653 For Standards Track RFCs, state "IETF". For others, give the name 1654 of the responsible party. Other details (e.g., postal address, 1655 email address, home page URI) may also be included. 1657 Specification Document(s): 1658 Reference to the document(s) that specify the parameter, 1659 preferably including URI(s) that can be used to retrieve copies of 1660 the document(s). An indication of the relevant sections may also 1661 be included but is not required. 1663 6.1.2. Initial Registry Contents 1665 o Algorithm Name: "HS256" 1666 o Algorithm Usage Location(s): "alg" 1667 o Implementation Requirements: Required 1668 o Change Controller: IETF 1669 o Specification Document(s): Section 3.1 of [[ this document ]] 1671 o Algorithm Name: "HS384" 1672 o Algorithm Usage Location(s): "alg" 1673 o Implementation Requirements: Optional 1674 o Change Controller: IETF 1675 o Specification Document(s): Section 3.1 of [[ this document ]] 1677 o Algorithm Name: "HS512" 1678 o Algorithm Usage Location(s): "alg" 1679 o Implementation Requirements: Optional 1680 o Change Controller: IETF 1681 o Specification Document(s): Section 3.1 of [[ this document ]] 1683 o Algorithm Name: "RS256" 1684 o Algorithm Usage Location(s): "alg" 1685 o Implementation Requirements: Recommended 1686 o Change Controller: IETF 1687 o Specification Document(s): Section 3.1 of [[ this document ]] 1689 o Algorithm Name: "RS384" 1690 o Algorithm Usage Location(s): "alg" 1691 o Implementation Requirements: Optional 1692 o Change Controller: IETF 1693 o Specification Document(s): Section 3.1 of [[ this document ]] 1695 o Algorithm Name: "RS512" 1696 o Algorithm Usage Location(s): "alg" 1697 o Implementation Requirements: Optional 1698 o Change Controller: IETF 1699 o Specification Document(s): Section 3.1 of [[ this document ]] 1701 o Algorithm Name: "ES256" 1702 o Algorithm Usage Location(s): "alg" 1703 o Implementation Requirements: Recommended+ 1704 o Change Controller: IETF 1705 o Specification Document(s): Section 3.1 of [[ this document ]] 1707 o Algorithm Name: "ES384" 1708 o Algorithm Usage Location(s): "alg" 1709 o Implementation Requirements: Optional 1710 o Change Controller: IETF 1711 o Specification Document(s): Section 3.1 of [[ this document ]] 1713 o Algorithm Name: "ES512" 1714 o Algorithm Usage Location(s): "alg" 1715 o Implementation Requirements: Optional 1716 o Change Controller: IETF 1717 o Specification Document(s): Section 3.1 of [[ this document ]] 1719 o Algorithm Name: "PS256" 1720 o Algorithm Usage Location(s): "alg" 1721 o Implementation Requirements: Optional 1722 o Change Controller: IETF 1723 o Specification Document(s): Section 3.1 of [[ this document ]] 1725 o Algorithm Name: "PS384" 1726 o Algorithm Usage Location(s): "alg" 1727 o Implementation Requirements: Optional 1728 o Change Controller: IETF 1729 o Specification Document(s): Section 3.1 of [[ this document ]] 1731 o Algorithm Name: "PS512" 1732 o Algorithm Usage Location(s): "alg" 1733 o Implementation Requirements: Optional 1734 o Change Controller: IETF 1735 o Specification Document(s): Section 3.1 of [[ this document ]] 1737 o Algorithm Name: "none" 1738 o Algorithm Usage Location(s): "alg" 1739 o Implementation Requirements: Required 1740 o Change Controller: IETF 1741 o Specification Document(s): Section 3.1 of [[ this document ]] 1743 o Algorithm Name: "RSA1_5" 1744 o Algorithm Usage Location(s): "alg" 1745 o Implementation Requirements: Required 1746 o Change Controller: IETF 1747 o Specification Document(s): Section 4.1 of [[ this document ]] 1749 o Algorithm Name: "RSA-OAEP" 1750 o Algorithm Usage Location(s): "alg" 1751 o Implementation Requirements: Optional 1752 o Change Controller: IETF 1753 o Specification Document(s): Section 4.1 of [[ this document ]] 1755 o Algorithm Name: "A128KW" 1756 o Algorithm Usage Location(s): "alg" 1757 o Implementation Requirements: Recommended 1758 o Change Controller: IETF 1759 o Specification Document(s): Section 4.1 of [[ this document ]] 1761 o Algorithm Name: "A192KW" 1762 o Algorithm Usage Location(s): "alg" 1763 o Implementation Requirements: Optional 1764 o Change Controller: IETF 1765 o Specification Document(s): Section 4.1 of [[ this document ]] 1767 o Algorithm Name: "A256KW" 1768 o Algorithm Usage Location(s): "alg" 1769 o Implementation Requirements: Recommended 1770 o Change Controller: IETF 1771 o Specification Document(s): Section 4.1 of [[ this document ]] 1772 o Algorithm Name: "dir" 1773 o Algorithm Usage Location(s): "alg" 1774 o Implementation Requirements: Recommended 1775 o Change Controller: IETF 1776 o Specification Document(s): Section 4.1 of [[ this document ]] 1778 o Algorithm Name: "ECDH-ES" 1779 o Algorithm Usage Location(s): "alg" 1780 o Implementation Requirements: Recommended+ 1781 o Change Controller: IETF 1782 o Specification Document(s): Section 4.1 of [[ this document ]] 1784 o Algorithm Name: "ECDH-ES+A128KW" 1785 o Algorithm Usage Location(s): "alg" 1786 o Implementation Requirements: Recommended 1787 o Change Controller: IETF 1788 o Specification Document(s): Section 4.1 of [[ this document ]] 1790 o Algorithm Name: "ECDH-ES+A192KW" 1791 o Algorithm Usage Location(s): "alg" 1792 o Implementation Requirements: Optional 1793 o Change Controller: IETF 1794 o Specification Document(s): Section 4.1 of [[ this document ]] 1796 o Algorithm Name: "ECDH-ES+A256KW" 1797 o Algorithm Usage Location(s): "alg" 1798 o Implementation Requirements: Recommended 1799 o Change Controller: IETF 1800 o Specification Document(s): Section 4.1 of [[ this document ]] 1802 o Algorithm Name: "A128GCMKW" 1803 o Algorithm Usage Location(s): "alg" 1804 o Implementation Requirements: Optional 1805 o Change Controller: IETF 1806 o Specification Document(s): Section 4.8 of [[ this document ]] 1808 o Algorithm Name: "A192GCMKW" 1809 o Algorithm Usage Location(s): "alg" 1810 o Implementation Requirements: Optional 1811 o Change Controller: IETF 1812 o Specification Document(s): Section 4.8 of [[ this document ]] 1814 o Algorithm Name: "A256GCMKW" 1815 o Algorithm Usage Location(s): "alg" 1816 o Implementation Requirements: Optional 1817 o Change Controller: IETF 1818 o Specification Document(s): Section 4.8 of [[ this document ]] 1820 o Algorithm Name: "PBES2-HS256+A128KW" 1821 o Algorithm Usage Location(s): "alg" 1822 o Implementation Requirements: Optional 1823 o Change Controller: IETF 1824 o Specification Document(s): Section 4.9 of [[ this document ]] 1826 o Algorithm Name: "PBES2-HS384+A192KW" 1827 o Algorithm Usage Location(s): "alg" 1828 o Implementation Requirements: Optional 1829 o Change Controller: IETF 1830 o Specification Document(s): Section 4.9 of [[ this document ]] 1832 o Algorithm Name: "PBES2-HS512+A256KW" 1833 o Algorithm Usage Location(s): "alg" 1834 o Implementation Requirements: Optional 1835 o Change Controller: IETF 1836 o Specification Document(s): Section 4.9 of [[ this document ]] 1838 o Algorithm Name: "A128CBC-HS256" 1839 o Algorithm Usage Location(s): "enc" 1840 o Implementation Requirements: Required 1841 o Change Controller: IETF 1842 o Specification Document(s): Section 4.2 of [[ this document ]] 1844 o Algorithm Name: "A192CBC-HS384" 1845 o Algorithm Usage Location(s): "enc" 1846 o Implementation Requirements: Optional 1847 o Change Controller: IETF 1848 o Specification Document(s): Section 4.2 of [[ this document ]] 1850 o Algorithm Name: "A256CBC-HS512" 1851 o Algorithm Usage Location(s): "enc" 1852 o Implementation Requirements: Required 1853 o Change Controller: IETF 1854 o Specification Document(s): Section 4.2 of [[ this document ]] 1856 o Algorithm Name: "A128GCM" 1857 o Algorithm Usage Location(s): "enc" 1858 o Implementation Requirements: Recommended 1859 o Change Controller: IETF 1860 o Specification Document(s): Section 4.2 of [[ this document ]] 1862 o Algorithm Name: "A192GCM" 1863 o Algorithm Usage Location(s): "enc" 1864 o Implementation Requirements: Optional 1865 o Change Controller: IETF 1866 o Specification Document(s): Section 4.2 of [[ this document ]] 1868 o Algorithm Name: "A256GCM" 1869 o Algorithm Usage Location(s): "enc" 1870 o Implementation Requirements: Recommended 1871 o Change Controller: IETF 1872 o Specification Document(s): Section 4.2 of [[ this document ]] 1874 6.2. JSON Web Key Types Registry 1876 This specification establishes the IANA JSON Web Key Types registry 1877 for values of the JWK "kty" (key type) parameter. The registry 1878 records the "kty" value, implementation requirements, and a reference 1879 to the specification that defines it. 1881 The implementation requirements of a key type MAY be changed over 1882 time by the Designated Experts(s) as the cryptographic landscape 1883 evolves, for instance, to change the status of a key type to 1884 Deprecated, or to change the status of a key type from Optional to 1885 Recommended+ or Required. Changes of implementation requirements are 1886 only permitted on a Specification Required basis, with the new 1887 specification defining the revised implementation requirements level. 1889 6.2.1. Registration Template 1891 "kty" Parameter Value: 1892 The name requested (e.g., "example"). This name is case 1893 sensitive. Names that match other registered names in a case 1894 insensitive manner SHOULD NOT be accepted. 1896 Change Controller: 1897 For Standards Track RFCs, state "IETF". For others, give the name 1898 of the responsible party. Other details (e.g., postal address, 1899 email address, home page URI) may also be included. 1901 Implementation Requirements: 1902 The key type implementation requirements, which must be one the 1903 words Required, Recommended, Optional, or Deprecated. Optionally, 1904 the word can be followed by a "+" or "-". The use of "+" 1905 indicates that the requirement strength is likely to be increased 1906 in a future version of the specification. The use of "-" 1907 indicates that the requirement strength is likely to be decreased 1908 in a future version of the specification. 1910 Specification Document(s): 1911 Reference to the document(s) that specify the parameter, 1912 preferably including URI(s) that can be used to retrieve copies of 1913 the document(s). An indication of the relevant sections may also 1914 be included but is not required. 1916 6.2.2. Initial Registry Contents 1918 This specification registers the values defined in Section 5.1. 1920 o "kty" Parameter Value: "EC" 1921 o Implementation Requirements: Recommended+ 1922 o Change Controller: IETF 1923 o Specification Document(s): Section 5.2 of [[ this document ]] 1925 o "kty" Parameter Value: "RSA" 1926 o Implementation Requirements: Required 1927 o Change Controller: IETF 1928 o Specification Document(s): Section 5.3 of [[ this document ]] 1930 o "kty" Parameter Value: "oct" 1931 o Implementation Requirements: Required 1932 o Change Controller: IETF 1933 o Specification Document(s): Section 5.4 of [[ this document ]] 1935 6.3. JSON Web Key Parameters Registration 1937 This specification registers the parameter names defined in Sections 1938 5.2, 5.3, and 5.4 in the IANA JSON Web Key Parameters registry [JWK]. 1940 6.3.1. Registry Contents 1942 o Parameter Name: "crv" 1943 o Parameter Information Class: Public 1944 o Change Controller: IETF 1945 o Specification Document(s): Section 5.2.1.1 of [[ this document ]] 1947 o Parameter Name: "x" 1948 o Parameter Information Class: Public 1949 o Change Controller: IETF 1950 o Specification Document(s): Section 5.2.1.2 of [[ this document ]] 1952 o Parameter Name: "y" 1953 o Parameter Information Class: Public 1954 o Change Controller: IETF 1955 o Specification Document(s): Section 5.2.1.3 of [[ this document ]] 1956 o Parameter Name: "d" 1957 o Parameter Information Class: Private 1958 o Change Controller: IETF 1959 o Specification Document(s): Section 5.2.2.1 of [[ this document ]] 1961 o Parameter Name: "n" 1962 o Parameter Information Class: Public 1963 o Change Controller: IETF 1964 o Specification Document(s): Section 5.3.1.1 of [[ this document ]] 1966 o Parameter Name: "e" 1967 o Parameter Information Class: Public 1968 o Change Controller: IETF 1969 o Specification Document(s): Section 5.3.1.2 of [[ this document ]] 1971 o Parameter Name: "d" 1972 o Parameter Information Class: Private 1973 o Change Controller: IETF 1974 o Specification Document(s): Section 5.3.2.1 of [[ this document ]] 1976 o Parameter Name: "p" 1977 o Parameter Information Class: Private 1978 o Change Controller: IETF 1979 o Specification Document(s): Section 5.3.2.2 of [[ this document ]] 1981 o Parameter Name: "q" 1982 o Parameter Information Class: Private 1983 o Change Controller: IETF 1984 o Specification Document(s): Section 5.3.2.3 of [[ this document ]] 1986 o Parameter Name: "dp" 1987 o Parameter Information Class: Private 1988 o Change Controller: IETF 1989 o Specification Document(s): Section 5.3.2.4 of [[ this document ]] 1991 o Parameter Name: "dq" 1992 o Parameter Information Class: Private 1993 o Change Controller: IETF 1994 o Specification Document(s): Section 5.3.2.5 of [[ this document ]] 1996 o Parameter Name: "qi" 1997 o Parameter Information Class: Private 1998 o Change Controller: IETF 1999 o Specification Document(s): Section 5.3.2.6 of [[ this document ]] 2001 o Parameter Name: "oth" 2002 o Parameter Information Class: Private 2003 o Change Controller: IETF 2004 o Specification Document(s): Section 5.3.2.7 of [[ this document ]] 2006 o Parameter Name: "k" 2007 o Parameter Information Class: Private 2008 o Change Controller: IETF 2009 o Specification Document(s): Section 5.4.1 of [[ this document ]] 2011 6.4. Registration of JWE Header Parameter Names 2013 This specification registers the Header Parameter Names defined in 2014 Section 4.7.1, Section 4.8.1, and Section 4.9.1 in the IANA JSON Web 2015 Signature and Encryption Header Parameters registry [JWS]. 2017 6.4.1. Registry Contents 2019 o Header Parameter Name: "epk" 2020 o Header Parameter Usage Location(s): JWE 2021 o Change Controller: IETF 2022 o Specification Document(s): Section 4.7.1.1 of [[ this document ]] 2024 o Header Parameter Name: "apu" 2025 o Header Parameter Usage Location(s): JWE 2026 o Change Controller: IETF 2027 o Specification Document(s): Section 4.7.1.2 of [[ this document ]] 2029 o Header Parameter Name: "apv" 2030 o Header Parameter Usage Location(s): JWE 2031 o Change Controller: IETF 2032 o Specification Document(s): Section 4.7.1.3 of [[ this document ]] 2034 o Header Parameter Name: "iv" 2035 o Header Parameter Usage Location(s): JWE 2036 o Change Controller: IETF 2037 o Specification Document(s): Section 4.8.1.1 of [[ this document ]] 2039 o Header Parameter Name: "tag" 2040 o Header Parameter Usage Location(s): JWE 2041 o Change Controller: IETF 2042 o Specification Document(s): Section 4.8.1.2 of [[ this document ]] 2044 o Header Parameter Name: "p2s" 2045 o Header Parameter Usage Location(s): JWE 2046 o Change Controller: IETF 2047 o Specification Document(s): Section 4.9.1.1 of [[ this document ]] 2048 o Header Parameter Name: "p2c" 2049 o Header Parameter Usage Location(s): JWE 2050 o Change Controller: IETF 2051 o Specification Document(s): Section 4.9.1.2 of [[ this document ]] 2053 7. Security Considerations 2055 All of the security issues faced by any cryptographic application 2056 must be faced by a JWS/JWE/JWK agent. Among these issues are 2057 protecting the user's private and symmetric keys, preventing various 2058 attacks, and helping the user avoid mistakes such as inadvertently 2059 encrypting a message for the wrong recipient. The entire list of 2060 security considerations is beyond the scope of this document, but 2061 some significant considerations are listed here. 2063 The security considerations in [AES], [DSS], [JWE], [JWK], [JWS], 2064 [NIST.800-38A], [NIST.800-38D], [NIST.800-56A], [RFC2104], [RFC3394], 2065 [RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this 2066 specification. 2068 Eventually the algorithms and/or key sizes currently described in 2069 this specification will no longer be considered sufficiently secure 2070 and will be removed. Therefore, implementers and deployments must be 2071 prepared for this eventuality. 2073 Many algorithms have associated security considerations related to 2074 key lifetimes and/or the number of times that a key may be used. 2075 Those security considerations continue to apply when using those 2076 algorithms with JOSE data structures. 2078 Algorithms of matching strengths should be used together whenever 2079 possible. For instance, when AES Key Wrap is used with a given key 2080 size, using the same key size is recommended when AES GCM is also 2081 used. 2083 While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not 2084 to adopt RSASSA-PKCS-v1_5 for new applications and instead requests 2085 that people transition to RSASSA-PSS, this specification does include 2086 RSASSA-PKCS-v1_5, for interoperability reasons, because it commonly 2087 implemented. 2089 Keys used with RSAES-PKCS1-v1_5 must follow the constraints in 2090 Section 7.2 of RFC 3447 [RFC3447]. In particular, keys with a low 2091 public key exponent value must not be used. 2093 Keys used with AES GCM must follow the constraints in Section 8.3 of 2094 [NIST.800-38D], which states: "The total number of invocations of the 2095 authenticated encryption function shall not exceed 2^32, including 2096 all IV lengths and all instances of the authenticated encryption 2097 function with the given key". In accordance with this rule, AES GCM 2098 MUST NOT be used with the same key encryption key or with the same 2099 direct encryption key more than 2^32 times. 2101 Plaintext JWSs (JWSs that use the "alg" value "none") provide no 2102 integrity protection. Thus, they must only be used in contexts where 2103 the payload is secured by means other than a digital signature or MAC 2104 value, or need not be secured. 2106 Receiving agents that validate signatures and sending agents that 2107 encrypt messages need to be cautious of cryptographic processing 2108 usage when validating signatures and encrypting messages using keys 2109 larger than those mandated in this specification. An attacker could 2110 send certificates with keys that would result in excessive 2111 cryptographic processing, for example, keys larger than those 2112 mandated in this specification, which could swamp the processing 2113 element. Agents that use such keys without first validating the 2114 certificate to a trust anchor are advised to have some sort of 2115 cryptographic resource management system to prevent such attacks. 2117 7.1. Reusing Key Material when Encrypting Keys 2119 It is NOT RECOMMENDED to reuse the same key material (Key Encryption 2120 Key, Content Encryption Key, Initialization Vector, etc.) to encrypt 2121 multiple JWK or JWK Set objects, or to encrypt the same JWK or JWK 2122 Set object multiple times. One suggestion for preventing re-use is 2123 to always generate a new set key material for each encryption 2124 operation, based on the considerations noted in this document as well 2125 as from [RFC4086]. 2127 7.2. Password Considerations 2129 While convenient for end users, passwords are vulnerable to a number 2130 of attacks. To help mitigate some of these limitations, this 2131 document applies principles from [RFC2898] to derive cryptographic 2132 keys from user-supplied passwords. 2134 However, the strength of the password still has a significant impact. 2135 A high-entry password has greater resistance to dictionary attacks. 2136 [NIST-800-63-1] contains guidelines for estimating password entropy, 2137 which can help applications and users generate stronger passwords. 2139 An ideal password is one that is as large (or larger) than the 2140 derived key length but less than the PRF's block size. Passwords 2141 larger than the PRF's block size are first hashed, which reduces an 2142 attacker's effective search space to the length of the hash algorithm 2143 (32 octets for HMAC SHA-256). It is RECOMMENDED that the password be 2144 no longer than 64 octets long for "PBES2-HS512+A256KW". 2146 Still, care needs to be taken in where and how password-based 2147 encryption is used. Such algorithms MUST NOT be used where the 2148 attacker can make an indefinite number of attempts to circumvent the 2149 protection. 2151 8. Internationalization Considerations 2153 Passwords obtained from users are likely to require preparation and 2154 normalization to account for differences of octet sequences generated 2155 by different input devices, locales, etc. It is RECOMMENDED that 2156 applications to perform the steps outlined in 2157 [I-D.melnikov-precis-saslprepbis] to prepare a password supplied 2158 directly by a user before performing key derivation and encryption. 2160 9. References 2162 9.1. Normative References 2164 [AES] National Institute of Standards and Technology (NIST), 2165 "Advanced Encryption Standard (AES)", FIPS PUB 197, 2166 November 2001. 2168 [DSS] National Institute of Standards and Technology, "Digital 2169 Signature Standard (DSS)", FIPS PUB 186-4, July 2013. 2171 [I-D.melnikov-precis-saslprepbis] 2172 Saint-Andre, P. and A. Melnikov, "Preparation and 2173 Comparison of Internationalized Strings Representing 2174 Simple User Names and Passwords", 2175 draft-melnikov-precis-saslprepbis-04 (work in progress), 2176 September 2012. 2178 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 2179 Encryption (JWE)", draft-ietf-jose-json-web-encryption 2180 (work in progress), September 2013. 2182 [JWK] Jones, M., "JSON Web Key (JWK)", 2183 draft-ietf-jose-json-web-key (work in progress), 2184 September 2013. 2186 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2187 Signature (JWS)", draft-ietf-jose-json-web-signature (work 2188 in progress), September 2013. 2190 [NIST.800-38A] 2191 National Institute of Standards and Technology (NIST), 2192 "Recommendation for Block Cipher Modes of Operation", 2193 NIST PUB 800-38A, December 2001. 2195 [NIST.800-38D] 2196 National Institute of Standards and Technology (NIST), 2197 "Recommendation for Block Cipher Modes of Operation: 2198 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 2199 December 2001. 2201 [NIST.800-56A] 2202 National Institute of Standards and Technology (NIST), 2203 "Recommendation for Pair-Wise Key Establishment Schemes 2204 Using Discrete Logarithm Cryptography", NIST Special 2205 Publication 800-56A, Revision 2, May 2013. 2207 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 2208 Hashing for Message Authentication", RFC 2104, 2209 February 1997. 2211 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2212 Requirement Levels", BCP 14, RFC 2119, March 1997. 2214 [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography 2215 Specification Version 2.0", RFC 2898, September 2000. 2217 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 2218 (AES) Key Wrap Algorithm", RFC 3394, September 2002. 2220 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2221 10646", STD 63, RFC 3629, November 2003. 2223 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 2224 Requirements for Security", BCP 106, RFC 4086, June 2005. 2226 [RFC4627] Crockford, D., "The application/json Media Type for 2227 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2229 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2230 Encodings", RFC 4648, October 2006. 2232 [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA- 2233 384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007. 2235 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 2236 Encryption", RFC 5116, January 2008. 2238 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2239 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2240 May 2008. 2242 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 2243 Curve Cryptography Algorithms", RFC 6090, February 2011. 2245 [SHS] National Institute of Standards and Technology, "Secure 2246 Hash Standard (SHS)", FIPS PUB 180-3, October 2008. 2248 [USASCII] American National Standards Institute, "Coded Character 2249 Set -- 7-bit American Standard Code for Information 2250 Interchange", ANSI X3.4, 1986. 2252 9.2. Informative References 2254 [CanvasApp] 2255 Facebook, "Canvas Applications", 2010. 2257 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 2258 McGrew, D., Foley, J., and K. Paterson, "Authenticated 2259 Encryption with AES-CBC and HMAC-SHA", 2260 draft-mcgrew-aead-aes-cbc-hmac-sha2-02 (work in progress), 2261 July 2013. 2263 [I-D.miller-jose-jwe-protected-jwk] 2264 Miller, M., "Using JavaScript Object Notation (JSON) Web 2265 Encryption (JWE) for Protecting JSON Web Key (JWK) 2266 Objects", draft-miller-jose-jwe-protected-jwk-02 (work in 2267 progress), June 2013. 2269 [I-D.rescorla-jsms] 2270 Rescorla, E. and J. Hildebrand, "JavaScript Message 2271 Security Format", draft-rescorla-jsms-00 (work in 2272 progress), March 2011. 2274 [JCA] Oracle, "Java Cryptography Architecture", 2011. 2276 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 2277 Encryption", September 2010. 2279 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 2280 September 2010. 2282 [MagicSignatures] 2283 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 2284 Signatures", January 2011. 2286 [NIST-800-63-1] 2287 National Institute of Standards and Technology (NIST), 2288 "Electronic Authentication Guideline", NIST 800-63-1, 2289 December 2011. 2291 [RFC2631] Rescorla, E., "Diffie-Hellman Key Agreement Method", 2292 RFC 2631, June 1999. 2294 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 2295 Language) XML-Signature Syntax and Processing", RFC 3275, 2296 March 2002. 2298 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 2299 Standards (PKCS) #1: RSA Cryptography Specifications 2300 Version 2.1", RFC 3447, February 2003. 2302 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2303 Unique IDentifier (UUID) URN Namespace", RFC 4122, 2304 July 2005. 2306 [W3C.CR-xmldsig-core2-20120124] 2307 Eastlake, D., Reagle, J., Yiu, K., Solo, D., Datta, P., 2308 Hirsch, F., Cantor, S., and T. Roessler, "XML Signature 2309 Syntax and Processing Version 2.0", World Wide Web 2310 Consortium CR CR-xmldsig-core2-20120124, January 2012, 2311 . 2313 [W3C.CR-xmlenc-core1-20120313] 2314 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 2315 "XML Encryption Syntax and Processing Version 1.1", World 2316 Wide Web Consortium CR CR-xmlenc-core1-20120313, 2317 March 2012, 2318 . 2320 [W3C.REC-xmlenc-core-20021210] 2321 Eastlake, D. and J. Reagle, "XML Encryption Syntax and 2322 Processing", World Wide Web Consortium Recommendation REC- 2323 xmlenc-core-20021210, December 2002, 2324 . 2326 Appendix A. Digital Signature/MAC Algorithm Identifier Cross-Reference 2328 This appendix contains a table cross-referencing the digital 2329 signature and MAC "alg" (algorithm) values used in this specification 2330 with the equivalent identifiers used by other standards and software 2331 packages. See XML DSIG [RFC3275], XML DSIG 2.0 2332 [W3C.CR-xmldsig-core2-20120124], and Java Cryptography Architecture 2334 [JCA] for more information about the names defined by those 2335 documents. 2337 +---------+----+---------------------------+----------+-------------+ 2338 | Algorit | JW | XML DSIG | JCA | OID | 2339 | hm | S | | | | 2340 +---------+----+---------------------------+----------+-------------+ 2341 | HMAC | HS | http://www.w3.org/2001/04 | HmacSHA2 | 1.2.840.113 | 2342 | using | 25 | /xmldsig-more#hmac-sha256 | 56 | 549.2.9 | 2343 | SHA-256 | 6 | | | | 2344 | hash | | | | | 2345 | algorit | | | | | 2346 | hm | | | | | 2347 | HMAC | HS | http://www.w3.org/2001/04 | HmacSHA3 | 1.2.840.113 | 2348 | using | 38 | /xmldsig-more#hmac-sha384 | 84 | 549.2.10 | 2349 | SHA-384 | 4 | | | | 2350 | hash | | | | | 2351 | algorit | | | | | 2352 | hm | | | | | 2353 | HMAC | HS | http://www.w3.org/2001/04 | HmacSHA5 | 1.2.840.113 | 2354 | using | 51 | /xmldsig-more#hmac-sha512 | 12 | 549.2.11 | 2355 | SHA-512 | 2 | | | | 2356 | hash | | | | | 2357 | algorit | | | | | 2358 | hm | | | | | 2359 | RSASSA- | RS | http://www.w3.org/2001/04 | SHA256wi | 1.2.840.113 | 2360 | PKCS-v1 | 25 | /xmldsig-more#rsa-sha256 | thRSA | 549.1.1.11 | 2361 | _5using | 6 | | | | 2362 | SHA-2 | | | | | 2363 | 56hash | | | | | 2364 | algor | | | | | 2365 | ithm | | | | | 2366 | RSASSA- | RS | http://www.w3.org/2001/04 | SHA384wi | 1.2.840.113 | 2367 | PKCS-v1 | 38 | /xmldsig-more#rsa-sha384 | thRSA | 549.1.1.12 | 2368 | _5using | 4 | | | | 2369 | SHA-3 | | | | | 2370 | 84hash | | | | | 2371 | algor | | | | | 2372 | ithm | | | | | 2373 | RSASSA- | RS | http://www.w3.org/2001/04 | SHA512wi | 1.2.840.113 | 2374 | PKCS-v1 | 51 | /xmldsig-more#rsa-sha512 | thRSA | 549.1.1.13 | 2375 | _5using | 2 | | | | 2376 | SHA-5 | | | | | 2377 | 12hash | | | | | 2378 | algor | | | | | 2379 | ithm | | | | | 2380 | ECDSA | ES | http://www.w3.org/2001/04 | SHA256wi | 1.2.840.100 | 2381 | using | 25 | /xmldsig-more#ecdsa-sha25 | thECDSA | 45.4.3.2 | 2382 | P-256 | 6 | 6 | | | 2383 | curve | | | | | 2384 | and | | | | | 2385 | SHA-256 | | | | | 2386 | hash | | | | | 2387 | algorit | | | | | 2388 | hm | | | | | 2389 | ECDSA | ES | http://www.w3.org/2001/04 | SHA384wi | 1.2.840.100 | 2390 | using | 38 | /xmldsig-more#ecdsa-sha38 | thECDSA | 45.4.3.3 | 2391 | P-384 | 4 | 4 | | | 2392 | curve | | | | | 2393 | and | | | | | 2394 | SHA-384 | | | | | 2395 | hash | | | | | 2396 | algorit | | | | | 2397 | hm | | | | | 2398 | ECDSA | ES | http://www.w3.org/2001/04 | SHA512wi | 1.2.840.100 | 2399 | using | 51 | /xmldsig-more#ecdsa-sha51 | thECDSA | 45.4.3.4 | 2400 | P-521 | 2 | 2 | | | 2401 | curve | | | | | 2402 | and | | | | | 2403 | SHA-512 | | | | | 2404 | hash | | | | | 2405 | algorit | | | | | 2406 | hm | | | | | 2407 | RSASSA- | PS | | | | 2408 | PSS | 25 | | | | 2409 | using | 6 | | | | 2410 | SHA-25 | | | | | 2411 | 6hash | | | | | 2412 | algori | | | | | 2413 | thm and | | | | | 2414 | MGF1 | | | | | 2415 | mask | | | | | 2416 | gener | | | | | 2417 | ation | | | | | 2418 | func | | | | | 2419 | tionwit | | | | | 2420 | h SHA | | | | | 2421 | -256 | | | | | 2422 | RSASSA- | PS | | | | 2423 | PSS | 38 | | | | 2424 | using | 4 | | | | 2425 | SHA-38 | | | | | 2426 | 4hash | | | | | 2427 | algori | | | | | 2428 | thm and | | | | | 2429 | MGF1 | | | | | 2430 | mask | | | | | 2431 | gener | | | | | 2432 | ation | | | | | 2433 | func | | | | | 2434 | tionwit | | | | | 2435 | h SHA | | | | | 2436 | -384 | | | | | 2437 | RSASSA- | PS | | | | 2438 | PSS | 51 | | | | 2439 | using | 2 | | | | 2440 | SHA-51 | | | | | 2441 | 2hash | | | | | 2442 | algori | | | | | 2443 | thm and | | | | | 2444 | MGF1 | | | | | 2445 | mask | | | | | 2446 | gener | | | | | 2447 | ation | | | | | 2448 | func | | | | | 2449 | tionwit | | | | | 2450 | h SHA | | | | | 2451 | -512 | | | | | 2452 +---------+----+---------------------------+----------+-------------+ 2454 Appendix B. Encryption Algorithm Identifier Cross-Reference 2456 This appendix contains a table cross-referencing the "alg" 2457 (algorithm) and "enc" (encryption method) values used in this 2458 specification with the equivalent identifiers used by other standards 2459 and software packages. See XML Encryption 2460 [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 2461 [W3C.CR-xmlenc-core1-20120313], and Java Cryptography Architecture 2462 [JCA] for more information about the names defined by those 2463 documents. 2465 For the composite algorithms "A128CBC-HS256", "A192CBC-HS384", and 2466 "A256CBC-HS512", the corresponding AES CBC algorithm identifiers are 2467 listed. 2469 +----------+--------+--------------------------+--------------------+ 2470 | Algorith | JWE | XML ENC | JCA | 2471 | m | | | | 2472 +----------+--------+--------------------------+--------------------+ 2473 | RSAES-PK | RSA1_5 | http://www.w3.org/2001/0 | RSA/ECB/PKCS1Paddi | 2474 | CS1-V1_5 | | 4/xmlenc#rsa-1_5 | ng | 2475 | RSAES | RSA-OA | http://www.w3.org/2001/0 | RSA/ECB/OAEPWithSH | 2476 | using | EP | 4/xmlenc#rsa-oaep-mgf1p | A-1AndMGF1Padding | 2477 | Optimal | | | | 2478 | Asymmetr | | | | 2479 | ic | | | | 2480 | Encrypt | | | | 2481 | ion | | | | 2482 | Paddin | | | | 2483 | g (OAEP) | | | | 2484 | Elliptic | ECDH-E | http://www.w3.org/2009/x | | 2485 | Curve | S | mlenc11#ECDH-ES | | 2486 | Diffie-H | | | | 2487 | ellman | | | | 2488 | Ephemer | | | | 2489 | alStatic | | | | 2490 | Advanced | A128KW | http://www.w3.org/2001/0 | | 2491 | Encrypti | | 4/xmlenc#kw-aes128 | | 2492 | on | | | | 2493 | Standar | | | | 2494 | d(AES) | | | | 2495 | Key Wra | | | | 2496 | pAlgorit | | | | 2497 | hmusing | | | | 2498 | 128 bi | | | | 2499 | t keys | | | | 2500 | AES Key | A192KW | http://www.w3.org/2001/0 | | 2501 | Wrap | | 4/xmlenc#kw-aes192 | | 2502 | Algorith | | | | 2503 | musing | | | | 2504 | 192 bit | | | | 2505 | keys | | | | 2506 | AES Key | A256KW | http://www.w3.org/2001/0 | | 2507 | Wrap | | 4/xmlenc#kw-aes256 | | 2508 | Algorith | | | | 2509 | musing | | | | 2510 | 256 bit | | | | 2511 | keys | | | | 2512 | AES in | A128CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 2513 | Cipher | C-HS25 | 4/xmlenc#aes128-cbc | ng | 2514 | Block | 6 | | | 2515 | Chaining | | | | 2516 | (CBC) | | | | 2517 | mode | | | | 2518 | with | | | | 2519 | PKCS #5 | | | | 2520 | padding | | | | 2521 | using | | | | 2522 | 128 bit | | | | 2523 | keys | | | | 2524 | AES in | A192CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 2525 | CBC mode | C-HS38 | 4/xmlenc#aes192-cbc | ng | 2526 | with | 4 | | | 2527 | PKCS #5 | | | | 2528 | padding | | | | 2529 | using | | | | 2530 | 192 bit | | | | 2531 | keys | | | | 2532 | AES in | A256CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 2533 | CBC mode | C-HS51 | 4/xmlenc#aes256-cbc | ng | 2534 | with | 2 | | | 2535 | PKCS #5 | | | | 2536 | padding | | | | 2537 | using | | | | 2538 | 256 bit | | | | 2539 | keys | | | | 2540 | AES in | A128GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 2541 | Galois/C | M | mlenc11#aes128-gcm | | 2542 | ounter | | | | 2543 | Mode | | | | 2544 | (GCM) | | | | 2545 | using | | | | 2546 | 128 bit | | | | 2547 | keys | | | | 2548 | AES GCM | A192GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 2549 | using | M | mlenc11#aes192-gcm | | 2550 | 192 bit | | | | 2551 | keys | | | | 2552 | AES GCM | A256GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 2553 | using | M | mlenc11#aes256-gcm | | 2554 | 256 bit | | | | 2555 | keys | | | | 2556 +----------+--------+--------------------------+--------------------+ 2558 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms 2560 The following test cases can be used to validate implementations of 2561 the AES_CBC_HMAC_SHA2 algorithms defined in Section 4.10. They are 2562 also intended to correspond to test cases that may appear in a future 2563 version of [I-D.mcgrew-aead-aes-cbc-hmac-sha2], demonstrating that 2564 the cryptographic computations performed are the same. 2566 The variable names are those defined in Section 4.10. All values are 2567 hexadecimal. 2569 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 2571 AES_128_CBC_HMAC_SHA_256 2573 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2574 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2576 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2578 ENC_KEY = 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2580 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2581 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2582 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2583 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2584 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2585 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2586 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2587 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2589 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2591 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2592 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2593 4b 65 72 63 6b 68 6f 66 66 73 2595 AL = 00 00 00 00 00 00 01 50 2597 E = c8 0e df a3 2d df 39 d5 ef 00 c0 b4 68 83 42 79 2598 a2 e4 6a 1b 80 49 f7 92 f7 6b fe 54 b9 03 a9 c9 2599 a9 4a c9 b4 7a d2 65 5c 5f 10 f9 ae f7 14 27 e2 2600 fc 6f 9b 3f 39 9a 22 14 89 f1 63 62 c7 03 23 36 2601 09 d4 5a c6 98 64 e3 32 1c f8 29 35 ac 40 96 c8 2602 6e 13 33 14 c5 40 19 e8 ca 79 80 df a4 b9 cf 1b 2603 38 4c 48 6f 3a 54 c5 10 78 15 8e e5 d7 9d e5 9f 2604 bd 34 d8 48 b3 d6 95 50 a6 76 46 34 44 27 ad e5 2605 4b 88 51 ff b5 98 f7 f8 00 74 b9 47 3c 82 e2 db 2607 M = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2608 e6 e5 45 82 47 65 15 f0 ad 9f 75 a2 b7 1c 73 ef 2610 T = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2612 C.2. Test Cases for AES_192_CBC_HMAC_SHA_384 2614 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2615 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2616 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2618 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2619 10 11 12 13 14 15 16 17 2621 ENC_KEY = 18 19 1a 1b 1c 1d 1e 1f 20 21 22 23 24 25 26 27 2622 28 29 2a 2b 2c 2d 2e 2f 2624 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2625 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2626 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2627 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2628 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2629 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2630 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2631 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2633 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2635 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2636 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2637 4b 65 72 63 6b 68 6f 66 66 73 2639 AL = 00 00 00 00 00 00 01 50 2641 E = ea 65 da 6b 59 e6 1e db 41 9b e6 2d 19 71 2a e5 2642 d3 03 ee b5 00 52 d0 df d6 69 7f 77 22 4c 8e db 2643 00 0d 27 9b dc 14 c1 07 26 54 bd 30 94 42 30 c6 2644 57 be d4 ca 0c 9f 4a 84 66 f2 2b 22 6d 17 46 21 2645 4b f8 cf c2 40 0a dd 9f 51 26 e4 79 66 3f c9 0b 2646 3b ed 78 7a 2f 0f fc bf 39 04 be 2a 64 1d 5c 21 2647 05 bf e5 91 ba e2 3b 1d 74 49 e5 32 ee f6 0a 9a 2648 c8 bb 6c 6b 01 d3 5d 49 78 7b cd 57 ef 48 49 27 2649 f2 80 ad c9 1a c0 c4 e7 9c 7b 11 ef c6 00 54 e3 2651 M = 84 90 ac 0e 58 94 9b fe 51 87 5d 73 3f 93 ac 20 2652 75 16 80 39 cc c7 33 d7 45 94 f8 86 b3 fa af d4 2653 86 f2 5c 71 31 e3 28 1e 36 c7 a2 d1 30 af de 57 2655 T = 84 90 ac 0e 58 94 9b fe 51 87 5d 73 3f 93 ac 20 2656 75 16 80 39 cc c7 33 d7 2658 C.3. Test Cases for AES_256_CBC_HMAC_SHA_512 2660 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2661 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2662 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2663 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2665 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2666 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2668 ENC_KEY = 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2669 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2671 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2672 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2673 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2674 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2675 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2676 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2677 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2678 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2680 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2682 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2683 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2684 4b 65 72 63 6b 68 6f 66 66 73 2686 AL = 00 00 00 00 00 00 01 50 2688 E = 4a ff aa ad b7 8c 31 c5 da 4b 1b 59 0d 10 ff bd 2689 3d d8 d5 d3 02 42 35 26 91 2d a0 37 ec bc c7 bd 2690 82 2c 30 1d d6 7c 37 3b cc b5 84 ad 3e 92 79 c2 2691 e6 d1 2a 13 74 b7 7f 07 75 53 df 82 94 10 44 6b 2692 36 eb d9 70 66 29 6a e6 42 7e a7 5c 2e 08 46 a1 2693 1a 09 cc f5 37 0d c8 0b fe cb ad 28 c7 3f 09 b3 2694 a3 b7 5e 66 2a 25 94 41 0a e4 96 b2 e2 e6 60 9e 2695 31 e6 e0 2c c8 37 f0 53 d2 1f 37 ff 4f 51 95 0b 2696 be 26 38 d0 9d d7 a4 93 09 30 80 6d 07 03 b1 f6 2698 M = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2699 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2700 fd 30 a5 65 c6 16 ff b2 f3 64 ba ec e6 8f c4 07 2701 53 bc fc 02 5d de 36 93 75 4a a1 f5 c3 37 3b 9c 2703 T = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2704 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2706 Appendix D. Example ECDH-ES Key Agreement Computation 2708 This example uses ECDH-ES Key Agreement and the Concat KDF to derive 2709 the Content Encryption Key (CEK) in the manner described in 2710 Section 4.7. In this example, the ECDH-ES Direct Key Agreement mode 2711 ("alg" value "ECDH-ES") is used to produce an agreed upon key for AES 2712 GCM with 128 bit keys ("enc" value "A128GCM"). 2714 In this example, a sender Alice is encrypting content to a recipient 2715 Bob. The sender (Alice) generates an ephemeral key for the key 2716 agreement computation. Alice's ephemeral key (in JWK format) used 2717 for the key agreement computation in this example (including the 2718 private part) is: 2720 {"kty":"EC", 2721 "crv":"P-256", 2722 "x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0", 2723 "y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps", 2724 "d":"0_NxaRPUMQoAJt50Gz8YiTr8gRTwyEaCumd-MToTmIo" 2725 } 2727 The recipient's (Bob's) key (in JWK format) used for the key 2728 agreement computation in this example (including the private part) 2729 is: 2731 {"kty":"EC", 2732 "crv":"P-256", 2733 "x":"weNJy2HscCSM6AEDTDg04biOvhFhyyWvOHQfeF_PxMQ", 2734 "y":"e8lnCO-AlStT-NJVX-crhB7QRYhiix03illJOVAOyck", 2735 "d":"VEmDZpDXXK8p8N0Cndsxs924q6nS1RXFASRl6BfUqdw" 2736 } 2738 Header parameter values used in this example are as follows. In this 2739 example, the "apu" (agreement PartyUInfo) parameter value is the 2740 base64url encoding of the UTF-8 string "Alice" and the "apv" 2741 (agreement PartyVInfo) parameter value is the base64url encoding of 2742 the UTF-8 string "Bob". The "epk" parameter is used to communicate 2743 the sender's (Alice's) ephemeral public key value to the recipient 2744 (Bob). 2746 {"alg":"ECDH-ES", 2747 "enc":"A128GCM", 2748 "apu":"QWxpY2U", 2749 "apv":"Qm9i", 2750 "epk": 2751 {"kty":"EC", 2752 "crv":"P-256", 2753 "x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0", 2754 "y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps" 2755 } 2756 } 2758 The resulting Concat KDF [NIST.800-56A] parameter values are: 2760 Z This is set to the ECDH-ES key agreement output. (This value is 2761 often not directly exposed by libraries, due to NIST security 2762 requirements, and only serves as an input to a KDF.) In this 2763 example, Z is the octet sequence: 2764 [158, 86, 217, 29, 129, 113, 53, 211, 114, 131, 66, 131, 191, 132, 2765 38, 156, 251, 49, 110, 163, 218, 128, 106, 72, 246, 218, 167, 121, 2766 140, 254, 144, 196]. 2768 keydatalen This value is 128 - the number of bits in the desired 2769 output key (because "A128GCM" uses a 128 bit key). 2771 AlgorithmID This is set to the octets representing the UTF-8 string 2772 "A128GCM" - [65, 49, 50, 56, 71, 67, 77]. 2774 PartyUInfo This is set to the octets representing the 32 bit big 2775 endian value 5 - [0, 0, 0, 5] - the number of octets in the 2776 PartyUInfo content "Alice", followed, by the octets representing 2777 the UTF-8 string "Alice" - [65, 108, 105, 99, 101]. 2779 PartyVInfo This is set to the octets representing the 32 bit big 2780 endian value 3 - [0, 0, 0, 3] - the number of octets in the 2781 PartyUInfo content "Bob", followed, by the octets representing the 2782 UTF-8 string "Bob" - [66, 111, 98]. 2784 SuppPubInfo This is set to the octets representing the 32 bit big 2785 endian value 128 - [0, 0, 0, 128] - the keydatalen value. 2787 SuppPrivInfo This is set to the empty octet sequence. 2789 Concatenating the parameters AlgorithmID through SuppPubInfo results 2790 in an otherInfo value of: 2791 [65, 49, 50, 56, 71, 67, 77, 0, 0, 0, 5, 65, 108, 105, 99, 101, 0, 0, 2792 0, 3, 66, 111, 98, 0, 0, 0, 128] 2793 Concatenating the round number 1 ([0, 0, 0, 1]), Z, and the otherInfo 2794 value results in the Concat KDF round 1 hash input of: 2795 [0, 0, 0, 1, 2796 158, 86, 217, 29, 129, 113, 53, 211, 114, 131, 66, 131, 191, 132, 38, 2797 156, 251, 49, 110, 163, 218, 128, 106, 72, 246, 218, 167, 121, 140, 2798 254, 144, 196, 2799 65, 49, 50, 56, 71, 67, 77, 0, 0, 0, 5, 65, 108, 105, 99, 101, 0, 0, 2800 0, 3, 66, 111, 98, 0, 0, 0, 128] 2802 The resulting derived key, which is the first 128 bits of the round 1 2803 hash output is: 2804 [186, 193, 41, 192, 82, 2, 254, 170, 230, 4, 76, 103, 180, 92, 49, 2805 48] 2807 The base64url encoded representation of this derived key is: 2809 usEpwFIC_qrmBExntFwxMA 2811 Appendix E. Acknowledgements 2813 Solutions for signing and encrypting JSON content were previously 2814 explored by Magic Signatures [MagicSignatures], JSON Simple Sign 2815 [JSS], Canvas Applications [CanvasApp], JSON Simple Encryption [JSE], 2816 and JavaScript Message Security Format [I-D.rescorla-jsms], all of 2817 which influenced this draft. 2819 The Authenticated Encryption with AES-CBC and HMAC-SHA 2820 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] specification, upon which the 2821 AES_CBC_HMAC_SHA2 algorithms are based, was written by David A. 2822 McGrew and Kenny Paterson. The test cases for AES_CBC_HMAC_SHA2 are 2823 based upon those for [I-D.mcgrew-aead-aes-cbc-hmac-sha2] by John 2824 Foley. 2826 Matt Miller wrote Using JavaScript Object Notation (JSON) Web 2827 Encryption (JWE) for Protecting JSON Web Key (JWK) Objects 2828 [I-D.miller-jose-jwe-protected-jwk], which the password-based 2829 encryption content of this draft is based upon. 2831 This specification is the work of the JOSE Working Group, which 2832 includes dozens of active and dedicated participants. In particular, 2833 the following individuals contributed ideas, feedback, and wording 2834 that influenced this specification: 2836 Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de 2837 Medeiros, Yaron Y. Goland, Dick Hardt, Jeff Hodges, Edmund Jay, James 2838 Manger, Matt Miller, Tony Nadalin, Axel Nennker, John Panzer, 2839 Emmanuel Raviart, Nat Sakimura, Jim Schaad, Hannes Tschofenig, and 2840 Sean Turner. 2842 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2843 Sean Turner and Stephen Farrell served as Security area directors 2844 during the creation of this specification. 2846 Appendix F. Document History 2848 [[ to be removed by the RFC editor before publication as an RFC ]] 2850 -15 2852 o Changed statements about rejecting JWSs to statements about 2853 validation failing, addressing issue #35. 2855 o Stated that changes of implementation requirements are only 2856 permitted on a Specification Required basis, addressing issue #38. 2858 o Made "oct" a required key type, addressing issue #40. 2860 o Updated the example ECDH-ES key agreement values. 2862 o Changes to address editorial and minor issues #34, #37, #49, #123, 2863 #124, #125, #130, #132, #133, #138, #139, #140, #142, #143, #144, 2864 #145, #148, #149, #150, and #162. 2866 -14 2868 o Removed "PBKDF2" key type and added "p2s" and "p2c" header 2869 parameters for use with the PBES2 algorithms. 2871 o Made the RSA private key parameters that are there to enable 2872 optimizations be RECOMMENDED rather than REQUIRED. 2874 o Added algorithm identifiers for AES algorithms using 192 bit keys 2875 and for RSASSA-PSS using HMAC SHA-384. 2877 o Added security considerations about key lifetimes, addressing 2878 issue #18. 2880 o Added an example ECDH-ES key agreement computation. 2882 -13 2884 o Added key encryption with AES GCM as specified in 2885 draft-jones-jose-aes-gcm-key-wrap-01, addressing issue #13. 2887 o Added security considerations text limiting the number of times 2888 that an AES GCM key can be used for key encryption or direct 2889 encryption, per Section 8.3 of NIST SP 800-38D, addressing issue 2890 #28. 2892 o Added password-based key encryption as specified in 2893 draft-miller-jose-jwe-protected-jwk-02. 2895 -12 2897 o In the Direct Key Agreement case, the Concat KDF AlgorithmID is 2898 set to the octets of the UTF-8 representation of the "enc" header 2899 parameter value. 2901 o Restored the "apv" (agreement PartyVInfo) parameter. 2903 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2904 be with the algorithm descriptions that use them. 2906 o Changed terminology from "block encryption" to "content 2907 encryption". 2909 -11 2911 o Removed the Encrypted Key value from the AAD computation since it 2912 is already effectively integrity protected by the encryption 2913 process. The AAD value now only contains the representation of 2914 the JWE Encrypted Header. 2916 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2918 o Added more information about the use of PartyUInfo during key 2919 agreement. 2921 o Use the keydatalen as the SuppPubInfo value for the Concat KDF 2922 when doing key agreement, as RFC 2631 does. 2924 o Added algorithm identifiers for RSASSA-PSS with SHA-256 and SHA- 2925 512. 2927 o Added a Parameter Information Class value to the JSON Web Key 2928 Parameters registry, which registers whether the parameter conveys 2929 public or private information. 2931 -10 2933 o Changed the JWE processing rules for multiple recipients so that a 2934 single AAD value contains the header parameters and encrypted key 2935 values for all the recipients, enabling AES GCM to be safely used 2936 for multiple recipients. 2938 -09 2940 o Expanded the scope of the JWK parameters to include private and 2941 symmetric key representations, as specified by 2942 draft-jones-jose-json-private-and-symmetric-key-00. 2944 o Changed term "JWS Secured Input" to "JWS Signing Input". 2946 o Changed from using the term "byte" to "octet" when referring to 8 2947 bit values. 2949 o Specified that AES Key Wrap uses the default initial value 2950 specified in Section 2.2.3.1 of RFC 3394. This addressed issue 2951 #19. 2953 o Added Key Management Mode definitions to terminology section and 2954 used the defined terms to provide clearer key management 2955 instructions. This addressed issue #5. 2957 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2958 and "A256CBC-HS512". The new algorithms perform the same 2959 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2960 but with the Initialization Vector and Authentication Tag values 2961 remaining separate from the Ciphertext value in the output 2962 representation. Also deleted the header parameters "epu" 2963 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2964 they are no longer used. 2966 o Changed from using the term "Integrity Value" to "Authentication 2967 Tag". 2969 -08 2971 o Changed the name of the JWK key type parameter from "alg" to 2972 "kty". 2974 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2975 since the term AEAD in the RFC 5116 sense implied the use of a 2976 particular data representation, rather than just referring to the 2977 class of algorithms that perform authenticated encryption with 2978 associated data. 2980 o Applied editorial improvements suggested by Jeff Hodges. Many of 2981 these simplified the terminology used. 2983 o Added seriesInfo information to Internet Draft references. 2985 -07 2987 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2989 o Changed the name of the JWK RSA modulus parameter from "mod" to 2990 "n" and the name of the JWK RSA exponent parameter from "xpo" to 2991 "e", so that the identifiers are the same as those used in RFC 2992 3447. 2994 o Made several local editorial changes to clean up loose ends left 2995 over from to the decision to only support block encryption methods 2996 providing integrity. 2998 -06 3000 o Removed the "int" and "kdf" parameters and defined the new 3001 composite Authenticated Encryption algorithms "A128CBC+HS256" and 3002 "A256CBC+HS512" to replace the former uses of AES CBC, which 3003 required the use of separate integrity and key derivation 3004 functions. 3006 o Included additional values in the Concat KDF calculation -- the 3007 desired output size and the algorithm value, and optionally 3008 PartyUInfo and PartyVInfo values. Added the optional header 3009 parameters "apu" (agreement PartyUInfo), "apv" (agreement 3010 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 3011 PartyVInfo). 3013 o Changed the name of the JWK RSA exponent parameter from "exp" to 3014 "xpo" so as to allow the potential use of the name "exp" for a 3015 future extension that might define an expiration parameter for 3016 keys. (The "exp" name is already used for this purpose in the JWT 3017 specification.) 3019 o Applied changes made by the RFC Editor to RFC 6749's registry 3020 language to this specification. 3022 -05 3024 o Support both direct encryption using a shared or agreed upon 3025 symmetric key, and the use of a shared or agreed upon symmetric 3026 key to key wrap the CMK. Specifically, added the "alg" values 3027 "dir", "ECDH-ES+A128KW", and "ECDH-ES+A256KW" to finish filling in 3028 this set of capabilities. 3030 o Updated open issues. 3032 -04 3034 o Added text requiring that any leading zero bytes be retained in 3035 base64url encoded key value representations for fixed-length 3036 values. 3038 o Added this language to Registration Templates: "This name is case 3039 sensitive. Names that match other registered names in a case 3040 insensitive manner SHOULD NOT be accepted." 3042 o Described additional open issues. 3044 o Applied editorial suggestions. 3046 -03 3048 o Always use a 128 bit "authentication tag" size for AES GCM, 3049 regardless of the key size. 3051 o Specified that use of a 128 bit IV is REQUIRED with AES CBC. It 3052 was previously RECOMMENDED. 3054 o Removed key size language for ECDSA algorithms, since the key size 3055 is implied by the algorithm being used. 3057 o Stated that the "int" key size must be the same as the hash output 3058 size (and not larger, as was previously allowed) so that its size 3059 is defined for key generation purposes. 3061 o Added the "kdf" (key derivation function) header parameter to 3062 provide crypto agility for key derivation. The default KDF 3063 remains the Concat KDF with the SHA-256 digest function. 3065 o Clarified that the "mod" and "exp" values are unsigned. 3067 o Added Implementation Requirements columns to algorithm tables and 3068 Implementation Requirements entries to algorithm registries. 3070 o Changed AES Key Wrap to RECOMMENDED. 3072 o Moved registries JSON Web Signature and Encryption Header 3073 Parameters and JSON Web Signature and Encryption Type Values to 3074 the JWS specification. 3076 o Moved JSON Web Key Parameters registry to the JWK specification. 3078 o Changed registration requirements from RFC Required to 3079 Specification Required with Expert Review. 3081 o Added Registration Template sections for defined registries. 3083 o Added Registry Contents sections to populate registry values. 3085 o No longer say "the UTF-8 representation of the JWS Secured Input 3086 (which is the same as the ASCII representation)". Just call it 3087 "the ASCII representation of the JWS Secured Input". 3089 o Added "Collision Resistant Namespace" to the terminology section. 3091 o Numerous editorial improvements. 3093 -02 3095 o For AES GCM, use the "additional authenticated data" parameter to 3096 provide integrity for the header, encrypted key, and ciphertext 3097 and use the resulting "authentication tag" value as the JWE 3098 Authentication Tag. 3100 o Defined minimum required key sizes for algorithms without 3101 specified key sizes. 3103 o Defined KDF output key sizes. 3105 o Specified the use of PKCS #5 padding with AES CBC. 3107 o Generalized text to allow key agreement to be employed as an 3108 alternative to key wrapping or key encryption. 3110 o Clarified that ECDH-ES is a key agreement algorithm. 3112 o Required implementation of AES-128-KW and AES-256-KW. 3114 o Removed the use of "A128GCM" and "A256GCM" for key wrapping. 3116 o Removed "A512KW" since it turns out that it's not a standard 3117 algorithm. 3119 o Clarified the relationship between "typ" header parameter values 3120 and MIME types. 3122 o Generalized language to refer to Message Authentication Codes 3123 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 3124 unless in a context specific to HMAC algorithms. 3126 o Established registries: JSON Web Signature and Encryption Header 3127 Parameters, JSON Web Signature and Encryption Algorithms, JSON Web 3128 Signature and Encryption "typ" Values, JSON Web Key Parameters, 3129 and JSON Web Key Algorithm Families. 3131 o Moved algorithm-specific definitions from JWK to JWA. 3133 o Reformatted to give each member definition its own section 3134 heading. 3136 -01 3138 o Moved definition of "alg":"none" for JWSs here from the JWT 3139 specification since this functionality is likely to be useful in 3140 more contexts that just for JWTs. 3142 o Added Advanced Encryption Standard (AES) Key Wrap Algorithm using 3143 512 bit keys ("A512KW"). 3145 o Added text "Alternatively, the Encoded JWS Signature MAY be 3146 base64url decoded to produce the JWS Signature and this value can 3147 be compared with the computed HMAC value, as this comparison 3148 produces the same result as comparing the encoded values". 3150 o Corrected the Magic Signatures reference. 3152 o Made other editorial improvements suggested by JOSE working group 3153 participants. 3155 -00 3157 o Created the initial IETF draft based upon 3158 draft-jones-json-web-signature-04 and 3159 draft-jones-json-web-encryption-02 with no normative changes. 3161 o Changed terminology to no longer call both digital signatures and 3162 HMACs "signatures". 3164 Author's Address 3166 Michael B. Jones 3167 Microsoft 3169 Email: mbj@microsoft.com 3170 URI: http://self-issued.info/