idnits 2.17.1 draft-ietf-jose-json-web-algorithms-27.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 23 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 10, 2014) is 3608 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 2906 -- Looks like a reference, but probably isn't: '0' on line 2906 -- Looks like a reference, but probably isn't: '7' on line 2878 -- Looks like a reference, but probably isn't: '65' on line 2886 -- Looks like a reference, but probably isn't: '49' on line 2880 -- Looks like a reference, but probably isn't: '50' on line 2880 -- Looks like a reference, but probably isn't: '56' on line 2880 -- Looks like a reference, but probably isn't: '71' on line 2880 -- Looks like a reference, but probably isn't: '67' on line 2880 -- Looks like a reference, but probably isn't: '77' on line 2880 -- Looks like a reference, but probably isn't: '5' on line 2884 -- Looks like a reference, but probably isn't: '108' on line 2886 -- Looks like a reference, but probably isn't: '105' on line 2886 -- Looks like a reference, but probably isn't: '99' on line 2886 -- Looks like a reference, but probably isn't: '101' on line 2886 -- Looks like a reference, but probably isn't: '3' on line 2890 -- Looks like a reference, but probably isn't: '66' on line 2892 -- Looks like a reference, but probably isn't: '111' on line 2892 -- Looks like a reference, but probably isn't: '98' on line 2892 -- Looks like a reference, but probably isn't: '128' on line 2896 -- 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 ** Downref: Normative reference to an Informational RFC: RFC 6090 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'SEC1' -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' == Outdated reference: A later version (-18) exists of draft-ietf-precis-saslprepbis-07 == Outdated reference: A later version (-05) exists of draft-mcgrew-aead-aes-cbc-hmac-sha2-04 -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 5 errors (**), 0 flaws (~~), 4 warnings (==), 29 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 June 10, 2014 5 Expires: December 12, 2014 7 JSON Web Algorithms (JWA) 8 draft-ietf-jose-json-web-algorithms-27 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 December 12, 2014. 35 Copyright Notice 37 Copyright (c) 2014 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 3. Cryptographic Algorithms for Digital Signatures and MACs . . . 6 56 3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 6 57 3.2. HMAC with SHA-2 Functions . . . . . . . . . . . . . . . . 7 58 3.3. Digital Signature with RSASSA-PKCS1-V1_5 . . . . . . . . . 8 59 3.4. Digital Signature with ECDSA . . . . . . . . . . . . . . . 9 60 3.5. Digital Signature with RSASSA-PSS . . . . . . . . . . . . 10 61 3.6. Using the Algorithm "none" . . . . . . . . . . . . . . . . 11 62 4. Cryptographic Algorithms for Key Management . . . . . . . . . 12 63 4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 12 64 4.2. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 14 65 4.3. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 14 66 4.4. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 15 67 4.5. Direct Encryption with a Shared Symmetric Key . . . . . . 15 68 4.6. Key Agreement with Elliptic Curve Diffie-Hellman 69 Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 15 70 4.6.1. Header Parameters Used for ECDH Key Agreement . . . . 16 71 4.6.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 16 72 4.6.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 17 73 4.6.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 17 74 4.6.2. Key Derivation for ECDH Key Agreement . . . . . . . . 17 75 4.7. Key Encryption with AES GCM . . . . . . . . . . . . . . . 19 76 4.7.1. Header Parameters Used for AES GCM Key Encryption . . 19 77 4.7.1.1. "iv" (Initialization Vector) Header Parameter . . 19 78 4.7.1.2. "tag" (Authentication Tag) Header Parameter . . . 20 79 4.8. Key Encryption with PBES2 . . . . . . . . . . . . . . . . 20 80 4.8.1. Header Parameters Used for PBES2 Key Encryption . . . 21 81 4.8.1.1. "p2s" (PBES2 salt input) Parameter . . . . . . . . 21 82 4.8.1.2. "p2c" (PBES2 count) Parameter . . . . . . . . . . 21 83 5. Cryptographic Algorithms for Content Encryption . . . . . . . 21 84 5.1. "enc" (Encryption Algorithm) Header Parameter Values 85 for JWE . . . . . . . . . . . . . . . . . . . . . . . . . 21 86 5.2. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 22 87 5.2.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 23 88 5.2.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 23 89 5.2.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 23 90 5.2.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 25 91 5.2.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 25 92 5.2.4. AES_192_CBC_HMAC_SHA_384 . . . . . . . . . . . . . . . 26 93 5.2.5. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 26 94 5.2.6. Content Encryption with AES_CBC_HMAC_SHA2 . . . . . . 27 95 5.3. Content Encryption with AES GCM . . . . . . . . . . . . . 27 96 6. Cryptographic Algorithms for Keys . . . . . . . . . . . . . . 28 97 6.1. "kty" (Key Type) Parameter Values . . . . . . . . . . . . 28 98 6.2. Parameters for Elliptic Curve Keys . . . . . . . . . . . . 28 99 6.2.1. Parameters for Elliptic Curve Public Keys . . . . . . 28 100 6.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 29 101 6.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 29 102 6.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 29 103 6.2.2. Parameters for Elliptic Curve Private Keys . . . . . . 29 104 6.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 30 105 6.3. Parameters for RSA Keys . . . . . . . . . . . . . . . . . 30 106 6.3.1. Parameters for RSA Public Keys . . . . . . . . . . . . 30 107 6.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 30 108 6.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 30 109 6.3.2. Parameters for RSA Private Keys . . . . . . . . . . . 30 110 6.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 31 111 6.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 31 112 6.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 31 113 6.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 31 114 6.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 31 115 6.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 31 116 6.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 32 117 6.4. Parameters for Symmetric Keys . . . . . . . . . . . . . . 32 118 6.4.1. "k" (Key Value) Parameter . . . . . . . . . . . . . . 33 119 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 120 7.1. JSON Web Signature and Encryption Algorithms Registry . . 34 121 7.1.1. Registration Template . . . . . . . . . . . . . . . . 34 122 7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 35 123 7.2. JWE Header Parameter Names Registration . . . . . . . . . 41 124 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 41 125 7.3. JSON Web Encryption Compression Algorithms Registry . . . 42 126 7.3.1. Registration Template . . . . . . . . . . . . . . . . 42 127 7.3.2. Initial Registry Contents . . . . . . . . . . . . . . 43 128 7.4. JSON Web Key Types Registry . . . . . . . . . . . . . . . 43 129 7.4.1. Registration Template . . . . . . . . . . . . . . . . 43 130 7.4.2. Initial Registry Contents . . . . . . . . . . . . . . 44 131 7.5. JSON Web Key Parameters Registration . . . . . . . . . . . 44 132 7.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 44 133 7.6. JSON Web Key Elliptic Curve Registry . . . . . . . . . . . 47 134 7.6.1. Registration Template . . . . . . . . . . . . . . . . 47 135 7.6.2. Initial Registry Contents . . . . . . . . . . . . . . 48 136 8. Security Considerations . . . . . . . . . . . . . . . . . . . 48 137 8.1. Algorithms and Key Sizes will be Deprecated . . . . . . . 49 138 8.2. Key Lifetimes . . . . . . . . . . . . . . . . . . . . . . 49 139 8.3. RSAES-PKCS1-v1_5 Security Considerations . . . . . . . . . 49 140 8.4. AES GCM Security Considerations . . . . . . . . . . . . . 49 141 8.5. Plaintext JWS Security Considerations . . . . . . . . . . 50 142 8.6. Differences between Digital Signatures and MACs . . . . . 50 143 8.7. Denial of Service Attacks . . . . . . . . . . . . . . . . 51 144 8.8. Reusing Key Material when Encrypting Keys . . . . . . . . 51 145 8.9. Password Considerations . . . . . . . . . . . . . . . . . 51 146 8.10. Adaptive Chosen-Ciphertext Attacks . . . . . . . . . . . . 52 147 8.11. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 52 148 8.12. RSA Private Key Representations and Blinding . . . . . . . 52 149 9. Internationalization Considerations . . . . . . . . . . . . . 52 150 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 52 151 10.1. Normative References . . . . . . . . . . . . . . . . . . . 52 152 10.2. Informative References . . . . . . . . . . . . . . . . . . 54 153 Appendix A. Algorithm Identifier Cross-Reference . . . . . . . . 56 154 A.1. Digital Signature/MAC Algorithm Identifier 155 Cross-Reference . . . . . . . . . . . . . . . . . . . . . 56 156 A.2. Key Management Algorithm Identifier Cross-Reference . . . 57 157 A.3. Content Encryption Algorithm Identifier Cross-Reference . 57 158 Appendix B. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 58 159 B.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 59 160 B.2. Test Cases for AES_192_CBC_HMAC_SHA_384 . . . . . . . . . 60 161 B.3. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 61 162 Appendix C. Example ECDH-ES Key Agreement Computation . . . . . . 62 163 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 64 164 Appendix E. Document History . . . . . . . . . . . . . . . . . . 65 165 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 74 167 1. Introduction 169 The JSON Web Algorithms (JWA) specification registers cryptographic 170 algorithms and identifiers to be used with the JSON Web Signature 171 (JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK) 172 [JWK] specifications. It defines several IANA registries for these 173 identifiers. All these specifications utilize JavaScript Object 174 Notation (JSON) [RFC7159] based data structures. This specification 175 also describes the semantics and operations that are specific to 176 these algorithms and key types. 178 Registering the algorithms and identifiers here, rather than in the 179 JWS, JWE, and JWK specifications, is intended to allow them to remain 180 unchanged in the face of changes in the set of Required, Recommended, 181 Optional, and Deprecated algorithms over time. This also allows 182 changes to the JWS, JWE, and JWK specifications without changing this 183 document. 185 Names defined by this specification are short because a core goal is 186 for the resulting representations to be compact. 188 1.1. Notational Conventions 190 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 191 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 192 "OPTIONAL" in this document are to be interpreted as described in Key 193 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 194 these words are used without being spelled in uppercase then they are 195 to be interpreted with their normal natural language meanings. 197 BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per 198 Section 2. 200 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 201 of STRING. 203 ASCII(STRING) denotes the octets of the ASCII [USASCII] 204 representation of STRING. 206 The concatenation of two values A and B is denoted as A || B. 208 2. Terminology 210 These terms defined by the JSON Web Signature (JWS) [JWS] 211 specification are incorporated into this specification: "JSON Web 212 Signature (JWS)", "JWS Header", "JWS Payload", "JWS Signature", "JWS 213 Protected Header", "Base64url Encoding", and "JWS Signing Input". 215 These terms defined by the JSON Web Encryption (JWE) [JWE] 216 specification are incorporated into this specification: "JSON Web 217 Encryption (JWE)", "Authenticated Encryption", "Plaintext", 218 "Ciphertext", "Additional Authenticated Data (AAD)", "Authentication 219 Tag", "Content Encryption Key (CEK)", "JWE Header", "JWE Encrypted 220 Key", "JWE Initialization Vector", "JWE Ciphertext", "JWE 221 Authentication Tag", "JWE Protected Header", "Key Management Mode", 222 "Key Encryption", "Key Wrapping", "Direct Key Agreement", "Key 223 Agreement with Key Wrapping", and "Direct Encryption". 225 These terms defined by the JSON Web Key (JWK) [JWK] specification are 226 incorporated into this specification: "JSON Web Key (JWK)" and "JSON 227 Web Key Set (JWK Set)". 229 These terms are defined for use by this specification: 231 Header Parameter 232 A name/value pair that is member of a JWS Header or JWE Header. 234 3. Cryptographic Algorithms for Digital Signatures and MACs 236 JWS uses cryptographic algorithms to digitally sign or create a 237 Message Authentication Codes (MAC) of the contents of the JWS Header 238 and the JWS Payload. 240 3.1. "alg" (Algorithm) Header Parameter Values for JWS 242 The table below is the set of "alg" (algorithm) header parameter 243 values defined by this specification for use with JWS, each of which 244 is explained in more detail in the following sections: 246 +---------------+------------------------------+--------------------+ 247 | alg Parameter | Digital Signature or MAC | Implementation | 248 | Value | Algorithm | Requirements | 249 +---------------+------------------------------+--------------------+ 250 | HS256 | HMAC using SHA-256 | Required | 251 | HS384 | HMAC using SHA-384 | Optional | 252 | HS512 | HMAC using SHA-512 | Optional | 253 | RS256 | RSASSA-PKCS-v1_5 using | Recommended | 254 | | SHA-256 | | 255 | RS384 | RSASSA-PKCS-v1_5 using | Optional | 256 | | SHA-384 | | 257 | RS512 | RSASSA-PKCS-v1_5 using | Optional | 258 | | SHA-512 | | 259 | ES256 | ECDSA using P-256 and | Recommended+ | 260 | | SHA-256 | | 261 | ES384 | ECDSA using P-384 and | Optional | 262 | | SHA-384 | | 263 | ES512 | ECDSA using P-521 and | Optional | 264 | | SHA-512 | | 265 | PS256 | RSASSA-PSS using SHA-256 and | Optional | 266 | | MGF1 with SHA-256 | | 267 | PS384 | RSASSA-PSS using SHA-384 and | Optional | 268 | | MGF1 with SHA-384 | | 269 | PS512 | RSASSA-PSS using SHA-512 and | Optional | 270 | | MGF1 with SHA-512 | | 271 | none | No digital signature or MAC | Optional | 272 | | performed | | 273 +---------------+------------------------------+--------------------+ 275 The use of "+" in the Implementation Requirements indicates that the 276 requirement strength is likely to be increased in a future version of 277 the specification. 279 See Appendix A.1 for a table cross-referencing the JWS digital 280 signature and MAC "alg" (algorithm) values defined in this 281 specification with the equivalent identifiers used by other standards 282 and software packages. 284 3.2. HMAC with SHA-2 Functions 286 Hash-based Message Authentication Codes (HMACs) enable one to use a 287 secret plus a cryptographic hash function to generate a Message 288 Authentication Code (MAC). This can be used to demonstrate that 289 whoever generated the MAC was in possession of the MAC key. The 290 algorithm for implementing and validating HMACs is provided in RFC 291 2104 [RFC2104]. 293 A key of the same size as the hash output (for instance, 256 bits for 294 "HS256") or larger MUST be used with this algorithm. 296 The HMAC SHA-256 MAC is generated per RFC 2104, using SHA-256 as the 297 hash algorithm "H", using the JWS Signing Input as the "text" value, 298 and using the shared key. The HMAC output value is the JWS 299 Signature. 301 The following "alg" (algorithm) Header Parameter values are used to 302 indicate that the JWS Signature is an HMAC value computed using the 303 corresponding algorithm: 305 +---------------------+--------------------+ 306 | alg Parameter Value | MAC Algorithm | 307 +---------------------+--------------------+ 308 | HS256 | HMAC using SHA-256 | 309 | HS384 | HMAC using SHA-384 | 310 | HS512 | HMAC using SHA-512 | 311 +---------------------+--------------------+ 313 The HMAC SHA-256 MAC for a JWS is validated by computing an HMAC 314 value per RFC 2104, using SHA-256 as the hash algorithm "H", using 315 the received JWS Signing Input as the "text" value, and using the 316 shared key. This computed HMAC value is then compared to the result 317 of base64url decoding the received encoded JWS Signature value. 318 Alternatively, the computed HMAC value can be base64url encoded and 319 compared to the received encoded JWS Signature value, as this 320 comparison produces the same result as comparing the unencoded 321 values. In either case, if the values match, the HMAC has been 322 validated. 324 Securing content and validation with the HMAC SHA-384 and HMAC SHA- 325 512 algorithms is performed identically to the procedure for HMAC 326 SHA-256 -- just using the corresponding hash algorithms with 327 correspondingly larger minimum key sizes and result values: 384 bits 328 each for HMAC SHA-384 and 512 bits each for HMAC SHA-512. 330 An example using this algorithm is shown in Appendix A.1 of [JWS]. 332 3.3. Digital Signature with RSASSA-PKCS1-V1_5 334 This section defines the use of the RSASSA-PKCS1-V1_5 digital 335 signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447] 336 (commonly known as PKCS #1), using SHA-2 [SHS] hash functions. 338 A key of size 2048 bits or larger MUST be used with these algorithms. 340 The RSASSA-PKCS1-V1_5 SHA-256 digital signature is generated as 341 follows: Generate a digital signature of the JWS Signing Input using 342 RSASSA-PKCS1-V1_5-SIGN and the SHA-256 hash function with the desired 343 private key. This is the JWS Signature value. 345 The following "alg" (algorithm) Header Parameter values are used to 346 indicate that the JWS Signature is a digital signature value computed 347 using the corresponding algorithm: 349 +---------------------+--------------------------------+ 350 | alg Parameter Value | Digital Signature Algorithm | 351 +---------------------+--------------------------------+ 352 | RS256 | RSASSA-PKCS-v1_5 using SHA-256 | 353 | RS384 | RSASSA-PKCS-v1_5 using SHA-384 | 354 | RS512 | RSASSA-PKCS-v1_5 using SHA-512 | 355 +---------------------+--------------------------------+ 357 The RSASSA-PKCS1-V1_5 SHA-256 digital signature for a JWS is 358 validated as follows: Submit the JWS Signing Input, the JWS 359 Signature, and the public key corresponding to the private key used 360 by the signer to the RSASSA-PKCS1-V1_5-VERIFY algorithm using SHA-256 361 as the hash function. 363 Signing and validation with the RSASSA-PKCS1-V1_5 SHA-384 and RSASSA- 364 PKCS1-V1_5 SHA-512 algorithms is performed identically to the 365 procedure for RSASSA-PKCS1-V1_5 SHA-256 -- just using the 366 corresponding hash algorithms instead of SHA-256. 368 An example using this algorithm is shown in Appendix A.2 of [JWS]. 370 3.4. Digital Signature with ECDSA 372 The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides 373 for the use of Elliptic Curve cryptography, which is able to provide 374 equivalent security to RSA cryptography but using shorter key sizes 375 and with greater processing speed. This means that ECDSA digital 376 signatures will be substantially smaller in terms of length than 377 equivalently strong RSA digital signatures. 379 This specification defines the use of ECDSA with the P-256 curve and 380 the SHA-256 cryptographic hash function, ECDSA with the P-384 curve 381 and the SHA-384 hash function, and ECDSA with the P-521 curve and the 382 SHA-512 hash function. The P-256, P-384, and P-521 curves are 383 defined in [DSS]. 385 The ECDSA P-256 SHA-256 digital signature is generated as follows: 387 1. Generate a digital signature of the JWS Signing Input using ECDSA 388 P-256 SHA-256 with the desired private key. The output will be 389 the pair (R, S), where R and S are 256 bit unsigned integers. 391 2. Turn R and S into octet sequences in big endian order, with each 392 array being be 32 octets long. The octet sequence 393 representations MUST NOT be shortened to omit any leading zero 394 octets contained in the values. 396 3. Concatenate the two octet sequences in the order R and then S. 397 (Note that many ECDSA implementations will directly produce this 398 concatenation as their output.) 400 4. The resulting 64 octet sequence is the JWS Signature value. 402 The following "alg" (algorithm) Header Parameter values are used to 403 indicate that the JWS Signature is a digital signature value computed 404 using the corresponding algorithm: 406 +---------------------+-------------------------------+ 407 | alg Parameter Value | Digital Signature Algorithm | 408 +---------------------+-------------------------------+ 409 | ES256 | ECDSA using P-256 and SHA-256 | 410 | ES384 | ECDSA using P-384 and SHA-384 | 411 | ES512 | ECDSA using P-521 and SHA-512 | 412 +---------------------+-------------------------------+ 414 The ECDSA P-256 SHA-256 digital signature for a JWS is validated as 415 follows: 417 1. The JWS Signature value MUST be a 64 octet sequence. If it is 418 not a 64 octet sequence, the validation has failed. 420 2. Split the 64 octet sequence into two 32 octet sequences. The 421 first octet sequence represents R and the second S. The values R 422 and S are represented as octet sequences using the Integer-to- 423 OctetString Conversion defined in Section 2.3.7 of SEC1 [SEC1] 424 (in big endian octet order). 426 3. Submit the JWS Signing Input R, S and the public key (x, y) to 427 the ECDSA P-256 SHA-256 validator. 429 Signing and validation with the ECDSA P-384 SHA-384 and ECDSA P-521 430 SHA-512 algorithms is performed identically to the procedure for 431 ECDSA P-256 SHA-256 -- just using the corresponding hash algorithms 432 with correspondingly larger result values. For ECDSA P-384 SHA-384, 433 R and S will be 384 bits each, resulting in a 96 octet sequence. For 434 ECDSA P-521 SHA-512, R and S will be 521 bits each, resulting in a 435 132 octet sequence. 437 Examples using these algorithms are shown in Appendices A.3 and A.4 438 of [JWS]. 440 3.5. Digital Signature with RSASSA-PSS 442 This section defines the use of the RSASSA-PSS digital signature 443 algorithm as defined in Section 8.1 of RFC 3447 [RFC3447] with the 444 MGF1 mask generation function and SHA-2 hash functions, always using 445 the same hash function for both the RSASSA-PSS hash function and the 446 MGF1 hash function. The size of the salt value is the same size as 447 the hash function output. All other algorithm parameters use the 448 defaults specified in Section A.2.3 of RFC 3447. 450 A key of size 2048 bits or larger MUST be used with this algorithm. 452 The RSASSA-PSS SHA-256 digital signature is generated as follows: 453 Generate a digital signature of the JWS Signing Input using RSASSA- 454 PSS-SIGN, the SHA-256 hash function, and the MGF1 mask generation 455 function with SHA-256 with the desired private key. This is the JWS 456 signature value. 458 The following "alg" (algorithm) Header Parameter values are used to 459 indicate that the JWS Signature is a digital signature value computed 460 using the corresponding algorithm: 462 +---------------------+---------------------------------------------+ 463 | alg Parameter Value | Digital Signature Algorithm | 464 +---------------------+---------------------------------------------+ 465 | PS256 | RSASSA-PSS using SHA-256 and MGF1 with | 466 | | SHA-256 | 467 | PS384 | RSASSA-PSS using SHA-384 and MGF1 with | 468 | | SHA-384 | 469 | PS512 | RSASSA-PSS using SHA-512 and MGF1 with | 470 | | SHA-512 | 471 +---------------------+---------------------------------------------+ 473 The RSASSA-PSS SHA-256 digital signature for a JWS is validated as 474 follows: Submit the JWS Signing Input, the JWS Signature, and the 475 public key corresponding to the private key used by the signer to the 476 RSASSA-PSS-VERIFY algorithm using SHA-256 as the hash function and 477 using MGF1 as the mask generation function with SHA-256. 479 Signing and validation with the RSASSA-PSS SHA-384 and RSASSA-PSS 480 SHA-512 algorithms is performed identically to the procedure for 481 RSASSA-PSS SHA-256 -- just using the alternative hash algorithm in 482 both roles. 484 3.6. Using the Algorithm "none" 486 JWSs MAY also be created that do not provide integrity protection. 487 Such a JWS is called a "Plaintext JWS". A Plaintext JWS MUST use the 488 "alg" value "none", and is formatted identically to other JWSs, but 489 MUST use the empty octet sequence as its JWS Signature value. 490 Receivers MUST verify that the JWS Signature value is the empty octet 491 sequence. See Section 8.5 for security considerations associated 492 with using this algorithm. 494 4. Cryptographic Algorithms for Key Management 496 JWE uses cryptographic algorithms to encrypt or determine the Content 497 Encryption Key (CEK). 499 4.1. "alg" (Algorithm) Header Parameter Values for JWE 501 The table below is the set of "alg" (algorithm) Header Parameter 502 values that are defined by this specification for use with JWE. 503 These algorithms are used to encrypt the CEK, producing the JWE 504 Encrypted Key, or to use key agreement to agree upon the CEK. 506 +-------------------+-----------------+------------+----------------+ 507 | alg Parameter | Key Management | Additional | Implementation | 508 | Value | Algorithm | Header | Requirements | 509 | | | Parameters | | 510 +-------------------+-----------------+------------+----------------+ 511 | RSA1_5 | RSAES-PKCS1-V1_ | (none) | Required | 512 | | 5 | | | 513 | RSA-OAEP | RSAES OAEP | (none) | Optional | 514 | | using default | | | 515 | | parameters | | | 516 | RSA-OAEP-256 | RSAES OAEP | (none) | Optional | 517 | | using SHA-256 | | | 518 | | and MGF1 with | | | 519 | | SHA-256 | | | 520 | A128KW | AES Key Wrap | (none) | Recommended | 521 | | with default | | | 522 | | initial value | | | 523 | | using 128 bit | | | 524 | | key | | | 525 | A192KW | AES Key Wrap | (none) | Optional | 526 | | with default | | | 527 | | initial value | | | 528 | | using 192 bit | | | 529 | | key | | | 530 | A256KW | AES Key Wrap | (none) | Recommended | 531 | | with default | | | 532 | | initial value | | | 533 | | using 256 bit | | | 534 | | key | | | 535 | dir | Direct use of a | (none) | Recommended | 536 | | shared | | | 537 | | symmetric key | | | 538 | | as the CEK | | | 539 | ECDH-ES | Elliptic Curve | "epk", | Recommended+ | 540 | | Diffie-Hellman | "apu", | | 541 | | Ephemeral | "apv" | | 542 | | Static key | | | 543 | | agreement using | | | 544 | | Concat KDF | | | 545 | ECDH-ES+A128KW | ECDH-ES using | "epk", | Recommended | 546 | | Concat KDF and | "apu", | | 547 | | CEK wrapped | "apv" | | 548 | | with "A128KW" | | | 549 | ECDH-ES+A192KW | ECDH-ES using | "epk", | Optional | 550 | | Concat KDF and | "apu", | | 551 | | CEK wrapped | "apv" | | 552 | | with "A192KW" | | | 553 | ECDH-ES+A256KW | ECDH-ES using | "epk", | Recommended | 554 | | Concat KDF and | "apu", | | 555 | | CEK wrapped | "apv" | | 556 | | with "A256KW" | | | 557 | A128GCMKW | Key wrapping | "iv", | Optional | 558 | | with AES GCM | "tag" | | 559 | | using 128 bit | | | 560 | | key | | | 561 | A192GCMKW | Key wrapping | "iv", | Optional | 562 | | with AES GCM | "tag" | | 563 | | using 192 bit | | | 564 | | key | | | 565 | A256GCMKW | Key wrapping | "iv", | Optional | 566 | | with AES GCM | "tag" | | 567 | | using 256 bit | | | 568 | | key | | | 569 | PBES2-HS256+A128K | PBES2 with HMAC | "p2s", | Optional | 570 | W | SHA-256 and | "p2c" | | 571 | | "A128KW" | | | 572 | | wrapping | | | 573 | PBES2-HS384+A192K | PBES2 with HMAC | "p2s", | Optional | 574 | W | SHA-384 and | "p2c" | | 575 | | "A192KW" | | | 576 | | wrapping | | | 577 | PBES2-HS512+A256K | PBES2 with HMAC | "p2s", | Optional | 578 | W | SHA-512 and | "p2c" | | 579 | | "A256KW" | | | 580 | | wrapping | | | 581 +-------------------+-----------------+------------+----------------+ 583 The Additional Header Parameters column indicates what additional 584 Header Parameters are used by the algorithm, beyond "alg", which all 585 use. All but "dir" and "ECDH-ES" also produce a JWE Encrypted Key 586 value. 588 The use of "+" in the Implementation Requirements indicates that the 589 requirement strength is likely to be increased in a future version of 590 the specification. 592 See Appendix A.2 for a table cross-referencing the JWE "alg" 593 (algorithm) values defined in this specification with the equivalent 594 identifiers used by other standards and software packages. 596 4.2. Key Encryption with RSAES-PKCS1-V1_5 598 This section defines the specifics of encrypting a JWE CEK with 599 RSAES-PKCS1-V1_5 [RFC3447]. The "alg" Header Parameter value 600 "RSA1_5" is used for this algorithm. 602 A key of size 2048 bits or larger MUST be used with this algorithm. 604 An example using this algorithm is shown in Appendix A.2 of [JWE]. 606 4.3. Key Encryption with RSAES OAEP 608 This section defines the specifics of encrypting a JWE CEK with RSAES 609 using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447]. Two 610 sets of parameters for using OAEP are defined, which use different 611 hash functions. In the first case, the default parameters specified 612 by RFC 3447 in Section A.2.1 are used. (Those default parameters are 613 the SHA-1 hash function and the MGF1 with SHA-1 mask generation 614 function.) In the second case, the SHA-256 hash function and the 615 MGF1 with SHA-256 mask generation function are used. 617 The following "alg" (algorithm) Header Parameter values are used to 618 indicate that the JWE Encrypted Key is the result of encrypting the 619 CEK using the corresponding algorithm: 621 +---------------------+---------------------------------------------+ 622 | alg Parameter Value | Key Management Algorithm | 623 +---------------------+---------------------------------------------+ 624 | RSA-OAEP | RSAES OAEP using default parameters | 625 | RSA-OAEP-256 | RSAES OAEP using SHA-256 and MGF1 with | 626 | | SHA-256 | 627 +---------------------+---------------------------------------------+ 629 A key of size 2048 bits or larger MUST be used with these algorithms. 631 An example using RSAES OAEP with the default parameters is shown in 632 Appendix A.1 of [JWE]. 634 4.4. Key Wrapping with AES Key Wrap 636 This section defines the specifics of encrypting a JWE CEK with the 637 Advanced Encryption Standard (AES) Key Wrap Algorithm [RFC3394] using 638 the default initial value specified in Section 2.2.3.1. 640 The following "alg" (algorithm) Header Parameter values are used to 641 indicate that the JWE Encrypted Key is the result of encrypting the 642 CEK using the corresponding algorithm and key size: 644 +------------------+------------------------------------------------+ 645 | alg Parameter | Key Management Algorithm | 646 | Value | | 647 +------------------+------------------------------------------------+ 648 | A128KW | AES Key Wrap with default initial value using | 649 | | 128 bit key | 650 | A192KW | AES Key Wrap with default initial value using | 651 | | 192 bit key | 652 | A256KW | AES Key Wrap with default initial value using | 653 | | 256 bit key | 654 +------------------+------------------------------------------------+ 656 An example using this algorithm is shown in Appendix A.3 of [JWE]. 658 4.5. Direct Encryption with a Shared Symmetric Key 660 This section defines the specifics of directly performing symmetric 661 key encryption without performing a key wrapping step. In this case, 662 the shared symmetric key is used directly as the Content Encryption 663 Key (CEK) value for the "enc" algorithm. An empty octet sequence is 664 used as the JWE Encrypted Key value. The "alg" Header Parameter 665 value "dir" is used in this case. 667 Refer to the security considerations on key lifetimes in Section 8.2 668 and AES GCM in Section 8.4 when considering utilizing direct 669 encryption. 671 4.6. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static 672 (ECDH-ES) 674 This section defines the specifics of key agreement with Elliptic 675 Curve Diffie-Hellman Ephemeral Static [RFC6090], in combination with 676 the Concat KDF, as defined in Section 5.8.1 of [NIST.800-56A]. The 677 key agreement result can be used in one of two ways: 679 1. directly as the Content Encryption Key (CEK) for the "enc" 680 algorithm, in the Direct Key Agreement mode, or 682 2. as a symmetric key used to wrap the CEK with the "A128KW", 683 "A192KW", or "A256KW" algorithms, in the Key Agreement with Key 684 Wrapping mode. 686 A new ephemeral public key value MUST be generated for each key 687 agreement operation. 689 In Direct Key Agreement mode, the output of the Concat KDF MUST be a 690 key of the same length as that used by the "enc" algorithm. In this 691 case, the empty octet sequence is used as the JWE Encrypted Key 692 value. The "alg" Header Parameter value "ECDH-ES" is used in the 693 Direct Key Agreement mode. 695 In Key Agreement with Key Wrapping mode, the output of the Concat KDF 696 MUST be a key of the length needed for the specified key wrapping 697 algorithm. In this case, the JWE Encrypted Key is the CEK wrapped 698 with the agreed upon key. 700 The following "alg" (algorithm) Header Parameter values are used to 701 indicate that the JWE Encrypted Key is the result of encrypting the 702 CEK using the result of the key agreement algorithm as the key 703 encryption key for the corresponding key wrapping algorithm: 705 +-------------------+-----------------------------------------------+ 706 | alg Parameter | Key Management Algorithm | 707 | Value | | 708 +-------------------+-----------------------------------------------+ 709 | ECDH-ES+A128KW | ECDH-ES using Concat KDF and CEK wrapped with | 710 | | "A128KW" | 711 | ECDH-ES+A192KW | ECDH-ES using Concat KDF and CEK wrapped with | 712 | | "A192KW" | 713 | ECDH-ES+A256KW | ECDH-ES using Concat KDF and CEK wrapped with | 714 | | "A256KW" | 715 +-------------------+-----------------------------------------------+ 717 4.6.1. Header Parameters Used for ECDH Key Agreement 719 The following Header Parameter names are used for key agreement as 720 defined below. 722 4.6.1.1. "epk" (Ephemeral Public Key) Header Parameter 724 The "epk" (ephemeral public key) value created by the originator for 725 the use in key agreement algorithms. This key is represented as a 726 JSON Web Key [JWK] public key value. It MUST contain only public key 727 parameters and SHOULD contain only the minimum JWK parameters 728 necessary to represent the key; other JWK parameters included can be 729 checked for consistency and honored or can be ignored. This Header 730 Parameter MUST be present and MUST be understood and processed by 731 implementations when these algorithms are used. 733 4.6.1.2. "apu" (Agreement PartyUInfo) Header Parameter 735 The "apu" (agreement PartyUInfo) value for key agreement algorithms 736 using it (such as "ECDH-ES"), represented as a base64url encoded 737 string. When used, the PartyUInfo value contains information about 738 the sender. Use of this Header Parameter is OPTIONAL. This Header 739 Parameter MUST be understood and processed by implementations when 740 these algorithms are used. 742 4.6.1.3. "apv" (Agreement PartyVInfo) Header Parameter 744 The "apv" (agreement PartyVInfo) value for key agreement algorithms 745 using it (such as "ECDH-ES"), represented as a base64url encoded 746 string. When used, the PartyVInfo value contains information about 747 the receiver. Use of this Header Parameter is OPTIONAL. This Header 748 Parameter MUST be understood and processed by implementations when 749 these algorithms are used. 751 4.6.2. Key Derivation for ECDH Key Agreement 753 The key derivation process derives the agreed upon key from the 754 shared secret Z established through the ECDH algorithm, per Section 755 6.2.2.2 of [NIST.800-56A]. 757 Key derivation is performed using the Concat KDF, as defined in 758 Section 5.8.1 of [NIST.800-56A], where the Digest Method is SHA-256. 759 The Concat KDF parameters are set as follows: 761 Z 762 This is set to the representation of the shared secret Z as an 763 octet sequence. 765 keydatalen 766 This is set to the number of bits in the desired output key. For 767 "ECDH-ES", this is length of the key used by the "enc" algorithm. 768 For "ECDH-ES+A128KW", "ECDH-ES+A192KW", and "ECDH-ES+A256KW", this 769 is 128, 192, and 256, respectively. 771 AlgorithmID 772 The AlgorithmID value is of the form Datalen || Data, where Data 773 is a variable-length string of zero or more octets, and Datalen is 774 a fixed-length, big endian 32 bit counter that indicates the 775 length (in octets) of Data. In the Direct Key Agreement case, 776 Data is set to the octets of the UTF-8 representation of the "enc" 777 Header Parameter value. In the Key Agreement with Key Wrapping 778 case, Data is set to the octets of the UTF-8 representation of the 779 "alg" Header Parameter value. 781 PartyUInfo 782 The PartyUInfo value is of the form Datalen || Data, where Data is 783 a variable-length string of zero or more octets, and Datalen is a 784 fixed-length, big endian 32 bit counter that indicates the length 785 (in octets) of Data. If an "apu" (agreement PartyUInfo) Header 786 Parameter is present, Data is set to the result of base64url 787 decoding the "apu" value and Datalen is set to the number of 788 octets in Data. Otherwise, Datalen is set to 0 and Data is set to 789 the empty octet sequence. 791 PartyVInfo 792 The PartyVInfo value is of the form Datalen || Data, where Data is 793 a variable-length string of zero or more octets, and Datalen is a 794 fixed-length, big endian 32 bit counter that indicates the length 795 (in octets) of Data. If an "apv" (agreement PartyVInfo) Header 796 Parameter is present, Data is set to the result of base64url 797 decoding the "apv" value and Datalen is set to the number of 798 octets in Data. Otherwise, Datalen is set to 0 and Data is set to 799 the empty octet sequence. 801 SuppPubInfo 802 This is set to the keydatalen represented as a 32 bit big endian 803 integer. 805 SuppPrivInfo 806 This is set to the empty octet sequence. 808 Applications need to specify how the "apu" and "apv" parameters are 809 used for that application. The "apu" and "apv" values MUST be 810 distinct, when used. Applications wishing to conform to 811 [NIST.800-56A] need to provide values that meet the requirements of 812 that document, e.g., by using values that identify the sender and 813 recipient. Alternatively, applications MAY conduct key derivation in 814 a manner similar to The Diffie-Hellman Key Agreement Method 815 [RFC2631]: In that case, the "apu" field MAY either be omitted or 816 represent a random 512-bit value (analogous to PartyAInfo in 817 Ephemeral-Static mode in RFC 2631) and the "apv" field SHOULD NOT be 818 present. 820 See Appendix C for an example key agreement computation using this 821 method. 823 4.7. Key Encryption with AES GCM 825 This section defines the specifics of encrypting a JWE Content 826 Encryption Key (CEK) with Advanced Encryption Standard (AES) in 827 Galois/Counter Mode (GCM) [AES] [NIST.800-38D]. 829 Use of an Initialization Vector of size 96 bits is REQUIRED with this 830 algorithm. The Initialization Vector is represented in base64url 831 encoded form as the "iv" (initialization vector) Header Parameter 832 value. 834 The Additional Authenticated Data value used is the empty octet 835 string. 837 The requested size of the Authentication Tag output MUST be 128 bits, 838 regardless of the key size. 840 The JWE Encrypted Key value is the Ciphertext output. 842 The Authentication Tag output is represented in base64url encoded 843 form as the "tag" (authentication tag) Header Parameter value. 845 The following "alg" (algorithm) Header Parameter values are used to 846 indicate that the JWE Encrypted Key is the result of encrypting the 847 CEK using the corresponding algorithm and key size: 849 +---------------------+---------------------------------------------+ 850 | alg Parameter Value | Key Management Algorithm | 851 +---------------------+---------------------------------------------+ 852 | A128GCMKW | Key wrapping with AES GCM using 128 bit key | 853 | A192GCMKW | Key wrapping with AES GCM using 192 bit key | 854 | A256GCMKW | Key wrapping with AES GCM using 256 bit key | 855 +---------------------+---------------------------------------------+ 857 4.7.1. Header Parameters Used for AES GCM Key Encryption 859 The following Header Parameters are used for AES GCM key encryption. 861 4.7.1.1. "iv" (Initialization Vector) Header Parameter 863 The "iv" (initialization vector) Header Parameter value is the 864 base64url encoded representation of the Initialization Vector value 865 used for the key encryption operation. This Header Parameter MUST be 866 present and MUST be understood and processed by implementations when 867 these algorithms are used. 869 4.7.1.2. "tag" (Authentication Tag) Header Parameter 871 The "tag" (authentication tag) Header Parameter value is the 872 base64url encoded representation of the Authentication Tag value 873 resulting from the key encryption operation. This Header Parameter 874 MUST be present and MUST be understood and processed by 875 implementations when these algorithms are used. 877 4.8. Key Encryption with PBES2 879 This section defines the specifies of performing password-based 880 encryption of a JWE CEK, by first deriving a key encryption key from 881 a user-supplied password using PBES2 schemes as specified in Section 882 6.2 of [RFC2898], then by encrypting the JWE CEK using the derived 883 key. 885 These algorithms use HMAC SHA-2 algorithms as the Pseudo-Random 886 Function (PRF) for the PBKDF2 key derivation and AES Key Wrap 887 [RFC3394] for the encryption scheme. The PBES2 password input is an 888 octet sequence; if the password to be used is represented as a text 889 string rather than an octet sequence, the UTF-8 encoding of the text 890 string MUST be used as the octet sequence. The salt parameter MUST 891 be computed from the "p2s" (PBES2 salt input) Header Parameter value 892 and the "alg" (algorithm) Header Parameter value as specified in the 893 "p2s" definition below. The iteration count parameter MUST be 894 provided as the "p2c" Header Parameter value. The algorithms 895 respectively use HMAC SHA-256, HMAC SHA-384, and HMAC SHA-512 as the 896 PRF and use 128, 192, and 256 bit AES Key Wrap keys. Their derived- 897 key lengths respectively are 16, 24, and 32 octets. 899 The following "alg" (algorithm) Header Parameter values are used to 900 indicate that the JWE Encrypted Key is the result of encrypting the 901 CEK using the result of the corresponding password-based encryption 902 algorithm as the key encryption key for the corresponding key 903 wrapping algorithm: 905 +---------------------+---------------------------------------------+ 906 | alg Parameter Value | Key Management Algorithm | 907 +---------------------+---------------------------------------------+ 908 | PBES2-HS256+A128KW | PBES2 with HMAC SHA-256 and "A128KW" | 909 | | wrapping | 910 | PBES2-HS384+A192KW | PBES2 with HMAC SHA-384 and "A192KW" | 911 | | wrapping | 912 | PBES2-HS512+A256KW | PBES2 with HMAC SHA-512 and "A256KW" | 913 | | wrapping | 914 +---------------------+---------------------------------------------+ 916 See Appendix C of JSON Web Key (JWK) [JWK] for an example key 917 encryption computation using "PBES2-HS256+A128KW". 919 4.8.1. Header Parameters Used for PBES2 Key Encryption 921 The following Header Parameters are used for Key Encryption with 922 PBES2. 924 4.8.1.1. "p2s" (PBES2 salt input) Parameter 926 The "p2s" (PBES2 salt input) Header Parameter encodes a Salt Input 927 value, which is used as part of the PBKDF2 salt value. The "p2s" 928 value is BASE64URL(Salt Input). This Header Parameter MUST be 929 present and MUST be understood and processed by implementations when 930 these algorithms are used. 932 The salt expands the possible keys that can be derived from a given 933 password. A Salt Input value containing 8 or more octets MUST be 934 used. A new Salt Input value MUST be generated randomly for every 935 encryption operation; see [RFC4086] for considerations on generating 936 random values. The salt value used is (UTF8(Alg) || 0x00 || Salt 937 Input), where Alg is the "alg" Header Parameter value. 939 4.8.1.2. "p2c" (PBES2 count) Parameter 941 The "p2c" (PBES2 count) Header Parameter contains the PBKDF2 942 iteration count, represented as a positive integer. This Header 943 Parameter MUST be present and MUST be understood and processed by 944 implementations when these algorithms are used. 946 The iteration count adds computational expense, ideally compounded by 947 the possible range of keys introduced by the salt. A minimum 948 iteration count of 1000 is RECOMMENDED. 950 5. Cryptographic Algorithms for Content Encryption 952 JWE uses cryptographic algorithms to encrypt the Plaintext. 954 5.1. "enc" (Encryption Algorithm) Header Parameter Values for JWE 956 The table below is the set of "enc" (encryption algorithm) Header 957 Parameter values that are defined by this specification for use with 958 JWE. These algorithms are used to encrypt the Plaintext, which 959 produces the Ciphertext. 961 +-------------+------------------------+------------+---------------+ 962 | enc | Content Encryption | Additional | Implementatio | 963 | Parameter | Algorithm | Header | nRequirements | 964 | Value | | Parameters | | 965 +-------------+------------------------+------------+---------------+ 966 | A128CBC-HS2 | AES_128_CBC_HMAC_SHA_2 | (none) | Required | 967 | 56 | 56 authenticated | | | 968 | | encryption algorithm, | | | 969 | | as defined in | | | 970 | | Section 5.2.3 | | | 971 | A192CBC-HS3 | AES_192_CBC_HMAC_SHA_3 | (none) | Optional | 972 | 84 | 84 authenticated | | | 973 | | encryption algorithm, | | | 974 | | as defined in | | | 975 | | Section 5.2.4 | | | 976 | A256CBC-HS5 | AES_256_CBC_HMAC_SHA_5 | (none) | Required | 977 | 12 | 12 authenticated | | | 978 | | encryption algorithm, | | | 979 | | as defined in | | | 980 | | Section 5.2.5 | | | 981 | A128GCM | AES GCM using 128 bit | (none) | Recommended | 982 | | key | | | 983 | A192GCM | AES GCM using 192 bit | (none) | Optional | 984 | | key | | | 985 | A256GCM | AES GCM using 256 bit | (none) | Recommended | 986 | | key | | | 987 +-------------+------------------------+------------+---------------+ 989 The Additional Header Parameters column indicates what additional 990 Header Parameters are used by the algorithm, beyond "enc", which all 991 use. All also use a JWE Initialization Vector value and produce JWE 992 Ciphertext and JWE Authentication Tag values. 994 See Appendix A.3 for a table cross-referencing the JWE "enc" 995 (encryption algorithm) values defined in this specification with the 996 equivalent identifiers used by other standards and software packages. 998 5.2. AES_CBC_HMAC_SHA2 Algorithms 1000 This section defines a family of authenticated encryption algorithms 1001 built using a composition of Advanced Encryption Standard (AES) in 1002 Cipher Block Chaining (CBC) mode with PKCS #5 padding [AES] 1003 [NIST.800-38A] operations and HMAC [RFC2104] [SHS] operations. This 1004 algorithm family is called AES_CBC_HMAC_SHA2. It also defines three 1005 instances of this family, the first using 128 bit CBC keys and HMAC 1006 SHA-256, the second using 192 bit CBC keys and HMAC SHA-384, and the 1007 third using 256 bit CBC keys and HMAC SHA-512. Test cases for these 1008 algorithms can be found in Appendix B. 1010 These algorithms are based upon Authenticated Encryption with AES-CBC 1011 and HMAC-SHA [I-D.mcgrew-aead-aes-cbc-hmac-sha2], performing the same 1012 cryptographic computations, but with the Initialization Vector and 1013 Authentication Tag values remaining separate, rather than being 1014 concatenated with the Ciphertext value in the output representation. 1015 This option is discussed in Appendix B of that specification. This 1016 algorithm family is a generalization of the algorithm family in 1017 [I-D.mcgrew-aead-aes-cbc-hmac-sha2], and can be used to implement 1018 those algorithms. 1020 5.2.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 1022 We use the following notational conventions. 1024 CBC-PKCS5-ENC(X, P) denotes the AES CBC encryption of P using PKCS 1025 #5 padding using the cipher with the key X. 1027 MAC(Y, M) denotes the application of the Message Authentication 1028 Code (MAC) to the message M, using the key Y. 1030 5.2.2. Generic AES_CBC_HMAC_SHA2 Algorithm 1032 This section defines AES_CBC_HMAC_SHA2 in a manner that is 1033 independent of the AES CBC key size or hash function to be used. 1034 Section 5.2.2.1 and Section 5.2.2.2 define the generic encryption and 1035 decryption algorithms. Section 5.2.3 and Section 5.2.5 define 1036 instances of AES_CBC_HMAC_SHA2 that specify those details. 1038 5.2.2.1. AES_CBC_HMAC_SHA2 Encryption 1040 The authenticated encryption algorithm takes as input four octet 1041 strings: a secret key K, a plaintext P, additional authenticated data 1042 A, and an initialization vector IV. The authenticated ciphertext 1043 value E and the authentication tag value T are provided as outputs. 1044 The data in the plaintext are encrypted and authenticated, and the 1045 additional authenticated data are authenticated, but not encrypted. 1047 The encryption process is as follows, or uses an equivalent set of 1048 steps: 1050 1. The secondary keys MAC_KEY and ENC_KEY are generated from the 1051 input key K as follows. Each of these two keys is an octet 1052 string. 1054 MAC_KEY consists of the initial MAC_KEY_LEN octets of K, in 1055 order. 1057 ENC_KEY consists of the final ENC_KEY_LEN octets of K, in 1058 order. 1060 Here we denote the number of octets in the MAC_KEY as 1061 MAC_KEY_LEN, and the number of octets in ENC_KEY as ENC_KEY_LEN; 1062 the values of these parameters are specified by the AEAD 1063 algorithms (in Section 5.2.3 and Section 5.2.5). The number of 1064 octets in the input key K is the sum of MAC_KEY_LEN and 1065 ENC_KEY_LEN. When generating the secondary keys from K, MAC_KEY 1066 and ENC_KEY MUST NOT overlap. Note that the MAC key comes before 1067 the encryption key in the input key K; this is in the opposite 1068 order of the algorithm names in the identifier 1069 "AES_CBC_HMAC_SHA2". 1071 2. The Initialization Vector (IV) used is a 128 bit value generated 1072 randomly or pseudorandomly for use in the cipher. 1074 3. The plaintext is CBC encrypted using PKCS #5 padding using 1075 ENC_KEY as the key, and the IV. We denote the ciphertext output 1076 from this step as E. 1078 4. The octet string AL is equal to the number of bits in A expressed 1079 as a 64-bit unsigned integer in network byte order. 1081 5. A message authentication tag T is computed by applying HMAC 1082 [RFC2104] to the following data, in order: 1084 the additional authenticated data A, 1086 the initialization vector IV, 1088 the ciphertext E computed in the previous step, and 1090 the octet string AL defined above. 1092 The string MAC_KEY is used as the MAC key. We denote the output 1093 of the MAC computed in this step as M. The first T_LEN bits of M 1094 are used as T. 1096 6. The Ciphertext E and the Authentication Tag T are returned as the 1097 outputs of the authenticated encryption. 1099 The encryption process can be illustrated as follows. Here K, P, A, 1100 IV, and E denote the key, plaintext, additional authenticated data, 1101 initialization vector, and ciphertext, respectively. 1103 MAC_KEY = initial MAC_KEY_LEN bytes of K, 1104 ENC_KEY = final ENC_KEY_LEN bytes of K, 1106 E = CBC-PKCS5-ENC(ENC_KEY, P), 1108 M = MAC(MAC_KEY, A || IV || E || AL), 1110 T = initial T_LEN bytes of M. 1112 5.2.2.2. AES_CBC_HMAC_SHA2 Decryption 1114 The authenticated decryption operation has four inputs: K, A, E, and 1115 T as defined above. It has only a single output, either a plaintext 1116 value P or a special symbol FAIL that indicates that the inputs are 1117 not authentic. The authenticated decryption algorithm is as follows, 1118 or uses an equivalent set of steps: 1120 1. The secondary keys MAC_KEY and ENC_KEY are generated from the 1121 input key K as in Step 1 of Section 5.2.2.1. 1123 2. The integrity and authenticity of A and E are checked by 1124 computing an HMAC with the inputs as in Step 5 of 1125 Section 5.2.2.1. The value T, from the previous step, is 1126 compared to the first MAC_KEY length bits of the HMAC output. If 1127 those values are identical, then A and E are considered valid, 1128 and processing is continued. Otherwise, all of the data used in 1129 the MAC validation are discarded, and the AEAD decryption 1130 operation returns an indication that it failed, and the operation 1131 halts. (But see Section 11.2 of [JWE] for security 1132 considerations on thwarting timing attacks.) 1134 3. The value E is decrypted and the PKCS #5 padding is removed. The 1135 value IV is used as the initialization vector. The value ENC_KEY 1136 is used as the decryption key. 1138 4. The plaintext value is returned. 1140 5.2.3. AES_128_CBC_HMAC_SHA_256 1142 This algorithm is a concrete instantiation of the generic 1143 AES_CBC_HMAC_SHA2 algorithm above. It uses the HMAC message 1144 authentication code [RFC2104] with the SHA-256 hash function [SHS] to 1145 provide message authentication, with the HMAC output truncated to 128 1146 bits, corresponding to the HMAC-SHA-256-128 algorithm defined in 1147 [RFC4868]. For encryption, it uses AES in the Cipher Block Chaining 1148 (CBC) mode of operation as defined in Section 6.2 of [NIST.800-38A], 1149 with PKCS #5 padding and a 128 bit initialization vector (IV) value. 1151 The AES_CBC_HMAC_SHA2 parameters specific to AES_128_CBC_HMAC_SHA_256 1152 are: 1154 The input key K is 32 octets long. 1156 ENC_KEY_LEN is 16 octets. 1158 MAC_KEY_LEN is 16 octets. 1160 The SHA-256 hash algorithm is used for the HMAC. 1162 The HMAC-SHA-256 output is truncated to T_LEN=16 octets, by 1163 stripping off the final 16 octets. 1165 5.2.4. AES_192_CBC_HMAC_SHA_384 1167 AES_192_CBC_HMAC_SHA_384 is based on AES_128_CBC_HMAC_SHA_256, but 1168 with the following differences: 1170 The input key K is 48 octets long instead of 32. 1172 ENC_KEY_LEN is 24 octets instead of 16. 1174 MAC_KEY_LEN is 24 octets instead of 16. 1176 SHA-384 is used for the HMAC instead of SHA-256. 1178 The HMAC SHA-384 value is truncated to T_LEN=24 octets instead of 1179 16. 1181 5.2.5. AES_256_CBC_HMAC_SHA_512 1183 AES_256_CBC_HMAC_SHA_512 is based on AES_128_CBC_HMAC_SHA_256, but 1184 with the following differences: 1186 The input key K is 64 octets long instead of 32. 1188 ENC_KEY_LEN is 32 octets instead of 16. 1190 MAC_KEY_LEN is 32 octets instead of 16. 1192 SHA-512 is used for the HMAC instead of SHA-256. 1194 The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of 1195 16. 1197 5.2.6. Content Encryption with AES_CBC_HMAC_SHA2 1199 This section defines the specifics of performing authenticated 1200 encryption with the AES_CBC_HMAC_SHA2 algorithms. 1202 The CEK is used as the secret key K. 1204 The following "enc" (encryption algorithm) Header Parameter values 1205 are used to indicate that the JWE Ciphertext and JWE Authentication 1206 Tag values have been computed using the corresponding algorithm: 1208 +---------------+---------------------------------------------------+ 1209 | enc Parameter | Content Encryption Algorithm | 1210 | Value | | 1211 +---------------+---------------------------------------------------+ 1212 | A128CBC-HS256 | AES_128_CBC_HMAC_SHA_256 authenticated encryption | 1213 | | algorithm, as defined in Section 5.2.3 | 1214 | A192CBC-HS384 | AES_192_CBC_HMAC_SHA_384 authenticated encryption | 1215 | | algorithm, as defined in Section 5.2.4 | 1216 | A256CBC-HS512 | AES_256_CBC_HMAC_SHA_512 authenticated encryption | 1217 | | algorithm, as defined in Section 5.2.5 | 1218 +---------------+---------------------------------------------------+ 1220 5.3. Content Encryption with AES GCM 1222 This section defines the specifics of performing authenticated 1223 encryption with Advanced Encryption Standard (AES) in Galois/Counter 1224 Mode (GCM) [AES] [NIST.800-38D]. 1226 The CEK is used as the encryption key. 1228 Use of an initialization vector of size 96 bits is REQUIRED with this 1229 algorithm. 1231 The requested size of the Authentication Tag output MUST be 128 bits, 1232 regardless of the key size. 1234 The following "enc" (encryption algorithm) Header Parameter values 1235 are used to indicate that the JWE Ciphertext and JWE Authentication 1236 Tag values have been computed using the corresponding algorithm and 1237 key size: 1239 +---------------------+------------------------------+ 1240 | enc Parameter Value | Content Encryption Algorithm | 1241 +---------------------+------------------------------+ 1242 | A128GCM | AES GCM using 128 bit key | 1243 | A192GCM | AES GCM using 192 bit key | 1244 | A256GCM | AES GCM using 256 bit key | 1245 +---------------------+------------------------------+ 1247 An example using this algorithm is shown in Appendix A.1 of [JWE]. 1249 6. Cryptographic Algorithms for Keys 1251 A JSON Web Key (JWK) [JWK] is a JSON data structure that represents a 1252 cryptographic key. These keys can be either asymmetric or symmetric. 1253 They can hold both public and private information about the key. 1254 This section defines the parameters for keys using the algorithms 1255 specified by this document. 1257 6.1. "kty" (Key Type) Parameter Values 1259 The table below is the set of "kty" (key type) parameter values that 1260 are defined by this specification for use in JWKs. 1262 +--------------+--------------------------------+-------------------+ 1263 | kty | Key Type | Implementation | 1264 | Parameter | | Requirements | 1265 | Value | | | 1266 +--------------+--------------------------------+-------------------+ 1267 | EC | Elliptic Curve [DSS] | Recommended+ | 1268 | RSA | RSA [RFC3447] | Required | 1269 | oct | Octet sequence (used to | Required | 1270 | | represent symmetric keys) | | 1271 +--------------+--------------------------------+-------------------+ 1273 The use of "+" in the Implementation Requirements indicates that the 1274 requirement strength is likely to be increased in a future version of 1275 the specification. 1277 6.2. Parameters for Elliptic Curve Keys 1279 JWKs can represent Elliptic Curve [DSS] keys. In this case, the 1280 "kty" member value MUST be "EC". 1282 6.2.1. Parameters for Elliptic Curve Public Keys 1284 An elliptic curve public key is represented by a pair of coordinates 1285 drawn from a finite field, which together define a point on an 1286 elliptic curve. The following members MUST be present for elliptic 1287 curve public keys: 1289 o "crv" 1290 o "x" 1291 o "y" 1293 SEC1 [SEC1] point compression is not supported for any values. 1295 6.2.1.1. "crv" (Curve) Parameter 1297 The "crv" (curve) member identifies the cryptographic curve used with 1298 the key. Curve values from [DSS] used by this specification are: 1300 o "P-256" 1301 o "P-384" 1302 o "P-521" 1304 These values are registered in the IANA JSON Web Key Elliptic Curve 1305 registry defined in Section 7.6. Additional "crv" values MAY be 1306 used, provided they are understood by implementations using that 1307 Elliptic Curve key. The "crv" value is a case-sensitive string. 1309 6.2.1.2. "x" (X Coordinate) Parameter 1311 The "x" (x coordinate) member contains the x coordinate for the 1312 elliptic curve point. It is represented as the base64url encoding of 1313 the octet string representation of the coordinate, as defined in 1314 Section 2.3.5 of SEC1 [SEC1]. The length of this octet string MUST 1315 be the full size of a coordinate for the curve specified in the "crv" 1316 parameter. For example, if the value of "crv" is "P-521", the octet 1317 string must be 66 octets long. 1319 6.2.1.3. "y" (Y Coordinate) Parameter 1321 The "y" (y coordinate) member contains the y coordinate for the 1322 elliptic curve point. It is represented as the base64url encoding of 1323 the octet string representation of the coordinate, as defined in 1324 Section 2.3.5 of SEC1 [SEC1]. The length of this octet string MUST 1325 be the full size of a coordinate for the curve specified in the "crv" 1326 parameter. For example, if the value of "crv" is "P-521", the octet 1327 string must be 66 octets long. 1329 6.2.2. Parameters for Elliptic Curve Private Keys 1331 In addition to the members used to represent Elliptic Curve public 1332 keys, the following member MUST be present to represent Elliptic 1333 Curve private keys. 1335 6.2.2.1. "d" (ECC Private Key) Parameter 1337 The "d" (ECC private key) member contains the Elliptic Curve private 1338 key value. It is represented as the base64url encoding of the octet 1339 string representation of the private key value, as defined in 1340 Sections C.4 and 2.3.7 of SEC1 [SEC1]. The length of this octet 1341 string MUST be ceiling(log-base-2(n)/8) octets (where n is the order 1342 of the curve). 1344 6.3. Parameters for RSA Keys 1346 JWKs can represent RSA [RFC3447] keys. In this case, the "kty" 1347 member value MUST be "RSA". 1349 6.3.1. Parameters for RSA Public Keys 1351 The following members MUST be present for RSA public keys. 1353 6.3.1.1. "n" (Modulus) Parameter 1355 The "n" (modulus) member contains the modulus value for the RSA 1356 public key. It is represented as the base64url encoding of the 1357 value's unsigned big endian representation as an octet sequence. The 1358 octet sequence MUST utilize the minimum number of octets to represent 1359 the value. 1361 6.3.1.2. "e" (Exponent) Parameter 1363 The "e" (exponent) member contains the exponent value for the RSA 1364 public key. It is represented as the base64url encoding of the 1365 value's unsigned big endian representation as an octet sequence. The 1366 octet sequence MUST utilize the minimum number of octets to represent 1367 the value. For instance, when representing the value 65537, the 1368 octet sequence to be base64url encoded MUST consist of the three 1369 octets [1, 0, 1]. 1371 6.3.2. Parameters for RSA Private Keys 1373 In addition to the members used to represent RSA public keys, the 1374 following members are used to represent RSA private keys. The 1375 parameter "d" is REQUIRED for RSA private keys. The others enable 1376 optimizations and SHOULD be included by producers of JWKs 1377 representing RSA private keys. If the producer includes any of the 1378 other private key parameters, then all of the others MUST be present, 1379 with the exception of "oth", which MUST only be present when more 1380 than two prime factors were used. The consumer of a JWK MAY choose 1381 to accept an RSA private key that does not contain a complete set of 1382 the private key parameters other than "d", including JWKs in which 1383 "d" is the only RSA private key parameter included. 1385 6.3.2.1. "d" (Private Exponent) Parameter 1387 The "d" (private exponent) member contains the private exponent value 1388 for the RSA private key. It is represented as the base64url encoding 1389 of the value's unsigned big endian representation as an octet 1390 sequence. The octet sequence MUST utilize the minimum number of 1391 octets to represent the value. 1393 6.3.2.2. "p" (First Prime Factor) Parameter 1395 The "p" (first prime factor) member contains the first prime factor, 1396 a positive integer. It is represented as the base64url encoding of 1397 the value's unsigned big endian representation as an octet sequence. 1398 The octet sequence MUST utilize the minimum number of octets to 1399 represent the value. 1401 6.3.2.3. "q" (Second Prime Factor) Parameter 1403 The "q" (second prime factor) member contains the second prime 1404 factor, a positive integer. It is represented as the base64url 1405 encoding of the value's unsigned big endian representation as an 1406 octet sequence. The octet sequence MUST utilize the minimum number 1407 of octets to represent the value. 1409 6.3.2.4. "dp" (First Factor CRT Exponent) Parameter 1411 The "dp" (first factor CRT exponent) member contains the Chinese 1412 Remainder Theorem (CRT) exponent of the first factor, a positive 1413 integer. It is represented as the base64url encoding of the value's 1414 unsigned big endian representation as an octet sequence. The octet 1415 sequence MUST utilize the minimum number of octets to represent the 1416 value. 1418 6.3.2.5. "dq" (Second Factor CRT Exponent) Parameter 1420 The "dq" (second factor CRT exponent) member contains the Chinese 1421 Remainder Theorem (CRT) exponent of the second factor, a positive 1422 integer. It is represented as the base64url encoding of the value's 1423 unsigned big endian representation as an octet sequence. The octet 1424 sequence MUST utilize the minimum number of octets to represent the 1425 value. 1427 6.3.2.6. "qi" (First CRT Coefficient) Parameter 1429 The "dp" (first CRT coefficient) member contains the Chinese 1430 Remainder Theorem (CRT) coefficient of the second factor, a positive 1431 integer. It is represented as the base64url encoding of the value's 1432 unsigned big endian representation as an octet sequence. The octet 1433 sequence MUST utilize the minimum number of octets to represent the 1434 value. 1436 6.3.2.7. "oth" (Other Primes Info) Parameter 1438 The "oth" (other primes info) member contains an array of information 1439 about any third and subsequent primes, should they exist. When only 1440 two primes have been used (the normal case), this parameter MUST be 1441 omitted. When three or more primes have been used, the number of 1442 array elements MUST be the number of primes used minus two. Each 1443 array element MUST be an object with the following members: 1445 6.3.2.7.1. "r" (Prime Factor) 1447 The "r" (prime factor) parameter within an "oth" array member 1448 represents the value of a subsequent prime factor, a positive 1449 integer. It is represented as the base64url encoding of the value's 1450 unsigned big endian representation as an octet sequence. The octet 1451 sequence MUST utilize the minimum number of octets to represent the 1452 value. 1454 6.3.2.7.2. "d" (Factor CRT Exponent) 1456 The "d" (Factor CRT Exponent) parameter within an "oth" array member 1457 represents the CRT exponent of the corresponding prime factor, a 1458 positive integer. It is represented as the base64url encoding of the 1459 value's unsigned big endian representation as an octet sequence. The 1460 octet sequence MUST utilize the minimum number of octets to represent 1461 the value. 1463 6.3.2.7.3. "t" (Factor CRT Coefficient) 1465 The "t" (factor CRT coefficient) parameter within an "oth" array 1466 member represents the CRT coefficient of the corresponding prime 1467 factor, a positive integer. It is represented as the base64url 1468 encoding of the value's unsigned big endian representation as an 1469 octet sequence. The octet sequence MUST utilize the minimum number 1470 of octets to represent the value. 1472 6.4. Parameters for Symmetric Keys 1474 When the JWK "kty" member value is "oct" (octet sequence), the member 1475 "k" is used to represent a symmetric key (or another key whose value 1476 is a single octet sequence). An "alg" member SHOULD also be present 1477 to identify the algorithm intended to be used with the key, unless 1478 the application uses another means or convention to determine the 1479 algorithm used. 1481 6.4.1. "k" (Key Value) Parameter 1483 The "k" (key value) member contains the value of the symmetric (or 1484 other single-valued) key. It is represented as the base64url 1485 encoding of the octet sequence containing the key value. 1487 7. IANA Considerations 1489 The following registration procedure is used for all the registries 1490 established by this specification. 1492 Values are registered with a Specification Required [RFC5226] after a 1493 two-week review period on the [TBD]@ietf.org mailing list, on the 1494 advice of one or more Designated Experts. However, to allow for the 1495 allocation of values prior to publication, the Designated Expert(s) 1496 may approve registration once they are satisfied that such a 1497 specification will be published. 1499 Registration requests must be sent to the [TBD]@ietf.org mailing list 1500 for review and comment, with an appropriate subject (e.g., "Request 1501 for access token type: example"). [[ Note to the RFC Editor: The name 1502 of the mailing list should be determined in consultation with the 1503 IESG and IANA. Suggested name: jose-reg-review. ]] 1505 Within the review period, the Designated Expert(s) will either 1506 approve or deny the registration request, communicating this decision 1507 to the review list and IANA. Denials should include an explanation 1508 and, if applicable, suggestions as to how to make the request 1509 successful. Registration requests that are undetermined for a period 1510 longer than 21 days can be brought to the IESG's attention (using the 1511 iesg@iesg.org mailing list) for resolution. 1513 Criteria that should be applied by the Designated Expert(s) includes 1514 determining whether the proposed registration duplicates existing 1515 functionality, determining whether it is likely to be of general 1516 applicability or whether it is useful only for a single application, 1517 and whether the registration makes sense. 1519 IANA must only accept registry updates from the Designated Expert(s) 1520 and should direct all requests for registration to the review mailing 1521 list. 1523 It is suggested that multiple Designated Experts be appointed who are 1524 able to represent the perspectives of different applications using 1525 this specification, in order to enable broadly-informed review of 1526 registration decisions. In cases where a registration decision could 1527 be perceived as creating a conflict of interest for a particular 1528 Expert, that Expert should defer to the judgment of the other 1529 Expert(s). 1531 7.1. JSON Web Signature and Encryption Algorithms Registry 1533 This specification establishes the IANA JSON Web Signature and 1534 Encryption Algorithms registry for values of the JWS and JWE "alg" 1535 (algorithm) and "enc" (encryption algorithm) Header Parameters. The 1536 registry records the algorithm name, the algorithm usage locations, 1537 implementation requirements, and a reference to the specification 1538 that defines it. The same algorithm name can be registered multiple 1539 times, provided that the sets of usage locations are disjoint. 1541 It is suggested that when algorithms can use keys of different 1542 lengths, that the length of the key be included in the algorithm 1543 name. This allows readers of the JSON text to easily make security 1544 consideration decisions. 1546 The implementation requirements of an algorithm MAY be changed over 1547 time by the Designated Experts(s) as the cryptographic landscape 1548 evolves, for instance, to change the status of an algorithm to 1549 Deprecated, or to change the status of an algorithm from Optional to 1550 Recommended+ or Required. Changes of implementation requirements are 1551 only permitted on a Specification Required basis, with the new 1552 specification defining the revised implementation requirements level. 1554 7.1.1. Registration Template 1556 Algorithm Name: 1557 The name requested (e.g., "example"). This name is case- 1558 sensitive. Names may not match other registered names in a case- 1559 insensitive manner unless the Designated Expert(s) state that 1560 there is a compelling reason to allow an exception in this 1561 particular case. 1563 Algorithm Description: 1564 Brief description of the Algorithm (e.g., "Example description"). 1566 Algorithm Usage Location(s): 1567 The algorithm usage location. This must be one or more of the 1568 values "alg" or "enc" if the algorithm is to be used with JWS or 1569 JWE. The value "JWK" is used if the algorithm identifier will be 1570 used as a JWK "alg" member value, but will not be used with JWS or 1571 JWE; this could be the case, for instance, for non-authenticated 1572 encryption algorithms. Other values may be used with the approval 1573 of a Designated Expert. 1575 JOSE Implementation Requirements: 1576 The algorithm implementation requirements for JWS and JWE, which 1577 must be one the words Required, Recommended, Optional, Deprecated, 1578 or Prohibited. Optionally, the word can be followed by a "+" or 1579 "-". The use of "+" indicates that the requirement strength is 1580 likely to be increased in a future version of the specification. 1581 The use of "-" indicates that the requirement strength is likely 1582 to be decreased in a future version of the specification. Any 1583 identifiers registered for non-authenticated encryption algorithms 1584 or other algorithms that are otherwise unsuitable for direct use 1585 as JWS or JWE algorithms must be registered as "Prohibited". 1587 Change Controller: 1588 For Standards Track RFCs, state "IESG". For others, give the name 1589 of the responsible party. Other details (e.g., postal address, 1590 email address, home page URI) may also be included. 1592 Specification Document(s): 1593 Reference to the document(s) that specify the parameter, 1594 preferably including URI(s) that can be used to retrieve copies of 1595 the document(s). An indication of the relevant sections may also 1596 be included but is not required. 1598 7.1.2. Initial Registry Contents 1600 o Algorithm Name: "HS256" 1601 o Algorithm Description: HMAC using SHA-256 1602 o Algorithm Usage Location(s): "alg" 1603 o JOSE Implementation Requirements: Required 1604 o Change Controller: IESG 1605 o Specification Document(s): Section 3.1 of [[ this document ]] 1607 o Algorithm Name: "HS384" 1608 o Algorithm Description: HMAC using SHA-384 1609 o Algorithm Usage Location(s): "alg" 1610 o JOSE Implementation Requirements: Optional 1611 o Change Controller: IESG 1612 o Specification Document(s): Section 3.1 of [[ this document ]] 1614 o Algorithm Name: "HS512" 1615 o Algorithm Description: HMAC using SHA-512 1616 o Algorithm Usage Location(s): "alg" 1617 o JOSE Implementation Requirements: Optional 1618 o Change Controller: IESG 1619 o Specification Document(s): Section 3.1 of [[ this document ]] 1620 o Algorithm Name: "RS256" 1621 o Algorithm Description: RSASSA-PKCS-v1_5 using SHA-256 1622 o Algorithm Usage Location(s): "alg" 1623 o JOSE Implementation Requirements: Recommended 1624 o Change Controller: IESG 1625 o Specification Document(s): Section 3.1 of [[ this document ]] 1627 o Algorithm Name: "RS384" 1628 o Algorithm Description: RSASSA-PKCS-v1_5 using SHA-384 1629 o Algorithm Usage Location(s): "alg" 1630 o JOSE Implementation Requirements: Optional 1631 o Change Controller: IESG 1632 o Specification Document(s): Section 3.1 of [[ this document ]] 1634 o Algorithm Name: "RS512" 1635 o Algorithm Description: RSASSA-PKCS-v1_5 using SHA-512 1636 o Algorithm Usage Location(s): "alg" 1637 o JOSE Implementation Requirements: Optional 1638 o Change Controller: IESG 1639 o Specification Document(s): Section 3.1 of [[ this document ]] 1641 o Algorithm Name: "ES256" 1642 o Algorithm Description: ECDSA using P-256 and SHA-256 1643 o Algorithm Usage Location(s): "alg" 1644 o JOSE Implementation Requirements: Recommended+ 1645 o Change Controller: IESG 1646 o Specification Document(s): Section 3.1 of [[ this document ]] 1648 o Algorithm Name: "ES384" 1649 o Algorithm Description: ECDSA using P-384 and SHA-384 1650 o Algorithm Usage Location(s): "alg" 1651 o JOSE Implementation Requirements: Optional 1652 o Change Controller: IESG 1653 o Specification Document(s): Section 3.1 of [[ this document ]] 1655 o Algorithm Name: "ES512" 1656 o Algorithm Description: ECDSA using P-521 and SHA-512 1657 o Algorithm Usage Location(s): "alg" 1658 o JOSE Implementation Requirements: Optional 1659 o Change Controller: IESG 1660 o Specification Document(s): Section 3.1 of [[ this document ]] 1662 o Algorithm Name: "PS256" 1663 o Algorithm Description: RSASSA-PSS using SHA-256 and MGF1 with SHA- 1664 256 1665 o Algorithm Usage Location(s): "alg" 1666 o JOSE Implementation Requirements: Optional 1667 o Change Controller: IESG 1668 o Specification Document(s): Section 3.1 of [[ this document ]] 1670 o Algorithm Name: "PS384" 1671 o Algorithm Description: RSASSA-PSS using SHA-384 and MGF1 with SHA- 1672 384 1673 o Algorithm Usage Location(s): "alg" 1674 o JOSE Implementation Requirements: Optional 1675 o Change Controller: IESG 1676 o Specification Document(s): Section 3.1 of [[ this document ]] 1678 o Algorithm Name: "PS512" 1679 o Algorithm Description: RSASSA-PSS using SHA-512 and MGF1 with SHA- 1680 512 1681 o Algorithm Usage Location(s): "alg" 1682 o JOSE Implementation Requirements: Optional 1683 o Change Controller: IESG 1684 o Specification Document(s): Section 3.1 of [[ this document ]] 1686 o Algorithm Name: "none" 1687 o Algorithm Description: No digital signature or MAC performed 1688 o Algorithm Usage Location(s): "alg" 1689 o JOSE Implementation Requirements: Optional 1690 o Change Controller: IESG 1691 o Specification Document(s): Section 3.1 of [[ this document ]] 1693 o Algorithm Name: "RSA1_5" 1694 o Algorithm Description: RSAES-PKCS1-V1_5 1695 o Algorithm Usage Location(s): "alg" 1696 o JOSE Implementation Requirements: Required 1697 o Change Controller: IESG 1698 o Specification Document(s): Section 4.1 of [[ this document ]] 1700 o Algorithm Name: "RSA-OAEP" 1701 o Algorithm Description: RSAES OAEP using default parameters 1702 o Algorithm Usage Location(s): "alg" 1703 o JOSE Implementation Requirements: Optional 1704 o Change Controller: IESG 1705 o Specification Document(s): Section 4.1 of [[ this document ]] 1707 o Algorithm Name: "RSA-OAEP-256" 1708 o Algorithm Description: RSAES OAEP using SHA-256 and MGF1 with SHA- 1709 256 1710 o Algorithm Usage Location(s): "alg" 1711 o JOSE Implementation Requirements: Optional 1712 o Change Controller: IESG 1713 o Specification Document(s): Section 4.1 of [[ this document ]] 1715 o Algorithm Name: "A128KW" 1716 o Algorithm Description: AES Key Wrap using 128 bit key 1717 o Algorithm Usage Location(s): "alg" 1718 o JOSE Implementation Requirements: Recommended 1719 o Change Controller: IESG 1720 o Specification Document(s): Section 4.1 of [[ this document ]] 1722 o Algorithm Name: "A192KW" 1723 o Algorithm Description: AES Key Wrap using 192 bit key 1724 o Algorithm Usage Location(s): "alg" 1725 o JOSE Implementation Requirements: Optional 1726 o Change Controller: IESG 1727 o Specification Document(s): Section 4.1 of [[ this document ]] 1729 o Algorithm Name: "A256KW" 1730 o Algorithm Description: AES Key Wrap using 256 bit key 1731 o Algorithm Usage Location(s): "alg" 1732 o JOSE Implementation Requirements: Recommended 1733 o Change Controller: IESG 1734 o Specification Document(s): Section 4.1 of [[ this document ]] 1736 o Algorithm Name: "dir" 1737 o Algorithm Description: Direct use of a shared symmetric key 1738 o Algorithm Usage Location(s): "alg" 1739 o JOSE Implementation Requirements: Recommended 1740 o Change Controller: IESG 1741 o Specification Document(s): Section 4.1 of [[ this document ]] 1743 o Algorithm Name: "ECDH-ES" 1744 o Algorithm Description: ECDH-ES using Concat KDF 1745 o Algorithm Usage Location(s): "alg" 1746 o JOSE Implementation Requirements: Recommended+ 1747 o Change Controller: IESG 1748 o Specification Document(s): Section 4.1 of [[ this document ]] 1750 o Algorithm Name: "ECDH-ES+A128KW" 1751 o Algorithm Description: ECDH-ES using Concat KDF and "A128KW" 1752 wrapping 1753 o Algorithm Usage Location(s): "alg" 1754 o JOSE Implementation Requirements: Recommended 1755 o Change Controller: IESG 1756 o Specification Document(s): Section 4.1 of [[ this document ]] 1757 o Algorithm Name: "ECDH-ES+A192KW" 1758 o Algorithm Description: ECDH-ES using Concat KDF and "A192KW" 1759 wrapping 1760 o Algorithm Usage Location(s): "alg" 1761 o JOSE Implementation Requirements: Optional 1762 o Change Controller: IESG 1763 o Specification Document(s): Section 4.1 of [[ this document ]] 1765 o Algorithm Name: "ECDH-ES+A256KW" 1766 o Algorithm Description: ECDH-ES using Concat KDF and "A256KW" 1767 wrapping 1768 o Algorithm Usage Location(s): "alg" 1769 o JOSE Implementation Requirements: Recommended 1770 o Change Controller: IESG 1771 o Specification Document(s): Section 4.1 of [[ this document ]] 1773 o Algorithm Name: "A128GCMKW" 1774 o Algorithm Description: Key wrapping with AES GCM using 128 bit key 1775 o Algorithm Usage Location(s): "alg" 1776 o JOSE Implementation Requirements: Optional 1777 o Change Controller: IESG 1778 o Specification Document(s): Section 4.7 of [[ this document ]] 1780 o Algorithm Name: "A192GCMKW" 1781 o Algorithm Description: Key wrapping with AES GCM using 192 bit key 1782 o Algorithm Usage Location(s): "alg" 1783 o JOSE Implementation Requirements: Optional 1784 o Change Controller: IESG 1785 o Specification Document(s): Section 4.7 of [[ this document ]] 1787 o Algorithm Name: "A256GCMKW" 1788 o Algorithm Description: Key wrapping with AES GCM using 256 bit key 1789 o Algorithm Usage Location(s): "alg" 1790 o JOSE Implementation Requirements: Optional 1791 o Change Controller: IESG 1792 o Specification Document(s): Section 4.7 of [[ this document ]] 1794 o Algorithm Name: "PBES2-HS256+A128KW" 1795 o Algorithm Description: PBES2 with HMAC SHA-256 and "A128KW" 1796 wrapping 1797 o Algorithm Usage Location(s): "alg" 1798 o JOSE Implementation Requirements: Optional 1799 o Change Controller: IESG 1800 o Specification Document(s): Section 4.8 of [[ this document ]] 1802 o Algorithm Name: "PBES2-HS384+A192KW" 1803 o Algorithm Description: PBES2 with HMAC SHA-384 and "A192KW" 1804 wrapping 1805 o Algorithm Usage Location(s): "alg" 1806 o JOSE Implementation Requirements: Optional 1807 o Change Controller: IESG 1808 o Specification Document(s): Section 4.8 of [[ this document ]] 1810 o Algorithm Name: "PBES2-HS512+A256KW" 1811 o Algorithm Description: PBES2 with HMAC SHA-512 and "A256KW" 1812 wrapping 1813 o Algorithm Usage Location(s): "alg" 1814 o JOSE Implementation Requirements: Optional 1815 o Change Controller: IESG 1816 o Specification Document(s): Section 4.8 of [[ this document ]] 1818 o Algorithm Name: "A128CBC-HS256" 1819 o Algorithm Description: AES_128_CBC_HMAC_SHA_256 authenticated 1820 encryption algorithm 1821 o Algorithm Usage Location(s): "enc" 1822 o JOSE Implementation Requirements: Required 1823 o Change Controller: IESG 1824 o Specification Document(s): Section 5.1 of [[ this document ]] 1826 o Algorithm Name: "A192CBC-HS384" 1827 o Algorithm Description: AES_192_CBC_HMAC_SHA_384 authenticated 1828 encryption algorithm 1829 o Algorithm Usage Location(s): "enc" 1830 o JOSE Implementation Requirements: Optional 1831 o Change Controller: IESG 1832 o Specification Document(s): Section 5.1 of [[ this document ]] 1834 o Algorithm Name: "A256CBC-HS512" 1835 o Algorithm Description: AES_256_CBC_HMAC_SHA_512 authenticated 1836 encryption algorithm 1837 o Algorithm Usage Location(s): "enc" 1838 o JOSE Implementation Requirements: Required 1839 o Change Controller: IESG 1840 o Specification Document(s): Section 5.1 of [[ this document ]] 1842 o Algorithm Name: "A128GCM" 1843 o Algorithm Description: AES GCM using 128 bit key 1844 o Algorithm Usage Location(s): "enc" 1845 o JOSE Implementation Requirements: Recommended 1846 o Change Controller: IESG 1847 o Specification Document(s): Section 5.1 of [[ this document ]] 1848 o Algorithm Name: "A192GCM" 1849 o Algorithm Description: AES GCM using 192 bit key 1850 o Algorithm Usage Location(s): "enc" 1851 o JOSE Implementation Requirements: Optional 1852 o Change Controller: IESG 1853 o Specification Document(s): Section 5.1 of [[ this document ]] 1855 o Algorithm Name: "A256GCM" 1856 o Algorithm Description: AES GCM using 256 bit key 1857 o Algorithm Usage Location(s): "enc" 1858 o JOSE Implementation Requirements: Recommended 1859 o Change Controller: IESG 1860 o Specification Document(s): Section 5.1 of [[ this document ]] 1862 7.2. JWE Header Parameter Names Registration 1864 This specification registers the Header Parameter names defined in 1865 Section 4.6.1, Section 4.7.1, and Section 4.8.1 in the IANA JSON Web 1866 Signature and Encryption Header Parameters registry defined in [JWS]. 1868 7.2.1. Registry Contents 1870 o Header Parameter Name: "epk" 1871 o Header Parameter Description: Ephemeral Public Key 1872 o Header Parameter Usage Location(s): JWE 1873 o Change Controller: IESG 1874 o Specification Document(s): Section 4.6.1.1 of [[ this document ]] 1876 o Header Parameter Name: "apu" 1877 o Header Parameter Description: Agreement PartyUInfo 1878 o Header Parameter Usage Location(s): JWE 1879 o Change Controller: IESG 1880 o Specification Document(s): Section 4.6.1.2 of [[ this document ]] 1882 o Header Parameter Name: "apv" 1883 o Header Parameter Description: Agreement PartyVInfo 1884 o Header Parameter Usage Location(s): JWE 1885 o Change Controller: IESG 1886 o Specification Document(s): Section 4.6.1.3 of [[ this document ]] 1888 o Header Parameter Name: "iv" 1889 o Header Parameter Description: Initialization Vector 1890 o Header Parameter Usage Location(s): JWE 1891 o Change Controller: IESG 1892 o Specification Document(s): Section 4.7.1.1 of [[ this document ]] 1893 o Header Parameter Name: "tag" 1894 o Header Parameter Description: Authentication Tag 1895 o Header Parameter Usage Location(s): JWE 1896 o Change Controller: IESG 1897 o Specification Document(s): Section 4.7.1.2 of [[ this document ]] 1899 o Header Parameter Name: "p2s" 1900 o Header Parameter Description: PBES2 salt 1901 o Header Parameter Usage Location(s): JWE 1902 o Change Controller: IESG 1903 o Specification Document(s): Section 4.8.1.1 of [[ this document ]] 1905 o Header Parameter Name: "p2c" 1906 o Header Parameter Description: PBES2 count 1907 o Header Parameter Usage Location(s): JWE 1908 o Change Controller: IESG 1909 o Specification Document(s): Section 4.8.1.2 of [[ this document ]] 1911 7.3. JSON Web Encryption Compression Algorithms Registry 1913 This specification establishes the IANA JSON Web Encryption 1914 Compression Algorithms registry for JWE "zip" member values. The 1915 registry records the compression algorithm value and a reference to 1916 the specification that defines it. 1918 7.3.1. Registration Template 1920 Compression Algorithm Value: 1921 The name requested (e.g., "example"). Because a core goal of this 1922 specification is for the resulting representations to be compact, 1923 it is RECOMMENDED that the name be short -- not to exceed 8 1924 characters without a compelling reason to do so. This name is 1925 case-sensitive. Names may not match other registered names in a 1926 case-insensitive manner unless the Designated Expert(s) state that 1927 there is a compelling reason to allow an exception in this 1928 particular case. 1930 Compression Algorithm Description: 1931 Brief description of the compression algorithm (e.g., "Example 1932 description"). 1934 Change Controller: 1935 For Standards Track RFCs, state "IESG". For others, give the name 1936 of the responsible party. Other details (e.g., postal address, 1937 email address, home page URI) may also be included. 1939 Specification Document(s): 1940 Reference to the document(s) that specify the parameter, 1941 preferably including URI(s) that can be used to retrieve copies of 1942 the document(s). An indication of the relevant sections may also 1943 be included but is not required. 1945 7.3.2. Initial Registry Contents 1947 o Compression Algorithm Value: "DEF" 1948 o Compression Algorithm Description: DEFLATE 1949 o Change Controller: IESG 1950 o Specification Document(s): JSON Web Encryption (JWE) [JWE] 1952 7.4. JSON Web Key Types Registry 1954 This specification establishes the IANA JSON Web Key Types registry 1955 for values of the JWK "kty" (key type) parameter. The registry 1956 records the "kty" value, implementation requirements, and a reference 1957 to the specification that defines it. 1959 The implementation requirements of a key type MAY be changed over 1960 time by the Designated Experts(s) as the cryptographic landscape 1961 evolves, for instance, to change the status of a key type to 1962 Deprecated, or to change the status of a key type from Optional to 1963 Recommended+ or Required. Changes of implementation requirements are 1964 only permitted on a Specification Required basis, with the new 1965 specification defining the revised implementation requirements level. 1967 7.4.1. Registration Template 1969 "kty" Parameter Value: 1970 The name requested (e.g., "example"). Because a core goal of this 1971 specification is for the resulting representations to be compact, 1972 it is RECOMMENDED that the name be short -- not to exceed 8 1973 characters without a compelling reason to do so. This name is 1974 case-sensitive. Names may not match other registered names in a 1975 case-insensitive manner unless the Designated Expert(s) state that 1976 there is a compelling reason to allow an exception in this 1977 particular case. 1979 Key Type Description: 1980 Brief description of the Key Type (e.g., "Example description"). 1982 Change Controller: 1983 For Standards Track RFCs, state "IESG". For others, give the name 1984 of the responsible party. Other details (e.g., postal address, 1985 email address, home page URI) may also be included. 1987 JOSE Implementation Requirements: 1988 The key type implementation requirements for JWS and JWE, which 1989 must be one the words Required, Recommended, Optional, Deprecated, 1990 or Prohibited. Optionally, the word can be followed by a "+" or 1991 "-". The use of "+" indicates that the requirement strength is 1992 likely to be increased in a future version of the specification. 1993 The use of "-" indicates that the requirement strength is likely 1994 to be decreased in a future version of the specification. 1996 Specification Document(s): 1997 Reference to the document(s) that specify the parameter, 1998 preferably including URI(s) that can be used to retrieve copies of 1999 the document(s). An indication of the relevant sections may also 2000 be included but is not required. 2002 7.4.2. Initial Registry Contents 2004 This specification registers the values defined in Section 6.1. 2006 o "kty" Parameter Value: "EC" 2007 o Key Type Description: Elliptic Curve 2008 o JOSE Implementation Requirements: Recommended+ 2009 o Change Controller: IESG 2010 o Specification Document(s): Section 6.2 of [[ this document ]] 2012 o "kty" Parameter Value: "RSA" 2013 o Key Type Description: RSA 2014 o JOSE Implementation Requirements: Required 2015 o Change Controller: IESG 2016 o Specification Document(s): Section 6.3 of [[ this document ]] 2018 o "kty" Parameter Value: "oct" 2019 o Key Type Description: Octet sequence 2020 o JOSE Implementation Requirements: Required 2021 o Change Controller: IESG 2022 o Specification Document(s): Section 6.4 of [[ this document ]] 2024 7.5. JSON Web Key Parameters Registration 2026 This specification registers the parameter names defined in Sections 2027 6.2, 6.3, and 6.4 in the IANA JSON Web Key Parameters registry 2028 defined in [JWK]. 2030 7.5.1. Registry Contents 2032 o Parameter Name: "crv" 2033 o Parameter Description: Curve 2034 o Used with "kty" Value(s): "EC" 2035 o Parameter Information Class: Public 2036 o Change Controller: IESG 2037 o Specification Document(s): Section 6.2.1.1 of [[ this document ]] 2039 o Parameter Name: "x" 2040 o Parameter Description: X Coordinate 2041 o Used with "kty" Value(s): "EC" 2042 o Parameter Information Class: Public 2043 o Change Controller: IESG 2044 o Specification Document(s): Section 6.2.1.2 of [[ this document ]] 2046 o Parameter Name: "y" 2047 o Parameter Description: Y Coordinate 2048 o Used with "kty" Value(s): "EC" 2049 o Parameter Information Class: Public 2050 o Change Controller: IESG 2051 o Specification Document(s): Section 6.2.1.3 of [[ this document ]] 2053 o Parameter Name: "d" 2054 o Parameter Description: ECC Private Key 2055 o Used with "kty" Value(s): "EC" 2056 o Parameter Information Class: Private 2057 o Change Controller: IESG 2058 o Specification Document(s): Section 6.2.2.1 of [[ this document ]] 2060 o Parameter Name: "n" 2061 o Parameter Description: Modulus 2062 o Used with "kty" Value(s): "RSA" 2063 o Parameter Information Class: Public 2064 o Change Controller: IESG 2065 o Specification Document(s): Section 6.3.1.1 of [[ this document ]] 2067 o Parameter Name: "e" 2068 o Parameter Description: Exponent 2069 o Used with "kty" Value(s): "RSA" 2070 o Parameter Information Class: Public 2071 o Change Controller: IESG 2072 o Specification Document(s): Section 6.3.1.2 of [[ this document ]] 2074 o Parameter Name: "d" 2075 o Parameter Description: Private Exponent 2076 o Used with "kty" Value(s): "RSA" 2077 o Parameter Information Class: Private 2078 o Change Controller: IESG 2079 o Specification Document(s): Section 6.3.2.1 of [[ this document ]] 2081 o Parameter Name: "p" 2082 o Parameter Description: First Prime Factor 2083 o Used with "kty" Value(s): "RSA" 2084 o Parameter Information Class: Private 2085 o Change Controller: IESG 2086 o Specification Document(s): Section 6.3.2.2 of [[ this document ]] 2088 o Parameter Name: "q" 2089 o Parameter Description: Second Prime Factor 2090 o Used with "kty" Value(s): "RSA" 2091 o Parameter Information Class: Private 2092 o Change Controller: IESG 2093 o Specification Document(s): Section 6.3.2.3 of [[ this document ]] 2095 o Parameter Name: "dp" 2096 o Parameter Description: First Factor CRT Exponent 2097 o Used with "kty" Value(s): "RSA" 2098 o Parameter Information Class: Private 2099 o Change Controller: IESG 2100 o Specification Document(s): Section 6.3.2.4 of [[ this document ]] 2102 o Parameter Name: "dq" 2103 o Parameter Description: Second Factor CRT Exponent 2104 o Used with "kty" Value(s): "RSA" 2105 o Parameter Information Class: Private 2106 o Change Controller: IESG 2107 o Specification Document(s): Section 6.3.2.5 of [[ this document ]] 2109 o Parameter Name: "qi" 2110 o Parameter Description: First CRT Coefficient 2111 o Used with "kty" Value(s): "RSA" 2112 o Parameter Information Class: Private 2113 o Change Controller: IESG 2114 o Specification Document(s): Section 6.3.2.6 of [[ this document ]] 2116 o Parameter Name: "oth" 2117 o Parameter Description: Other Primes Info 2118 o Used with "kty" Value(s): "RSA" 2119 o Parameter Information Class: Private 2120 o Change Controller: IESG 2121 o Specification Document(s): Section 6.3.2.7 of [[ this document ]] 2123 o Parameter Name: "k" 2124 o Parameter Description: Key Value 2125 o Used with "kty" Value(s): "oct" 2126 o Parameter Information Class: Private 2127 o Change Controller: IESG 2128 o Specification Document(s): Section 6.4.1 of [[ this document ]] 2130 7.6. JSON Web Key Elliptic Curve Registry 2132 This specification establishes the IANA JSON Web Key Elliptic Curve 2133 registry for JWK "crv" member values. The registry records the curve 2134 name, implementation requirements, and a reference to the 2135 specification that defines it. This specification registers the 2136 parameter names defined in Section 6.2.1.1. 2138 The implementation requirements of a curve MAY be changed over time 2139 by the Designated Experts(s) as the cryptographic landscape evolves, 2140 for instance, to change the status of a curve to Deprecated, or to 2141 change the status of a curve from Optional to Recommended+ or 2142 Required. Changes of implementation requirements are only permitted 2143 on a Specification Required basis, with the new specification 2144 defining the revised implementation requirements level. 2146 7.6.1. Registration Template 2148 Curve Name: 2149 The name requested (e.g., "example"). Because a core goal of this 2150 specification is for the resulting representations to be compact, 2151 it is RECOMMENDED that the name be short -- not to exceed 8 2152 characters without a compelling reason to do so. This name is 2153 case-sensitive. Names may not match other registered names in a 2154 case-insensitive manner unless the Designated Expert(s) state that 2155 there is a compelling reason to allow an exception in this 2156 particular case. 2158 Curve Description: 2159 Brief description of the curve (e.g., "Example description"). 2161 JOSE Implementation Requirements: 2162 The curve implementation requirements for JWS and JWE, which must 2163 be one the words Required, Recommended, Optional, Deprecated, or 2164 Prohibited. Optionally, the word can be followed by a "+" or "-". 2165 The use of "+" indicates that the requirement strength is likely 2166 to be increased in a future version of the specification. The use 2167 of "-" indicates that the requirement strength is likely to be 2168 decreased in a future version of the specification. 2170 Change Controller: 2171 For Standards Track RFCs, state "IESG". For others, give the name 2172 of the responsible party. Other details (e.g., postal address, 2173 email address, home page URI) may also be included. 2175 Specification Document(s): 2176 Reference to the document(s) that specify the parameter, 2177 preferably including URI(s) that can be used to retrieve copies of 2178 the document(s). An indication of the relevant sections may also 2179 be included but is not required. 2181 7.6.2. Initial Registry Contents 2183 o Curve Name: "P-256" 2184 o Curve Description: P-256 curve 2185 o JOSE Implementation Requirements: Recommended+ 2186 o Change Controller: IESG 2187 o Specification Document(s): Section 6.2.1.1 of [[ this document ]] 2189 o Curve Name: "P-384" 2190 o Curve Description: P-384 curve 2191 o JOSE Implementation Requirements: Optional 2192 o Change Controller: IESG 2193 o Specification Document(s): Section 6.2.1.1 of [[ this document ]] 2195 o Curve Name: "P-521" 2196 o Curve Description: P-521 curve 2197 o JOSE Implementation Requirements: Optional 2198 o Change Controller: IESG 2199 o Specification Document(s): Section 6.2.1.1 of [[ this document ]] 2201 8. Security Considerations 2203 All of the security issues faced by any cryptographic application 2204 must be faced by a JWS/JWE/JWK agent. Among these issues are 2205 protecting the user's private and symmetric keys, preventing various 2206 attacks, and helping the user avoid mistakes such as inadvertently 2207 encrypting a message for the wrong recipient. The entire list of 2208 security considerations is beyond the scope of this document, but 2209 some significant considerations are listed here. 2211 The security considerations in [AES], [DSS], [JWE], [JWK], [JWS], 2212 [NIST.800-38A], [NIST.800-38D], [NIST.800-56A], [RFC2104], [RFC3394], 2213 [RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this 2214 specification. 2216 Algorithms of matching strengths should be used together whenever 2217 possible. For instance, when AES Key Wrap is used with a given key 2218 size, using the same key size is recommended when AES GCM is also 2219 used. 2221 8.1. Algorithms and Key Sizes will be Deprecated 2223 Eventually the algorithms and/or key sizes currently described in 2224 this specification will no longer be considered sufficiently secure 2225 and will be deprecated. Therefore, implementers and deployments must 2226 be prepared for this eventuality. 2228 8.2. Key Lifetimes 2230 Many algorithms have associated security considerations related to 2231 key lifetimes and/or the number of times that a key may be used. 2232 Those security considerations continue to apply when using those 2233 algorithms with JOSE data structures. 2235 8.3. RSAES-PKCS1-v1_5 Security Considerations 2237 While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not 2238 to adopt RSASSA-PKCS-v1_5 for new applications and instead requests 2239 that people transition to RSASSA-PSS, this specification does include 2240 RSASSA-PKCS-v1_5, for interoperability reasons, because it commonly 2241 implemented. 2243 Keys used with RSAES-PKCS1-v1_5 must follow the constraints in 2244 Section 7.2 of RFC 3447 [RFC3447]. In particular, keys with a low 2245 public key exponent value must not be used. 2247 8.4. AES GCM Security Considerations 2249 Keys used with AES GCM must follow the constraints in Section 8.3 of 2250 [NIST.800-38D], which states: "The total number of invocations of the 2251 authenticated encryption function shall not exceed 2^32, including 2252 all IV lengths and all instances of the authenticated encryption 2253 function with the given key". In accordance with this rule, AES GCM 2254 MUST NOT be used with the same key value more than 2^32 times. 2256 An Initialization Vector value MUST never be used multiple times with 2257 the same AES GCM key. One way to prevent this is to store a counter 2258 with the key and increment it with every use. The counter can also 2259 be used to prevent exceeding the 2^32 limit above. 2261 This security consideration does not apply to the composite AES-CBC 2262 HMAC SHA-2 or AES Key Wrap algorithms. 2264 8.5. Plaintext JWS Security Considerations 2266 Plaintext JWSs (JWSs that use the "alg" value "none") provide no 2267 integrity protection. Thus, they must only be used in contexts where 2268 the payload is secured by means other than a digital signature or MAC 2269 value, or need not be secured. 2271 Implementations that support plaintext JWS objects MUST NOT accept 2272 such objects as valid unless the application specifies that it is 2273 acceptable for a specific object to not be integrity-protected. 2274 Implementations MUST NOT accept plaintext JWS objects by default. 2275 For example, the "verify" method of a hypothetical JWS software 2276 library might have a Boolean "acceptUnsigned" parameter that 2277 indicates "none" is an acceptable "alg" value. As another example, 2278 the "verify" method might take a list of algorithms that are 2279 acceptable to the application as a parameter and would reject 2280 plaintext JWS values if "none" is not in that list. 2282 In order to mitigate downgrade attacks, applications MUST NOT signal 2283 acceptance of plaintext JWS objects at a global level, and SHOULD 2284 signal acceptance on a per-object basis. For example, suppose an 2285 application accepts JWS objects over two channels, (1) HTTP and (2) 2286 HTTPS with client authentication. It requires a JWS signature on 2287 objects received over HTTP, but accepts plaintext JWS objects over 2288 HTTPS. If the application were to globally indicate that "none" is 2289 acceptable, then an attacker could provide it with an unsigned object 2290 over HTTP and still have that object successfully validate. Instead, 2291 the application needs to indicate acceptance of "none" for each 2292 object received over HTTPS (e.g., by setting "acceptUnsigned" to 2293 "true" for the first hypothetical JWS software library above), but 2294 not for each object received over HTTP. 2296 8.6. Differences between Digital Signatures and MACs 2298 While in many cases, MACs and digital signatures can be used for 2299 integrity checking, there are some significant differences between 2300 the security properties that each of them provides. These need to be 2301 taken into consideration when designing protocols and selecting the 2302 algorithms to be used in protocols. 2304 Both signatures and MACs provide for integrity checking -- verifying 2305 that the message has not been modified since the integrity value was 2306 computed. However, MACs provide for origination identification only 2307 under specific circumstances. It can normally be assumed that a 2308 private key used for a signature is only in the hands of a single 2309 entity (although perhaps a distributed entity, in the case of 2310 replicated servers); however, a MAC key needs to be in the hands of 2311 all the entities that use it for integrity computation and checking. 2313 This means that origination can only be determined if a MAC key is 2314 known only to two entities and the receiver knows that it did not 2315 create the message. MAC validation cannot be used to prove 2316 origination to a third party. 2318 8.7. Denial of Service Attacks 2320 Receiving agents that validate signatures and sending agents that 2321 encrypt messages need to be cautious of cryptographic processing 2322 usage when validating signatures and encrypting messages using keys 2323 larger than those mandated in this specification. An attacker could 2324 send certificates with keys that would result in excessive 2325 cryptographic processing, for example, keys larger than those 2326 mandated in this specification, which could swamp the processing 2327 element. Agents that use such keys without first validating the 2328 certificate to a trust anchor are advised to have some sort of 2329 cryptographic resource management system to prevent such attacks. 2331 8.8. Reusing Key Material when Encrypting Keys 2333 It is NOT RECOMMENDED to reuse the same key material (Key Encryption 2334 Key, Content Encryption Key, Initialization Vector, etc.) to encrypt 2335 multiple JWK or JWK Set objects, or to encrypt the same JWK or JWK 2336 Set object multiple times. One suggestion for preventing re-use is 2337 to always generate a new set key material for each encryption 2338 operation, based on the considerations noted in this document as well 2339 as from [RFC4086]. 2341 8.9. Password Considerations 2343 Passwords are vulnerable to a number of attacks. To help mitigate 2344 some of these limitations, this document applies principles from 2345 [RFC2898] to derive cryptographic keys from user-supplied passwords. 2347 However, the strength of the password still has a significant impact. 2348 A high-entropy password has greater resistance to dictionary attacks. 2349 [NIST-800-63-1] contains guidelines for estimating password entropy, 2350 which can help applications and users generate stronger passwords. 2352 An ideal password is one that is as large as (or larger than) the 2353 derived key length. However, passwords larger than a certain 2354 algorithm-specific size are first hashed, which reduces an attacker's 2355 effective search space to the length of the hash algorithm. It is 2356 RECOMMENDED that a password used for "PBES2-HS256+A128KW" be no 2357 shorter than 16 octets and no longer than 128 octets and a password 2358 used for "PBES2-HS512+A256KW" be no shorter than 32 octets and no 2359 longer than 128 octets long. 2361 Still, care needs to be taken in where and how password-based 2362 encryption is used. These algorithms can still be susceptible to 2363 dictionary-based attacks if the iteration count is too small; this is 2364 of particular concern if these algorithms are used to protect data 2365 that an attacker can have indefinite number of attempts to circumvent 2366 the protection, such as protected data stored on a file system. 2368 8.10. Adaptive Chosen-Ciphertext Attacks 2370 See Section 11.1 of [JWE] for security considerations on adaptive 2371 chosen-ciphertext attacks. 2373 8.11. Timing Attacks 2375 See Section 11.2 of [JWE] for security considerations on timing 2376 attacks. 2378 8.12. RSA Private Key Representations and Blinding 2380 See Section 9.3 of [JWK] for security considerations on RSA private 2381 key representations and blinding. 2383 9. Internationalization Considerations 2385 Passwords obtained from users are likely to require preparation and 2386 normalization to account for differences of octet sequences generated 2387 by different input devices, locales, etc. It is RECOMMENDED that 2388 applications to perform the steps outlined in 2389 [I-D.ietf-precis-saslprepbis] to prepare a password supplied directly 2390 by a user before performing key derivation and encryption. 2392 10. References 2394 10.1. Normative References 2396 [AES] National Institute of Standards and Technology (NIST), 2397 "Advanced Encryption Standard (AES)", FIPS PUB 197, 2398 November 2001. 2400 [DSS] National Institute of Standards and Technology, "Digital 2401 Signature Standard (DSS)", FIPS PUB 186-4, July 2013. 2403 [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 2404 draft-ietf-jose-json-web-encryption (work in progress), 2405 June 2014. 2407 [JWK] Jones, M., "JSON Web Key (JWK)", 2408 draft-ietf-jose-json-web-key (work in progress), 2409 June 2014. 2411 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2412 Signature (JWS)", draft-ietf-jose-json-web-signature (work 2413 in progress), June 2014. 2415 [NIST.800-38A] 2416 National Institute of Standards and Technology (NIST), 2417 "Recommendation for Block Cipher Modes of Operation", 2418 NIST PUB 800-38A, December 2001. 2420 [NIST.800-38D] 2421 National Institute of Standards and Technology (NIST), 2422 "Recommendation for Block Cipher Modes of Operation: 2423 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 2424 December 2001. 2426 [NIST.800-56A] 2427 National Institute of Standards and Technology (NIST), 2428 "Recommendation for Pair-Wise Key Establishment Schemes 2429 Using Discrete Logarithm Cryptography", NIST Special 2430 Publication 800-56A, Revision 2, May 2013. 2432 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 2433 Hashing for Message Authentication", RFC 2104, 2434 February 1997. 2436 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2437 Requirement Levels", BCP 14, RFC 2119, March 1997. 2439 [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography 2440 Specification Version 2.0", RFC 2898, September 2000. 2442 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 2443 (AES) Key Wrap Algorithm", RFC 3394, September 2002. 2445 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2446 10646", STD 63, RFC 3629, November 2003. 2448 [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA- 2449 384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007. 2451 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 2452 Curve Cryptography Algorithms", RFC 6090, February 2011. 2454 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 2455 Interchange Format", RFC 7159, March 2014. 2457 [SEC1] Standards for Efficient Cryptography Group, "SEC 1: 2458 Elliptic Curve Cryptography", May 2009. 2460 [SHS] National Institute of Standards and Technology, "Secure 2461 Hash Standard (SHS)", FIPS PUB 180-3, October 2008. 2463 [USASCII] American National Standards Institute, "Coded Character 2464 Set -- 7-bit American Standard Code for Information 2465 Interchange", ANSI X3.4, 1986. 2467 10.2. Informative References 2469 [CanvasApp] 2470 Facebook, "Canvas Applications", 2010. 2472 [I-D.ietf-precis-saslprepbis] 2473 Saint-Andre, P. and A. Melnikov, "Preparation and 2474 Comparison of Internationalized Strings Representing 2475 Usernames and Passwords", draft-ietf-precis-saslprepbis-07 2476 (work in progress), March 2014. 2478 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 2479 McGrew, D., Foley, J., and K. Paterson, "Authenticated 2480 Encryption with AES-CBC and HMAC-SHA", 2481 draft-mcgrew-aead-aes-cbc-hmac-sha2-04 (work in progress), 2482 February 2014. 2484 [I-D.miller-jose-jwe-protected-jwk] 2485 Miller, M., "Using JavaScript Object Notation (JSON) Web 2486 Encryption (JWE) for Protecting JSON Web Key (JWK) 2487 Objects", draft-miller-jose-jwe-protected-jwk-02 (work in 2488 progress), June 2013. 2490 [I-D.rescorla-jsms] 2491 Rescorla, E. and J. Hildebrand, "JavaScript Message 2492 Security Format", draft-rescorla-jsms-00 (work in 2493 progress), March 2011. 2495 [JCA] Oracle, "Java Cryptography Architecture (JCA) Reference 2496 Guide", 2014. 2498 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 2499 Encryption", September 2010. 2501 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 2502 September 2010. 2504 [MagicSignatures] 2505 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 2506 Signatures", January 2011. 2508 [NIST-800-63-1] 2509 National Institute of Standards and Technology (NIST), 2510 "Electronic Authentication Guideline", NIST 800-63-1, 2511 December 2011. 2513 [RFC2631] Rescorla, E., "Diffie-Hellman Key Agreement Method", 2514 RFC 2631, June 1999. 2516 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 2517 Language) XML-Signature Syntax and Processing", RFC 3275, 2518 March 2002. 2520 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 2521 Standards (PKCS) #1: RSA Cryptography Specifications 2522 Version 2.1", RFC 3447, February 2003. 2524 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 2525 Requirements for Security", BCP 106, RFC 4086, June 2005. 2527 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 2528 Encryption", RFC 5116, January 2008. 2530 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2531 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2532 May 2008. 2534 [W3C.NOTE-xmldsig-core2-20130411] 2535 Eastlake, D., Reagle, J., Solo, D., Hirsch, F., Roessler, 2536 T., Yiu, K., Datta, P., and S. Cantor, "XML Signature 2537 Syntax and Processing Version 2.0", World Wide Web 2538 Consortium Note NOTE-xmldsig-core2-20130411, April 2013, 2539 . 2541 [W3C.REC-xmlenc-core-20021210] 2542 Eastlake, D. and J. Reagle, "XML Encryption Syntax and 2543 Processing", World Wide Web Consortium Recommendation REC- 2544 xmlenc-core-20021210, December 2002, 2545 . 2547 [W3C.REC-xmlenc-core1-20130411] 2548 Eastlake, D., Reagle, J., Hirsch, F., and T. Roessler, 2549 "XML Encryption Syntax and Processing Version 1.1", World 2550 Wide Web Consortium Recommendation REC-xmlenc-core1- 2551 20130411, April 2013, 2552 . 2554 Appendix A. Algorithm Identifier Cross-Reference 2556 This appendix contains tables cross-referencing the cryptographic 2557 algorithm identifier values defined in this specification with the 2558 equivalent identifiers used by other standards and software packages. 2559 See XML DSIG [RFC3275], XML DSIG 2.0 2560 [W3C.NOTE-xmldsig-core2-20130411], XML Encryption 2561 [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 2562 [W3C.REC-xmlenc-core1-20130411], and Java Cryptography Architecture 2563 [JCA] for more information about the names defined by those 2564 documents. 2566 A.1. Digital Signature/MAC Algorithm Identifier Cross-Reference 2568 This section contains a table cross-referencing the JWS digital 2569 signature and MAC "alg" (algorithm) values defined in this 2570 specification with the equivalent identifiers used by other standards 2571 and software packages. 2573 +-----+-------------------------------+--------------+--------------+ 2574 | JWS | XML DSIG | JCA | OID | 2575 +-----+-------------------------------+--------------+--------------+ 2576 | HS2 | http://www.w3.org/2001/04/xml | HmacSHA256 | 1.2.840.1135 | 2577 | 56 | dsig-more#hmac-sha256 | | 49.2.9 | 2578 | HS3 | http://www.w3.org/2001/04/xml | HmacSHA384 | 1.2.840.1135 | 2579 | 84 | dsig-more#hmac-sha384 | | 49.2.10 | 2580 | HS5 | http://www.w3.org/2001/04/xml | HmacSHA512 | 1.2.840.1135 | 2581 | 12 | dsig-more#hmac-sha512 | | 49.2.11 | 2582 | RS2 | http://www.w3.org/2001/04/xml | SHA256withRS | 1.2.840.1135 | 2583 | 56 | dsig-more#rsa-sha256 | A | 49.1.1.11 | 2584 | RS3 | http://www.w3.org/2001/04/xml | SHA384withRS | 1.2.840.1135 | 2585 | 84 | dsig-more#rsa-sha384 | A | 49.1.1.12 | 2586 | RS5 | http://www.w3.org/2001/04/xml | SHA512withRS | 1.2.840.1135 | 2587 | 12 | dsig-more#rsa-sha512 | A | 49.1.1.13 | 2588 | ES2 | http://www.w3.org/2001/04/xml | SHA256withEC | 1.2.840.1004 | 2589 | 56 | dsig-more#ecdsa-sha256 | DSA | 5.4.3.2 | 2590 | ES3 | http://www.w3.org/2001/04/xml | SHA384withEC | 1.2.840.1004 | 2591 | 84 | dsig-more#ecdsa-sha384 | DSA | 5.4.3.3 | 2592 | ES5 | http://www.w3.org/2001/04/xml | SHA512withEC | 1.2.840.1004 | 2593 | 12 | dsig-more#ecdsa-sha512 | DSA | 5.4.3.4 | 2594 | PS2 | http://www.w3.org/2007/05/xml | SHA256withRS | 1.2.840.1135 | 2595 | 56 | dsig-more#sha256-rsa-MGF1 | AandMGF1 | 49.1.1.10 | 2596 | PS3 | http://www.w3.org/2007/05/xml | SHA384withRS | 1.2.840.1135 | 2597 | 84 | dsig-more#sha384-rsa-MGF1 | AandMGF1 | 49.1.1.10 | 2598 | PS5 | http://www.w3.org/2007/05/xml | SHA512withRS | 1.2.840.1135 | 2599 | 12 | dsig-more#sha512-rsa-MGF1 | AandMGF1 | 49.1.1.10 | 2600 +-----+-------------------------------+--------------+--------------+ 2602 A.2. Key Management Algorithm Identifier Cross-Reference 2604 This section contains a table cross-referencing the JWE "alg" 2605 (algorithm) values defined in this specification with the equivalent 2606 identifiers used by other standards and software packages. 2608 +-------+------------------------+--------------------+-------------+ 2609 | JWE | XML ENC | JCA | OID | 2610 +-------+------------------------+--------------------+-------------+ 2611 | RSA1_ | http://www.w3.org/2001 | RSA/ECB/PKCS1Paddi | 1.2.840.113 | 2612 | 5 | /04/xmlenc#rsa-1_5 | ng | 549.1.1.1 | 2613 | RSA-O | http://www.w3.org/2001 | RSA/ECB/OAEPWithSH | 1.2.840.113 | 2614 | AEP | /04/xmlenc#rsa-oaep-mg | A-1AndMGF1Padding | 549.1.1.7 | 2615 | | f1p | | | 2616 | RSA-O | http://www.w3.org/2009 | RSA/ECB/OAEPWithSH | 1.2.840.113 | 2617 | AEP-2 | /xmlenc11#rsa-oaep & | A-256AndMGF1Paddin | 549.1.1.7 | 2618 | 56 | http://www.w3.org/200 | g& | | 2619 | | 9/xmlenc11#mgf1sha256 | MGF1ParameterSpec | | 2620 | | | .SHA256 | | 2621 | ECDH- | http://www.w3.org/2009 | ECDH | 1.3.132.1.1 | 2622 | ES | /xmlenc11#ECDH-ES | | 2 | 2623 | A128K | http://www.w3.org/2001 | AESWrap | 2.16.840.1. | 2624 | W | /04/xmlenc#kw-aes128 | | 101.3.4.1.5 | 2625 | A192K | http://www.w3.org/2001 | AESWrap | 2.16.840.1. | 2626 | W | /04/xmlenc#kw-aes192 | | 101.3.4.1.2 | 2627 | | | | 5 | 2628 | A256K | http://www.w3.org/2001 | AESWrap | 2.16.840.1. | 2629 | W | /04/xmlenc#kw-aes256 | | 101.3.4.1.4 | 2630 | | | | 5 | 2631 +-------+------------------------+--------------------+-------------+ 2633 A.3. Content Encryption Algorithm Identifier Cross-Reference 2635 This section contains a table cross-referencing the JWE "enc" 2636 (encryption algorithm) values defined in this specification with the 2637 equivalent identifiers used by other standards and software packages. 2639 For the composite algorithms "A128CBC-HS256", "A192CBC-HS384", and 2640 "A256CBC-HS512", the corresponding AES CBC algorithm identifiers are 2641 listed. 2643 +---------+-------------------------+--------------+----------------+ 2644 | JWE | XML ENC | JCA | OID | 2645 +---------+-------------------------+--------------+----------------+ 2646 | A128CBC | http://www.w3.org/2001/ | AES/CBC/PKCS | 2.16.840.1.101 | 2647 | -HS256 | 04/xmlenc#aes128-cbc | 5Padding | .3.4.1.2 | 2648 | A192CBC | http://www.w3.org/2001/ | AES/CBC/PKCS | 2.16.840.1.101 | 2649 | -HS384 | 04/xmlenc#aes192-cbc | 5Padding | .3.4.1.22 | 2650 | A256CBC | http://www.w3.org/2001/ | AES/CBC/PKCS | 2.16.840.1.101 | 2651 | -HS512 | 04/xmlenc#aes256-cbc | 5Padding | .3.4.1.42 | 2652 | A128GCM | http://www.w3.org/2009/ | AES/GCM/NoPa | 2.16.840.1.101 | 2653 | | xmlenc11#aes128-gcm | dding | .3.4.1.6 | 2654 | A192GCM | http://www.w3.org/2009/ | AES/GCM/NoPa | 2.16.840.1.101 | 2655 | | xmlenc11#aes192-gcm | dding | .3.4.1.26 | 2656 | A256GCM | http://www.w3.org/2009/ | AES/GCM/NoPa | 2.16.840.1.101 | 2657 | | xmlenc11#aes256-gcm | dding | .3.4.1.46 | 2658 +---------+-------------------------+--------------+----------------+ 2660 Appendix B. Test Cases for AES_CBC_HMAC_SHA2 Algorithms 2662 The following test cases can be used to validate implementations of 2663 the AES_CBC_HMAC_SHA2 algorithms defined in Section 5.2. They are 2664 also intended to correspond to test cases that may appear in a future 2665 version of [I-D.mcgrew-aead-aes-cbc-hmac-sha2], demonstrating that 2666 the cryptographic computations performed are the same. 2668 The variable names are those defined in Section 5.2. All values are 2669 hexadecimal. 2671 B.1. Test Cases for AES_128_CBC_HMAC_SHA_256 2673 AES_128_CBC_HMAC_SHA_256 2675 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2676 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2678 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2680 ENC_KEY = 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2682 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2683 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2684 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2685 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2686 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2687 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2688 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2689 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2691 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2693 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2694 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2695 4b 65 72 63 6b 68 6f 66 66 73 2697 AL = 00 00 00 00 00 00 01 50 2699 E = c8 0e df a3 2d df 39 d5 ef 00 c0 b4 68 83 42 79 2700 a2 e4 6a 1b 80 49 f7 92 f7 6b fe 54 b9 03 a9 c9 2701 a9 4a c9 b4 7a d2 65 5c 5f 10 f9 ae f7 14 27 e2 2702 fc 6f 9b 3f 39 9a 22 14 89 f1 63 62 c7 03 23 36 2703 09 d4 5a c6 98 64 e3 32 1c f8 29 35 ac 40 96 c8 2704 6e 13 33 14 c5 40 19 e8 ca 79 80 df a4 b9 cf 1b 2705 38 4c 48 6f 3a 54 c5 10 78 15 8e e5 d7 9d e5 9f 2706 bd 34 d8 48 b3 d6 95 50 a6 76 46 34 44 27 ad e5 2707 4b 88 51 ff b5 98 f7 f8 00 74 b9 47 3c 82 e2 db 2709 M = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2710 e6 e5 45 82 47 65 15 f0 ad 9f 75 a2 b7 1c 73 ef 2712 T = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2714 B.2. Test Cases for AES_192_CBC_HMAC_SHA_384 2716 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2717 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2718 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2720 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2721 10 11 12 13 14 15 16 17 2723 ENC_KEY = 18 19 1a 1b 1c 1d 1e 1f 20 21 22 23 24 25 26 27 2724 28 29 2a 2b 2c 2d 2e 2f 2726 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2727 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2728 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2729 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2730 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2731 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2732 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2733 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2735 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2737 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2738 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2739 4b 65 72 63 6b 68 6f 66 66 73 2741 AL = 00 00 00 00 00 00 01 50 2743 E = ea 65 da 6b 59 e6 1e db 41 9b e6 2d 19 71 2a e5 2744 d3 03 ee b5 00 52 d0 df d6 69 7f 77 22 4c 8e db 2745 00 0d 27 9b dc 14 c1 07 26 54 bd 30 94 42 30 c6 2746 57 be d4 ca 0c 9f 4a 84 66 f2 2b 22 6d 17 46 21 2747 4b f8 cf c2 40 0a dd 9f 51 26 e4 79 66 3f c9 0b 2748 3b ed 78 7a 2f 0f fc bf 39 04 be 2a 64 1d 5c 21 2749 05 bf e5 91 ba e2 3b 1d 74 49 e5 32 ee f6 0a 9a 2750 c8 bb 6c 6b 01 d3 5d 49 78 7b cd 57 ef 48 49 27 2751 f2 80 ad c9 1a c0 c4 e7 9c 7b 11 ef c6 00 54 e3 2753 M = 84 90 ac 0e 58 94 9b fe 51 87 5d 73 3f 93 ac 20 2754 75 16 80 39 cc c7 33 d7 45 94 f8 86 b3 fa af d4 2755 86 f2 5c 71 31 e3 28 1e 36 c7 a2 d1 30 af de 57 2757 T = 84 90 ac 0e 58 94 9b fe 51 87 5d 73 3f 93 ac 20 2758 75 16 80 39 cc c7 33 d7 2760 B.3. Test Cases for AES_256_CBC_HMAC_SHA_512 2762 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2763 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2764 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2765 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2767 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2768 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2770 ENC_KEY = 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2771 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2773 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2774 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2775 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2776 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2777 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2778 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2779 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2780 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2782 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2784 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2785 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2786 4b 65 72 63 6b 68 6f 66 66 73 2788 AL = 00 00 00 00 00 00 01 50 2790 E = 4a ff aa ad b7 8c 31 c5 da 4b 1b 59 0d 10 ff bd 2791 3d d8 d5 d3 02 42 35 26 91 2d a0 37 ec bc c7 bd 2792 82 2c 30 1d d6 7c 37 3b cc b5 84 ad 3e 92 79 c2 2793 e6 d1 2a 13 74 b7 7f 07 75 53 df 82 94 10 44 6b 2794 36 eb d9 70 66 29 6a e6 42 7e a7 5c 2e 08 46 a1 2795 1a 09 cc f5 37 0d c8 0b fe cb ad 28 c7 3f 09 b3 2796 a3 b7 5e 66 2a 25 94 41 0a e4 96 b2 e2 e6 60 9e 2797 31 e6 e0 2c c8 37 f0 53 d2 1f 37 ff 4f 51 95 0b 2798 be 26 38 d0 9d d7 a4 93 09 30 80 6d 07 03 b1 f6 2800 M = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2801 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2802 fd 30 a5 65 c6 16 ff b2 f3 64 ba ec e6 8f c4 07 2803 53 bc fc 02 5d de 36 93 75 4a a1 f5 c3 37 3b 9c 2805 T = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2806 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2808 Appendix C. Example ECDH-ES Key Agreement Computation 2810 This example uses ECDH-ES Key Agreement and the Concat KDF to derive 2811 the Content Encryption Key (CEK) in the manner described in 2812 Section 4.6. In this example, the ECDH-ES Direct Key Agreement mode 2813 ("alg" value "ECDH-ES") is used to produce an agreed upon key for AES 2814 GCM with a 128 bit key ("enc" value "A128GCM"). 2816 In this example, a sender Alice is encrypting content to a recipient 2817 Bob. The sender (Alice) generates an ephemeral key for the key 2818 agreement computation. Alice's ephemeral key (in JWK format) used 2819 for the key agreement computation in this example (including the 2820 private part) is: 2822 {"kty":"EC", 2823 "crv":"P-256", 2824 "x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0", 2825 "y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps", 2826 "d":"0_NxaRPUMQoAJt50Gz8YiTr8gRTwyEaCumd-MToTmIo" 2827 } 2829 The recipient's (Bob's) key (in JWK format) used for the key 2830 agreement computation in this example (including the private part) 2831 is: 2833 {"kty":"EC", 2834 "crv":"P-256", 2835 "x":"weNJy2HscCSM6AEDTDg04biOvhFhyyWvOHQfeF_PxMQ", 2836 "y":"e8lnCO-AlStT-NJVX-crhB7QRYhiix03illJOVAOyck", 2837 "d":"VEmDZpDXXK8p8N0Cndsxs924q6nS1RXFASRl6BfUqdw" 2838 } 2840 Header Parameter values used in this example are as follows. In this 2841 example, the "apu" (agreement PartyUInfo) parameter value is the 2842 base64url encoding of the UTF-8 string "Alice" and the "apv" 2843 (agreement PartyVInfo) parameter value is the base64url encoding of 2844 the UTF-8 string "Bob". The "epk" parameter is used to communicate 2845 the sender's (Alice's) ephemeral public key value to the recipient 2846 (Bob). 2848 {"alg":"ECDH-ES", 2849 "enc":"A128GCM", 2850 "apu":"QWxpY2U", 2851 "apv":"Qm9i", 2852 "epk": 2853 {"kty":"EC", 2854 "crv":"P-256", 2855 "x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0", 2856 "y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps" 2857 } 2858 } 2860 The resulting Concat KDF [NIST.800-56A] parameter values are: 2862 Z 2863 This is set to the ECDH-ES key agreement output. (This value is 2864 often not directly exposed by libraries, due to NIST security 2865 requirements, and only serves as an input to a KDF.) In this 2866 example, Z is following the octet sequence (using JSON array 2867 notation): 2868 [158, 86, 217, 29, 129, 113, 53, 211, 114, 131, 66, 131, 191, 132, 2869 38, 156, 251, 49, 110, 163, 218, 128, 106, 72, 246, 218, 167, 121, 2870 140, 254, 144, 196]. 2872 keydatalen 2873 This value is 128 - the number of bits in the desired output key 2874 (because "A128GCM" uses a 128 bit key). 2876 AlgorithmID 2877 This is set to the octets representing the 32 bit big endian value 2878 7 - [0, 0, 0, 7] - the number of octets in the AlgorithmID content 2879 "A128GCM", followed, by the octets representing the UTF-8 string 2880 "A128GCM" - [65, 49, 50, 56, 71, 67, 77]. 2882 PartyUInfo 2883 This is set to the octets representing the 32 bit big endian value 2884 5 - [0, 0, 0, 5] - the number of octets in the PartyUInfo content 2885 "Alice", followed, by the octets representing the UTF-8 string 2886 "Alice" - [65, 108, 105, 99, 101]. 2888 PartyVInfo 2889 This is set to the octets representing the 32 bit big endian value 2890 3 - [0, 0, 0, 3] - the number of octets in the PartyUInfo content 2891 "Bob", followed, by the octets representing the UTF-8 string "Bob" 2892 - [66, 111, 98]. 2894 SuppPubInfo 2895 This is set to the octets representing the 32 bit big endian value 2896 128 - [0, 0, 0, 128] - the keydatalen value. 2898 SuppPrivInfo 2899 This is set to the empty octet sequence. 2901 Concatenating the parameters AlgorithmID through SuppPubInfo results 2902 in an OtherInfo value of: 2903 [0, 0, 0, 7, 65, 49, 50, 56, 71, 67, 77, 0, 0, 0, 5, 65, 108, 105, 2904 99, 101, 0, 0, 0, 3, 66, 111, 98, 0, 0, 0, 128] 2906 Concatenating the round number 1 ([0, 0, 0, 1]), Z, and the OtherInfo 2907 value results in the Concat KDF round 1 hash input of: 2908 [0, 0, 0, 1, 2909 158, 86, 217, 29, 129, 113, 53, 211, 114, 131, 66, 131, 191, 132, 38, 2910 156, 251, 49, 110, 163, 218, 128, 106, 72, 246, 218, 167, 121, 140, 2911 254, 144, 196, 2912 0, 0, 0, 7, 65, 49, 50, 56, 71, 67, 77, 0, 0, 0, 5, 65, 108, 105, 99, 2913 101, 0, 0, 0, 3, 66, 111, 98, 0, 0, 0, 128] 2915 The resulting derived key, which is the first 128 bits of the round 1 2916 hash output is: 2917 [86, 170, 141, 234, 248, 35, 109, 32, 92, 34, 40, 205, 113, 167, 16, 2918 26] 2920 The base64url encoded representation of this derived key is: 2922 VqqN6vgjbSBcIijNcacQGg 2924 Appendix D. Acknowledgements 2926 Solutions for signing and encrypting JSON content were previously 2927 explored by Magic Signatures [MagicSignatures], JSON Simple Sign 2928 [JSS], Canvas Applications [CanvasApp], JSON Simple Encryption [JSE], 2929 and JavaScript Message Security Format [I-D.rescorla-jsms], all of 2930 which influenced this draft. 2932 The Authenticated Encryption with AES-CBC and HMAC-SHA 2933 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] specification, upon which the 2934 AES_CBC_HMAC_SHA2 algorithms are based, was written by David A. 2935 McGrew and Kenny Paterson. The test cases for AES_CBC_HMAC_SHA2 are 2936 based upon those for [I-D.mcgrew-aead-aes-cbc-hmac-sha2] by John 2937 Foley. 2939 Matt Miller wrote Using JavaScript Object Notation (JSON) Web 2940 Encryption (JWE) for Protecting JSON Web Key (JWK) Objects 2942 [I-D.miller-jose-jwe-protected-jwk], which the password-based 2943 encryption content of this draft is based upon. 2945 This specification is the work of the JOSE Working Group, which 2946 includes dozens of active and dedicated participants. In particular, 2947 the following individuals contributed ideas, feedback, and wording 2948 that influenced this specification: 2950 Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de 2951 Medeiros, Vladimir Dzhuvinov, Yaron Y. Goland, Dick Hardt, Joe 2952 Hildebrand, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Tony 2953 Nadalin, Axel Nennker, John Panzer, Emmanuel Raviart, Eric Rescorla, 2954 Nat Sakimura, Jim Schaad, Hannes Tschofenig, and Sean Turner. 2956 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2957 Sean Turner, Stephen Farrell, and Kathleen Moriarty served as 2958 Security area directors during the creation of this specification. 2960 Appendix E. Document History 2962 [[ to be removed by the RFC Editor before publication as an RFC ]] 2964 -27 2966 o Described additional security considerations. 2968 o Updated the JCA and XMLENC parameters for "RSA-OAEP-256" and the 2969 JCA parameters for "A128KW", "A192KW", "A256KW", and "ECDH-ES". 2971 -26 2973 o Added algorithm identifier "RSA-OAEP-256" for RSAES OAEP using 2974 SHA-256 and MGF1 with SHA-256. 2976 o Clarified that the ECDSA signature values R and S are represented 2977 as octet sequences as defined in Section 2.3.7 of SEC1 [SEC1]. 2979 o Noted that octet sequences are depicted using JSON array notation. 2981 o Updated references, including to W3C specifications. 2983 -25 2985 o Corrected an external section number reference that had changed. 2987 -24 2988 o Replaced uses of the term "associated data" wherever it was used 2989 to refer to a data value with "additional authenticated data", 2990 since both terms were being used as synonyms, causing confusion. 2992 o Updated the JSON reference to RFC 7159. 2994 -23 2996 o No changes were made, other than to the version number and date. 2998 -22 3000 o Corrected RFC 2119 terminology usage. 3002 o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. 3004 -21 3006 o Compute the PBES2 salt parameter as (UTF8(Alg) || 0x00 || Salt 3007 Input), where the "p2s" Header Parameter encodes the Salt Input 3008 value and Alg is the "alg" Header Parameter value. 3010 o Changed some references from being normative to informative, 3011 addressing issue #90. 3013 -20 3015 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 3016 addressing issue #90. 3018 -19 3020 o Used tables to show the correspondence between algorithm 3021 identifiers and algorithm descriptions and parameters in the 3022 algorithm definition sections, addressing issue #183. 3024 o Changed the "Implementation Requirements" registry field names to 3025 "JOSE Implementation Requirements" to make it clear that these 3026 implementation requirements apply only to JWS and JWE 3027 implementations. 3029 -18 3031 o Changes to address editorial and minor issues #129, #134, #135, 3032 #158, #161, #185, #186, and #187. 3034 o Added and used Description registry fields. 3036 -17 3038 o Explicitly named all the logical components of a JWS and JWE and 3039 defined the processing rules and serializations in terms of those 3040 components, addressing issues #60, #61, and #62. 3042 o Removed processing steps in algorithm definitions that duplicated 3043 processing steps in JWS or JWE, addressing issue #56. 3045 o Replaced verbose repetitive phases such as "base64url encode the 3046 octets of the UTF-8 representation of X" with mathematical 3047 notation such as "BASE64URL(UTF8(X))". 3049 o Terms used in multiple documents are now defined in one place and 3050 incorporated by reference. Some lightly used or obvious terms 3051 were also removed. This addresses issue #58. 3053 o Changes to address minor issue #53. 3055 -16 3057 o Added a DataLen prefix to the AlgorithmID value in the Concat KDF 3058 computation. 3060 o Added OIDs for encryption algorithms, additional signature 3061 algorithm OIDs, and additional XML DSIG/ENC URIs in the algorithm 3062 cross-reference tables. 3064 o Changes to address editorial and minor issues #28, #36, #39, #52, 3065 #53, #55, #127, #128, #136, #137, #141, #150, #151, #152, and 3066 #155. 3068 -15 3070 o Changed statements about rejecting JWSs to statements about 3071 validation failing, addressing issue #35. 3073 o Stated that changes of implementation requirements are only 3074 permitted on a Specification Required basis, addressing issue #38. 3076 o Made "oct" a required key type, addressing issue #40. 3078 o Updated the example ECDH-ES key agreement values. 3080 o Changes to address editorial and minor issues #34, #37, #49, #63, 3081 #123, #124, #125, #130, #132, #133, #138, #139, #140, #142, #143, 3082 #144, #145, #148, #149, #150, and #162. 3084 -14 3086 o Removed "PBKDF2" key type and added "p2s" and "p2c" header 3087 parameters for use with the PBES2 algorithms. 3089 o Made the RSA private key parameters that are there to enable 3090 optimizations be RECOMMENDED rather than REQUIRED. 3092 o Added algorithm identifiers for AES algorithms using 192 bit keys 3093 and for RSASSA-PSS using HMAC SHA-384. 3095 o Added security considerations about key lifetimes, addressing 3096 issue #18. 3098 o Added an example ECDH-ES key agreement computation. 3100 -13 3102 o Added key encryption with AES GCM as specified in 3103 draft-jones-jose-aes-gcm-key-wrap-01, addressing issue #13. 3105 o Added security considerations text limiting the number of times 3106 that an AES GCM key can be used for key encryption or direct 3107 encryption, per Section 8.3 of NIST SP 800-38D, addressing issue 3108 #28. 3110 o Added password-based key encryption as specified in 3111 draft-miller-jose-jwe-protected-jwk-02. 3113 -12 3115 o In the Direct Key Agreement case, the Concat KDF AlgorithmID is 3116 set to the octets of the UTF-8 representation of the "enc" header 3117 parameter value. 3119 o Restored the "apv" (agreement PartyVInfo) parameter. 3121 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 3122 be with the algorithm descriptions that use them. 3124 o Changed terminology from "block encryption" to "content 3125 encryption". 3127 -11 3129 o Removed the Encrypted Key value from the AAD computation since it 3130 is already effectively integrity protected by the encryption 3131 process. The AAD value now only contains the representation of 3132 the JWE Encrypted Header. 3134 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 3136 o Added more information about the use of PartyUInfo during key 3137 agreement. 3139 o Use the keydatalen as the SuppPubInfo value for the Concat KDF 3140 when doing key agreement, as RFC 2631 does. 3142 o Added algorithm identifiers for RSASSA-PSS with SHA-256 and SHA- 3143 512. 3145 o Added a Parameter Information Class value to the JSON Web Key 3146 Parameters registry, which registers whether the parameter conveys 3147 public or private information. 3149 -10 3151 o Changed the JWE processing rules for multiple recipients so that a 3152 single AAD value contains the header parameters and encrypted key 3153 values for all the recipients, enabling AES GCM to be safely used 3154 for multiple recipients. 3156 -09 3158 o Expanded the scope of the JWK parameters to include private and 3159 symmetric key representations, as specified by 3160 draft-jones-jose-json-private-and-symmetric-key-00. 3162 o Changed term "JWS Secured Input" to "JWS Signing Input". 3164 o Changed from using the term "byte" to "octet" when referring to 8 3165 bit values. 3167 o Specified that AES Key Wrap uses the default initial value 3168 specified in Section 2.2.3.1 of RFC 3394. This addressed issue 3169 #19. 3171 o Added Key Management Mode definitions to terminology section and 3172 used the defined terms to provide clearer key management 3173 instructions. This addressed issue #5. 3175 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 3176 and "A256CBC-HS512". The new algorithms perform the same 3177 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 3178 but with the Initialization Vector and Authentication Tag values 3179 remaining separate from the Ciphertext value in the output 3180 representation. Also deleted the header parameters "epu" 3181 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 3182 they are no longer used. 3184 o Changed from using the term "Integrity Value" to "Authentication 3185 Tag". 3187 -08 3189 o Changed the name of the JWK key type parameter from "alg" to 3190 "kty". 3192 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 3193 since the term AEAD in the RFC 5116 sense implied the use of a 3194 particular data representation, rather than just referring to the 3195 class of algorithms that perform authenticated encryption with 3196 associated data. 3198 o Applied editorial improvements suggested by Jeff Hodges. Many of 3199 these simplified the terminology used. 3201 o Added seriesInfo information to Internet Draft references. 3203 -07 3205 o Added a data length prefix to PartyUInfo and PartyVInfo values. 3207 o Changed the name of the JWK RSA modulus parameter from "mod" to 3208 "n" and the name of the JWK RSA exponent parameter from "xpo" to 3209 "e", so that the identifiers are the same as those used in RFC 3210 3447. 3212 o Made several local editorial changes to clean up loose ends left 3213 over from to the decision to only support block encryption methods 3214 providing integrity. 3216 -06 3218 o Removed the "int" and "kdf" parameters and defined the new 3219 composite Authenticated Encryption algorithms "A128CBC+HS256" and 3220 "A256CBC+HS512" to replace the former uses of AES CBC, which 3221 required the use of separate integrity and key derivation 3222 functions. 3224 o Included additional values in the Concat KDF calculation -- the 3225 desired output size and the algorithm value, and optionally 3226 PartyUInfo and PartyVInfo values. Added the optional header 3227 parameters "apu" (agreement PartyUInfo), "apv" (agreement 3228 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 3229 PartyVInfo). 3231 o Changed the name of the JWK RSA exponent parameter from "exp" to 3232 "xpo" so as to allow the potential use of the name "exp" for a 3233 future extension that might define an expiration parameter for 3234 keys. (The "exp" name is already used for this purpose in the JWT 3235 specification.) 3237 o Applied changes made by the RFC Editor to RFC 6749's registry 3238 language to this specification. 3240 -05 3242 o Support both direct encryption using a shared or agreed upon 3243 symmetric key, and the use of a shared or agreed upon symmetric 3244 key to key wrap the CMK. Specifically, added the "alg" values 3245 "dir", "ECDH-ES+A128KW", and "ECDH-ES+A256KW" to finish filling in 3246 this set of capabilities. 3248 o Updated open issues. 3250 -04 3252 o Added text requiring that any leading zero bytes be retained in 3253 base64url encoded key value representations for fixed-length 3254 values. 3256 o Added this language to Registration Templates: "This name is case 3257 sensitive. Names that match other registered names in a case 3258 insensitive manner SHOULD NOT be accepted." 3260 o Described additional open issues. 3262 o Applied editorial suggestions. 3264 -03 3266 o Always use a 128 bit "authentication tag" size for AES GCM, 3267 regardless of the key size. 3269 o Specified that use of a 128 bit IV is REQUIRED with AES CBC. It 3270 was previously RECOMMENDED. 3272 o Removed key size language for ECDSA algorithms, since the key size 3273 is implied by the algorithm being used. 3275 o Stated that the "int" key size must be the same as the hash output 3276 size (and not larger, as was previously allowed) so that its size 3277 is defined for key generation purposes. 3279 o Added the "kdf" (key derivation function) header parameter to 3280 provide crypto agility for key derivation. The default KDF 3281 remains the Concat KDF with the SHA-256 digest function. 3283 o Clarified that the "mod" and "exp" values are unsigned. 3285 o Added Implementation Requirements columns to algorithm tables and 3286 Implementation Requirements entries to algorithm registries. 3288 o Changed AES Key Wrap to RECOMMENDED. 3290 o Moved registries JSON Web Signature and Encryption Header 3291 Parameters and JSON Web Signature and Encryption Type Values to 3292 the JWS specification. 3294 o Moved JSON Web Key Parameters registry to the JWK specification. 3296 o Changed registration requirements from RFC Required to 3297 Specification Required with Expert Review. 3299 o Added Registration Template sections for defined registries. 3301 o Added Registry Contents sections to populate registry values. 3303 o No longer say "the UTF-8 representation of the JWS Secured Input 3304 (which is the same as the ASCII representation)". Just call it 3305 "the ASCII representation of the JWS Secured Input". 3307 o Added "Collision Resistant Namespace" to the terminology section. 3309 o Numerous editorial improvements. 3311 -02 3313 o For AES GCM, use the "additional authenticated data" parameter to 3314 provide integrity for the header, encrypted key, and ciphertext 3315 and use the resulting "authentication tag" value as the JWE 3316 Authentication Tag. 3318 o Defined minimum required key sizes for algorithms without 3319 specified key sizes. 3321 o Defined KDF output key sizes. 3323 o Specified the use of PKCS #5 padding with AES CBC. 3325 o Generalized text to allow key agreement to be employed as an 3326 alternative to key wrapping or key encryption. 3328 o Clarified that ECDH-ES is a key agreement algorithm. 3330 o Required implementation of AES-128-KW and AES-256-KW. 3332 o Removed the use of "A128GCM" and "A256GCM" for key wrapping. 3334 o Removed "A512KW" since it turns out that it's not a standard 3335 algorithm. 3337 o Clarified the relationship between "typ" header parameter values 3338 and MIME types. 3340 o Generalized language to refer to Message Authentication Codes 3341 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 3342 unless in a context specific to HMAC algorithms. 3344 o Established registries: JSON Web Signature and Encryption Header 3345 Parameters, JSON Web Signature and Encryption Algorithms, JSON Web 3346 Signature and Encryption "typ" Values, JSON Web Key Parameters, 3347 and JSON Web Key Algorithm Families. 3349 o Moved algorithm-specific definitions from JWK to JWA. 3351 o Reformatted to give each member definition its own section 3352 heading. 3354 -01 3356 o Moved definition of "alg":"none" for JWSs here from the JWT 3357 specification since this functionality is likely to be useful in 3358 more contexts that just for JWTs. 3360 o Added Advanced Encryption Standard (AES) Key Wrap Algorithm using 3361 512 bit keys ("A512KW"). 3363 o Added text "Alternatively, the Encoded JWS Signature MAY be 3364 base64url decoded to produce the JWS Signature and this value can 3365 be compared with the computed HMAC value, as this comparison 3366 produces the same result as comparing the encoded values". 3368 o Corrected the Magic Signatures reference. 3370 o Made other editorial improvements suggested by JOSE working group 3371 participants. 3373 -00 3375 o Created the initial IETF draft based upon 3376 draft-jones-json-web-signature-04 and 3377 draft-jones-json-web-encryption-02 with no normative changes. 3379 o Changed terminology to no longer call both digital signatures and 3380 HMACs "signatures". 3382 Author's Address 3384 Michael B. Jones 3385 Microsoft 3387 Email: mbj@microsoft.com 3388 URI: http://self-issued.info/