idnits 2.17.1 draft-ietf-jose-json-web-algorithms-18.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 26 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (November 12, 2013) is 3811 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 2725 -- Looks like a reference, but probably isn't: '0' on line 2725 -- Looks like a reference, but probably isn't: '7' on line 2699 -- Looks like a reference, but probably isn't: '5' on line 2705 -- Looks like a reference, but probably isn't: '65' on line 2707 -- Looks like a reference, but probably isn't: '108' on line 2707 -- Looks like a reference, but probably isn't: '105' on line 2707 -- Looks like a reference, but probably isn't: '99' on line 2707 -- Looks like a reference, but probably isn't: '101' on line 2707 -- Looks like a reference, but probably isn't: '3' on line 2710 -- Looks like a reference, but probably isn't: '66' on line 2712 -- Looks like a reference, but probably isn't: '111' on line 2712 -- Looks like a reference, but probably isn't: '98' on line 2712 -- Looks like a reference, but probably isn't: '128' on line 2715 -- Possible downref: Non-RFC (?) normative reference: ref. 'AES' -- Possible downref: Non-RFC (?) normative reference: ref. 'DSS' ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Obsolete normative reference: RFC 2898 (Obsoleted by RFC 8018) ** Downref: Normative reference to an Informational RFC: RFC 3394 ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Downref: Normative reference to an Informational RFC: RFC 6090 -- Possible downref: Non-RFC (?) normative reference: ref. 'SEC1' -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' == Outdated reference: A later version (-05) exists of draft-mcgrew-aead-aes-cbc-hmac-sha2-02 -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) Summary: 6 errors (**), 0 flaws (~~), 4 warnings (==), 22 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 November 12, 2013 5 Expires: May 16, 2014 7 JSON Web Algorithms (JWA) 8 draft-ietf-jose-json-web-algorithms-18 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 May 16, 2014. 35 Copyright Notice 37 Copyright (c) 2013 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 53 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 54 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 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" . . . . . . . . . . . . . . . . 10 62 4. Cryptographic Algorithms for Key Management . . . . . . . . . 11 63 4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 11 64 4.2. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 13 65 4.3. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 13 66 4.4. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 13 67 4.5. Direct Encryption with a Shared Symmetric Key . . . . . . 14 68 4.6. Key Agreement with Elliptic Curve Diffie-Hellman 69 Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 14 70 4.6.1. Header Parameters Used for ECDH Key Agreement . . . . 14 71 4.6.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 15 72 4.6.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 15 73 4.6.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 15 74 4.6.2. Key Derivation for ECDH Key Agreement . . . . . . . . 15 75 4.7. Key Encryption with AES GCM . . . . . . . . . . . . . . . 17 76 4.7.1. Header Parameters Used for AES GCM Key Encryption . . 17 77 4.7.1.1. "iv" (Initialization Vector) Header Parameter . . 17 78 4.7.1.2. "tag" (Authentication Tag) Header Parameter . . . 17 79 4.8. Key Encryption with PBES2 . . . . . . . . . . . . . . . . 17 80 4.8.1. Header Parameters Used for PBES2 Key Encryption . . . 18 81 4.8.1.1. "p2s" (PBES2 salt) Parameter . . . . . . . . . . . 18 82 4.8.1.2. "p2c" (PBES2 count) Parameter . . . . . . . . . . 18 83 5. Cryptographic Algorithms for Content Encryption . . . . . . . 19 84 5.1. "enc" (Encryption Method) Header Parameter Values for 85 JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 86 5.2. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 20 87 5.2.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 20 88 5.2.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 20 89 5.2.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 20 90 5.2.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 22 91 5.2.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 23 92 5.2.4. AES_192_CBC_HMAC_SHA_384 . . . . . . . . . . . . . . . 23 93 5.2.5. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 23 94 5.2.6. Plaintext Encryption with AES_CBC_HMAC_SHA2 . . . . . 24 95 5.3. Plaintext Encryption with AES GCM . . . . . . . . . . . . 24 96 6. Cryptographic Algorithms for Keys . . . . . . . . . . . . . . 24 97 6.1. "kty" (Key Type) Parameter Values . . . . . . . . . . . . 25 98 6.2. Parameters for Elliptic Curve Keys . . . . . . . . . . . . 25 99 6.2.1. Parameters for Elliptic Curve Public Keys . . . . . . 25 100 6.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 25 101 6.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 26 102 6.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 26 103 6.2.2. Parameters for Elliptic Curve Private Keys . . . . . . 26 104 6.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 26 105 6.3. Parameters for RSA Keys . . . . . . . . . . . . . . . . . 26 106 6.3.1. Parameters for RSA Public Keys . . . . . . . . . . . . 27 107 6.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 27 108 6.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 27 109 6.3.2. Parameters for RSA Private Keys . . . . . . . . . . . 27 110 6.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 27 111 6.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 27 112 6.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 28 113 6.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 28 114 6.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 28 115 6.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 28 116 6.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 28 117 6.4. Parameters for Symmetric Keys . . . . . . . . . . . . . . 29 118 6.4.1. "k" (Key Value) Parameter . . . . . . . . . . . . . . 29 119 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 120 7.1. JSON Web Signature and Encryption Algorithms Registry . . 30 121 7.1.1. Registration Template . . . . . . . . . . . . . . . . 31 122 7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 32 123 7.2. JWE Header Parameter Names Registration . . . . . . . . . 37 124 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 38 125 7.3. JSON Web Encryption Compression Algorithms Registry . . . 38 126 7.3.1. Registration Template . . . . . . . . . . . . . . . . 39 127 7.3.2. Initial Registry Contents . . . . . . . . . . . . . . 39 128 7.4. JSON Web Key Types Registry . . . . . . . . . . . . . . . 39 129 7.4.1. Registration Template . . . . . . . . . . . . . . . . 40 130 7.4.2. Initial Registry Contents . . . . . . . . . . . . . . 40 131 7.5. JSON Web Key Parameters Registration . . . . . . . . . . . 41 132 7.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 41 133 7.6. JSON Web Key Elliptic Curve Registry . . . . . . . . . . . 43 134 7.6.1. Registration Template . . . . . . . . . . . . . . . . 43 135 7.6.2. Initial Registry Contents . . . . . . . . . . . . . . 44 136 8. Security Considerations . . . . . . . . . . . . . . . . . . . 45 137 8.1. Algorithms and Key Sizes will be Deprecated . . . . . . . 45 138 8.2. Key Lifetimes . . . . . . . . . . . . . . . . . . . . . . 45 139 8.3. RSAES-PKCS1-v1_5 Security Considerations . . . . . . . . . 45 140 8.4. AES GCM Security Considerations . . . . . . . . . . . . . 46 141 8.5. Plaintext JWS Security Considerations . . . . . . . . . . 46 142 8.6. Differences between Digital Signatures and MACs . . . . . 47 143 8.7. Denial of Service Attacks . . . . . . . . . . . . . . . . 47 144 8.8. Reusing Key Material when Encrypting Keys . . . . . . . . 47 145 8.9. Password Considerations . . . . . . . . . . . . . . . . . 48 147 9. Internationalization Considerations . . . . . . . . . . . . . 48 148 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 48 149 10.1. Normative References . . . . . . . . . . . . . . . . . . . 48 150 10.2. Informative References . . . . . . . . . . . . . . . . . . 50 151 Appendix A. Algorithm Identifier Cross-Reference . . . . . . . . 52 152 A.1. Digital Signature/MAC Algorithm Identifier 153 Cross-Reference . . . . . . . . . . . . . . . . . . . . . 52 154 A.2. Key Management Algorithm Identifier Cross-Reference . . . 53 155 A.3. Content Encryption Algorithm Identifier Cross-Reference . 53 156 Appendix B. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 54 157 B.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 55 158 B.2. Test Cases for AES_192_CBC_HMAC_SHA_384 . . . . . . . . . 56 159 B.3. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 57 160 Appendix C. Example ECDH-ES Key Agreement Computation . . . . . . 58 161 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 60 162 Appendix E. Document History . . . . . . . . . . . . . . . . . . 61 163 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 68 165 1. Introduction 167 The JSON Web Algorithms (JWA) specification registers cryptographic 168 algorithms and identifiers to be used with the JSON Web Signature 169 (JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK) 170 [JWK] specifications. It defines several IANA registries for these 171 identifiers. All these specifications utilize JavaScript Object 172 Notation (JSON) [RFC4627] based data structures. This specification 173 also describes the semantics and operations that are specific to 174 these algorithms and key types. 176 Registering the algorithms and identifiers here, rather than in the 177 JWS, JWE, and JWK specifications, is intended to allow them to remain 178 unchanged in the face of changes in the set of Required, Recommended, 179 Optional, and Deprecated algorithms over time. This also allows 180 changes to the JWS, JWE, and JWK specifications without changing this 181 document. 183 Names defined by this specification are short because a core goal is 184 for the resulting representations to be compact. 186 1.1. Notational Conventions 188 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 189 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 190 document are to be interpreted as described in Key words for use in 191 RFCs to Indicate Requirement Levels [RFC2119]. If these words are 192 used without being spelled in uppercase then they are to be 193 interpreted with their normal natural language meanings. 195 BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per 196 Section 2. 198 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 199 of STRING. 201 ASCII(STRING) denotes the octets of the ASCII [USASCII] 202 representation of STRING. 204 The concatenation of two values A and B is denoted as A || B. 206 2. Terminology 208 These terms defined by the JSON Web Signature (JWS) [JWS] 209 specification are incorporated into this specification: "JSON Web 210 Signature (JWS)", "JWS Header", "JWS Payload", "JWS Signature", "JWS 211 Protected Header", "Base64url Encoding", and "JWS Signing Input". 213 These terms defined by the JSON Web Encryption (JWE) [JWE] 214 specification are incorporated into this specification: "JSON Web 215 Encryption (JWE)", "Authenticated Encryption", "Plaintext", 216 "Ciphertext", "Additional Authenticated Data (AAD)", "Authentication 217 Tag", "Content Encryption Key (CEK)", "JWE Header", "JWE Encrypted 218 Key", "JWE Initialization Vector", "JWE Ciphertext", "JWE 219 Authentication Tag", "JWE Protected Header", "Key Management Mode", 220 "Key Encryption", "Key Wrapping", "Direct Key Agreement", "Key 221 Agreement with Key Wrapping", and "Direct Encryption". 223 These terms defined by the JSON Web Key (JWK) [JWK] specification are 224 incorporated into this specification: "JSON Web Key (JWK)" and "JSON 225 Web Key Set (JWK Set)". 227 These terms are defined for use by this specification: 229 Header Parameter A name/value pair that is member of a JWS Header or 230 JWE Header. 232 3. Cryptographic Algorithms for Digital Signatures and MACs 234 JWS uses cryptographic algorithms to digitally sign or create a 235 Message Authentication Codes (MAC) of the contents of the JWS Header 236 and the JWS Payload. 238 3.1. "alg" (Algorithm) Header Parameter Values for JWS 240 The table below is the set of "alg" (algorithm) header parameter 241 values defined by this specification for use with JWS, each of which 242 is explained in more detail in the following sections: 244 +---------------+------------------------------+--------------------+ 245 | alg Parameter | Digital Signature or MAC | Implementation | 246 | Value | Algorithm | Requirements | 247 +---------------+------------------------------+--------------------+ 248 | HS256 | HMAC using SHA-256 | Required | 249 | HS384 | HMAC using SHA-384 | Optional | 250 | HS512 | HMAC using SHA-512 | Optional | 251 | RS256 | RSASSA-PKCS-v1_5 using | Recommended | 252 | | SHA-256 | | 253 | RS384 | RSASSA-PKCS-v1_5 using | Optional | 254 | | SHA-384 | | 255 | RS512 | RSASSA-PKCS-v1_5 using | Optional | 256 | | SHA-512 | | 257 | ES256 | ECDSA using P-256 and | Recommended+ | 258 | | SHA-256 | | 259 | ES384 | ECDSA using P-384 and | Optional | 260 | | SHA-384 | | 261 | ES512 | ECDSA using P-521 and | Optional | 262 | | SHA-512 | | 263 | PS256 | RSASSA-PSS using SHA-256 and | Optional | 264 | | MGF1 with SHA-256 | | 265 | PS384 | RSASSA-PSS using SHA-384 and | Optional | 266 | | MGF1 with SHA-384 | | 267 | PS512 | RSASSA-PSS using SHA-512 and | Optional | 268 | | MGF1 with SHA-512 | | 269 | none | No digital signature or MAC | Optional | 270 | | performed | | 271 +---------------+------------------------------+--------------------+ 273 The use of "+" in the Implementation Requirements indicates that the 274 requirement strength is likely to be increased in a future version of 275 the specification. 277 See Appendix A.1 for a table cross-referencing the JWS digital 278 signature and MAC "alg" (algorithm) values defined in this 279 specification with the equivalent identifiers used by other standards 280 and software packages. 282 3.2. HMAC with SHA-2 Functions 284 Hash-based Message Authentication Codes (HMACs) enable one to use a 285 secret plus a cryptographic hash function to generate a Message 286 Authentication Code (MAC). This can be used to demonstrate that 287 whoever generated the MAC was in possession of the MAC key. 289 The algorithm for implementing and validating HMACs is provided in 290 RFC 2104 [RFC2104]. This section defines the use of the HMAC SHA- 291 256, HMAC SHA-384, and HMAC SHA-512 functions [SHS]. The "alg" 292 (algorithm) Header Parameter values "HS256", "HS384", and "HS512" are 293 used in the JWS Header to indicate that the JWS Signature contains an 294 HMAC value using the respective hash function. 296 A key of the same size as the hash output (for instance, 256 bits for 297 "HS256") or larger MUST be used with this algorithm. 299 The HMAC SHA-256 MAC is generated per RFC 2104, using SHA-256 as the 300 hash algorithm "H", using the JWS Signing Input as the "text" value, 301 and using the shared key. The HMAC output value is the JWS 302 Signature. 304 The HMAC SHA-256 MAC for a JWS is validated by computing an HMAC 305 value per RFC 2104, using SHA-256 as the hash algorithm "H", using 306 the received JWS Signing Input as the "text" value, and using the 307 shared key. This computed HMAC value is then compared to the result 308 of base64url decoding the received encoded JWS Signature value. 309 Alternatively, the computed HMAC value can be base64url encoded and 310 compared to the received encoded JWS Signature value, as this 311 comparison produces the same result as comparing the unencoded 312 values. In either case, if the values match, the HMAC has been 313 validated. 315 Securing content with the HMAC SHA-384 and HMAC SHA-512 algorithms is 316 performed identically to the procedure for HMAC SHA-256 -- just using 317 the corresponding hash algorithms with correspondingly larger minimum 318 key sizes and result values: 384 bits each for HMAC SHA-384 and 512 319 bits each for HMAC SHA-512. 321 An example using this algorithm is shown in Appendix A.1 of [JWS]. 323 3.3. Digital Signature with RSASSA-PKCS1-V1_5 325 This section defines the use of the RSASSA-PKCS1-V1_5 digital 326 signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447] 327 (commonly known as PKCS #1), using SHA-256, SHA-384, or SHA-512 [SHS] 328 as the hash functions. The "alg" (algorithm) header parameter values 329 "RS256", "RS384", and "RS512" are used in the JWS Header to indicate 330 that the JWS Signature contains a RSASSA-PKCS1-V1_5 digital signature 331 using the respective hash function. 333 A key of size 2048 bits or larger MUST be used with these algorithms. 335 The RSASSA-PKCS1-V1_5 SHA-256 digital signature is generated as 336 follows: Generate a digital signature of the JWS Signing Input using 337 RSASSA-PKCS1-V1_5-SIGN and the SHA-256 hash function with the desired 338 private key. This is the JWS Signature value. 340 The RSASSA-PKCS1-V1_5 SHA-256 digital signature for a JWS is 341 validated as follows: Submit the JWS Signing Input, the JWS 342 Signature, and the public key corresponding to the private key used 343 by the signer to the RSASSA-PKCS1-V1_5-VERIFY algorithm using SHA-256 344 as the hash function. 346 Signing with the RSASSA-PKCS1-V1_5 SHA-384 and RSASSA-PKCS1-V1_5 SHA- 347 512 algorithms is performed identically to the procedure for RSASSA- 348 PKCS1-V1_5 SHA-256 -- just using the corresponding hash algorithms 349 instead of SHA-256. 351 An example using this algorithm is shown in Appendix A.2 of [JWS]. 353 3.4. Digital Signature with ECDSA 355 The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides 356 for the use of Elliptic Curve cryptography, which is able to provide 357 equivalent security to RSA cryptography but using shorter key sizes 358 and with greater processing speed. This means that ECDSA digital 359 signatures will be substantially smaller in terms of length than 360 equivalently strong RSA digital signatures. 362 This specification defines the use of ECDSA with the P-256 curve and 363 the SHA-256 cryptographic hash function, ECDSA with the P-384 curve 364 and the SHA-384 hash function, and ECDSA with the P-521 curve and the 365 SHA-512 hash function. The P-256, P-384, and P-521 curves are 366 defined in [DSS]. The "alg" (algorithm) Header Parameter values 367 "ES256", "ES384", and "ES512" are used in the JWS Header to indicate 368 that the JWS Signature contains a base64url encoded ECDSA P-256 SHA- 369 256, ECDSA P-384 SHA-384, or ECDSA P-521 SHA-512 digital signature, 370 respectively. 372 The ECDSA P-256 SHA-256 digital signature is generated as follows: 374 1. Generate a digital signature of the JWS Signing Input using ECDSA 375 P-256 SHA-256 with the desired private key. The output will be 376 the pair (R, S), where R and S are 256 bit unsigned integers. 378 2. Turn R and S into octet sequences in big endian order, with each 379 array being be 32 octets long. The octet sequence 380 representations MUST NOT be shortened to omit any leading zero 381 octets contained in the values. 383 3. Concatenate the two octet sequences in the order R and then S. 384 (Note that many ECDSA implementations will directly produce this 385 concatenation as their output.) 387 4. The resulting 64 octet sequence is the JWS Signature value. 389 The ECDSA P-256 SHA-256 digital signature for a JWS is validated as 390 follows: 392 1. The JWS Signature value MUST be a 64 octet sequence. If it is 393 not a 64 octet sequence, the validation has failed. 395 2. Split the 64 octet sequence into two 32 octet sequences. The 396 first array will be R and the second S (with both being in big 397 endian octet order). 399 3. Submit the JWS Signing Input R, S and the public key (x, y) to 400 the ECDSA P-256 SHA-256 validator. 402 Signing with the ECDSA P-384 SHA-384 and ECDSA P-521 SHA-512 403 algorithms is performed identically to the procedure for ECDSA P-256 404 SHA-256 -- just using the corresponding hash algorithms with 405 correspondingly larger result values. For ECDSA P-384 SHA-384, R and 406 S will be 384 bits each, resulting in a 96 octet sequence. For ECDSA 407 P-521 SHA-512, R and S will be 521 bits each, resulting in a 132 408 octet sequence. 410 Examples using these algorithms are shown in Appendices A.3 and A.4 411 of [JWS]. 413 3.5. Digital Signature with RSASSA-PSS 415 This section defines the use of the RSASSA-PSS digital signature 416 algorithm as defined in Section 8.1 of RFC 3447 [RFC3447] with the 417 MGF1 mask generation function, always using the same hash function 418 for both the RSASSA-PSS hash function and the MGF1 hash function. 419 Use of SHA-256, SHA-384, and SHA-512 as these hash functions is 420 defined. The size of the salt value is the same size as the hash 421 function output. All other algorithm parameters use the defaults 422 specified in Section A.2.3 of RFC 3447. The "alg" (algorithm) header 423 parameter values "PS256", "PS384", and "PS512" are used in the JWS 424 Header to indicate that the JWS Signature contains a base64url 425 encoded RSASSA-PSS digital signature using the respective hash 426 function in both roles. 428 A key of size 2048 bits or larger MUST be used with this algorithm. 430 The RSASSA-PSS SHA-256 digital signature is generated as follows: 431 Generate a digital signature of the JWS Signing Input using RSASSA- 432 PSS-SIGN, the SHA-256 hash function, and the MGF1 mask generation 433 function with SHA-256 with the desired private key. This is the JWS 434 signature value. 436 The RSASSA-PSS SHA-256 digital signature for a JWS is validated as 437 follows: Submit the JWS Signing Input, the JWS Signature, and the 438 public key corresponding to the private key used by the signer to the 439 RSASSA-PSS-VERIFY algorithm using SHA-256 as the hash function and 440 using MGF1 as the mask generation function with SHA-256. 442 Signing with the RSASSA-PSS SHA-384 and RSASSA-PSS SHA-512 algorithms 443 is performed identically to the procedure for RSASSA-PSS SHA-256 -- 444 just using the alternative hash algorithm in both roles. 446 3.6. Using the Algorithm "none" 448 JWSs MAY also be created that do not provide integrity protection. 449 Such a JWS is called a "Plaintext JWS". A Plaintext JWS MUST use the 450 "alg" value "none", and is formatted identically to other JWSs, but 451 MUST use the empty octet sequence as its JWS Signature value. 452 Receivers MUST verify that the JWS Signature value is the empty octet 453 sequence. See Section 8.5 for security considerations associated 454 with using this algorithm. 456 4. Cryptographic Algorithms for Key Management 458 JWE uses cryptographic algorithms to encrypt or determine the Content 459 Encryption Key (CEK). 461 4.1. "alg" (Algorithm) Header Parameter Values for JWE 463 The table below is the set of "alg" (algorithm) Header Parameter 464 values that are defined by this specification for use with JWE. 465 These algorithms are used to encrypt the CEK, producing the JWE 466 Encrypted Key, or to use key agreement to agree upon the CEK. 468 +-------------------+-----------------+------------+----------------+ 469 | alg Parameter | Key Management | Additional | Implementation | 470 | Value | Algorithm | Header | Requirements | 471 | | | Parameters | | 472 +-------------------+-----------------+------------+----------------+ 473 | RSA1_5 | RSAES-PKCS1-V1_ | (none) | Required | 474 | | 5 | | | 475 | RSA-OAEP | RSAES using | (none) | Optional | 476 | | OAEP with | | | 477 | | default | | | 478 | | parameters | | | 479 | A128KW | AES Key Wrap | (none) | Recommended | 480 | | with default | | | 481 | | initial value | | | 482 | | using 128 bit | | | 483 | | key | | | 484 | A192KW | AES Key Wrap | (none) | Optional | 485 | | with default | | | 486 | | initial value | | | 487 | | using 192 bit | | | 488 | | key | | | 489 | A256KW | AES Key Wrap | (none) | Recommended | 490 | | with default | | | 491 | | initial value | | | 492 | | using 256 bit | | | 493 | | key | | | 494 | dir | Direct use of a | (none) | Recommended | 495 | | shared | | | 496 | | symmetric key | | | 497 | | as the CEK | | | 498 | ECDH-ES | Elliptic Curve | "epk", | Recommended+ | 499 | | Diffie-Hellman | "apu", | | 500 | | Ephemeral | "apv" | | 501 | | Static key | | | 502 | | agreement using | | | 503 | | Concat KDF | | | 504 | ECDH-ES+A128KW | ECDH-ES using | "epk", | Recommended | 505 | | Concat KDF and | "apu", | | 506 | | CEK wrapped | "apv" | | 507 | | with "A128KW" | | | 508 | ECDH-ES+A192KW | ECDH-ES using | "epk", | Optional | 509 | | Concat KDF and | "apu", | | 510 | | CEK wrapped | "apv" | | 511 | | with "A192KW" | | | 512 | ECDH-ES+A256KW | ECDH-ES using | "epk", | Recommended | 513 | | Concat KDF and | "apu", | | 514 | | CEK wrapped | "apv" | | 515 | | with "A256KW" | | | 516 | A128GCMKW | Key wrapping | "iv", | Optional | 517 | | with AES GCM | "tag" | | 518 | | using 128 bit | | | 519 | | key | | | 520 | A192GCMKW | Key wrapping | "iv", | Optional | 521 | | with AES GCM | "tag" | | 522 | | using 192 bit | | | 523 | | key | | | 524 | A256GCMKW | Key wrapping | "iv", | Optional | 525 | | with AES GCM | "tag" | | 526 | | using 256 bit | | | 527 | | key | | | 528 | PBES2-HS256+A128K | PBES2 with HMAC | "p2s", | Optional | 529 | W | SHA-256 and | "p2c" | | 530 | | "A128KW" | | | 531 | | wrapping | | | 532 | PBES2-HS384+A192K | PBES2 with HMAC | "p2s", | Optional | 533 | W | SHA-384 and | "p2c" | | 534 | | "A192KW" | | | 535 | | wrapping | | | 536 | PBES2-HS512+A256K | PBES2 with HMAC | "p2s", | Optional | 537 | W | SHA-512 and | "p2c" | | 538 | | "A256KW" | | | 539 | | wrapping | | | 540 +-------------------+-----------------+------------+----------------+ 541 The Additional Header Parameters column indicates what additional 542 Header Parameters are used by the algorithm, beyond "alg", which all 543 use. All but "dir" and "ECDH-ES" also produce a JWE Encrypted Key 544 value. 546 The use of "+" in the Implementation Requirements indicates that the 547 requirement strength is likely to be increased in a future version of 548 the specification. 550 See Appendix A.2 for a table cross-referencing the JWE "alg" 551 (algorithm) values defined in this specification with the equivalent 552 identifiers used by other standards and software packages. 554 4.2. Key Encryption with RSAES-PKCS1-V1_5 556 This section defines the specifics of encrypting a JWE CEK with 557 RSAES-PKCS1-V1_5 [RFC3447]. The "alg" Header Parameter value 558 "RSA1_5" is used in this case. 560 A key of size 2048 bits or larger MUST be used with this algorithm. 562 An example using this algorithm is shown in Appendix A.2 of [JWE]. 564 4.3. Key Encryption with RSAES OAEP 566 This section defines the specifics of encrypting a JWE CEK with RSAES 567 using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447], with 568 the default parameters specified by RFC 3447 in Section A.2.1. 569 (Those default parameters are using a hash function of SHA-1 and a 570 mask generation function of MGF1 with SHA-1.) The "alg" Header 571 Parameter value "RSA-OAEP" is used in this case. 573 A key of size 2048 bits or larger MUST be used with this algorithm. 575 An example using this algorithm is shown in Appendix A.1 of [JWE]. 577 4.4. Key Wrapping with AES Key Wrap 579 This section defines the specifics of encrypting a JWE CEK with the 580 Advanced Encryption Standard (AES) Key Wrap Algorithm [RFC3394] using 581 the default initial value specified in Section 2.2.3.1 using a 128, 582 192, or 256 bit key. The "alg" Header Parameter values "A128KW", 583 "A192KW", or "A256KW" are respectively used in this case. 585 An example using this algorithm is shown in Appendix A.3 of [JWE]. 587 4.5. Direct Encryption with a Shared Symmetric Key 589 This section defines the specifics of directly performing symmetric 590 key encryption without performing a key wrapping step. In this case, 591 the shared symmetric key is used directly as the Content Encryption 592 Key (CEK) value for the "enc" algorithm. An empty octet sequence is 593 used as the JWE Encrypted Key value. The "alg" Header Parameter 594 value "dir" is used in this case. 596 Refer to the security considerations on key lifetimes in Section 8.2 597 and AES GCM in Section 8.4 when considering utilizing direct 598 encryption. 600 4.6. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static 601 (ECDH-ES) 603 This section defines the specifics of key agreement with Elliptic 604 Curve Diffie-Hellman Ephemeral Static [RFC6090], in combination with 605 the Concat KDF, as defined in Section 5.8.1 of [NIST.800-56A]. The 606 key agreement result can be used in one of two ways: 608 1. directly as the Content Encryption Key (CEK) for the "enc" 609 algorithm, in the Direct Key Agreement mode, or 611 2. as a symmetric key used to wrap the CEK with the "A128KW", 612 "A192KW", or "A256KW" algorithms, in the Key Agreement with Key 613 Wrapping mode. 615 The "alg" Header Parameter value "ECDH-ES" is used in the Direct Key 616 Agreement mode. In this mode, the output of the Concat KDF MUST be a 617 key of the same length as that used by the "enc" algorithm; in this 618 case, the empty octet sequence is used as the JWE Encrypted Key 619 value. 621 The "alg" Header Parameter values "ECDH-ES+A128KW", "ECDH-ES+A192KW", 622 or "ECDH-ES+A256KW" are used in the Key Agreement with Key Wrapping 623 mode. In this mode, the output of the Concat KDF MUST be a key of 624 the length needed for the specified key wrapping algorithm, one of 625 128, 192, or 256 bits respectively. 627 A new ephemeral public key value MUST be generated for each key 628 agreement operation. 630 4.6.1. Header Parameters Used for ECDH Key Agreement 632 The following Header Parameter names are used for key agreement as 633 defined below. 635 4.6.1.1. "epk" (Ephemeral Public Key) Header Parameter 637 The "epk" (ephemeral public key) value created by the originator for 638 the use in key agreement algorithms. This key is represented as a 639 JSON Web Key [JWK] public key value. It MUST contain only public key 640 parameters and SHOULD contain only the minimum JWK parameters 641 necessary to represent the key; other JWK parameters included can be 642 checked for consistency and honored or can be ignored. This Header 643 Parameter MUST be present and MUST be understood and processed by 644 implementations when these algorithms are used. 646 4.6.1.2. "apu" (Agreement PartyUInfo) Header Parameter 648 The "apu" (agreement PartyUInfo) value for key agreement algorithms 649 using it (such as "ECDH-ES"), represented as a base64url encoded 650 string. When used, the PartyUInfo value contains information about 651 the sender. Use of this Header Parameter is OPTIONAL. This Header 652 Parameter MUST be understood and processed by implementations when 653 these algorithms are used. 655 4.6.1.3. "apv" (Agreement PartyVInfo) Header Parameter 657 The "apv" (agreement PartyVInfo) value for key agreement algorithms 658 using it (such as "ECDH-ES"), represented as a base64url encoded 659 string. When used, the PartyVInfo value contains information about 660 the receiver. Use of this Header Parameter is OPTIONAL. This Header 661 Parameter MUST be understood and processed by implementations when 662 these algorithms are used. 664 4.6.2. Key Derivation for ECDH Key Agreement 666 The key derivation process derives the agreed upon key from the 667 shared secret Z established through the ECDH algorithm, per Section 668 6.2.2.2 of [NIST.800-56A]. 670 Key derivation is performed using the Concat KDF, as defined in 671 Section 5.8.1 of [NIST.800-56A], where the Digest Method is SHA-256. 672 The Concat KDF parameters are set as follows: 674 Z This is set to the representation of the shared secret Z as an 675 octet sequence. 677 keydatalen This is set to the number of bits in the desired output 678 key. For "ECDH-ES", this is length of the key used by the "enc" 679 algorithm. For "ECDH-ES+A128KW", "ECDH-ES+A192KW", and 680 "ECDH-ES+A256KW", this is 128, 192, and 256, respectively. 682 AlgorithmID The AlgorithmID value is of the form Datalen || Data, 683 where Data is a variable-length string of zero or more octets, and 684 Datalen is a fixed-length, big endian 32 bit counter that 685 indicates the length (in octets) of Data. In the Direct Key 686 Agreement case, Data is set to the octets of the UTF-8 687 representation of the "enc" Header Parameter value. In the Key 688 Agreement with Key Wrapping case, Data is set to the octets of the 689 UTF-8 representation of the "alg" Header Parameter value. 691 PartyUInfo The PartyUInfo value is of the form Datalen || Data, 692 where Data is a variable-length string of zero or more octets, and 693 Datalen is a fixed-length, big endian 32 bit counter that 694 indicates the length (in octets) of Data. If an "apu" (agreement 695 PartyUInfo) Header Parameter is present, Data is set to the result 696 of base64url decoding the "apu" value and Datalen is set to the 697 number of octets in Data. Otherwise, Datalen is set to 0 and Data 698 is set to the empty octet sequence. 700 PartyVInfo The PartyVInfo value is of the form Datalen || Data, 701 where Data is a variable-length string of zero or more octets, and 702 Datalen is a fixed-length, big endian 32 bit counter that 703 indicates the length (in octets) of Data. If an "apv" (agreement 704 PartyVInfo) Header Parameter is present, Data is set to the result 705 of base64url decoding the "apv" value and Datalen is set to the 706 number of octets in Data. Otherwise, Datalen is set to 0 and Data 707 is set to the empty octet sequence. 709 SuppPubInfo This is set to the keydatalen represented as a 32 bit 710 big endian integer. 712 SuppPrivInfo This is set to the empty octet sequence. 714 Applications need to specify how the "apu" and "apv" parameters are 715 used for that application. The "apu" and "apv" values MUST be 716 distinct, when used. Applications wishing to conform to 717 [NIST.800-56A] need to provide values that meet the requirements of 718 that document, e.g., by using values that identify the sender and 719 recipient. Alternatively, applications MAY conduct key derivation in 720 a manner similar to The Diffie-Hellman Key Agreement Method 721 [RFC2631]: In that case, the "apu" field MAY either be omitted or 722 represent a random 512-bit value (analogous to PartyAInfo in 723 Ephemeral-Static mode in [RFC2631]) and the "apv" field should not be 724 present. 726 See Appendix C for an example key agreement computation using this 727 method. 729 4.7. Key Encryption with AES GCM 731 This section defines the specifics of encrypting a JWE Content 732 Encryption Key (CEK) with Advanced Encryption Standard (AES) in 733 Galois/Counter Mode (GCM) [AES] [NIST.800-38D] using a 128, 192, or 734 256 bit key. The "alg" Header Parameter values "A128GCMKW", 735 "A192GCMKW", or "A256GCMKW" are respectively used in this case. 737 Use of an Initialization Vector of size 96 bits is REQUIRED with this 738 algorithm. The Initialization Vector is represented in base64url 739 encoded form as the "iv" (initialization vector) Header Parameter 740 value. 742 The Additional Authenticated Data value used is the empty octet 743 string. 745 The requested size of the Authentication Tag output MUST be 128 bits, 746 regardless of the key size. 748 The JWE Encrypted Key value is the Ciphertext output. 750 The Authentication Tag output is represented in base64url encoded 751 form as the "tag" (authentication tag) Header Parameter value. 753 4.7.1. Header Parameters Used for AES GCM Key Encryption 755 The following Header Parameters are used for AES GCM key encryption. 757 4.7.1.1. "iv" (Initialization Vector) Header Parameter 759 The "iv" (initialization vector) Header Parameter value is the 760 base64url encoded representation of the Initialization Vector value 761 used for the key encryption operation. This Header Parameter MUST be 762 present and MUST be understood and processed by implementations when 763 these algorithms are used. 765 4.7.1.2. "tag" (Authentication Tag) Header Parameter 767 The "tag" (authentication tag) Header Parameter value is the 768 base64url encoded representation of the Authentication Tag value 769 resulting from the key encryption operation. This Header Parameter 770 MUST be present and MUST be understood and processed by 771 implementations when these algorithms are used. 773 4.8. Key Encryption with PBES2 775 The "PBES2-HS256+A128KW", "PBES2-HS384+A192KW", and 776 "PBES2-HS512+A256KW" composite algorithms are used to perform 777 password-based encryption of a JWE CEK, by first deriving a key 778 encryption key from a user-supplied password, then encrypting the JWE 779 CEK using the derived key. These algorithms are PBES2 schemes as 780 specified in Section 6.2 of [RFC2898]. 782 These algorithms use HMAC SHA-2 algorithms as the Pseudo-Random 783 Function (PRF) for the PBKDF2 key derivation and AES Key Wrap 784 [RFC3394] for the encryption scheme. The PBES2 password input is an 785 octet sequence; if the password to be used is represented as a text 786 string rather than an octet sequence, the UTF-8 encoding of the text 787 string MUST be used as the octet sequence. The salt MUST be provided 788 as the "p2s" Header Parameter value, and MUST be base64url decoded to 789 obtain the value. The iteration count parameter MUST be provided as 790 the "p2c" Header Parameter value. The algorithms respectively use 791 HMAC SHA-256, HMAC SHA-384, and HMAC SHA-512 as the PRF and use 128, 792 192, and 256 bit AES Key Wrap keys. Their derived-key lengths 793 respectively are 16, 24, and 32 octets. 795 See Appendix C of JSON Web Key (JWK) [JWK] for an example key 796 encryption computation using "PBES2-HS256+A128KW". 798 4.8.1. Header Parameters Used for PBES2 Key Encryption 800 The following Header Parameters are used for Key Encryption with 801 PBES2. 803 4.8.1.1. "p2s" (PBES2 salt) Parameter 805 The "p2s" (PBES2 salt) Header Parameter contains the PBKDF2 salt 806 value, encoded using base64url. This Header Parameter MUST be 807 present and MUST be understood and processed by implementations when 808 these algorithms are used. 810 The salt expands the possible keys that can be derived from a given 811 password. A salt value containing 8 or more octets MUST be used. A 812 new salt value MUST be generated randomly for every encryption 813 operation; see [RFC4086] for considerations on generating random 814 values. 816 4.8.1.2. "p2c" (PBES2 count) Parameter 818 The "p2c" (PBES2 count) Header Parameter contains the PBKDF2 819 iteration count, represented as a positive integer. This Header 820 Parameter MUST be present and MUST be understood and processed by 821 implementations when these algorithms are used. 823 The iteration count adds computational expense, ideally compounded by 824 the possible range of keys introduced by the salt. A minimum 825 iteration count of 1000 is RECOMMENDED. 827 5. Cryptographic Algorithms for Content Encryption 829 JWE uses cryptographic algorithms to encrypt the Plaintext. 831 5.1. "enc" (Encryption Method) Header Parameter Values for JWE 833 The table below is the set of "enc" (encryption method) Header 834 Parameter values that are defined by this specification for use with 835 JWE. These algorithms are used to encrypt the Plaintext, which 836 produces the Ciphertext. 838 +-------------+------------------------+------------+---------------+ 839 | enc | Content Encryption | Additional | Implementatio | 840 | Parameter | Algorithm | Header | nRequirements | 841 | Value | | Parameters | | 842 +-------------+------------------------+------------+---------------+ 843 | A128CBC-HS2 | AES_128_CBC_HMAC_SHA_2 | (none) | Required | 844 | 56 | 56 authenticated | | | 845 | | encryption algorithm, | | | 846 | | as defined in | | | 847 | | Section 5.2.3 | | | 848 | A192CBC-HS3 | AES_192_CBC_HMAC_SHA_3 | (none) | Optional | 849 | 84 | 84 authenticated | | | 850 | | encryption algorithm, | | | 851 | | as defined in | | | 852 | | Section 5.2.4 | | | 853 | A256CBC-HS5 | AES_256_CBC_HMAC_SHA_5 | (none) | Required | 854 | 12 | 12 authenticated | | | 855 | | encryption algorithm, | | | 856 | | as defined in | | | 857 | | Section 5.2.5 | | | 858 | A128GCM | AES GCM using 128 bit | (none) | Recommended | 859 | | key | | | 860 | A192GCM | AES GCM using 192 bit | (none) | Optional | 861 | | key | | | 862 | A256GCM | AES GCM using 256 bit | (none) | Recommended | 863 | | key | | | 864 +-------------+------------------------+------------+---------------+ 866 The Additional Header Parameters column indicates what additional 867 Header Parameters are used by the algorithm, beyond "enc", which all 868 use. All also use a JWE Initialization Vector value and produce JWE 869 Ciphertext and JWE Authentication Tag values. 871 See Appendix A.3 for a table cross-referencing the JWE "enc" 872 (encryption method) values defined in this specification with the 873 equivalent identifiers used by other standards and software packages. 875 5.2. AES_CBC_HMAC_SHA2 Algorithms 877 This section defines a family of authenticated encryption algorithms 878 built using a composition of Advanced Encryption Standard (AES) in 879 Cipher Block Chaining (CBC) mode with PKCS #5 padding [AES] 880 [NIST.800-38A] operations and HMAC [RFC2104] [SHS] operations. This 881 algorithm family is called AES_CBC_HMAC_SHA2. It also defines three 882 instances of this family, the first using 128 bit CBC keys and HMAC 883 SHA-256, the second using 192 bit CBC keys and HMAC SHA-384, and the 884 third using 256 bit CBC keys and HMAC SHA-512. Test cases for these 885 algorithms can be found in Appendix B. 887 These algorithms are based upon Authenticated Encryption with AES-CBC 888 and HMAC-SHA [I-D.mcgrew-aead-aes-cbc-hmac-sha2], performing the same 889 cryptographic computations, but with the Initialization Vector and 890 Authentication Tag values remaining separate, rather than being 891 concatenated with the Ciphertext value in the output representation. 892 This option is discussed in Appendix B of that specification. This 893 algorithm family is a generalization of the algorithm family in 894 [I-D.mcgrew-aead-aes-cbc-hmac-sha2], and can be used to implement 895 those algorithms. 897 5.2.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 899 We use the following notational conventions. 901 CBC-PKCS5-ENC(X, P) denotes the AES CBC encryption of P using PKCS 902 #5 padding using the cipher with the key X. 904 MAC(Y, M) denotes the application of the Message Authentication 905 Code (MAC) to the message M, using the key Y. 907 5.2.2. Generic AES_CBC_HMAC_SHA2 Algorithm 909 This section defines AES_CBC_HMAC_SHA2 in a manner that is 910 independent of the AES CBC key size or hash function to be used. 911 Section 5.2.2.1 and Section 5.2.2.2 define the generic encryption and 912 decryption algorithms. Section 5.2.3 and Section 5.2.5 define 913 instances of AES_CBC_HMAC_SHA2 that specify those details. 915 5.2.2.1. AES_CBC_HMAC_SHA2 Encryption 917 The authenticated encryption algorithm takes as input four octet 918 strings: a secret key K, a plaintext P, associated data A, and an 919 initialization vector IV. The authenticated ciphertext value E and 920 the authentication tag value T are provided as outputs. The data in 921 the plaintext are encrypted and authenticated, and the associated 922 data are authenticated, but not encrypted. 924 The encryption process is as follows, or uses an equivalent set of 925 steps: 927 1. The secondary keys MAC_KEY and ENC_KEY are generated from the 928 input key K as follows. Each of these two keys is an octet 929 string. 931 MAC_KEY consists of the initial MAC_KEY_LEN octets of K, in 932 order. 934 ENC_KEY consists of the final ENC_KEY_LEN octets of K, in 935 order. 937 Here we denote the number of octets in the MAC_KEY as 938 MAC_KEY_LEN, and the number of octets in ENC_KEY as ENC_KEY_LEN; 939 the values of these parameters are specified by the AEAD 940 algorithms (in Section 5.2.3 and Section 5.2.5). The number of 941 octets in the input key K is the sum of MAC_KEY_LEN and 942 ENC_KEY_LEN. When generating the secondary keys from K, MAC_KEY 943 and ENC_KEY MUST NOT overlap. Note that the MAC key comes before 944 the encryption key in the input key K; this is in the opposite 945 order of the algorithm names in the identifier 946 "AES_CBC_HMAC_SHA2". 948 2. The Initialization Vector (IV) used is a 128 bit value generated 949 randomly or pseudorandomly for use in the cipher. 951 3. The plaintext is CBC encrypted using PKCS #5 padding using 952 ENC_KEY as the key, and the IV. We denote the ciphertext output 953 from this step as E. 955 4. The octet string AL is equal to the number of bits in A expressed 956 as a 64-bit unsigned integer in network byte order. 958 5. A message authentication tag T is computed by applying HMAC 959 [RFC2104] to the following data, in order: 961 the associated data A, 963 the initialization vector IV, 965 the ciphertext E computed in the previous step, and 966 the octet string AL defined above. 968 The string MAC_KEY is used as the MAC key. We denote the output 969 of the MAC computed in this step as M. The first T_LEN bits of M 970 are used as T. 972 6. The Ciphertext E and the Authentication Tag T are returned as the 973 outputs of the authenticated encryption. 975 The encryption process can be illustrated as follows. Here K, P, A, 976 IV, and E denote the key, plaintext, associated data, initialization 977 vector, and ciphertext, respectively. 979 MAC_KEY = initial MAC_KEY_LEN bytes of K, 981 ENC_KEY = final ENC_KEY_LEN bytes of K, 983 E = CBC-PKCS5-ENC(ENC_KEY, P), 985 M = MAC(MAC_KEY, A || IV || E || AL), 987 T = initial T_LEN bytes of M. 989 5.2.2.2. AES_CBC_HMAC_SHA2 Decryption 991 The authenticated decryption operation has four inputs: K, A, E, and 992 T as defined above. It has only a single output, either a plaintext 993 value P or a special symbol FAIL that indicates that the inputs are 994 not authentic. The authenticated decryption algorithm is as follows, 995 or uses an equivalent set of steps: 997 1. The secondary keys MAC_KEY and ENC_KEY are generated from the 998 input key K as in Step 1 of Section 5.2.2.1. 1000 2. The integrity and authenticity of A and E are checked by 1001 computing an HMAC with the inputs as in Step 5 of 1002 Section 5.2.2.1. The value T, from the previous step, is 1003 compared to the first MAC_KEY length bits of the HMAC output. If 1004 those values are identical, then A and E are considered valid, 1005 and processing is continued. Otherwise, all of the data used in 1006 the MAC validation are discarded, and the AEAD decryption 1007 operation returns an indication that it failed, and the operation 1008 halts. (But see Section 10 of [JWE] for security considerations 1009 on thwarting timing attacks.) 1011 3. The value E is decrypted and the PKCS #5 padding is removed. The 1012 value IV is used as the initialization vector. The value ENC_KEY 1013 is used as the decryption key. 1015 4. The plaintext value is returned. 1017 5.2.3. AES_128_CBC_HMAC_SHA_256 1019 This algorithm is a concrete instantiation of the generic 1020 AES_CBC_HMAC_SHA2 algorithm above. It uses the HMAC message 1021 authentication code [RFC2104] with the SHA-256 hash function [SHS] to 1022 provide message authentication, with the HMAC output truncated to 128 1023 bits, corresponding to the HMAC-SHA-256-128 algorithm defined in 1024 [RFC4868]. For encryption, it uses AES in the Cipher Block Chaining 1025 (CBC) mode of operation as defined in Section 6.2 of [NIST.800-38A], 1026 with PKCS #5 padding. 1028 The input key K is 32 octets long. 1030 The AES CBC IV is 16 octets long. ENC_KEY_LEN is 16 octets. 1032 The SHA-256 hash algorithm is used in HMAC. MAC_KEY_LEN is 16 1033 octets. The HMAC-SHA-256 output is truncated to T_LEN=16 octets, by 1034 stripping off the final 16 octets. 1036 5.2.4. AES_192_CBC_HMAC_SHA_384 1038 AES_192_CBC_HMAC_SHA_384 is based on AES_128_CBC_HMAC_SHA_256, but 1039 with the following differences: 1041 A 192 bit AES CBC key is used instead of 128. 1043 SHA-384 is used in HMAC instead of SHA-256. 1045 ENC_KEY_LEN is 24 octets instead of 16. 1047 MAC_KEY_LEN is 24 octets instead of 16. 1049 The length of the input key K is 48 octets instead of 32. 1051 The HMAC SHA-384 value is truncated to T_LEN=24 octets instead of 1052 16. 1054 5.2.5. AES_256_CBC_HMAC_SHA_512 1056 AES_256_CBC_HMAC_SHA_512 is based on AES_128_CBC_HMAC_SHA_256, but 1057 with the following differences: 1059 A 256 bit AES CBC key is used instead of 128. 1061 SHA-512 is used in HMAC instead of SHA-256. 1063 ENC_KEY_LEN is 32 octets instead of 16. 1065 MAC_KEY_LEN is 32 octets instead of 16. 1067 The length of the input key K is 64 octets instead of 32. 1069 The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of 1070 16. 1072 5.2.6. Plaintext Encryption with AES_CBC_HMAC_SHA2 1074 The algorithm value "A128CBC-HS256" is used as the "alg" value when 1075 using AES_128_CBC_HMAC_SHA_256 with JWE. The algorithm value 1076 "A192CBC-HS384" is used as the "alg" value when using 1077 AES_192_CBC_HMAC_SHA_384 with JWE. The algorithm value 1078 "A256CBC-HS512" is used as the "alg" value when using 1079 AES_256_CBC_HMAC_SHA_512 with JWE. 1081 5.3. Plaintext Encryption with AES GCM 1083 This section defines the specifics of encrypting the JWE Plaintext 1084 with Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) 1085 [AES] [NIST.800-38D] using a 128, 192, or 256 bit key. The "enc" 1086 Header Parameter values "A128GCM", "A192GCM", or "A256GCM" are 1087 respectively used in this case. 1089 The CEK is used as the encryption key. 1091 Use of an initialization vector of size 96 bits is REQUIRED with this 1092 algorithm. 1094 The requested size of the Authentication Tag output MUST be 128 bits, 1095 regardless of the key size. 1097 The JWE Authentication Tag is set to be the Authentication Tag value 1098 produced by the encryption. During decryption, the received JWE 1099 Authentication Tag is used as the Authentication Tag value. 1101 An example using this algorithm is shown in Appendix A.1 of [JWE]. 1103 6. Cryptographic Algorithms for Keys 1105 A JSON Web Key (JWK) [JWK] is a JSON data structure that represents a 1106 cryptographic key. These keys can be either asymmetric or symmetric. 1107 They can hold both public and private information about the key. 1108 This section defines the parameters for keys using the algorithms 1109 specified by this document. 1111 6.1. "kty" (Key Type) Parameter Values 1113 The table below is the set of "kty" (key type) parameter values that 1114 are defined by this specification for use in JWKs. 1116 +--------------+--------------------------------+-------------------+ 1117 | kty | Key Type | Implementation | 1118 | Parameter | | Requirements | 1119 | Value | | | 1120 +--------------+--------------------------------+-------------------+ 1121 | EC | Elliptic Curve [DSS] | Recommended+ | 1122 | RSA | RSA [RFC3447] | Required | 1123 | oct | Octet sequence (used to | Required | 1124 | | represent symmetric keys) | | 1125 +--------------+--------------------------------+-------------------+ 1127 The use of "+" in the Implementation Requirements indicates that the 1128 requirement strength is likely to be increased in a future version of 1129 the specification. 1131 6.2. Parameters for Elliptic Curve Keys 1133 JWKs can represent Elliptic Curve [DSS] keys. In this case, the 1134 "kty" member value MUST be "EC". 1136 6.2.1. Parameters for Elliptic Curve Public Keys 1138 An elliptic curve public key is represented by a pair of coordinates 1139 drawn from a finite field, which together define a point on an 1140 elliptic curve. The following members MUST be present for elliptic 1141 curve public keys: 1143 o "crv" 1145 o "x" 1147 o "y" 1149 SEC1 [SEC1] point compression is not supported for any values. 1151 6.2.1.1. "crv" (Curve) Parameter 1153 The "crv" (curve) member identifies the cryptographic curve used with 1154 the key. Curve values from [DSS] used by this specification are: 1156 o "P-256" 1157 o "P-384" 1159 o "P-521" 1161 These values are registered in the IANA JSON Web Key Elliptic Curve 1162 registry defined in Section 7.6. Additional "crv" values MAY be 1163 used, provided they are understood by implementations using that 1164 Elliptic Curve key. The "crv" value is a case-sensitive string. 1166 6.2.1.2. "x" (X Coordinate) Parameter 1168 The "x" (x coordinate) member contains the x coordinate for the 1169 elliptic curve point. It is represented as the base64url encoding of 1170 the octet string representation of the coordinate, as defined in 1171 Section 2.3.5 of SEC1 [SEC1]. The length of this octet string MUST 1172 be the full size of a coordinate for the curve specified in the "crv" 1173 parameter. For example, if the value of "crv" is "P-521", the octet 1174 string must be 66 octets long. 1176 6.2.1.3. "y" (Y Coordinate) Parameter 1178 The "y" (y coordinate) member contains the y coordinate for the 1179 elliptic curve point. It is represented as the base64url encoding of 1180 the octet string representation of the coordinate, as defined in 1181 Section 2.3.5 of SEC1 [SEC1]. The length of this octet string MUST 1182 be the full size of a coordinate for the curve specified in the "crv" 1183 parameter. For example, if the value of "crv" is "P-521", the octet 1184 string must be 66 octets long. 1186 6.2.2. Parameters for Elliptic Curve Private Keys 1188 In addition to the members used to represent Elliptic Curve public 1189 keys, the following member MUST be present to represent Elliptic 1190 Curve private keys. 1192 6.2.2.1. "d" (ECC Private Key) Parameter 1194 The "d" (ECC private key) member contains the Elliptic Curve private 1195 key value. It is represented as the base64url encoding of the octet 1196 string representation of the private key value, as defined in 1197 Sections C.4 and 2.3.7 of SEC1 [SEC1]. The length of this octet 1198 string MUST be ceiling(log-base-2(n)/8) octets (where n is the order 1199 of the curve). 1201 6.3. Parameters for RSA Keys 1203 JWKs can represent RSA [RFC3447] keys. In this case, the "kty" 1204 member value MUST be "RSA". 1206 6.3.1. Parameters for RSA Public Keys 1208 The following members MUST be present for RSA public keys. 1210 6.3.1.1. "n" (Modulus) Parameter 1212 The "n" (modulus) member contains the modulus value for the RSA 1213 public key. It is represented as the base64url encoding of the 1214 value's unsigned big endian representation as an octet sequence. The 1215 octet sequence MUST utilize the minimum number of octets to represent 1216 the value. 1218 6.3.1.2. "e" (Exponent) Parameter 1220 The "e" (exponent) member contains the exponent value for the RSA 1221 public key. It is represented as the base64url encoding of the 1222 value's unsigned big endian representation as an octet sequence. The 1223 octet sequence MUST utilize the minimum number of octets to represent 1224 the value. For instance, when representing the value 65537, the 1225 octet sequence to be base64url encoded MUST consist of the three 1226 octets [1, 0, 1]. 1228 6.3.2. Parameters for RSA Private Keys 1230 In addition to the members used to represent RSA public keys, the 1231 following members are used to represent RSA private keys. The 1232 parameter "d" is REQUIRED for RSA private keys. The others enable 1233 optimizations and SHOULD be included by producers of JWKs 1234 representing RSA private keys. If the producer includes any of the 1235 other private key parameters, then all of the others MUST be present, 1236 with the exception of "oth", which MUST only be present when more 1237 than two prime factors were used. The consumer of a JWK MAY choose 1238 to accept an RSA private key that does not contain a complete set of 1239 the private key parameters other than "d", including JWKs in which 1240 "d" is the only RSA private key parameter included. 1242 6.3.2.1. "d" (Private Exponent) Parameter 1244 The "d" (private exponent) member contains the private exponent value 1245 for the RSA private key. It is represented as the base64url encoding 1246 of the value's unsigned big endian representation as an octet 1247 sequence. The octet sequence MUST utilize the minimum number of 1248 octets to represent the value. 1250 6.3.2.2. "p" (First Prime Factor) Parameter 1252 The "p" (first prime factor) member contains the first prime factor, 1253 a positive integer. It is represented as the base64url encoding of 1254 the value's unsigned big endian representation as an octet sequence. 1255 The octet sequence MUST utilize the minimum number of octets to 1256 represent the value. 1258 6.3.2.3. "q" (Second Prime Factor) Parameter 1260 The "q" (second prime factor) member contains the second prime 1261 factor, a positive integer. It is represented as the base64url 1262 encoding of the value's unsigned big endian representation as an 1263 octet sequence. The octet sequence MUST utilize the minimum number 1264 of octets to represent the value. 1266 6.3.2.4. "dp" (First Factor CRT Exponent) Parameter 1268 The "dp" (first factor CRT exponent) member contains the Chinese 1269 Remainder Theorem (CRT) exponent of the first factor, a positive 1270 integer. It is represented as the base64url encoding of the value's 1271 unsigned big endian representation as an octet sequence. The octet 1272 sequence MUST utilize the minimum number of octets to represent the 1273 value. 1275 6.3.2.5. "dq" (Second Factor CRT Exponent) Parameter 1277 The "dq" (second factor CRT exponent) member contains the Chinese 1278 Remainder Theorem (CRT) exponent of the second factor, a positive 1279 integer. It is represented as the base64url encoding of the value's 1280 unsigned big endian representation as an octet sequence. The octet 1281 sequence MUST utilize the minimum number of octets to represent the 1282 value. 1284 6.3.2.6. "qi" (First CRT Coefficient) Parameter 1286 The "dp" (first CRT coefficient) member contains the Chinese 1287 Remainder Theorem (CRT) coefficient of the second factor, a positive 1288 integer. It is represented as the base64url encoding of the value's 1289 unsigned big endian representation as an octet sequence. The octet 1290 sequence MUST utilize the minimum number of octets to represent the 1291 value. 1293 6.3.2.7. "oth" (Other Primes Info) Parameter 1295 The "oth" (other primes info) member contains an array of information 1296 about any third and subsequent primes, should they exist. When only 1297 two primes have been used (the normal case), this parameter MUST be 1298 omitted. When three or more primes have been used, the number of 1299 array elements MUST be the number of primes used minus two. Each 1300 array element MUST be an object with the following members: 1302 6.3.2.7.1. "r" (Prime Factor) 1304 The "r" (prime factor) parameter within an "oth" array member 1305 represents the value of a subsequent prime factor, a positive 1306 integer. It is represented as the base64url encoding of the value's 1307 unsigned big endian representation as an octet sequence. The octet 1308 sequence MUST utilize the minimum number of octets to represent the 1309 value. 1311 6.3.2.7.2. "d" (Factor CRT Exponent) 1313 The "d" (Factor CRT Exponent) parameter within an "oth" array member 1314 represents the CRT exponent of the corresponding prime factor, a 1315 positive integer. It is represented as the base64url encoding of the 1316 value's unsigned big endian representation as an octet sequence. The 1317 octet sequence MUST utilize the minimum number of octets to represent 1318 the value. 1320 6.3.2.7.3. "t" (Factor CRT Coefficient) 1322 The "t" (factor CRT coefficient) parameter within an "oth" array 1323 member represents the CRT coefficient of the corresponding prime 1324 factor, a positive integer. It is represented as the base64url 1325 encoding of the value's unsigned big endian representation as an 1326 octet sequence. The octet sequence MUST utilize the minimum number 1327 of octets to represent the value. 1329 6.4. Parameters for Symmetric Keys 1331 When the JWK "kty" member value is "oct" (octet sequence), the member 1332 "k" is used to represent a symmetric key (or another key whose value 1333 is a single octet sequence). An "alg" member SHOULD also be present 1334 to identify the algorithm intended to be used with the key, unless 1335 the application uses another means or convention to determine the 1336 algorithm used. 1338 6.4.1. "k" (Key Value) Parameter 1340 The "k" (key value) member contains the value of the symmetric (or 1341 other single-valued) key. It is represented as the base64url 1342 encoding of the octet sequence containing the key value. 1344 7. IANA Considerations 1346 The following registration procedure is used for all the registries 1347 established by this specification. 1349 Values are registered with a Specification Required [RFC5226] after a 1350 two-week review period on the [TBD]@ietf.org mailing list, on the 1351 advice of one or more Designated Experts. However, to allow for the 1352 allocation of values prior to publication, the Designated Expert(s) 1353 may approve registration once they are satisfied that such a 1354 specification will be published. 1356 Registration requests must be sent to the [TBD]@ietf.org mailing list 1357 for review and comment, with an appropriate subject (e.g., "Request 1358 for access token type: example"). [[ Note to the RFC Editor: The name 1359 of the mailing list should be determined in consultation with the 1360 IESG and IANA. Suggested name: jose-reg-review. ]] 1362 Within the review period, the Designated Expert(s) will either 1363 approve or deny the registration request, communicating this decision 1364 to the review list and IANA. Denials should include an explanation 1365 and, if applicable, suggestions as to how to make the request 1366 successful. Registration requests that are undetermined for a period 1367 longer than 21 days can be brought to the IESG's attention (using the 1368 iesg@iesg.org mailing list) for resolution. 1370 Criteria that should be applied by the Designated Expert(s) includes 1371 determining whether the proposed registration duplicates existing 1372 functionality, determining whether it is likely to be of general 1373 applicability or whether it is useful only for a single application, 1374 and whether the registration makes sense. 1376 IANA must only accept registry updates from the Designated Expert(s) 1377 and should direct all requests for registration to the review mailing 1378 list. 1380 It is suggested that multiple Designated Experts be appointed who are 1381 able to represent the perspectives of different applications using 1382 this specification, in order to enable broadly-informed review of 1383 registration decisions. In cases where a registration decision could 1384 be perceived as creating a conflict of interest for a particular 1385 Expert, that Expert should defer to the judgment of the other 1386 Expert(s). 1388 7.1. JSON Web Signature and Encryption Algorithms Registry 1390 This specification establishes the IANA JSON Web Signature and 1391 Encryption Algorithms registry for values of the JWS and JWE "alg" 1392 (algorithm) and "enc" (encryption method) Header Parameters. The 1393 registry records the algorithm name, the algorithm usage locations, 1394 implementation requirements, and a reference to the specification 1395 that defines it. The same algorithm name can be registered multiple 1396 times, provided that the sets of usage locations are disjoint. 1398 It is suggested that when algorithms can use keys of different 1399 lengths, that the length of the key be included in the algorithm 1400 name. This allows readers of the JSON text to easily make security 1401 consideration decisions. 1403 The implementation requirements of an algorithm MAY be changed over 1404 time by the Designated Experts(s) as the cryptographic landscape 1405 evolves, for instance, to change the status of an algorithm to 1406 Deprecated, or to change the status of an algorithm from Optional to 1407 Recommended+ or Required. Changes of implementation requirements are 1408 only permitted on a Specification Required basis, with the new 1409 specification defining the revised implementation requirements level. 1411 7.1.1. Registration Template 1413 Algorithm Name: 1414 The name requested (e.g., "example"). This name is case- 1415 sensitive. Names may not match other registered names in a case- 1416 insensitive manner unless the Designated Expert(s) state that 1417 there is a compelling reason to allow an exception in this 1418 particular case. 1420 Algorithm Description: 1421 Brief description of the Algorithm (e.g., "Example description"). 1423 Algorithm Usage Location(s): 1424 The algorithm usage location. This must be one or more of the 1425 values "alg" or "enc" if the algorithm is to be used with JWS or 1426 JWE. The value "JWK" is used if the algorithm identifier will be 1427 used as a JWK "alg" member value, but will not be used with JWS or 1428 JWE; this could be the case, for instance, for non-authenticated 1429 encryption algorithms. Other values may be used with the approval 1430 of a Designated Expert. 1432 Implementation Requirements: 1433 The algorithm implementation requirements, which must be one the 1434 words Required, Recommended, Optional, Deprecated, or Prohibited. 1435 Optionally, the word can be followed by a "+" or "-". The use of 1436 "+" indicates that the requirement strength is likely to be 1437 increased in a future version of the specification. The use of 1438 "-" indicates that the requirement strength is likely to be 1439 decreased in a future version of the specification. Any 1440 identifiers registered for non-authenticated encryption algorithms 1441 or other algorithms that are otherwise unsuitable for direct use 1442 as JWS or JWE algorithms must be registered as "Prohibited". 1444 Change Controller: 1445 For Standards Track RFCs, state "IESG". For others, give the name 1446 of the responsible party. Other details (e.g., postal address, 1447 email address, home page URI) may also be included. 1449 Specification Document(s): 1450 Reference to the document(s) that specify the parameter, 1451 preferably including URI(s) that can be used to retrieve copies of 1452 the document(s). An indication of the relevant sections may also 1453 be included but is not required. 1455 7.1.2. Initial Registry Contents 1457 o Algorithm Name: "HS256" 1458 o Algorithm Description: HMAC using SHA-256 1459 o Algorithm Usage Location(s): "alg" 1460 o Implementation Requirements: Required 1461 o Change Controller: IESG 1462 o Specification Document(s): Section 3.1 of [[ this document ]] 1464 o Algorithm Name: "HS384" 1465 o Algorithm Description: HMAC using SHA-384 1466 o Algorithm Usage Location(s): "alg" 1467 o Implementation Requirements: Optional 1468 o Change Controller: IESG 1469 o Specification Document(s): Section 3.1 of [[ this document ]] 1471 o Algorithm Name: "HS512" 1472 o Algorithm Description: HMAC using SHA-512 1473 o Algorithm Usage Location(s): "alg" 1474 o Implementation Requirements: Optional 1475 o Change Controller: IESG 1476 o Specification Document(s): Section 3.1 of [[ this document ]] 1478 o Algorithm Name: "RS256" 1479 o Algorithm Description: RSASSA-PKCS-v1_5 using SHA-256 1480 o Algorithm Usage Location(s): "alg" 1481 o Implementation Requirements: Recommended 1482 o Change Controller: IESG 1483 o Specification Document(s): Section 3.1 of [[ this document ]] 1485 o Algorithm Name: "RS384" 1486 o Algorithm Description: RSASSA-PKCS-v1_5 using SHA-384 1487 o Algorithm Usage Location(s): "alg" 1488 o Implementation Requirements: Optional 1489 o Change Controller: IESG 1490 o Specification Document(s): Section 3.1 of [[ this document ]] 1492 o Algorithm Name: "RS512" 1493 o Algorithm Description: RSASSA-PKCS-v1_5 using SHA-512 1494 o Algorithm Usage Location(s): "alg" 1495 o Implementation Requirements: Optional 1496 o Change Controller: IESG 1497 o Specification Document(s): Section 3.1 of [[ this document ]] 1499 o Algorithm Name: "ES256" 1500 o Algorithm Description: ECDSA using P-256 and SHA-256 1501 o Algorithm Usage Location(s): "alg" 1502 o Implementation Requirements: Recommended+ 1503 o Change Controller: IESG 1504 o Specification Document(s): Section 3.1 of [[ this document ]] 1506 o Algorithm Name: "ES384" 1507 o Algorithm Description: ECDSA using P-384 and SHA-384 1508 o Algorithm Usage Location(s): "alg" 1509 o Implementation Requirements: Optional 1510 o Change Controller: IESG 1511 o Specification Document(s): Section 3.1 of [[ this document ]] 1513 o Algorithm Name: "ES512" 1514 o Algorithm Description: ECDSA using P-521 and SHA-512 1515 o Algorithm Usage Location(s): "alg" 1516 o Implementation Requirements: Optional 1517 o Change Controller: IESG 1518 o Specification Document(s): Section 3.1 of [[ this document ]] 1520 o Algorithm Name: "PS256" 1521 o Algorithm Description: RSASSA-PSS using SHA-256 and MGF1 with SHA- 1522 256 1523 o Algorithm Usage Location(s): "alg" 1524 o Implementation Requirements: Optional 1525 o Change Controller: IESG 1526 o Specification Document(s): Section 3.1 of [[ this document ]] 1528 o Algorithm Name: "PS384" 1529 o Algorithm Description: RSASSA-PSS using SHA-384 and MGF1 with SHA- 1530 384 1531 o Algorithm Usage Location(s): "alg" 1532 o Implementation Requirements: Optional 1533 o Change Controller: IESG 1534 o Specification Document(s): Section 3.1 of [[ this document ]] 1535 o Algorithm Name: "PS512" 1536 o Algorithm Description: RSASSA-PSS using SHA-512 and MGF1 with SHA- 1537 512 1538 o Algorithm Usage Location(s): "alg" 1539 o Implementation Requirements: Optional 1540 o Change Controller: IESG 1541 o Specification Document(s): Section 3.1 of [[ this document ]] 1543 o Algorithm Name: "none" 1544 o Algorithm Description: No digital signature or MAC performed 1545 o Algorithm Usage Location(s): "alg" 1546 o Implementation Requirements: Optional 1547 o Change Controller: IESG 1548 o Specification Document(s): Section 3.1 of [[ this document ]] 1550 o Algorithm Name: "RSA1_5" 1551 o Algorithm Description: RSAES-PKCS1-V1_5 1552 o Algorithm Usage Location(s): "alg" 1553 o Implementation Requirements: Required 1554 o Change Controller: IESG 1555 o Specification Document(s): Section 4.1 of [[ this document ]] 1557 o Algorithm Name: "RSA-OAEP" 1558 o Algorithm Description: RSAES using OAEP with default parameters 1559 o Algorithm Usage Location(s): "alg" 1560 o Implementation Requirements: Optional 1561 o Change Controller: IESG 1562 o Specification Document(s): Section 4.1 of [[ this document ]] 1564 o Algorithm Name: "A128KW" 1565 o Algorithm Description: AES Key Wrap using 128 bit key 1566 o Algorithm Usage Location(s): "alg" 1567 o Implementation Requirements: Recommended 1568 o Change Controller: IESG 1569 o Specification Document(s): Section 4.1 of [[ this document ]] 1571 o Algorithm Name: "A192KW" 1572 o Algorithm Description: AES Key Wrap using 192 bit key 1573 o Algorithm Usage Location(s): "alg" 1574 o Implementation Requirements: Optional 1575 o Change Controller: IESG 1576 o Specification Document(s): Section 4.1 of [[ this document ]] 1578 o Algorithm Name: "A256KW" 1579 o Algorithm Description: AES Key Wrap using 256 bit key 1580 o Algorithm Usage Location(s): "alg" 1581 o Implementation Requirements: Recommended 1582 o Change Controller: IESG 1583 o Specification Document(s): Section 4.1 of [[ this document ]] 1585 o Algorithm Name: "dir" 1586 o Algorithm Description: Direct use of a shared symmetric key 1587 o Algorithm Usage Location(s): "alg" 1588 o Implementation Requirements: Recommended 1589 o Change Controller: IESG 1590 o Specification Document(s): Section 4.1 of [[ this document ]] 1592 o Algorithm Name: "ECDH-ES" 1593 o Algorithm Description: ECDH-ES using Concat KDF 1594 o Algorithm Usage Location(s): "alg" 1595 o Implementation Requirements: Recommended+ 1596 o Change Controller: IESG 1597 o Specification Document(s): Section 4.1 of [[ this document ]] 1599 o Algorithm Name: "ECDH-ES+A128KW" 1600 o Algorithm Description: ECDH-ES using Concat KDF and "A128KW" 1601 wrapping 1602 o Algorithm Usage Location(s): "alg" 1603 o Implementation Requirements: Recommended 1604 o Change Controller: IESG 1605 o Specification Document(s): Section 4.1 of [[ this document ]] 1607 o Algorithm Name: "ECDH-ES+A192KW" 1608 o Algorithm Description: ECDH-ES using Concat KDF and "A192KW" 1609 wrapping 1610 o Algorithm Usage Location(s): "alg" 1611 o Implementation Requirements: Optional 1612 o Change Controller: IESG 1613 o Specification Document(s): Section 4.1 of [[ this document ]] 1615 o Algorithm Name: "ECDH-ES+A256KW" 1616 o Algorithm Description: ECDH-ES using Concat KDF and "A256KW" 1617 wrapping 1618 o Algorithm Usage Location(s): "alg" 1619 o Implementation Requirements: Recommended 1620 o Change Controller: IESG 1621 o Specification Document(s): Section 4.1 of [[ this document ]] 1623 o Algorithm Name: "A128GCMKW" 1624 o Algorithm Description: Key wrapping with AES GCM using 128 bit key 1625 o Algorithm Usage Location(s): "alg" 1626 o Implementation Requirements: Optional 1627 o Change Controller: IESG 1628 o Specification Document(s): Section 4.7 of [[ this document ]] 1630 o Algorithm Name: "A192GCMKW" 1631 o Algorithm Description: Key wrapping with AES GCM using 192 bit key 1632 o Algorithm Usage Location(s): "alg" 1633 o Implementation Requirements: Optional 1634 o Change Controller: IESG 1635 o Specification Document(s): Section 4.7 of [[ this document ]] 1637 o Algorithm Name: "A256GCMKW" 1638 o Algorithm Description: Key wrapping with AES GCM using 256 bit key 1639 o Algorithm Usage Location(s): "alg" 1640 o Implementation Requirements: Optional 1641 o Change Controller: IESG 1642 o Specification Document(s): Section 4.7 of [[ this document ]] 1644 o Algorithm Name: "PBES2-HS256+A128KW" 1645 o Algorithm Description: PBES2 with HMAC SHA-256 and "A128KW" 1646 wrapping 1647 o Algorithm Usage Location(s): "alg" 1648 o Implementation Requirements: Optional 1649 o Change Controller: IESG 1650 o Specification Document(s): Section 4.8 of [[ this document ]] 1652 o Algorithm Name: "PBES2-HS384+A192KW" 1653 o Algorithm Description: PBES2 with HMAC SHA-384 and "A192KW" 1654 wrapping 1655 o Algorithm Usage Location(s): "alg" 1656 o Implementation Requirements: Optional 1657 o Change Controller: IESG 1658 o Specification Document(s): Section 4.8 of [[ this document ]] 1660 o Algorithm Name: "PBES2-HS512+A256KW" 1661 o Algorithm Description: PBES2 with HMAC SHA-512 and "A256KW" 1662 wrapping 1663 o Algorithm Usage Location(s): "alg" 1664 o Implementation Requirements: Optional 1665 o Change Controller: IESG 1666 o Specification Document(s): Section 4.8 of [[ this document ]] 1668 o Algorithm Name: "A128CBC-HS256" 1669 o Algorithm Description: AES_128_CBC_HMAC_SHA_256 authenticated 1670 encryption algorithm 1671 o Algorithm Usage Location(s): "enc" 1672 o Implementation Requirements: Required 1673 o Change Controller: IESG 1674 o Specification Document(s): Section 5.1 of [[ this document ]] 1676 o Algorithm Name: "A192CBC-HS384" 1677 o Algorithm Description: AES_192_CBC_HMAC_SHA_384 authenticated 1678 encryption algorithm 1679 o Algorithm Usage Location(s): "enc" 1680 o Implementation Requirements: Optional 1681 o Change Controller: IESG 1682 o Specification Document(s): Section 5.1 of [[ this document ]] 1684 o Algorithm Name: "A256CBC-HS512" 1685 o Algorithm Description: AES_256_CBC_HMAC_SHA_512 authenticated 1686 encryption algorithm 1687 o Algorithm Usage Location(s): "enc" 1688 o Implementation Requirements: Required 1689 o Change Controller: IESG 1690 o Specification Document(s): Section 5.1 of [[ this document ]] 1692 o Algorithm Name: "A128GCM" 1693 o Algorithm Description: AES GCM using 128 bit key 1694 o Algorithm Usage Location(s): "enc" 1695 o Implementation Requirements: Recommended 1696 o Change Controller: IESG 1697 o Specification Document(s): Section 5.1 of [[ this document ]] 1699 o Algorithm Name: "A192GCM" 1700 o Algorithm Description: AES GCM using 192 bit key 1701 o Algorithm Usage Location(s): "enc" 1702 o Implementation Requirements: Optional 1703 o Change Controller: IESG 1704 o Specification Document(s): Section 5.1 of [[ this document ]] 1706 o Algorithm Name: "A256GCM" 1707 o Algorithm Description: AES GCM using 256 bit key 1708 o Algorithm Usage Location(s): "enc" 1709 o Implementation Requirements: Recommended 1710 o Change Controller: IESG 1711 o Specification Document(s): Section 5.1 of [[ this document ]] 1713 7.2. JWE Header Parameter Names Registration 1715 This specification registers the Header Parameter names defined in 1716 Section 4.6.1, Section 4.7.1, and Section 4.8.1 in the IANA JSON Web 1717 Signature and Encryption Header Parameters registry defined in [JWS]. 1719 7.2.1. Registry Contents 1721 o Header Parameter Name: "epk" 1722 o Header Parameter Description: Ephemeral Public Key 1723 o Header Parameter Usage Location(s): JWE 1724 o Change Controller: IESG 1725 o Specification Document(s): Section 4.6.1.1 of [[ this document ]] 1727 o Header Parameter Name: "apu" 1728 o Header Parameter Description: Agreement PartyUInfo 1729 o Header Parameter Usage Location(s): JWE 1730 o Change Controller: IESG 1731 o Specification Document(s): Section 4.6.1.2 of [[ this document ]] 1733 o Header Parameter Name: "apv" 1734 o Header Parameter Description: Agreement PartyVInfo 1735 o Header Parameter Usage Location(s): JWE 1736 o Change Controller: IESG 1737 o Specification Document(s): Section 4.6.1.3 of [[ this document ]] 1739 o Header Parameter Name: "iv" 1740 o Header Parameter Description: Initialization Vector 1741 o Header Parameter Usage Location(s): JWE 1742 o Change Controller: IESG 1743 o Specification Document(s): Section 4.7.1.1 of [[ this document ]] 1745 o Header Parameter Name: "tag" 1746 o Header Parameter Description: Authentication Tag 1747 o Header Parameter Usage Location(s): JWE 1748 o Change Controller: IESG 1749 o Specification Document(s): Section 4.7.1.2 of [[ this document ]] 1751 o Header Parameter Name: "p2s" 1752 o Header Parameter Description: PBES2 salt 1753 o Header Parameter Usage Location(s): JWE 1754 o Change Controller: IESG 1755 o Specification Document(s): Section 4.8.1.1 of [[ this document ]] 1757 o Header Parameter Name: "p2c" 1758 o Header Parameter Description: PBES2 count 1759 o Header Parameter Usage Location(s): JWE 1760 o Change Controller: IESG 1761 o Specification Document(s): Section 4.8.1.2 of [[ this document ]] 1763 7.3. JSON Web Encryption Compression Algorithms Registry 1765 This specification establishes the IANA JSON Web Encryption 1766 Compression Algorithms registry for JWE "zip" member values. The 1767 registry records the compression algorithm value and a reference to 1768 the specification that defines it. 1770 7.3.1. Registration Template 1772 Compression Algorithm Value: 1773 The name requested (e.g., "example"). Because a core goal of this 1774 specification is for the resulting representations to be compact, 1775 it is RECOMMENDED that the name be short -- not to exceed 8 1776 characters without a compelling reason to do so. This name is 1777 case-sensitive. Names may not match other registered names in a 1778 case-insensitive manner unless the Designated Expert(s) state that 1779 there is a compelling reason to allow an exception in this 1780 particular case. 1782 Compression Algorithm Description: 1783 Brief description of the compression algorithm (e.g., "Example 1784 description"). 1786 Change Controller: 1787 For Standards Track RFCs, state "IESG". For others, give the name 1788 of the responsible party. Other details (e.g., postal address, 1789 email address, home page URI) may also be included. 1791 Specification Document(s): 1792 Reference to the document(s) that specify the parameter, 1793 preferably including URI(s) that can be used to retrieve copies of 1794 the document(s). An indication of the relevant sections may also 1795 be included but is not required. 1797 7.3.2. Initial Registry Contents 1799 o Compression Algorithm Value: "DEF" 1800 o Compression Algorithm Description: DEFLATE 1801 o Change Controller: IESG 1802 o Specification Document(s): JSON Web Encryption (JWE) [JWE] 1804 7.4. JSON Web Key Types Registry 1806 This specification establishes the IANA JSON Web Key Types registry 1807 for values of the JWK "kty" (key type) parameter. The registry 1808 records the "kty" value, implementation requirements, and a reference 1809 to the specification that defines it. 1811 The implementation requirements of a key type MAY be changed over 1812 time by the Designated Experts(s) as the cryptographic landscape 1813 evolves, for instance, to change the status of a key type to 1814 Deprecated, or to change the status of a key type from Optional to 1815 Recommended+ or Required. Changes of implementation requirements are 1816 only permitted on a Specification Required basis, with the new 1817 specification defining the revised implementation requirements level. 1819 7.4.1. Registration Template 1821 "kty" Parameter Value: 1822 The name requested (e.g., "example"). Because a core goal of this 1823 specification is for the resulting representations to be compact, 1824 it is RECOMMENDED that the name be short -- not to exceed 8 1825 characters without a compelling reason to do so. This name is 1826 case-sensitive. Names may not match other registered names in a 1827 case-insensitive manner unless the Designated Expert(s) state that 1828 there is a compelling reason to allow an exception in this 1829 particular case. 1831 Key Type Description: 1832 Brief description of the Key Type (e.g., "Example description"). 1834 Change Controller: 1835 For Standards Track RFCs, state "IESG". For others, give the name 1836 of the responsible party. Other details (e.g., postal address, 1837 email address, home page URI) may also be included. 1839 Implementation Requirements: 1840 The key type implementation requirements, which must be one the 1841 words Required, Recommended, Optional, or Deprecated. Optionally, 1842 the word can be followed by a "+" or "-". The use of "+" 1843 indicates that the requirement strength is likely to be increased 1844 in a future version of the specification. The use of "-" 1845 indicates that the requirement strength is likely to be decreased 1846 in a future version of the specification. 1848 Specification Document(s): 1849 Reference to the document(s) that specify the parameter, 1850 preferably including URI(s) that can be used to retrieve copies of 1851 the document(s). An indication of the relevant sections may also 1852 be included but is not required. 1854 7.4.2. Initial Registry Contents 1856 This specification registers the values defined in Section 6.1. 1858 o "kty" Parameter Value: "EC" 1859 o Key Type Description: Elliptic Curve 1860 o Implementation Requirements: Recommended+ 1861 o Change Controller: IESG 1862 o Specification Document(s): Section 6.2 of [[ this document ]] 1864 o "kty" Parameter Value: "RSA" 1865 o Key Type Description: RSA 1866 o Implementation Requirements: Required 1867 o Change Controller: IESG 1868 o Specification Document(s): Section 6.3 of [[ this document ]] 1870 o "kty" Parameter Value: "oct" 1871 o Key Type Description: Octet sequence 1872 o Implementation Requirements: Required 1873 o Change Controller: IESG 1874 o Specification Document(s): Section 6.4 of [[ this document ]] 1876 7.5. JSON Web Key Parameters Registration 1878 This specification registers the parameter names defined in Sections 1879 6.2, 6.3, and 6.4 in the IANA JSON Web Key Parameters registry 1880 defined in [JWK]. 1882 7.5.1. Registry Contents 1884 o Parameter Name: "crv" 1885 o Parameter Description: Curve 1886 o Used with "kty" Value(s): "EC" 1887 o Parameter Information Class: Public 1888 o Change Controller: IESG 1889 o Specification Document(s): Section 6.2.1.1 of [[ this document ]] 1891 o Parameter Name: "x" 1892 o Parameter Description: X Coordinate 1893 o Used with "kty" Value(s): "EC" 1894 o Parameter Information Class: Public 1895 o Change Controller: IESG 1896 o Specification Document(s): Section 6.2.1.2 of [[ this document ]] 1898 o Parameter Name: "y" 1899 o Parameter Description: Y Coordinate 1900 o Used with "kty" Value(s): "EC" 1901 o Parameter Information Class: Public 1902 o Change Controller: IESG 1903 o Specification Document(s): Section 6.2.1.3 of [[ this document ]] 1905 o Parameter Name: "d" 1906 o Parameter Description: ECC Private Key 1907 o Used with "kty" Value(s): "EC" 1908 o Parameter Information Class: Private 1909 o Change Controller: IESG 1910 o Specification Document(s): Section 6.2.2.1 of [[ this document ]] 1912 o Parameter Name: "n" 1913 o Parameter Description: Modulus 1914 o Used with "kty" Value(s): "RSA" 1915 o Parameter Information Class: Public 1916 o Change Controller: IESG 1917 o Specification Document(s): Section 6.3.1.1 of [[ this document ]] 1919 o Parameter Name: "e" 1920 o Parameter Description: Exponent 1921 o Used with "kty" Value(s): "RSA" 1922 o Parameter Information Class: Public 1923 o Change Controller: IESG 1924 o Specification Document(s): Section 6.3.1.2 of [[ this document ]] 1926 o Parameter Name: "d" 1927 o Parameter Description: Private Exponent 1928 o Used with "kty" Value(s): "RSA" 1929 o Parameter Information Class: Private 1930 o Change Controller: IESG 1931 o Specification Document(s): Section 6.3.2.1 of [[ this document ]] 1933 o Parameter Name: "p" 1934 o Parameter Description: First Prime Factor 1935 o Used with "kty" Value(s): "RSA" 1936 o Parameter Information Class: Private 1937 o Change Controller: IESG 1938 o Specification Document(s): Section 6.3.2.2 of [[ this document ]] 1940 o Parameter Name: "q" 1941 o Parameter Description: Second Prime Factor 1942 o Used with "kty" Value(s): "RSA" 1943 o Parameter Information Class: Private 1944 o Change Controller: IESG 1945 o Specification Document(s): Section 6.3.2.3 of [[ this document ]] 1947 o Parameter Name: "dp" 1948 o Parameter Description: First Factor CRT Exponent 1949 o Used with "kty" Value(s): "RSA" 1950 o Parameter Information Class: Private 1951 o Change Controller: IESG 1952 o Specification Document(s): Section 6.3.2.4 of [[ this document ]] 1953 o Parameter Name: "dq" 1954 o Parameter Description: Second Factor CRT Exponent 1955 o Used with "kty" Value(s): "RSA" 1956 o Parameter Information Class: Private 1957 o Change Controller: IESG 1958 o Specification Document(s): Section 6.3.2.5 of [[ this document ]] 1960 o Parameter Name: "qi" 1961 o Parameter Description: First CRT Coefficient 1962 o Used with "kty" Value(s): "RSA" 1963 o Parameter Information Class: Private 1964 o Change Controller: IESG 1965 o Specification Document(s): Section 6.3.2.6 of [[ this document ]] 1967 o Parameter Name: "oth" 1968 o Parameter Description: Other Primes Info 1969 o Used with "kty" Value(s): "RSA" 1970 o Parameter Information Class: Private 1971 o Change Controller: IESG 1972 o Specification Document(s): Section 6.3.2.7 of [[ this document ]] 1974 o Parameter Name: "k" 1975 o Parameter Description: Key Value 1976 o Used with "kty" Value(s): "oct" 1977 o Parameter Information Class: Private 1978 o Change Controller: IESG 1979 o Specification Document(s): Section 6.4.1 of [[ this document ]] 1981 7.6. JSON Web Key Elliptic Curve Registry 1983 This specification establishes the IANA JSON Web Key Elliptic Curve 1984 registry for JWK "crv" member values. The registry records the curve 1985 name, implementation requirements, and a reference to the 1986 specification that defines it. This specification registers the 1987 parameter names defined in Section 6.2.1.1. 1989 The implementation requirements of a curve MAY be changed over time 1990 by the Designated Experts(s) as the cryptographic landscape evolves, 1991 for instance, to change the status of a curve to Deprecated, or to 1992 change the status of a curve from Optional to Recommended+ or 1993 Required. Changes of implementation requirements are only permitted 1994 on a Specification Required basis, with the new specification 1995 defining the revised implementation requirements level. 1997 7.6.1. Registration Template 1998 Curve Name: 1999 The name requested (e.g., "example"). Because a core goal of this 2000 specification is for the resulting representations to be compact, 2001 it is RECOMMENDED that the name be short -- not to exceed 8 2002 characters without a compelling reason to do so. This name is 2003 case-sensitive. Names may not match other registered names in a 2004 case-insensitive manner unless the Designated Expert(s) state that 2005 there is a compelling reason to allow an exception in this 2006 particular case. 2008 Curve Description: 2009 Brief description of the curve (e.g., "Example description"). 2011 Implementation Requirements: 2012 The curve implementation requirements, which must be one the words 2013 Required, Recommended, Optional, or Deprecated. Optionally, the 2014 word can be followed by a "+" or "-". The use of "+" indicates 2015 that the requirement strength is likely to be increased in a 2016 future version of the specification. The use of "-" indicates 2017 that the requirement strength is likely to be decreased in a 2018 future version of the specification. 2020 Change Controller: 2021 For Standards Track RFCs, state "IESG". For others, give the name 2022 of the responsible party. Other details (e.g., postal address, 2023 email address, home page URI) may also be included. 2025 Specification Document(s): 2026 Reference to the document(s) that specify the parameter, 2027 preferably including URI(s) that can be used to retrieve copies of 2028 the document(s). An indication of the relevant sections may also 2029 be included but is not required. 2031 7.6.2. Initial Registry Contents 2033 o Curve Name: "P-256" 2034 o Curve Description: P-256 curve 2035 o Implementation Requirements: Recommended+ 2036 o Change Controller: IESG 2037 o Specification Document(s): Section 6.2.1.1 of [[ this document ]] 2039 o Curve Name: "P-384" 2040 o Curve Description: P-384 curve 2041 o Implementation Requirements: Optional 2042 o Change Controller: IESG 2043 o Specification Document(s): Section 6.2.1.1 of [[ this document ]] 2044 o Curve Name: "P-521" 2045 o Curve Description: P-521 curve 2046 o Implementation Requirements: Optional 2047 o Change Controller: IESG 2048 o Specification Document(s): Section 6.2.1.1 of [[ this document ]] 2050 8. Security Considerations 2052 All of the security issues faced by any cryptographic application 2053 must be faced by a JWS/JWE/JWK agent. Among these issues are 2054 protecting the user's private and symmetric keys, preventing various 2055 attacks, and helping the user avoid mistakes such as inadvertently 2056 encrypting a message for the wrong recipient. The entire list of 2057 security considerations is beyond the scope of this document, but 2058 some significant considerations are listed here. 2060 The security considerations in [AES], [DSS], [JWE], [JWK], [JWS], 2061 [NIST.800-38A], [NIST.800-38D], [NIST.800-56A], [RFC2104], [RFC3394], 2062 [RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this 2063 specification. 2065 Algorithms of matching strengths should be used together whenever 2066 possible. For instance, when AES Key Wrap is used with a given key 2067 size, using the same key size is recommended when AES GCM is also 2068 used. 2070 8.1. Algorithms and Key Sizes will be Deprecated 2072 Eventually the algorithms and/or key sizes currently described in 2073 this specification will no longer be considered sufficiently secure 2074 and will be deprecated. Therefore, implementers and deployments must 2075 be prepared for this eventuality. 2077 8.2. Key Lifetimes 2079 Many algorithms have associated security considerations related to 2080 key lifetimes and/or the number of times that a key may be used. 2081 Those security considerations continue to apply when using those 2082 algorithms with JOSE data structures. 2084 8.3. RSAES-PKCS1-v1_5 Security Considerations 2086 While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not 2087 to adopt RSASSA-PKCS-v1_5 for new applications and instead requests 2088 that people transition to RSASSA-PSS, this specification does include 2089 RSASSA-PKCS-v1_5, for interoperability reasons, because it commonly 2090 implemented. 2092 Keys used with RSAES-PKCS1-v1_5 must follow the constraints in 2093 Section 7.2 of RFC 3447 [RFC3447]. In particular, keys with a low 2094 public key exponent value must not be used. 2096 8.4. AES GCM Security Considerations 2098 Keys used with AES GCM must follow the constraints in Section 8.3 of 2099 [NIST.800-38D], which states: "The total number of invocations of the 2100 authenticated encryption function shall not exceed 2^32, including 2101 all IV lengths and all instances of the authenticated encryption 2102 function with the given key". In accordance with this rule, AES GCM 2103 MUST NOT be used with the same key value more than 2^32 times. 2105 An Initialization Vector value MUST never be used multiple times with 2106 the same AES GCM key. One way to prevent this is to store a counter 2107 with the key and increment it with every use. The counter can also 2108 be used to prevent exceeding the 2^32 limit above. 2110 This security consideration does not apply to the composite AES-CBC 2111 HMAC SHA-2 or AES Key Wrap algorithms. 2113 8.5. Plaintext JWS Security Considerations 2115 Plaintext JWSs (JWSs that use the "alg" value "none") provide no 2116 integrity protection. Thus, they must only be used in contexts where 2117 the payload is secured by means other than a digital signature or MAC 2118 value, or need not be secured. 2120 Implementations that support plaintext JWS objects MUST NOT accept 2121 such objects as valid unless the application specifies that it is 2122 acceptable for a specific object to not be integrity-protected. 2123 Implementations MUST NOT accept plaintext JWS objects by default. 2124 For example, the "verify" method of a hypothetical JWS software 2125 library might have a Boolean "acceptUnsigned" parameter that 2126 indicates "none" is an acceptable "alg" value. As another example, 2127 the "verify" method might take a list of algorithms that are 2128 acceptable to the application as a parameter and would reject 2129 plaintext JWS values if "none" is not in that list. 2131 In order to mitigate downgrade attacks, applications MUST NOT signal 2132 acceptance of plaintext JWS objects at a global level, and SHOULD 2133 signal acceptance on a per-object basis. For example, suppose an 2134 application accepts JWS objects over two channels, (1) HTTP and (2) 2135 HTTPS with client authentication. It requires a JWS signature on 2136 objects received over HTTP, but accepts plaintext JWS objects over 2137 HTTPS. If the application were to globally indicate that "none" is 2138 acceptable, then an attacker could provide it with an unsigned object 2139 over HTTP and still have that object successfully validate. Instead, 2140 the application needs to indicate acceptance of "none" for each 2141 object received over HTTPS (e.g., by setting "acceptUnsigned" to 2142 "true" for the first hypothetical JWS software library above), but 2143 not for each object received over HTTP. 2145 8.6. Differences between Digital Signatures and MACs 2147 While in many cases, MACs and digital signatures can be used for 2148 integrity checking, there are some significant differences between 2149 the security properties that each of them provides. These need to be 2150 taken into consideration when designing protocols and selecting the 2151 algorithms to be used in protocols. 2153 Both signatures and MACs provide for integrity checking -- verifying 2154 that the message has not been modified since the integrity value was 2155 computed. However, MACs provide for origination identification only 2156 under specific circumstances. It can normally be assumed that a 2157 private key used for a signature is only in the hands of a single 2158 entity (although perhaps a distributed entity, in the case of 2159 replicated servers), however a MAC key needs to be in the hands of 2160 all the entities that use it for integrity computation and checking. 2161 This means that origination can only be determined if a MAC key is 2162 known only to two entities and the receiver knows that it did not 2163 create the message. MAC validation cannot be used to prove 2164 origination to a third party. 2166 8.7. Denial of Service Attacks 2168 Receiving agents that validate signatures and sending agents that 2169 encrypt messages need to be cautious of cryptographic processing 2170 usage when validating signatures and encrypting messages using keys 2171 larger than those mandated in this specification. An attacker could 2172 send certificates with keys that would result in excessive 2173 cryptographic processing, for example, keys larger than those 2174 mandated in this specification, which could swamp the processing 2175 element. Agents that use such keys without first validating the 2176 certificate to a trust anchor are advised to have some sort of 2177 cryptographic resource management system to prevent such attacks. 2179 8.8. Reusing Key Material when Encrypting Keys 2181 It is NOT RECOMMENDED to reuse the same key material (Key Encryption 2182 Key, Content Encryption Key, Initialization Vector, etc.) to encrypt 2183 multiple JWK or JWK Set objects, or to encrypt the same JWK or JWK 2184 Set object multiple times. One suggestion for preventing re-use is 2185 to always generate a new set key material for each encryption 2186 operation, based on the considerations noted in this document as well 2187 as from [RFC4086]. 2189 8.9. Password Considerations 2191 Passwords are vulnerable to a number of attacks. To help mitigate 2192 some of these limitations, this document applies principles from 2193 [RFC2898] to derive cryptographic keys from user-supplied passwords. 2195 However, the strength of the password still has a significant impact. 2196 A high-entropy password has greater resistance to dictionary attacks. 2197 [NIST-800-63-1] contains guidelines for estimating password entropy, 2198 which can help applications and users generate stronger passwords. 2200 An ideal password is one that is as large as (or larger than) the 2201 derived key length. However, passwords larger than a certain 2202 algorithm-specific size are first hashed, which reduces an attacker's 2203 effective search space to the length of the hash algorithm. It is 2204 RECOMMENDED that a password used for "PBES2-HS256+A128KW" be no 2205 shorter than 16 octets and no longer than 128 octets and a password 2206 used for "PBES2-HS512+A256KW" be no shorter than 32 octets and no 2207 longer than 128 octets long. 2209 Still, care needs to be taken in where and how password-based 2210 encryption is used. These algorithms can still be susceptible to 2211 dictionary-based attacks if the iteration count is too small; this is 2212 of particular concern if these algorithms are used to protect data 2213 that an attacker can have indefinite number of attempts to circumvent 2214 the protection, such as protected data stored on a file system. 2216 9. Internationalization Considerations 2218 Passwords obtained from users are likely to require preparation and 2219 normalization to account for differences of octet sequences generated 2220 by different input devices, locales, etc. It is RECOMMENDED that 2221 applications to perform the steps outlined in 2222 [I-D.melnikov-precis-saslprepbis] to prepare a password supplied 2223 directly by a user before performing key derivation and encryption. 2225 10. References 2227 10.1. Normative References 2229 [AES] National Institute of Standards and Technology (NIST), 2230 "Advanced Encryption Standard (AES)", FIPS PUB 197, 2231 November 2001. 2233 [DSS] National Institute of Standards and Technology, "Digital 2234 Signature Standard (DSS)", FIPS PUB 186-4, July 2013. 2236 [I-D.melnikov-precis-saslprepbis] 2237 Saint-Andre, P. and A. Melnikov, "Preparation and 2238 Comparison of Internationalized Strings Representing 2239 Simple User Names and Passwords", 2240 draft-melnikov-precis-saslprepbis-04 (work in progress), 2241 September 2012. 2243 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 2244 Encryption (JWE)", draft-ietf-jose-json-web-encryption 2245 (work in progress), November 2013. 2247 [JWK] Jones, M., "JSON Web Key (JWK)", 2248 draft-ietf-jose-json-web-key (work in progress), 2249 November 2013. 2251 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2252 Signature (JWS)", draft-ietf-jose-json-web-signature (work 2253 in progress), November 2013. 2255 [NIST.800-38A] 2256 National Institute of Standards and Technology (NIST), 2257 "Recommendation for Block Cipher Modes of Operation", 2258 NIST PUB 800-38A, December 2001. 2260 [NIST.800-38D] 2261 National Institute of Standards and Technology (NIST), 2262 "Recommendation for Block Cipher Modes of Operation: 2263 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 2264 December 2001. 2266 [NIST.800-56A] 2267 National Institute of Standards and Technology (NIST), 2268 "Recommendation for Pair-Wise Key Establishment Schemes 2269 Using Discrete Logarithm Cryptography", NIST Special 2270 Publication 800-56A, Revision 2, May 2013. 2272 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 2273 Hashing for Message Authentication", RFC 2104, 2274 February 1997. 2276 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2277 Requirement Levels", BCP 14, RFC 2119, March 1997. 2279 [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography 2280 Specification Version 2.0", RFC 2898, September 2000. 2282 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 2283 (AES) Key Wrap Algorithm", RFC 3394, September 2002. 2285 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2286 10646", STD 63, RFC 3629, November 2003. 2288 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 2289 Requirements for Security", BCP 106, RFC 4086, June 2005. 2291 [RFC4627] Crockford, D., "The application/json Media Type for 2292 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2294 [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA- 2295 384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007. 2297 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 2298 Encryption", RFC 5116, January 2008. 2300 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2301 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2302 May 2008. 2304 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 2305 Curve Cryptography Algorithms", RFC 6090, February 2011. 2307 [SEC1] Standards for Efficient Cryptography Group, "SEC 1: 2308 Elliptic Curve Cryptography", May 2009. 2310 [SHS] National Institute of Standards and Technology, "Secure 2311 Hash Standard (SHS)", FIPS PUB 180-3, October 2008. 2313 [USASCII] American National Standards Institute, "Coded Character 2314 Set -- 7-bit American Standard Code for Information 2315 Interchange", ANSI X3.4, 1986. 2317 10.2. Informative References 2319 [CanvasApp] 2320 Facebook, "Canvas Applications", 2010. 2322 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 2323 McGrew, D., Foley, J., and K. Paterson, "Authenticated 2324 Encryption with AES-CBC and HMAC-SHA", 2325 draft-mcgrew-aead-aes-cbc-hmac-sha2-02 (work in progress), 2326 July 2013. 2328 [I-D.miller-jose-jwe-protected-jwk] 2329 Miller, M., "Using JavaScript Object Notation (JSON) Web 2330 Encryption (JWE) for Protecting JSON Web Key (JWK) 2331 Objects", draft-miller-jose-jwe-protected-jwk-02 (work in 2332 progress), June 2013. 2334 [I-D.rescorla-jsms] 2335 Rescorla, E. and J. Hildebrand, "JavaScript Message 2336 Security Format", draft-rescorla-jsms-00 (work in 2337 progress), March 2011. 2339 [JCA] Oracle, "Java Cryptography Architecture", 2013. 2341 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 2342 Encryption", September 2010. 2344 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 2345 September 2010. 2347 [MagicSignatures] 2348 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 2349 Signatures", January 2011. 2351 [NIST-800-63-1] 2352 National Institute of Standards and Technology (NIST), 2353 "Electronic Authentication Guideline", NIST 800-63-1, 2354 December 2011. 2356 [RFC2631] Rescorla, E., "Diffie-Hellman Key Agreement Method", 2357 RFC 2631, June 1999. 2359 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 2360 Language) XML-Signature Syntax and Processing", RFC 3275, 2361 March 2002. 2363 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 2364 Standards (PKCS) #1: RSA Cryptography Specifications 2365 Version 2.1", RFC 3447, February 2003. 2367 [W3C.CR-xmldsig-core2-20120124] 2368 Eastlake, D., Reagle, J., Yiu, K., Solo, D., Datta, P., 2369 Hirsch, F., Cantor, S., and T. Roessler, "XML Signature 2370 Syntax and Processing Version 2.0", World Wide Web 2371 Consortium CR CR-xmldsig-core2-20120124, January 2012, 2372 . 2374 [W3C.CR-xmlenc-core1-20120313] 2375 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 2376 "XML Encryption Syntax and Processing Version 1.1", World 2377 Wide Web Consortium CR CR-xmlenc-core1-20120313, 2378 March 2012, 2379 . 2381 [W3C.REC-xmlenc-core-20021210] 2382 Eastlake, D. and J. Reagle, "XML Encryption Syntax and 2383 Processing", World Wide Web Consortium Recommendation REC- 2384 xmlenc-core-20021210, December 2002, 2385 . 2387 Appendix A. Algorithm Identifier Cross-Reference 2389 This appendix contains tables cross-referencing the cryptographic 2390 algorithm identifier values defined in this specification with the 2391 equivalent identifiers used by other standards and software packages. 2392 See XML DSIG [RFC3275], XML DSIG 2.0 [W3C.CR-xmldsig-core2-20120124], 2393 XML Encryption [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 2394 [W3C.CR-xmlenc-core1-20120313], and Java Cryptography Architecture 2395 [JCA] for more information about the names defined by those 2396 documents. 2398 A.1. Digital Signature/MAC Algorithm Identifier Cross-Reference 2400 This section contains a table cross-referencing the JWS digital 2401 signature and MAC "alg" (algorithm) values defined in this 2402 specification with the equivalent identifiers used by other standards 2403 and software packages. 2405 +-----+-------------------------------+--------------+--------------+ 2406 | JWS | XML DSIG | JCA | OID | 2407 +-----+-------------------------------+--------------+--------------+ 2408 | HS2 | http://www.w3.org/2001/04/xml | HmacSHA256 | 1.2.840.1135 | 2409 | 56 | dsig-more#hmac-sha256 | | 49.2.9 | 2410 | HS3 | http://www.w3.org/2001/04/xml | HmacSHA384 | 1.2.840.1135 | 2411 | 84 | dsig-more#hmac-sha384 | | 49.2.10 | 2412 | HS5 | http://www.w3.org/2001/04/xml | HmacSHA512 | 1.2.840.1135 | 2413 | 12 | dsig-more#hmac-sha512 | | 49.2.11 | 2414 | RS2 | http://www.w3.org/2001/04/xml | SHA256withRS | 1.2.840.1135 | 2415 | 56 | dsig-more#rsa-sha256 | A | 49.1.1.11 | 2416 | RS3 | http://www.w3.org/2001/04/xml | SHA384withRS | 1.2.840.1135 | 2417 | 84 | dsig-more#rsa-sha384 | A | 49.1.1.12 | 2418 | RS5 | http://www.w3.org/2001/04/xml | SHA512withRS | 1.2.840.1135 | 2419 | 12 | dsig-more#rsa-sha512 | A | 49.1.1.13 | 2420 | ES2 | http://www.w3.org/2001/04/xml | SHA256withEC | 1.2.840.1004 | 2421 | 56 | dsig-more#ecdsa-sha256 | DSA | 5.4.3.2 | 2422 | ES3 | http://www.w3.org/2001/04/xml | SHA384withEC | 1.2.840.1004 | 2423 | 84 | dsig-more#ecdsa-sha384 | DSA | 5.4.3.3 | 2424 | ES5 | http://www.w3.org/2001/04/xml | SHA512withEC | 1.2.840.1004 | 2425 | 12 | dsig-more#ecdsa-sha512 | DSA | 5.4.3.4 | 2426 | PS2 | http://www.w3.org/2007/05/xml | SHA256withRS | 1.2.840.1135 | 2427 | 56 | dsig-more#sha256-rsa-MGF1 | AandMGF1 | 49.1.1.10 | 2428 | PS3 | http://www.w3.org/2007/05/xml | SHA384withRS | 1.2.840.1135 | 2429 | 84 | dsig-more#sha384-rsa-MGF1 | AandMGF1 | 49.1.1.10 | 2430 | PS5 | http://www.w3.org/2007/05/xml | SHA512withRS | 1.2.840.1135 | 2431 | 12 | dsig-more#sha512-rsa-MGF1 | AandMGF1 | 49.1.1.10 | 2432 +-----+-------------------------------+--------------+--------------+ 2434 A.2. Key Management Algorithm Identifier Cross-Reference 2436 This section contains a table cross-referencing the JWE "alg" 2437 (algorithm) values defined in this specification with the equivalent 2438 identifiers used by other standards and software packages. 2440 +------+------------------------+--------------------+--------------+ 2441 | JWE | XML ENC | JCA | OID | 2442 +------+------------------------+--------------------+--------------+ 2443 | RSA1 | http://www.w3.org/2001 | RSA/ECB/PKCS1Paddi | 1.2.840.1135 | 2444 | _5 | /04/xmlenc#rsa-1_5 | ng | 49.1.1.1 | 2445 | RSA- | http://www.w3.org/2001 | RSA/ECB/OAEPWithSH | 1.2.840.1135 | 2446 | OAEP | /04/xmlenc#rsa-oaep-mg | A-1AndMGF1Padding | 49.1.1.7 | 2447 | | f1p | | | 2448 | ECDH | http://www.w3.org/2009 | | 1.3.132.1.12 | 2449 | -ES | /xmlenc11#ECDH-ES | | | 2450 | A128 | http://www.w3.org/2001 | | 2.16.840.1.1 | 2451 | KW | /04/xmlenc#kw-aes128 | | 01.3.4.1.5 | 2452 | A192 | http://www.w3.org/2001 | | 2.16.840.1.1 | 2453 | KW | /04/xmlenc#kw-aes192 | | 01.3.4.1.25 | 2454 | A256 | http://www.w3.org/2001 | | 2.16.840.1.1 | 2455 | KW | /04/xmlenc#kw-aes256 | | 01.3.4.1.45 | 2456 +------+------------------------+--------------------+--------------+ 2458 A.3. Content Encryption Algorithm Identifier Cross-Reference 2460 This section contains a table cross-referencing the JWE "enc" 2461 (encryption method) values defined in this specification with the 2462 equivalent identifiers used by other standards and software packages. 2464 For the composite algorithms "A128CBC-HS256", "A192CBC-HS384", and 2465 "A256CBC-HS512", the corresponding AES CBC algorithm identifiers are 2466 listed. 2468 +---------+-------------------------+--------------+----------------+ 2469 | JWE | XML ENC | JCA | OID | 2470 +---------+-------------------------+--------------+----------------+ 2471 | A128CBC | http://www.w3.org/2001/ | AES/CBC/PKCS | 2.16.840.1.101 | 2472 | -HS256 | 04/xmlenc#aes128-cbc | 5Padding | .3.4.1.2 | 2473 | A192CBC | http://www.w3.org/2001/ | AES/CBC/PKCS | 2.16.840.1.101 | 2474 | -HS384 | 04/xmlenc#aes192-cbc | 5Padding | .3.4.1.22 | 2475 | A256CBC | http://www.w3.org/2001/ | AES/CBC/PKCS | 2.16.840.1.101 | 2476 | -HS512 | 04/xmlenc#aes256-cbc | 5Padding | .3.4.1.42 | 2477 | A128GCM | http://www.w3.org/2009/ | AES/GCM/NoPa | 2.16.840.1.101 | 2478 | | xmlenc11#aes128-gcm | dding | .3.4.1.6 | 2479 | A192GCM | http://www.w3.org/2009/ | AES/GCM/NoPa | 2.16.840.1.101 | 2480 | | xmlenc11#aes192-gcm | dding | .3.4.1.26 | 2481 | A256GCM | http://www.w3.org/2009/ | AES/GCM/NoPa | 2.16.840.1.101 | 2482 | | xmlenc11#aes256-gcm | dding | .3.4.1.46 | 2483 +---------+-------------------------+--------------+----------------+ 2485 Appendix B. Test Cases for AES_CBC_HMAC_SHA2 Algorithms 2487 The following test cases can be used to validate implementations of 2488 the AES_CBC_HMAC_SHA2 algorithms defined in Section 5.2. They are 2489 also intended to correspond to test cases that may appear in a future 2490 version of [I-D.mcgrew-aead-aes-cbc-hmac-sha2], demonstrating that 2491 the cryptographic computations performed are the same. 2493 The variable names are those defined in Section 5.2. All values are 2494 hexadecimal. 2496 B.1. Test Cases for AES_128_CBC_HMAC_SHA_256 2498 AES_128_CBC_HMAC_SHA_256 2500 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2501 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2503 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2505 ENC_KEY = 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2507 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2508 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2509 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2510 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2511 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2512 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2513 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2514 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2516 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2518 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2519 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2520 4b 65 72 63 6b 68 6f 66 66 73 2522 AL = 00 00 00 00 00 00 01 50 2524 E = c8 0e df a3 2d df 39 d5 ef 00 c0 b4 68 83 42 79 2525 a2 e4 6a 1b 80 49 f7 92 f7 6b fe 54 b9 03 a9 c9 2526 a9 4a c9 b4 7a d2 65 5c 5f 10 f9 ae f7 14 27 e2 2527 fc 6f 9b 3f 39 9a 22 14 89 f1 63 62 c7 03 23 36 2528 09 d4 5a c6 98 64 e3 32 1c f8 29 35 ac 40 96 c8 2529 6e 13 33 14 c5 40 19 e8 ca 79 80 df a4 b9 cf 1b 2530 38 4c 48 6f 3a 54 c5 10 78 15 8e e5 d7 9d e5 9f 2531 bd 34 d8 48 b3 d6 95 50 a6 76 46 34 44 27 ad e5 2532 4b 88 51 ff b5 98 f7 f8 00 74 b9 47 3c 82 e2 db 2534 M = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2535 e6 e5 45 82 47 65 15 f0 ad 9f 75 a2 b7 1c 73 ef 2537 T = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2539 B.2. Test Cases for AES_192_CBC_HMAC_SHA_384 2541 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2542 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2543 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2545 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2546 10 11 12 13 14 15 16 17 2548 ENC_KEY = 18 19 1a 1b 1c 1d 1e 1f 20 21 22 23 24 25 26 27 2549 28 29 2a 2b 2c 2d 2e 2f 2551 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2552 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2553 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2554 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2555 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2556 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2557 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2558 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2560 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2562 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2563 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2564 4b 65 72 63 6b 68 6f 66 66 73 2566 AL = 00 00 00 00 00 00 01 50 2568 E = ea 65 da 6b 59 e6 1e db 41 9b e6 2d 19 71 2a e5 2569 d3 03 ee b5 00 52 d0 df d6 69 7f 77 22 4c 8e db 2570 00 0d 27 9b dc 14 c1 07 26 54 bd 30 94 42 30 c6 2571 57 be d4 ca 0c 9f 4a 84 66 f2 2b 22 6d 17 46 21 2572 4b f8 cf c2 40 0a dd 9f 51 26 e4 79 66 3f c9 0b 2573 3b ed 78 7a 2f 0f fc bf 39 04 be 2a 64 1d 5c 21 2574 05 bf e5 91 ba e2 3b 1d 74 49 e5 32 ee f6 0a 9a 2575 c8 bb 6c 6b 01 d3 5d 49 78 7b cd 57 ef 48 49 27 2576 f2 80 ad c9 1a c0 c4 e7 9c 7b 11 ef c6 00 54 e3 2578 M = 84 90 ac 0e 58 94 9b fe 51 87 5d 73 3f 93 ac 20 2579 75 16 80 39 cc c7 33 d7 45 94 f8 86 b3 fa af d4 2580 86 f2 5c 71 31 e3 28 1e 36 c7 a2 d1 30 af de 57 2582 T = 84 90 ac 0e 58 94 9b fe 51 87 5d 73 3f 93 ac 20 2583 75 16 80 39 cc c7 33 d7 2585 B.3. Test Cases for AES_256_CBC_HMAC_SHA_512 2587 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2588 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2589 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2590 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2592 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2593 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2595 ENC_KEY = 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2596 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2598 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2599 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2600 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2601 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2602 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2603 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2604 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2605 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2607 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2609 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2610 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2611 4b 65 72 63 6b 68 6f 66 66 73 2613 AL = 00 00 00 00 00 00 01 50 2615 E = 4a ff aa ad b7 8c 31 c5 da 4b 1b 59 0d 10 ff bd 2616 3d d8 d5 d3 02 42 35 26 91 2d a0 37 ec bc c7 bd 2617 82 2c 30 1d d6 7c 37 3b cc b5 84 ad 3e 92 79 c2 2618 e6 d1 2a 13 74 b7 7f 07 75 53 df 82 94 10 44 6b 2619 36 eb d9 70 66 29 6a e6 42 7e a7 5c 2e 08 46 a1 2620 1a 09 cc f5 37 0d c8 0b fe cb ad 28 c7 3f 09 b3 2621 a3 b7 5e 66 2a 25 94 41 0a e4 96 b2 e2 e6 60 9e 2622 31 e6 e0 2c c8 37 f0 53 d2 1f 37 ff 4f 51 95 0b 2623 be 26 38 d0 9d d7 a4 93 09 30 80 6d 07 03 b1 f6 2625 M = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2626 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2627 fd 30 a5 65 c6 16 ff b2 f3 64 ba ec e6 8f c4 07 2628 53 bc fc 02 5d de 36 93 75 4a a1 f5 c3 37 3b 9c 2630 T = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2631 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2633 Appendix C. Example ECDH-ES Key Agreement Computation 2635 This example uses ECDH-ES Key Agreement and the Concat KDF to derive 2636 the Content Encryption Key (CEK) in the manner described in 2637 Section 4.6. In this example, the ECDH-ES Direct Key Agreement mode 2638 ("alg" value "ECDH-ES") is used to produce an agreed upon key for AES 2639 GCM with a 128 bit key ("enc" value "A128GCM"). 2641 In this example, a sender Alice is encrypting content to a recipient 2642 Bob. The sender (Alice) generates an ephemeral key for the key 2643 agreement computation. Alice's ephemeral key (in JWK format) used 2644 for the key agreement computation in this example (including the 2645 private part) is: 2647 {"kty":"EC", 2648 "crv":"P-256", 2649 "x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0", 2650 "y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps", 2651 "d":"0_NxaRPUMQoAJt50Gz8YiTr8gRTwyEaCumd-MToTmIo" 2652 } 2654 The recipient's (Bob's) key (in JWK format) used for the key 2655 agreement computation in this example (including the private part) 2656 is: 2658 {"kty":"EC", 2659 "crv":"P-256", 2660 "x":"weNJy2HscCSM6AEDTDg04biOvhFhyyWvOHQfeF_PxMQ", 2661 "y":"e8lnCO-AlStT-NJVX-crhB7QRYhiix03illJOVAOyck", 2662 "d":"VEmDZpDXXK8p8N0Cndsxs924q6nS1RXFASRl6BfUqdw" 2663 } 2665 Header Parameter values used in this example are as follows. In this 2666 example, the "apu" (agreement PartyUInfo) parameter value is the 2667 base64url encoding of the UTF-8 string "Alice" and the "apv" 2668 (agreement PartyVInfo) parameter value is the base64url encoding of 2669 the UTF-8 string "Bob". The "epk" parameter is used to communicate 2670 the sender's (Alice's) ephemeral public key value to the recipient 2671 (Bob). 2673 {"alg":"ECDH-ES", 2674 "enc":"A128GCM", 2675 "apu":"QWxpY2U", 2676 "apv":"Qm9i", 2677 "epk": 2678 {"kty":"EC", 2679 "crv":"P-256", 2680 "x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0", 2681 "y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps" 2682 } 2683 } 2685 The resulting Concat KDF [NIST.800-56A] parameter values are: 2687 Z This is set to the ECDH-ES key agreement output. (This value is 2688 often not directly exposed by libraries, due to NIST security 2689 requirements, and only serves as an input to a KDF.) In this 2690 example, Z is the octet sequence: 2691 [158, 86, 217, 29, 129, 113, 53, 211, 114, 131, 66, 131, 191, 132, 2692 38, 156, 251, 49, 110, 163, 218, 128, 106, 72, 246, 218, 167, 121, 2693 140, 254, 144, 196]. 2695 keydatalen This value is 128 - the number of bits in the desired 2696 output key (because "A128GCM" uses a 128 bit key). 2698 AlgorithmID This is set to the octets representing the 32 bit big 2699 endian value 7 - [0, 0, 0, 7] - the number of octets in the 2700 AlgorithmID content "A128GCM", followed, by the octets 2701 representing the UTF-8 string "A128GCM" - [65, 49, 50, 56, 71, 67, 2702 77]. 2704 PartyUInfo This is set to the octets representing the 32 bit big 2705 endian value 5 - [0, 0, 0, 5] - the number of octets in the 2706 PartyUInfo content "Alice", followed, by the octets representing 2707 the UTF-8 string "Alice" - [65, 108, 105, 99, 101]. 2709 PartyVInfo This is set to the octets representing the 32 bit big 2710 endian value 3 - [0, 0, 0, 3] - the number of octets in the 2711 PartyUInfo content "Bob", followed, by the octets representing the 2712 UTF-8 string "Bob" - [66, 111, 98]. 2714 SuppPubInfo This is set to the octets representing the 32 bit big 2715 endian value 128 - [0, 0, 0, 128] - the keydatalen value. 2717 SuppPrivInfo This is set to the empty octet sequence. 2719 Concatenating the parameters AlgorithmID through SuppPubInfo results 2720 in an OtherInfo value of: 2722 [0, 0, 0, 7, 65, 49, 50, 56, 71, 67, 77, 0, 0, 0, 5, 65, 108, 105, 2723 99, 101, 0, 0, 0, 3, 66, 111, 98, 0, 0, 0, 128] 2725 Concatenating the round number 1 ([0, 0, 0, 1]), Z, and the OtherInfo 2726 value results in the Concat KDF round 1 hash input of: 2727 [0, 0, 0, 1, 2728 158, 86, 217, 29, 129, 113, 53, 211, 114, 131, 66, 131, 191, 132, 38, 2729 156, 251, 49, 110, 163, 218, 128, 106, 72, 246, 218, 167, 121, 140, 2730 254, 144, 196, 2731 0, 0, 0, 7, 65, 49, 50, 56, 71, 67, 77, 0, 0, 0, 5, 65, 108, 105, 99, 2732 101, 0, 0, 0, 3, 66, 111, 98, 0, 0, 0, 128] 2734 The resulting derived key, which is the first 128 bits of the round 1 2735 hash output is: 2736 [86, 170, 141, 234, 248, 35, 109, 32, 92, 34, 40, 205, 113, 167, 16, 2737 26] 2739 The base64url encoded representation of this derived key is: 2741 VqqN6vgjbSBcIijNcacQGg 2743 Appendix D. Acknowledgements 2745 Solutions for signing and encrypting JSON content were previously 2746 explored by Magic Signatures [MagicSignatures], JSON Simple Sign 2747 [JSS], Canvas Applications [CanvasApp], JSON Simple Encryption [JSE], 2748 and JavaScript Message Security Format [I-D.rescorla-jsms], all of 2749 which influenced this draft. 2751 The Authenticated Encryption with AES-CBC and HMAC-SHA 2752 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] specification, upon which the 2753 AES_CBC_HMAC_SHA2 algorithms are based, was written by David A. 2754 McGrew and Kenny Paterson. The test cases for AES_CBC_HMAC_SHA2 are 2755 based upon those for [I-D.mcgrew-aead-aes-cbc-hmac-sha2] by John 2756 Foley. 2758 Matt Miller wrote Using JavaScript Object Notation (JSON) Web 2759 Encryption (JWE) for Protecting JSON Web Key (JWK) Objects 2760 [I-D.miller-jose-jwe-protected-jwk], which the password-based 2761 encryption content of this draft is based upon. 2763 This specification is the work of the JOSE Working Group, which 2764 includes dozens of active and dedicated participants. In particular, 2765 the following individuals contributed ideas, feedback, and wording 2766 that influenced this specification: 2768 Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de 2769 Medeiros, Vladimir Dzhuvinov, Yaron Y. Goland, Dick Hardt, Jeff 2770 Hodges, Edmund Jay, James Manger, Matt Miller, Tony Nadalin, Axel 2771 Nennker, John Panzer, Emmanuel Raviart, Nat Sakimura, Jim Schaad, 2772 Hannes Tschofenig, and Sean Turner. 2774 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2775 Sean Turner and Stephen Farrell served as Security area directors 2776 during the creation of this specification. 2778 Appendix E. Document History 2780 [[ to be removed by the RFC Editor before publication as an RFC ]] 2782 -18 2784 o Changes to address editorial and minor issues #129, #134, #135, 2785 #158, #161, #185, #186, and #187. 2787 o Added and used Description registry fields. 2789 -17 2791 o Explicitly named all the logical components of a JWS and JWE and 2792 defined the processing rules and serializations in terms of those 2793 components, addressing issues #60, #61, and #62. 2795 o Removed processing steps in algorithm definitions that duplicated 2796 processing steps in JWS or JWE, addressing issue #56. 2798 o Replaced verbose repetitive phases such as "base64url encode the 2799 octets of the UTF-8 representation of X" with mathematical 2800 notation such as "BASE64URL(UTF8(X))". 2802 o Terms used in multiple documents are now defined in one place and 2803 incorporated by reference. Some lightly used or obvious terms 2804 were also removed. This addresses issue #58. 2806 o Changes to address minor issue #53. 2808 -16 2810 o Added a DataLen prefix to the AlgorithmID value in the Concat KDF 2811 computation. 2813 o Added OIDs for encryption algorithms, additional signature 2814 algorithm OIDs, and additional XML DSIG/ENC URIs in the algorithm 2815 cross-reference tables. 2817 o Changes to address editorial and minor issues #28, #36, #39, #52, 2818 #53, #55, #127, #128, #136, #137, #141, #150, #151, #152, and 2819 #155. 2821 -15 2823 o Changed statements about rejecting JWSs to statements about 2824 validation failing, addressing issue #35. 2826 o Stated that changes of implementation requirements are only 2827 permitted on a Specification Required basis, addressing issue #38. 2829 o Made "oct" a required key type, addressing issue #40. 2831 o Updated the example ECDH-ES key agreement values. 2833 o Changes to address editorial and minor issues #34, #37, #49, #63, 2834 #123, #124, #125, #130, #132, #133, #138, #139, #140, #142, #143, 2835 #144, #145, #148, #149, #150, and #162. 2837 -14 2839 o Removed "PBKDF2" key type and added "p2s" and "p2c" header 2840 parameters for use with the PBES2 algorithms. 2842 o Made the RSA private key parameters that are there to enable 2843 optimizations be RECOMMENDED rather than REQUIRED. 2845 o Added algorithm identifiers for AES algorithms using 192 bit keys 2846 and for RSASSA-PSS using HMAC SHA-384. 2848 o Added security considerations about key lifetimes, addressing 2849 issue #18. 2851 o Added an example ECDH-ES key agreement computation. 2853 -13 2855 o Added key encryption with AES GCM as specified in 2856 draft-jones-jose-aes-gcm-key-wrap-01, addressing issue #13. 2858 o Added security considerations text limiting the number of times 2859 that an AES GCM key can be used for key encryption or direct 2860 encryption, per Section 8.3 of NIST SP 800-38D, addressing issue 2861 #28. 2863 o Added password-based key encryption as specified in 2864 draft-miller-jose-jwe-protected-jwk-02. 2866 -12 2868 o In the Direct Key Agreement case, the Concat KDF AlgorithmID is 2869 set to the octets of the UTF-8 representation of the "enc" header 2870 parameter value. 2872 o Restored the "apv" (agreement PartyVInfo) parameter. 2874 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2875 be with the algorithm descriptions that use them. 2877 o Changed terminology from "block encryption" to "content 2878 encryption". 2880 -11 2882 o Removed the Encrypted Key value from the AAD computation since it 2883 is already effectively integrity protected by the encryption 2884 process. The AAD value now only contains the representation of 2885 the JWE Encrypted Header. 2887 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2889 o Added more information about the use of PartyUInfo during key 2890 agreement. 2892 o Use the keydatalen as the SuppPubInfo value for the Concat KDF 2893 when doing key agreement, as RFC 2631 does. 2895 o Added algorithm identifiers for RSASSA-PSS with SHA-256 and SHA- 2896 512. 2898 o Added a Parameter Information Class value to the JSON Web Key 2899 Parameters registry, which registers whether the parameter conveys 2900 public or private information. 2902 -10 2904 o Changed the JWE processing rules for multiple recipients so that a 2905 single AAD value contains the header parameters and encrypted key 2906 values for all the recipients, enabling AES GCM to be safely used 2907 for multiple recipients. 2909 -09 2911 o Expanded the scope of the JWK parameters to include private and 2912 symmetric key representations, as specified by 2913 draft-jones-jose-json-private-and-symmetric-key-00. 2915 o Changed term "JWS Secured Input" to "JWS Signing Input". 2917 o Changed from using the term "byte" to "octet" when referring to 8 2918 bit values. 2920 o Specified that AES Key Wrap uses the default initial value 2921 specified in Section 2.2.3.1 of RFC 3394. This addressed issue 2922 #19. 2924 o Added Key Management Mode definitions to terminology section and 2925 used the defined terms to provide clearer key management 2926 instructions. This addressed issue #5. 2928 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2929 and "A256CBC-HS512". The new algorithms perform the same 2930 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2931 but with the Initialization Vector and Authentication Tag values 2932 remaining separate from the Ciphertext value in the output 2933 representation. Also deleted the header parameters "epu" 2934 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2935 they are no longer used. 2937 o Changed from using the term "Integrity Value" to "Authentication 2938 Tag". 2940 -08 2942 o Changed the name of the JWK key type parameter from "alg" to 2943 "kty". 2945 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2946 since the term AEAD in the RFC 5116 sense implied the use of a 2947 particular data representation, rather than just referring to the 2948 class of algorithms that perform authenticated encryption with 2949 associated data. 2951 o Applied editorial improvements suggested by Jeff Hodges. Many of 2952 these simplified the terminology used. 2954 o Added seriesInfo information to Internet Draft references. 2956 -07 2958 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2960 o Changed the name of the JWK RSA modulus parameter from "mod" to 2961 "n" and the name of the JWK RSA exponent parameter from "xpo" to 2962 "e", so that the identifiers are the same as those used in RFC 2963 3447. 2965 o Made several local editorial changes to clean up loose ends left 2966 over from to the decision to only support block encryption methods 2967 providing integrity. 2969 -06 2971 o Removed the "int" and "kdf" parameters and defined the new 2972 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2973 "A256CBC+HS512" to replace the former uses of AES CBC, which 2974 required the use of separate integrity and key derivation 2975 functions. 2977 o Included additional values in the Concat KDF calculation -- the 2978 desired output size and the algorithm value, and optionally 2979 PartyUInfo and PartyVInfo values. Added the optional header 2980 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2981 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2982 PartyVInfo). 2984 o Changed the name of the JWK RSA exponent parameter from "exp" to 2985 "xpo" so as to allow the potential use of the name "exp" for a 2986 future extension that might define an expiration parameter for 2987 keys. (The "exp" name is already used for this purpose in the JWT 2988 specification.) 2990 o Applied changes made by the RFC Editor to RFC 6749's registry 2991 language to this specification. 2993 -05 2995 o Support both direct encryption using a shared or agreed upon 2996 symmetric key, and the use of a shared or agreed upon symmetric 2997 key to key wrap the CMK. Specifically, added the "alg" values 2998 "dir", "ECDH-ES+A128KW", and "ECDH-ES+A256KW" to finish filling in 2999 this set of capabilities. 3001 o Updated open issues. 3003 -04 3005 o Added text requiring that any leading zero bytes be retained in 3006 base64url encoded key value representations for fixed-length 3007 values. 3009 o Added this language to Registration Templates: "This name is case 3010 sensitive. Names that match other registered names in a case 3011 insensitive manner SHOULD NOT be accepted." 3013 o Described additional open issues. 3015 o Applied editorial suggestions. 3017 -03 3019 o Always use a 128 bit "authentication tag" size for AES GCM, 3020 regardless of the key size. 3022 o Specified that use of a 128 bit IV is REQUIRED with AES CBC. It 3023 was previously RECOMMENDED. 3025 o Removed key size language for ECDSA algorithms, since the key size 3026 is implied by the algorithm being used. 3028 o Stated that the "int" key size must be the same as the hash output 3029 size (and not larger, as was previously allowed) so that its size 3030 is defined for key generation purposes. 3032 o Added the "kdf" (key derivation function) header parameter to 3033 provide crypto agility for key derivation. The default KDF 3034 remains the Concat KDF with the SHA-256 digest function. 3036 o Clarified that the "mod" and "exp" values are unsigned. 3038 o Added Implementation Requirements columns to algorithm tables and 3039 Implementation Requirements entries to algorithm registries. 3041 o Changed AES Key Wrap to RECOMMENDED. 3043 o Moved registries JSON Web Signature and Encryption Header 3044 Parameters and JSON Web Signature and Encryption Type Values to 3045 the JWS specification. 3047 o Moved JSON Web Key Parameters registry to the JWK specification. 3049 o Changed registration requirements from RFC Required to 3050 Specification Required with Expert Review. 3052 o Added Registration Template sections for defined registries. 3054 o Added Registry Contents sections to populate registry values. 3056 o No longer say "the UTF-8 representation of the JWS Secured Input 3057 (which is the same as the ASCII representation)". Just call it 3058 "the ASCII representation of the JWS Secured Input". 3060 o Added "Collision Resistant Namespace" to the terminology section. 3062 o Numerous editorial improvements. 3064 -02 3066 o For AES GCM, use the "additional authenticated data" parameter to 3067 provide integrity for the header, encrypted key, and ciphertext 3068 and use the resulting "authentication tag" value as the JWE 3069 Authentication Tag. 3071 o Defined minimum required key sizes for algorithms without 3072 specified key sizes. 3074 o Defined KDF output key sizes. 3076 o Specified the use of PKCS #5 padding with AES CBC. 3078 o Generalized text to allow key agreement to be employed as an 3079 alternative to key wrapping or key encryption. 3081 o Clarified that ECDH-ES is a key agreement algorithm. 3083 o Required implementation of AES-128-KW and AES-256-KW. 3085 o Removed the use of "A128GCM" and "A256GCM" for key wrapping. 3087 o Removed "A512KW" since it turns out that it's not a standard 3088 algorithm. 3090 o Clarified the relationship between "typ" header parameter values 3091 and MIME types. 3093 o Generalized language to refer to Message Authentication Codes 3094 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 3095 unless in a context specific to HMAC algorithms. 3097 o Established registries: JSON Web Signature and Encryption Header 3098 Parameters, JSON Web Signature and Encryption Algorithms, JSON Web 3099 Signature and Encryption "typ" Values, JSON Web Key Parameters, 3100 and JSON Web Key Algorithm Families. 3102 o Moved algorithm-specific definitions from JWK to JWA. 3104 o Reformatted to give each member definition its own section 3105 heading. 3107 -01 3108 o Moved definition of "alg":"none" for JWSs here from the JWT 3109 specification since this functionality is likely to be useful in 3110 more contexts that just for JWTs. 3112 o Added Advanced Encryption Standard (AES) Key Wrap Algorithm using 3113 512 bit keys ("A512KW"). 3115 o Added text "Alternatively, the Encoded JWS Signature MAY be 3116 base64url decoded to produce the JWS Signature and this value can 3117 be compared with the computed HMAC value, as this comparison 3118 produces the same result as comparing the encoded values". 3120 o Corrected the Magic Signatures reference. 3122 o Made other editorial improvements suggested by JOSE working group 3123 participants. 3125 -00 3127 o Created the initial IETF draft based upon 3128 draft-jones-json-web-signature-04 and 3129 draft-jones-json-web-encryption-02 with no normative changes. 3131 o Changed terminology to no longer call both digital signatures and 3132 HMACs "signatures". 3134 Author's Address 3136 Michael B. Jones 3137 Microsoft 3139 Email: mbj@microsoft.com 3140 URI: http://self-issued.info/