idnits 2.17.1 draft-ietf-jose-json-web-algorithms-16.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 23 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (September 15, 2013) is 3875 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 2882 -- Looks like a reference, but probably isn't: '0' on line 2882 -- Looks like a reference, but probably isn't: '7' on line 2856 -- Looks like a reference, but probably isn't: '5' on line 2862 -- Looks like a reference, but probably isn't: '65' on line 2864 -- Looks like a reference, but probably isn't: '108' on line 2864 -- Looks like a reference, but probably isn't: '105' on line 2864 -- Looks like a reference, but probably isn't: '99' on line 2864 -- Looks like a reference, but probably isn't: '101' on line 2864 -- Looks like a reference, but probably isn't: '3' on line 2867 -- Looks like a reference, but probably isn't: '66' on line 2869 -- Looks like a reference, but probably isn't: '111' on line 2869 -- Looks like a reference, but probably isn't: '98' on line 2869 -- Looks like a reference, but probably isn't: '128' on line 2872 -- 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 September 15, 2013 5 Expires: March 19, 2014 7 JSON Web Algorithms (JWA) 8 draft-ietf-jose-json-web-algorithms-16 10 Abstract 12 The JSON Web Algorithms (JWA) specification registers cryptographic 13 algorithms and identifiers to be used with the JSON Web Signature 14 (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) 15 specifications. It defines several IANA registries for these 16 identifiers. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on March 19, 2014. 35 Copyright Notice 37 Copyright (c) 2013 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 53 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 54 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 2.1. Terms Incorporated from the JWS Specification . . . . . . 5 56 2.2. Terms Incorporated from the JWE Specification . . . . . . 6 57 2.3. Terms Incorporated from the JWK Specification . . . . . . 9 58 2.4. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 9 59 3. Cryptographic Algorithms for Digital Signatures and MACs . . . 9 60 3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 9 61 3.2. HMAC with SHA-2 Functions . . . . . . . . . . . . . . . . 10 62 3.3. Digital Signature with RSASSA-PKCS1-V1_5 . . . . . . . . . 11 63 3.4. Digital Signature with ECDSA . . . . . . . . . . . . . . . 12 64 3.5. Digital Signature with RSASSA-PSS . . . . . . . . . . . . 14 65 3.6. Using the Algorithm "none" . . . . . . . . . . . . . . . . 15 66 4. Cryptographic Algorithms for Encryption . . . . . . . . . . . 15 67 4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 15 68 4.2. "enc" (Encryption Method) Header Parameter Values for 69 JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 70 4.3. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 21 71 4.4. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 21 72 4.5. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 21 73 4.6. Direct Encryption with a Shared Symmetric Key . . . . . . 21 74 4.7. Key Agreement with Elliptic Curve Diffie-Hellman 75 Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 22 76 4.7.1. Header Parameters Used for ECDH Key Agreement . . . . 22 77 4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 22 78 4.7.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 23 79 4.7.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 23 80 4.7.2. Key Derivation for ECDH Key Agreement . . . . . . . . 23 81 4.8. Key Encryption with AES GCM . . . . . . . . . . . . . . . 24 82 4.8.1. Header Parameters Used for AES GCM Key Encryption . . 25 83 4.8.1.1. "iv" (Initialization Vector) Header Parameter . . 25 84 4.8.1.2. "tag" (Authentication Tag) Header Parameter . . . 25 85 4.9. Key Encryption with PBES2 . . . . . . . . . . . . . . . . 25 86 4.9.1. Header Parameters Used for PBES2 Key Encryption . . . 26 87 4.9.1.1. "p2s" (PBES2 salt) Parameter . . . . . . . . . . . 26 88 4.9.1.2. "p2c" (PBES2 count) Parameter . . . . . . . . . . 26 89 4.10. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 26 90 4.10.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 27 91 4.10.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 27 92 4.10.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 27 93 4.10.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 29 94 4.10.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 29 95 4.10.4. AES_192_CBC_HMAC_SHA_384 . . . . . . . . . . . . . . . 30 96 4.10.5. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 30 97 4.10.6. Plaintext Encryption with AES_CBC_HMAC_SHA2 . . . . . 30 99 4.11. Plaintext Encryption with AES GCM . . . . . . . . . . . . 31 100 5. Cryptographic Algorithms for Keys . . . . . . . . . . . . . . 31 101 5.1. "kty" (Key Type) Parameter Values . . . . . . . . . . . . 31 102 5.2. Parameters for Elliptic Curve Keys . . . . . . . . . . . . 32 103 5.2.1. Parameters for Elliptic Curve Public Keys . . . . . . 32 104 5.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 32 105 5.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 33 106 5.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 33 107 5.2.2. Parameters for Elliptic Curve Private Keys . . . . . . 33 108 5.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 33 109 5.3. Parameters for RSA Keys . . . . . . . . . . . . . . . . . 33 110 5.3.1. Parameters for RSA Public Keys . . . . . . . . . . . . 33 111 5.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 33 112 5.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 34 113 5.3.2. Parameters for RSA Private Keys . . . . . . . . . . . 34 114 5.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 34 115 5.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 34 116 5.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 34 117 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 35 118 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 35 119 5.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 35 120 5.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 35 121 5.4. Parameters for Symmetric Keys . . . . . . . . . . . . . . 36 122 5.4.1. "k" (Key Value) Parameter . . . . . . . . . . . . . . 36 123 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 124 6.1. JSON Web Signature and Encryption Algorithms Registry . . 37 125 6.1.1. Template . . . . . . . . . . . . . . . . . . . . . . . 38 126 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 38 127 6.2. JWE Header Parameter Names Registration . . . . . . . . . 43 128 6.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 43 129 6.3. JSON Web Encryption Compression Algorithms Registry . . . 44 130 6.3.1. Registration Template . . . . . . . . . . . . . . . . 44 131 6.3.2. Initial Registry Contents . . . . . . . . . . . . . . 45 132 6.4. JSON Web Key Types Registry . . . . . . . . . . . . . . . 45 133 6.4.1. Registration Template . . . . . . . . . . . . . . . . 45 134 6.4.2. Initial Registry Contents . . . . . . . . . . . . . . 46 135 6.5. JSON Web Key Parameters Registration . . . . . . . . . . . 46 136 6.5.1. Registry Contents . . . . . . . . . . . . . . . . . . 46 137 6.6. JSON Web Key Elliptic Curve Registry . . . . . . . . . . . 48 138 6.6.1. Registration Template . . . . . . . . . . . . . . . . 48 139 6.6.2. Initial Registry Contents . . . . . . . . . . . . . . 49 140 7. Security Considerations . . . . . . . . . . . . . . . . . . . 49 141 7.1. Algorithms and Key Sizes will be Deprecated . . . . . . . 50 142 7.2. Key Lifetimes . . . . . . . . . . . . . . . . . . . . . . 50 143 7.3. RSAES-PKCS1-v1_5 Security Considerations . . . . . . . . . 50 144 7.4. AES GCM Security Considerations . . . . . . . . . . . . . 50 145 7.5. Plaintext JWS Security Considerations . . . . . . . . . . 51 146 7.6. Denial of Service Attacks . . . . . . . . . . . . . . . . 51 147 7.7. Reusing Key Material when Encrypting Keys . . . . . . . . 52 148 7.8. Password Considerations . . . . . . . . . . . . . . . . . 52 149 8. Internationalization Considerations . . . . . . . . . . . . . 52 150 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 53 151 9.1. Normative References . . . . . . . . . . . . . . . . . . . 53 152 9.2. Informative References . . . . . . . . . . . . . . . . . . 55 153 Appendix A. Digital Signature/MAC Algorithm Identifier 154 Cross-Reference . . . . . . . . . . . . . . . . . . . 56 155 Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 57 156 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 58 157 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 59 158 C.2. Test Cases for AES_192_CBC_HMAC_SHA_384 . . . . . . . . . 60 159 C.3. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 61 160 Appendix D. Example ECDH-ES Key Agreement Computation . . . . . . 62 161 Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 64 162 Appendix F. Document History . . . . . . . . . . . . . . . . . . 65 163 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 72 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 2. Terminology 197 2.1. Terms Incorporated from the JWS Specification 199 These terms defined by the JSON Web Signature (JWS) [JWS] 200 specification are incorporated into this specification: 202 JSON Web Signature (JWS) A data structure representing a digitally 203 signed or MACed message. The structure represents three values: 204 the JWS Header, the JWS Payload, and the JWS Signature. 206 JSON Text Object A UTF-8 [RFC3629] encoded text string representing 207 a JSON object; the syntax of JSON objects is defined in Section 208 2.2 of [RFC4627]. 210 JWS Header A JSON Text Object (or JSON Text Objects, when using the 211 JWS JSON Serialization) that describes the digital signature or 212 MAC operation applied to create the JWS Signature value. The 213 members of the JWS Header object(s) are Header Parameters. 215 JWS Payload The sequence of octets to be secured -- a.k.a., the 216 message. The payload can contain an arbitrary sequence of octets. 218 JWS Signature A sequence of octets containing the cryptographic 219 material that ensures the integrity of the JWS Protected Header 220 and the JWS Payload. The JWS Signature value is a digital 221 signature or MAC value calculated over the JWS Signing Input using 222 the parameters specified in the JWS Header. 224 JWS Protected Header A JSON Text Object that contains the portion of 225 the JWS Header that is integrity protected. For the JWS Compact 226 Serialization, this comprises the entire JWS Header. For the JWS 227 JSON Serialization, this is one component of the JWS Header. 229 Base64url Encoding Base64 encoding using the URL- and filename-safe 230 character set defined in Section 5 of RFC 4648 [RFC4648], with all 231 trailing '=' characters omitted (as permitted by Section 3.2). 232 (See Appendix C of [JWS] for notes on implementing base64url 233 encoding without padding.) 235 Encoded JWS Header Base64url encoding of the JWS Protected Header. 237 Encoded JWS Payload Base64url encoding of the JWS Payload. 239 Encoded JWS Signature Base64url encoding of the JWS Signature. 241 JWS Signing Input The concatenation of the Encoded JWS Header, a 242 period ('.') character, and the Encoded JWS Payload. 244 2.2. Terms Incorporated from the JWE Specification 246 These terms defined by the JSON Web Encryption (JWE) [JWE] 247 specification are incorporated into this specification: 249 JSON Web Encryption (JWE) A data structure representing an encrypted 250 message. The structure represents five values: the JWE Header, 251 the JWE Encrypted Key, the JWE Initialization Vector, the JWE 252 Ciphertext, and the JWE Authentication Tag. 254 Authenticated Encryption An Authenticated Encryption algorithm is 255 one that provides an integrated content integrity check. 256 Authenticated Encryption algorithms accept two inputs, the 257 Plaintext and the Additional Authenticated Data value, and produce 258 two outputs, the Ciphertext and the Authentication Tag value. AES 259 Galois/Counter Mode (GCM) is one such algorithm. 261 Plaintext The sequence of octets to be encrypted -- a.k.a., the 262 message. The plaintext can contain an arbitrary sequence of 263 octets. 265 Ciphertext An encrypted representation of the Plaintext. 267 Additional Authenticated Data (AAD) An input to an Authenticated 268 Encryption operation that is integrity protected but not 269 encrypted. 271 Authentication Tag An output of an Authenticated Encryption 272 operation that ensures the integrity of the Ciphertext and the 273 Additional Authenticated Data. Note that some algorithms may not 274 use an Authentication Tag, in which case this value is the empty 275 octet sequence. 277 Content Encryption Key (CEK) A symmetric key for the Authenticated 278 Encryption algorithm used to encrypt the Plaintext for the 279 recipient to produce the Ciphertext and the Authentication Tag. 281 JWE Header A JSON Text Object (or JSON Text Objects, when using the 282 JWE JSON Serialization) that describes the encryption operations 283 applied to create the JWE Encrypted Key, the JWE Ciphertext, and 284 the JWE Authentication Tag. The members of the JWE Header 285 object(s) are Header Parameters. 287 JWE Encrypted Key The result of encrypting the Content Encryption 288 Key (CEK) with the intended recipient's key using the specified 289 algorithm. Note that for some algorithms, the JWE Encrypted Key 290 value is specified as being the empty octet sequence. 292 JWE Initialization Vector A sequence of octets containing the 293 Initialization Vector used when encrypting the Plaintext. Note 294 that some algorithms may not use an Initialization Vector, in 295 which case this value is the empty octet sequence. 297 JWE Ciphertext A sequence of octets containing the Ciphertext for a 298 JWE. 300 JWE Authentication Tag A sequence of octets containing the 301 Authentication Tag for a JWE. 303 JWE Protected Header A JSON Text Object that contains the portion of 304 the JWE Header that is integrity protected. For the JWE Compact 305 Serialization, this comprises the entire JWE Header. For the JWE 306 JSON Serialization, this is one component of the JWE Header. 308 Encoded JWE Header Base64url encoding of the JWE Protected Header. 310 Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted 311 Key. 313 Encoded JWE Initialization Vector Base64url encoding of the JWE 314 Initialization Vector. 316 Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. 318 Encoded JWE Authentication Tag Base64url encoding of the JWE 319 Authentication Tag. 321 Key Management Mode A method of determining the Content Encryption 322 Key (CEK) value to use. Each algorithm used for determining the 323 CEK value uses a specific Key Management Mode. Key Management 324 Modes employed by this specification are Key Encryption, Key 325 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 326 and Direct Encryption. 328 Key Encryption A Key Management Mode in which the Content Encryption 329 Key (CEK) value is encrypted to the intended recipient using an 330 asymmetric encryption algorithm. 332 Key Wrapping A Key Management Mode in which the Content Encryption 333 Key (CEK) value is encrypted to the intended recipient using a 334 symmetric key wrapping algorithm. 336 Direct Key Agreement A Key Management Mode in which a key agreement 337 algorithm is used to agree upon the Content Encryption Key (CEK) 338 value. 340 Key Agreement with Key Wrapping A Key Management Mode in which a key 341 agreement algorithm is used to agree upon a symmetric key used to 342 encrypt the Content Encryption Key (CEK) value to the intended 343 recipient using a symmetric key wrapping algorithm. 345 Direct Encryption A Key Management Mode in which the Content 346 Encryption Key (CEK) value used is the secret symmetric key value 347 shared between the parties. 349 2.3. Terms Incorporated from the JWK Specification 351 These terms defined by the JSON Web Key (JWK) [JWK] specification are 352 incorporated into this specification: 354 JSON Web Key (JWK) A JSON object that represents a cryptographic 355 key. 357 JSON Web Key Set (JWK Set) A JSON object that contains an array of 358 JWKs as the value of its "keys" member. 360 2.4. Defined Terms 362 These terms are defined for use by this specification: 364 Header Parameter A name/value pair that is member of a JWS Header or 365 JWE Header. 367 Header Parameter Name The name of a member of a JSON object 368 representing a JWS Header or JWE Header. 370 Header Parameter Value The value of a member of a JSON object 371 representing a JWS Header or JWE Header. 373 3. Cryptographic Algorithms for Digital Signatures and MACs 375 JWS uses cryptographic algorithms to digitally sign or create a 376 Message Authentication Codes (MAC) of the contents of the JWS Header 377 and the JWS Payload. 379 3.1. "alg" (Algorithm) Header Parameter Values for JWS 381 The table below is the set of "alg" (algorithm) header parameter 382 values defined by this specification for use with JWS, each of which 383 is explained in more detail in the following sections: 385 +-----------+--------------------------------------+----------------+ 386 | alg | Digital Signature or MAC Algorithm | Implementation | 387 | Parameter | | Requirements | 388 | Value | | | 389 +-----------+--------------------------------------+----------------+ 390 | HS256 | HMAC using SHA-256 hash algorithm | Required | 391 | HS384 | HMAC using SHA-384 hash algorithm | Optional | 392 | HS512 | HMAC using SHA-512 hash algorithm | Optional | 393 | RS256 | RSASSA-PKCS-v1_5 using SHA-256 hash | Recommended | 394 | | algorithm | | 395 | RS384 | RSASSA-PKCS-v1_5 using SHA-384 hash | Optional | 396 | | algorithm | | 397 | RS512 | RSASSA-PKCS-v1_5 using SHA-512 hash | Optional | 398 | | algorithm | | 399 | ES256 | ECDSA using P-256 curve and SHA-256 | Recommended+ | 400 | | hash algorithm | | 401 | ES384 | ECDSA using P-384 curve and SHA-384 | Optional | 402 | | hash algorithm | | 403 | ES512 | ECDSA using P-521 curve and SHA-512 | Optional | 404 | | hash algorithm | | 405 | PS256 | RSASSA-PSS using SHA-256 hash | Optional | 406 | | algorithm and MGF1 mask generation | | 407 | | function with SHA-256 | | 408 | PS384 | RSASSA-PSS using SHA-384 hash | Optional | 409 | | algorithm and MGF1 mask generation | | 410 | | function with SHA-384 | | 411 | PS512 | RSASSA-PSS using SHA-512 hash | Optional | 412 | | algorithm and MGF1 mask generation | | 413 | | function with SHA-512 | | 414 | none | No digital signature or MAC value | Optional | 415 | | included | | 416 +-----------+--------------------------------------+----------------+ 418 The use of "+" in the Implementation Requirements indicates that the 419 requirement strength is likely to be increased in a future version of 420 the specification. 422 See Appendix A for a table cross-referencing the digital signature 423 and MAC "alg" (algorithm) values used in this specification with the 424 equivalent identifiers used by other standards and software packages. 426 3.2. HMAC with SHA-2 Functions 428 Hash-based Message Authentication Codes (HMACs) enable one to use a 429 secret plus a cryptographic hash function to generate a Message 430 Authentication Code (MAC). This can be used to demonstrate that 431 whoever generated the MAC was in possession of the MAC key. 433 The algorithm for implementing and validating HMACs is provided in 434 RFC 2104 [RFC2104]. This section defines the use of the HMAC SHA- 435 256, HMAC SHA-384, and HMAC SHA-512 functions [SHS]. The "alg" 436 (algorithm) header parameter values "HS256", "HS384", and "HS512" are 437 used in the JWS Header to indicate that the Encoded JWS Signature 438 contains a base64url encoded HMAC value using the respective hash 439 function. 441 A key of the same size as the hash output (for instance, 256 bits for 442 "HS256") or larger MUST be used with this algorithm. 444 The HMAC SHA-256 MAC is generated per RFC 2104, using SHA-256 as the 445 hash algorithm "H", using the octets of the ASCII [USASCII] 446 representation of the JWS Signing Input as the "text" value, and 447 using the shared key. The HMAC output value is the JWS Signature. 448 The JWS signature is base64url encoded to produce the Encoded JWS 449 Signature. 451 The HMAC SHA-256 MAC for a JWS is validated by computing an HMAC 452 value per RFC 2104, using SHA-256 as the hash algorithm "H", using 453 the octets of the ASCII representation of the received JWS Signing 454 Input as the "text" value, and using the shared key. This computed 455 HMAC value is then compared to the result of base64url decoding the 456 received Encoded JWS signature. Alternatively, the computed HMAC 457 value can be base64url encoded and compared to the received Encoded 458 JWS Signature, as this comparison produces the same result as 459 comparing the unencoded values. In either case, if the values match, 460 the HMAC has been validated. 462 Securing content with the HMAC SHA-384 and HMAC SHA-512 algorithms is 463 performed identically to the procedure for HMAC SHA-256 - just using 464 the corresponding hash algorithms with correspondingly larger minimum 465 key sizes and result values: 384 bits each for HMAC SHA-384 and 512 466 bits each for HMAC SHA-512. 468 An example using this algorithm is shown in Appendix A.1 of [JWS]. 470 3.3. Digital Signature with RSASSA-PKCS1-V1_5 472 This section defines the use of the RSASSA-PKCS1-V1_5 digital 473 signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447] 474 (commonly known as PKCS #1), using SHA-256, SHA-384, or SHA-512 [SHS] 475 as the hash functions. The "alg" (algorithm) header parameter values 476 "RS256", "RS384", and "RS512" are used in the JWS Header to indicate 477 that the Encoded JWS Signature contains a base64url encoded RSASSA- 478 PKCS1-V1_5 digital signature using the respective hash function. 480 A key of size 2048 bits or larger MUST be used with these algorithms. 482 The RSASSA-PKCS1-V1_5 SHA-256 digital signature is generated as 483 follows: 485 1. Generate a digital signature of the octets of the ASCII 486 representation of the JWS Signing Input using RSASSA-PKCS1-V1_5- 487 SIGN and the SHA-256 hash function with the desired private key. 488 The output will be an octet sequence. 490 2. Base64url encode the resulting octet sequence. 492 The output is the Encoded JWS Signature for that JWS. 494 The RSASSA-PKCS1-V1_5 SHA-256 digital signature for a JWS is 495 validated as follows: 497 1. Take the Encoded JWS Signature and base64url decode it into an 498 octet sequence. If decoding fails, the validation has failed. 500 2. Submit the octets of the ASCII representation of the JWS Signing 501 Input and the public key corresponding to the private key used by 502 the signer to the RSASSA-PKCS1-V1_5-VERIFY algorithm using SHA- 503 256 as the hash function. 505 Signing with the RSASSA-PKCS1-V1_5 SHA-384 and RSASSA-PKCS1-V1_5 SHA- 506 512 algorithms is performed identically to the procedure for RSASSA- 507 PKCS1-V1_5 SHA-256 - just using the corresponding hash algorithms 508 instead of SHA-256. 510 An example using this algorithm is shown in Appendix A.2 of [JWS]. 512 3.4. Digital Signature with ECDSA 514 The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides 515 for the use of Elliptic Curve cryptography, which is able to provide 516 equivalent security to RSA cryptography but using shorter key sizes 517 and with greater processing speed. This means that ECDSA digital 518 signatures will be substantially smaller in terms of length than 519 equivalently strong RSA digital signatures. 521 This specification defines the use of ECDSA with the P-256 curve and 522 the SHA-256 cryptographic hash function, ECDSA with the P-384 curve 523 and the SHA-384 hash function, and ECDSA with the P-521 curve and the 524 SHA-512 hash function. The P-256, P-384, and P-521 curves are 525 defined in [DSS]. The "alg" (algorithm) header parameter values 526 "ES256", "ES384", and "ES512" are used in the JWS Header to indicate 527 that the Encoded JWS Signature contains a base64url encoded ECDSA 528 P-256 SHA-256, ECDSA P-384 SHA-384, or ECDSA P-521 SHA-512 digital 529 signature, respectively. 531 The ECDSA P-256 SHA-256 digital signature is generated as follows: 533 1. Generate a digital signature of the octets of the ASCII 534 representation of the JWS Signing Input using ECDSA P-256 SHA-256 535 with the desired private key. The output will be the pair (R, 536 S), where R and S are 256 bit unsigned integers. 538 2. Turn R and S into octet sequences in big endian order, with each 539 array being be 32 octets long. The octet sequence 540 representations MUST NOT be shortened to omit any leading zero 541 octets contained in the values. 543 3. Concatenate the two octet sequences in the order R and then S. 544 (Note that many ECDSA implementations will directly produce this 545 concatenation as their output.) 547 4. Base64url encode the resulting 64 octet sequence. 549 The output is the Encoded JWS Signature for the JWS. 551 The ECDSA P-256 SHA-256 digital signature for a JWS is validated as 552 follows: 554 1. Take the Encoded JWS Signature and base64url decode it into an 555 octet sequence. If decoding fails, the validation has failed. 557 2. The output of the base64url decoding MUST be a 64 octet sequence. 558 If decoding does not result in a 64 octet sequence, the 559 validation has failed. 561 3. Split the 64 octet sequence into two 32 octet sequences. The 562 first array will be R and the second S (with both being in big 563 endian octet order). 565 4. Submit the octets of the ASCII representation of the JWS Signing 566 Input R, S and the public key (x, y) to the ECDSA P-256 SHA-256 567 validator. 569 Signing with the ECDSA P-384 SHA-384 and ECDSA P-521 SHA-512 570 algorithms is performed identically to the procedure for ECDSA P-256 571 SHA-256 - just using the corresponding hash algorithms with 572 correspondingly larger result values. For ECDSA P-384 SHA-384, R and 573 S will be 384 bits each, resulting in a 96 octet sequence. For ECDSA 574 P-521 SHA-512, R and S will be 521 bits each, resulting in a 132 575 octet sequence. 577 Examples using these algorithms are shown in Appendices A.3 and A.4 578 of [JWS]. 580 3.5. Digital Signature with RSASSA-PSS 582 This section defines the use of the RSASSA-PSS digital signature 583 algorithm as defined in Section 8.1 of RFC 3447 [RFC3447] with the 584 MGF1 mask generation function, always using the same hash function 585 for both the RSASSA-PSS hash function and the MGF1 hash function. 586 Use of SHA-256, SHA-384, and SHA-512 as these hash functions is 587 defined. The size of the salt value is the same size as the hash 588 function output. All other algorithm parameters use the defaults 589 specified in Section A.2.3 of RFC 3447. The "alg" (algorithm) header 590 parameter values "PS256", "PS384", and "PS512" are used in the JWS 591 Header to indicate that the Encoded JWS Signature contains a 592 base64url encoded RSASSA-PSS digital signature using the respective 593 hash function in both roles. 595 A key of size 2048 bits or larger MUST be used with this algorithm. 597 The RSASSA-PSS SHA-256 digital signature is generated as follows: 599 1. Generate a digital signature of the octets of the ASCII 600 representation of the JWS Signing Input using RSASSA-PSS-SIGN, 601 the SHA-256 hash function, and the MGF1 mask generation function 602 with SHA-256 with the desired private key. The output will be an 603 octet sequence. 605 2. Base64url encode the resulting octet sequence. 607 The output is the Encoded JWS Signature for that JWS. 609 The RSASSA-PSS SHA-256 digital signature for a JWS is validated as 610 follows: 612 1. Take the Encoded JWS Signature and base64url decode it into an 613 octet sequence. If decoding fails, the validation has failed. 615 2. Submit the octets of the ASCII representation of the JWS Signing 616 Input and the public key corresponding to the private key used by 617 the signer to the RSASSA-PSS-VERIFY algorithm using SHA-256 as 618 the hash function and using MGF1 as the mask generation function 619 with SHA-256. 621 Signing with the RSASSA-PSS SHA-384 and RSASSA-PSS SHA-512 algorithms 622 is performed identically to the procedure for RSASSA-PSS SHA-256 - 623 just using the alternative hash algorithm in both roles. 625 3.6. Using the Algorithm "none" 627 JWSs MAY also be created that do not provide integrity protection. 628 Such a JWS is called a "Plaintext JWS". Plaintext JWSs MUST use the 629 "alg" value "none", and are formatted identically to other JWSs, but 630 with the empty string for its JWS Signature value. See Section 7.5 631 for security considerations associated with using this algorithm. 633 4. Cryptographic Algorithms for Encryption 635 JWE uses cryptographic algorithms to encrypt the Content Encryption 636 Key (CEK) and the Plaintext. 638 4.1. "alg" (Algorithm) Header Parameter Values for JWE 640 The table below is the set of "alg" (algorithm) header parameter 641 values that are defined by this specification for use with JWE. 642 These algorithms are used to encrypt the CEK, producing the JWE 643 Encrypted Key, or to use key agreement to agree upon the CEK. 645 +-------------------+-----------------+------------+----------------+ 646 | alg Parameter | Key Management | Additional | Implementation | 647 | Value | Algorithm | Header | Requirements | 648 | | | Parameters | | 649 +-------------------+-----------------+------------+----------------+ 650 | RSA1_5 | RSAES-PKCS1-V1_ | (none) | Required | 651 | | 5[RFC3447] | | | 652 | RSA-OAEP | RSAES using | (none) | Optional | 653 | | Optimal | | | 654 | | Asymmetric | | | 655 | | Encryption | | | 656 | | Padding (OAEP) | | | 657 | | [RFC3447], with | | | 658 | | the default | | | 659 | | parameters | | | 660 | | specified by | | | 661 | | RFC 3447 in | | | 662 | | Section A.2.1 | | | 663 | A128KW | Advanced | (none) | Recommended | 664 | | Encryption | | | 665 | | Standard (AES) | | | 666 | | Key Wrap | | | 667 | | Algorithm | | | 668 | | [RFC3394] using | | | 669 | | the default | | | 670 | | initial value | | | 671 | | specified in | | | 672 | | Section 2.2.3.1 | | | 673 | | and using 128 | | | 674 | | bit keys | | | 675 | A192KW | AES Key Wrap | (none) | Optional | 676 | | Algorithm using | | | 677 | | the default | | | 678 | | initial value | | | 679 | | specified in | | | 680 | | Section 2.2.3.1 | | | 681 | | and using 192 | | | 682 | | bit keys | | | 683 | A256KW | AES Key Wrap | (none) | Recommended | 684 | | Algorithm using | | | 685 | | the default | | | 686 | | initial value | | | 687 | | specified in | | | 688 | | Section 2.2.3.1 | | | 689 | | and using 256 | | | 690 | | bit keys | | | 691 | dir | Direct use of a | (none) | Recommended | 692 | | shared | | | 693 | | symmetric key | | | 694 | | as the Content | | | 695 | | Encryption Key | | | 696 | | (CEK) for the | | | 697 | | content | | | 698 | | encryption step | | | 699 | | (rather than | | | 700 | | using the | | | 701 | | symmetric key | | | 702 | | to wrap the | | | 703 | | CEK) | | | 704 | ECDH-ES | Elliptic Curve | "epk", | Recommended+ | 705 | | Diffie-Hellman | "apu", | | 706 | | Ephemeral | "apv" | | 707 | | Static | | | 708 | | [RFC6090] key | | | 709 | | agreement using | | | 710 | | the Concat KDF, | | | 711 | | as defined in | | | 712 | | Section 5.8.1 | | | 713 | | of | | | 714 | | [NIST.800-56A], | | | 715 | | with the | | | 716 | | agreed-upon key | | | 717 | | being used | | | 718 | | directly as the | | | 719 | | Content | | | 720 | | Encryption Key | | | 721 | | (CEK) (rather | | | 722 | | than being used | | | 723 | | to wrap the | | | 724 | | CEK), as | | | 725 | | specified in | | | 726 | | Section 4.7 | | | 727 | ECDH-ES+A128KW | Elliptic Curve | "epk", | Recommended | 728 | | Diffie-Hellman | "apu", | | 729 | | Ephemeral | "apv" | | 730 | | Static key | | | 731 | | agreement per | | | 732 | | "ECDH-ES" and | | | 733 | | Section 4.7, | | | 734 | | where the | | | 735 | | agreed-upon key | | | 736 | | is used to wrap | | | 737 | | the Content | | | 738 | | Encryption Key | | | 739 | | (CEK) with the | | | 740 | | "A128KW" | | | 741 | | function | | | 742 | | (rather than | | | 743 | | being used | | | 744 | | directly as the | | | 745 | | CEK) | | | 746 | ECDH-ES+A192KW | Elliptic Curve | "epk", | Optional | 747 | | Diffie-Hellman | "apu", | | 748 | | Ephemeral | "apv" | | 749 | | Static key | | | 750 | | agreement, | | | 751 | | where the | | | 752 | | agreed-upon key | | | 753 | | is used to wrap | | | 754 | | the Content | | | 755 | | Encryption Key | | | 756 | | (CEK) with the | | | 757 | | "A192KW" | | | 758 | | function | | | 759 | | (rather than | | | 760 | | being used | | | 761 | | directly as the | | | 762 | | CEK) | | | 763 | ECDH-ES+A256KW | Elliptic Curve | "epk", | Recommended | 764 | | Diffie-Hellman | "apu", | | 765 | | Ephemeral | "apv" | | 766 | | Static key | | | 767 | | agreement, | | | 768 | | where the | | | 769 | | agreed-upon key | | | 770 | | is used to wrap | | | 771 | | the Content | | | 772 | | Encryption Key | | | 773 | | (CEK) with the | | | 774 | | "A256KW" | | | 775 | | function | | | 776 | | (rather than | | | 777 | | being used | | | 778 | | directly as the | | | 779 | | CEK) | | | 780 | A128GCMKW | AES in | "iv", | Optional | 781 | | Galois/Counter | "tag" | | 782 | | Mode (GCM) | | | 783 | | [AES] | | | 784 | | [NIST.800-38D] | | | 785 | | using 128 bit | | | 786 | | keys | | | 787 | A192GCMKW | AES GCM using | "iv", | Optional | 788 | | 192 bit keys | "tag" | | 789 | A256GCMKW | AES GCM using | "iv", | Optional | 790 | | 256 bit keys | "tag" | | 791 | PBES2-HS256+A128K | PBES2 [RFC2898] | "p2s", | Optional | 792 | W | with HMAC | "p2c" | | 793 | | SHA-256 as the | | | 794 | | PRF and AES Key | | | 795 | | Wrap [RFC3394] | | | 796 | | using 128 bit | | | 797 | | keys for the | | | 798 | | encryption | | | 799 | | scheme | | | 800 | PBES2-HS384+A192K | PBES2 with HMAC | "p2s", | Optional | 801 | W | SHA-256 as the | "p2c" | | 802 | | PRF and AES Key | | | 803 | | Wrap using 192 | | | 804 | | bit keys for | | | 805 | | the encryption | | | 806 | | scheme | | | 807 | PBES2-HS512+A256K | PBES2 with HMAC | "p2s", | Optional | 808 | W | SHA-256 as the | "p2c" | | 809 | | PRF and AES Key | | | 810 | | Wrap using 256 | | | 811 | | bit keys for | | | 812 | | the encryption | | | 813 | | scheme | | | 814 +-------------------+-----------------+------------+----------------+ 816 The Additional Header Parameters column indicates what additional 817 Header Parameters are used by the algorithm, beyond "alg", which all 818 use. All but "dir" and "ECDH-ES" also produce a JWE Encrypted Key 819 value. 821 The use of "+" in the Implementation Requirements indicates that the 822 requirement strength is likely to be increased in a future version of 823 the specification. 825 4.2. "enc" (Encryption Method) Header Parameter Values for JWE 827 The table below is the set of "enc" (encryption method) header 828 parameter values that are defined by this specification for use with 829 JWE. These algorithms are used to encrypt the Plaintext, which 830 produces the Ciphertext. 832 +-------------+------------------------+------------+---------------+ 833 | enc | Content Encryption | Additional | Implementatio | 834 | Parameter | Algorithm | Header | nRequirements | 835 | Value | | Parameters | | 836 +-------------+------------------------+------------+---------------+ 837 | A128CBC-HS2 | The | (none) | Required | 838 | 56 | AES_128_CBC_HMAC_SHA_2 | | | 839 | | 56 authenticated | | | 840 | | encryption algorithm, | | | 841 | | as defined in | | | 842 | | Section 4.10.3. This | | | 843 | | algorithm uses a 256 | | | 844 | | bit key. | | | 845 | A192CBC-HS3 | The | (none) | Optional | 846 | 84 | AES_192_CBC_HMAC_SHA_3 | | | 847 | | 84 authenticated | | | 848 | | encryption algorithm, | | | 849 | | as defined in | | | 850 | | Section 4.10.4. This | | | 851 | | algorithm uses a 384 | | | 852 | | bit key. | | | 853 | A256CBC-HS5 | The | (none) | Required | 854 | 12 | AES_256_CBC_HMAC_SHA_5 | | | 855 | | 12 authenticated | | | 856 | | encryption algorithm, | | | 857 | | as defined in | | | 858 | | Section 4.10.5. This | | | 859 | | algorithm uses a 512 | | | 860 | | bit key. | | | 861 | A128GCM | AES in Galois/Counter | (none) | Recommended | 862 | | Mode (GCM) [AES] | | | 863 | | [NIST.800-38D] using | | | 864 | | 128 bit keys | | | 865 | A192GCM | AES GCM using 192 bit | (none) | Optional | 866 | | keys | | | 867 | A256GCM | AES GCM using 256 bit | (none) | Recommended | 868 | | keys | | | 869 +-------------+------------------------+------------+---------------+ 871 The Additional Header Parameters column indicates what additional 872 Header Parameters are used by the algorithm, beyond "enc", which all 873 use. All also use a JWE Initialization Vector value and produce JWE 874 Ciphertext and JWE Authentication Tag values. 876 See Appendix B for a table cross-referencing the encryption "alg" 877 (algorithm) and "enc" (encryption method) values used in this 878 specification with the equivalent identifiers used by other standards 879 and software packages. 881 4.3. Key Encryption with RSAES-PKCS1-V1_5 883 This section defines the specifics of encrypting a JWE CEK with 884 RSAES-PKCS1-V1_5 [RFC3447]. The "alg" header parameter value 885 "RSA1_5" is used in this case. 887 A key of size 2048 bits or larger MUST be used with this algorithm. 889 An example using this algorithm is shown in Appendix A.2 of [JWE]. 891 4.4. Key Encryption with RSAES OAEP 893 This section defines the specifics of encrypting a JWE CEK with RSAES 894 using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447], with 895 the default parameters specified by RFC 3447 in Section A.2.1. 896 (Those default parameters are using a hash function of SHA-1 and a 897 mask generation function of MGF1 with SHA-1.) The "alg" header 898 parameter value "RSA-OAEP" is used in this case. 900 A key of size 2048 bits or larger MUST be used with this algorithm. 902 An example using this algorithm is shown in Appendix A.1 of [JWE]. 904 4.5. Key Wrapping with AES Key Wrap 906 This section defines the specifics of encrypting a JWE CEK with the 907 Advanced Encryption Standard (AES) Key Wrap Algorithm [RFC3394] using 908 the default initial value specified in Section 2.2.3.1 using 128, 909 192, or 256 bit keys. The "alg" header parameter values "A128KW", 910 "A192KW", or "A256KW" are respectively used in this case. 912 An example using this algorithm is shown in Appendix A.3 of [JWE]. 914 4.6. Direct Encryption with a Shared Symmetric Key 916 This section defines the specifics of directly performing symmetric 917 key encryption without performing a key wrapping step. In this case, 918 the shared symmetric key is used directly as the Content Encryption 919 Key (CEK) value for the "enc" algorithm. An empty octet sequence is 920 used as the JWE Encrypted Key value. The "alg" header parameter 921 value "dir" is used in this case. 923 Refer to the security considerations on key lifetimes in Section 7.2 924 and AES GCM in Section 7.4 when considering utilizing direct 925 encryption. 927 4.7. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static 928 (ECDH-ES) 930 This section defines the specifics of key agreement with Elliptic 931 Curve Diffie-Hellman Ephemeral Static [RFC6090], in combination with 932 the Concat KDF, as defined in Section 5.8.1 of [NIST.800-56A]. The 933 key agreement result can be used in one of two ways: 935 1. directly as the Content Encryption Key (CEK) for the "enc" 936 algorithm, in the Direct Key Agreement mode, or 938 2. as a symmetric key used to wrap the CEK with the "A128KW", 939 "A192KW", or "A256KW" algorithms, in the Key Agreement with Key 940 Wrapping mode. 942 The "alg" header parameter value "ECDH-ES" is used in the Direct Key 943 Agreement mode and the values "ECDH-ES+A128KW", "ECDH-ES+A192KW", or 944 "ECDH-ES+A256KW" are used in the Key Agreement with Key Wrapping 945 mode. 947 In the Direct Key Agreement case, the output of the Concat KDF MUST 948 be a key of the same length as that used by the "enc" algorithm; in 949 this case, the empty octet sequence is used as the JWE Encrypted Key 950 value. In the Key Agreement with Key Wrapping case, the output of 951 the Concat KDF MUST be a key of the length needed for the specified 952 key wrapping algorithm, one of 128, 192, or 256 bits respectively. 954 A new ephemeral public key value MUST be generated for each key 955 agreement operation. 957 4.7.1. Header Parameters Used for ECDH Key Agreement 959 The following Header Parameter Names are used for key agreement as 960 defined below. 962 4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter 964 The "epk" (ephemeral public key) value created by the originator for 965 the use in key agreement algorithms. This key is represented as a 966 JSON Web Key [JWK] public key value. It MUST contain only public key 967 parameters and SHOULD contain only the minimum JWK parameters 968 necessary to represent the key; other JWK parameters included can be 969 checked for consistency and honored or can be ignored. This Header 970 Parameter is REQUIRED and MUST be understood and processed by 971 implementations when these algorithms are used. 973 4.7.1.2. "apu" (Agreement PartyUInfo) Header Parameter 975 The "apu" (agreement PartyUInfo) value for key agreement algorithms 976 using it (such as "ECDH-ES"), represented as a base64url encoded 977 string. When used, the PartyUInfo value contains information about 978 the sender. Use of this Header Parameter is OPTIONAL. This Header 979 Parameter MUST be understood and processed by implementations when 980 these algorithms are used. 982 4.7.1.3. "apv" (Agreement PartyVInfo) Header Parameter 984 The "apv" (agreement PartyVInfo) value for key agreement algorithms 985 using it (such as "ECDH-ES"), represented as a base64url encoded 986 string. When used, the PartyVInfo value contains information about 987 the receiver. Use of this Header Parameter is OPTIONAL. This Header 988 Parameter MUST be understood and processed by implementations when 989 these algorithms are used. 991 4.7.2. Key Derivation for ECDH Key Agreement 993 The key derivation process derives the agreed upon key from the 994 shared secret Z established through the ECDH algorithm, per Section 995 6.2.2.2 of [NIST.800-56A]. 997 Key derivation is performed using the Concat KDF, as defined in 998 Section 5.8.1 of [NIST.800-56A], where the Digest Method is SHA-256. 999 The Concat KDF parameters are set as follows: 1001 Z This is set to the representation of the shared secret Z as an 1002 octet sequence. 1004 keydatalen This is set to the number of bits in the desired output 1005 key. For "ECDH-ES", this is length of the key used by the "enc" 1006 algorithm. For "ECDH-ES+A128KW", "ECDH-ES+A192KW", and 1007 "ECDH-ES+A256KW", this is 128, 192, and 256, respectively. 1009 AlgorithmID The AlgorithmID value is of the form Datalen || Data, 1010 where Data is a variable-length string of zero or more octets, and 1011 Datalen is a fixed-length, big endian 32 bit counter that 1012 indicates the length (in octets) of Data, with || being 1013 concatenation. In the Direct Key Agreement case, Data is set to 1014 the octets of the UTF-8 representation of the "enc" header 1015 parameter value. In the Key Agreement with Key Wrapping case, 1016 Data is set to the octets of the UTF-8 representation of the "alg" 1017 header parameter value. 1019 PartyUInfo The PartyUInfo value is of the form Datalen || Data, 1020 where Data is a variable-length string of zero or more octets, and 1021 Datalen is a fixed-length, big endian 32 bit counter that 1022 indicates the length (in octets) of Data, with || being 1023 concatenation. If an "apu" (agreement PartyUInfo) header 1024 parameter is present, Data is set to the result of base64url 1025 decoding the "apu" value and Datalen is set to the number of 1026 octets in Data. Otherwise, Datalen is set to 0 and Data is set to 1027 the empty octet sequence. 1029 PartyVInfo The PartyVInfo value is of the form Datalen || Data, 1030 where Data is a variable-length string of zero or more octets, and 1031 Datalen is a fixed-length, big endian 32 bit counter that 1032 indicates the length (in octets) of Data, with || being 1033 concatenation. If an "apv" (agreement PartyVInfo) header 1034 parameter is present, Data is set to the result of base64url 1035 decoding the "apv" value and Datalen is set to the number of 1036 octets in Data. Otherwise, Datalen is set to 0 and Data is set to 1037 the empty octet sequence. 1039 SuppPubInfo This is set to the keydatalen represented as a 32 bit 1040 big endian integer. 1042 SuppPrivInfo This is set to the empty octet sequence. 1044 Applications MUST specify what values should be used in the "apu" and 1045 "apv" parameters. The "apu" and "apv" values MUST be distinct. 1046 Applications wishing to conform to [NIST.800-56A] need to provide 1047 values that meet the requirements of that document, e.g., by using 1048 values that identify the sender and recipient. Alternatively, 1049 applications MAY conduct key derivation in a manner similar to The 1050 Diffie-Hellman Key Agreement Method [RFC2631]: In that case, the 1051 "apu" field MAY either be omitted or represent a random 512-bit value 1052 (analogous to PartyAInfo in Ephemeral-Static mode in [RFC2631]) and 1053 the "apv" field should not be present. 1055 See Appendix D for an example key agreement computation using this 1056 method. 1058 4.8. Key Encryption with AES GCM 1060 This section defines the specifics of encrypting a JWE Content 1061 Encryption Key (CEK) with Advanced Encryption Standard (AES) in 1062 Galois/Counter Mode (GCM) [AES] [NIST.800-38D] using 128, 192, or 256 1063 bit keys. The "alg" header parameter values "A128GCMKW", 1064 "A192GCMKW", or "A256GCMKW" are respectively used in this case. 1066 Use of an Initialization Vector of size 96 bits is REQUIRED with this 1067 algorithm. The Initialization Vector is represented in base64url 1068 encoded form as the "iv" (initialization vector) header parameter 1069 value. 1071 The Additional Authenticated Data value used is the empty octet 1072 string. 1074 The requested size of the Authentication Tag output MUST be 128 bits, 1075 regardless of the key size. 1077 The JWE Encrypted Key value is the Ciphertext output. 1079 The Authentication Tag output is represented in base64url encoded 1080 form as the "tag" (authentication tag) header parameter value. 1082 4.8.1. Header Parameters Used for AES GCM Key Encryption 1084 The following Header Parameters are used for AES GCM key encryption. 1086 4.8.1.1. "iv" (Initialization Vector) Header Parameter 1088 The "iv" (initialization vector) header parameter value is the 1089 base64url encoded representation of the Initialization Vector value 1090 used for the key encryption operation. This Header Parameter is 1091 REQUIRED and MUST be understood and processed by implementations when 1092 these algorithms are used. 1094 4.8.1.2. "tag" (Authentication Tag) Header Parameter 1096 The "tag" (authentication tag) header parameter value is the 1097 base64url encoded representation of the Authentication Tag value 1098 resulting from the key encryption operation. This Header Parameter 1099 is REQUIRED and MUST be understood and processed by implementations 1100 when these algorithms are used. 1102 4.9. Key Encryption with PBES2 1104 The "PBES2-HS256+A128KW", "PBES2-HS384+A192KW", and 1105 "PBES2-HS512+A256KW" composite algorithms are used to perform 1106 password-based encryption of a JWE CEK, by first deriving a key 1107 encryption key from a user-supplied password, then encrypting the JWE 1108 CEK using the derived key. These algorithms are PBES2 schemes as 1109 specified in Section 6.2 of [RFC2898]. 1111 These algorithms use HMAC SHA-2 algorithms as the Pseudo-Random 1112 Function (PRF) for the PBKDF2 key derivation and AES Key Wrap 1113 [RFC3394] for the encryption scheme. The salt MUST be provided as 1114 the "p2s" header parameter value, and MUST be base64url decoded to 1115 obtain the value. The iteration count parameter MUST be provided as 1116 the "p2c" header parameter value. The algorithms respectively use 1117 HMAC SHA-256, HMAC SHA-384, and HMAC SHA-512 as the PRF and use 128, 1118 192, and 256 bit AES Key Wrap keys. Their derived-key lengths 1119 respectively are 16, 24, and 32 octets. 1121 4.9.1. Header Parameters Used for PBES2 Key Encryption 1123 The following Header Parameters are used for Key Encryption with 1124 PBES2. 1126 4.9.1.1. "p2s" (PBES2 salt) Parameter 1128 The "p2s" (PBES2 salt) header parameter contains the PBKDF2 salt 1129 value, encoded using base64url. This Header Parameter is REQUIRED 1130 and MUST be understood and processed by implementations when these 1131 algorithms are used. 1133 The salt expands the possible keys that can be derived from a given 1134 password. A salt value containing 8 or more octets MUST be used. A 1135 new salt value MUST be generated randomly for every encryption 1136 operation; see [RFC4086] for considerations on generating random 1137 values. 1139 4.9.1.2. "p2c" (PBES2 count) Parameter 1141 The "p2c" (PBES2 count) header parameter contains the PBKDF2 1142 iteration count, represented as a positive integer. This Header 1143 Parameter is REQUIRED and MUST be understood and processed by 1144 implementations when these algorithms are used. 1146 The iteration count adds computational expense, ideally compounded by 1147 the possible range of keys introduced by the salt. A minimum 1148 iteration count of 1000 is RECOMMENDED. 1150 4.10. AES_CBC_HMAC_SHA2 Algorithms 1152 This section defines a family of authenticated encryption algorithms 1153 built using a composition of Advanced Encryption Standard (AES) in 1154 Cipher Block Chaining (CBC) mode with PKCS #5 padding [AES] 1155 [NIST.800-38A] operations and HMAC [RFC2104] [SHS] operations. This 1156 algorithm family is called AES_CBC_HMAC_SHA2. It also defines three 1157 instances of this family, the first using 128 bit CBC keys and HMAC 1158 SHA-256, the second using 192 bit CBC keys and HMAC SHA-384, and the 1159 third using 256 bit CBC keys and HMAC SHA-512. Test cases for these 1160 algorithms can be found in Appendix C. 1162 These algorithms are based upon Authenticated Encryption with AES-CBC 1163 and HMAC-SHA [I-D.mcgrew-aead-aes-cbc-hmac-sha2], performing the same 1164 cryptographic computations, but with the Initialization Vector and 1165 Authentication Tag values remaining separate, rather than being 1166 concatenated with the Ciphertext value in the output representation. 1167 This option is discussed in Appendix B of that specification. This 1168 algorithm family is a generalization of the algorithm family in 1169 [I-D.mcgrew-aead-aes-cbc-hmac-sha2], and can be used to implement 1170 those algorithms. 1172 4.10.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 1174 We use the following notational conventions. 1176 CBC-PKCS5-ENC(X, P) denotes the AES CBC encryption of P using PKCS 1177 #5 padding using the cipher with the key X. 1179 MAC(Y, M) denotes the application of the Message Authentication 1180 Code (MAC) to the message M, using the key Y. 1182 The concatenation of two octet strings A and B is denoted as 1183 A || B. 1185 4.10.2. Generic AES_CBC_HMAC_SHA2 Algorithm 1187 This section defines AES_CBC_HMAC_SHA2 in a manner that is 1188 independent of the AES CBC key size or hash function to be used. 1189 Section 4.10.2.1 and Section 4.10.2.2 define the generic encryption 1190 and decryption algorithms. Section 4.10.3 and Section 4.10.5 define 1191 instances of AES_CBC_HMAC_SHA2 that specify those details. 1193 4.10.2.1. AES_CBC_HMAC_SHA2 Encryption 1195 The authenticated encryption algorithm takes as input four octet 1196 strings: a secret key K, a plaintext P, associated data A, and an 1197 initialization vector IV. The authenticated ciphertext value E and 1198 the authentication tag value T are provided as outputs. The data in 1199 the plaintext are encrypted and authenticated, and the associated 1200 data are authenticated, but not encrypted. 1202 The encryption process is as follows, or uses an equivalent set of 1203 steps: 1205 1. The secondary keys MAC_KEY and ENC_KEY are generated from the 1206 input key K as follows. Each of these two keys is an octet 1207 string. 1209 MAC_KEY consists of the initial MAC_KEY_LEN octets of K, in 1210 order. 1212 ENC_KEY consists of the final ENC_KEY_LEN octets of K, in 1213 order. 1215 Here we denote the number of octets in the MAC_KEY as 1216 MAC_KEY_LEN, and the number of octets in ENC_KEY as ENC_KEY_LEN; 1217 the values of these parameters are specified by the AEAD 1218 algorithms (in Section 4.10.3 and Section 4.10.5). The number of 1219 octets in the input key K is the sum of MAC_KEY_LEN and 1220 ENC_KEY_LEN. When generating the secondary keys from K, MAC_KEY 1221 and ENC_KEY MUST NOT overlap. Note that the MAC key comes before 1222 the encryption key in the input key K; this is in the opposite 1223 order of the algorithm names in the identifier 1224 "AES_CBC_HMAC_SHA2". 1226 2. The Initialization Vector (IV) used is a 128 bit value generated 1227 randomly or pseudorandomly for use in the cipher. 1229 3. The plaintext is CBC encrypted using PKCS #5 padding using 1230 ENC_KEY as the key, and the IV. We denote the ciphertext output 1231 from this step as E. 1233 4. The octet string AL is equal to the number of bits in A expressed 1234 as a 64-bit unsigned integer in network byte order. 1236 5. A message authentication tag T is computed by applying HMAC 1237 [RFC2104] to the following data, in order: 1239 the associated data A, 1241 the initialization vector IV, 1243 the ciphertext E computed in the previous step, and 1245 the octet string AL defined above. 1247 The string MAC_KEY is used as the MAC key. We denote the output 1248 of the MAC computed in this step as M. The first T_LEN bits of M 1249 are used as T. 1251 6. The Ciphertext E and the Authentication Tag T are returned as the 1252 outputs of the authenticated encryption. 1254 The encryption process can be illustrated as follows. Here K, P, A, 1255 IV, and E denote the key, plaintext, associated data, initialization 1256 vector, and ciphertext, respectively. 1258 MAC_KEY = initial MAC_KEY_LEN bytes of K, 1259 ENC_KEY = final ENC_KEY_LEN bytes of K, 1261 E = CBC-PKCS5-ENC(ENC_KEY, P), 1263 M = MAC(MAC_KEY, A || IV || E || AL), 1265 T = initial T_LEN bytes of M. 1267 4.10.2.2. AES_CBC_HMAC_SHA2 Decryption 1269 The authenticated decryption operation has four inputs: K, A, E, and 1270 T as defined above. It has only a single output, either a plaintext 1271 value P or a special symbol FAIL that indicates that the inputs are 1272 not authentic. The authenticated decryption algorithm is as follows, 1273 or uses an equivalent set of steps: 1275 1. The secondary keys MAC_KEY and ENC_KEY are generated from the 1276 input key K as in Step 1 of Section 4.10.2.1. 1278 2. The integrity and authenticity of A and E are checked by 1279 computing an HMAC with the inputs as in Step 5 of 1280 Section 4.10.2.1. The value T, from the previous step, is 1281 compared to the first MAC_KEY length bits of the HMAC output. If 1282 those values are identical, then A and E are considered valid, 1283 and processing is continued. Otherwise, all of the data used in 1284 the MAC validation are discarded, and the AEAD decryption 1285 operation returns an indication that it failed, and the operation 1286 halts. (But see Section 10 of [JWE] for security considerations 1287 on thwarting timing attacks.) 1289 3. The value E is decrypted and the PKCS #5 padding is removed. The 1290 value IV is used as the initialization vector. The value ENC_KEY 1291 is used as the decryption key. 1293 4. The plaintext value is returned. 1295 4.10.3. AES_128_CBC_HMAC_SHA_256 1297 This algorithm is a concrete instantiation of the generic 1298 AES_CBC_HMAC_SHA2 algorithm above. It uses the HMAC message 1299 authentication code [RFC2104] with the SHA-256 hash function [SHS] to 1300 provide message authentication, with the HMAC output truncated to 128 1301 bits, corresponding to the HMAC-SHA-256-128 algorithm defined in 1302 [RFC4868]. For encryption, it uses AES in the Cipher Block Chaining 1303 (CBC) mode of operation as defined in Section 6.2 of [NIST.800-38A], 1304 with PKCS #5 padding. 1306 The input key K is 32 octets long. 1308 The AES CBC IV is 16 octets long. ENC_KEY_LEN is 16 octets. 1310 The SHA-256 hash algorithm is used in HMAC. MAC_KEY_LEN is 16 1311 octets. The HMAC-SHA-256 output is truncated to T_LEN=16 octets, by 1312 stripping off the final 16 octets. 1314 4.10.4. AES_192_CBC_HMAC_SHA_384 1316 AES_192_CBC_HMAC_SHA_384 is based on AES_128_CBC_HMAC_SHA_256, but 1317 with the following differences: 1319 A 192 bit AES CBC key is used instead of 128. 1321 SHA-384 is used in HMAC instead of SHA-256. 1323 ENC_KEY_LEN is 24 octets instead of 16. 1325 MAC_KEY_LEN is 24 octets instead of 16. 1327 The length of the input key K is 48 octets instead of 32. 1329 The HMAC SHA-384 value is truncated to T_LEN=24 octets instead of 1330 16. 1332 4.10.5. AES_256_CBC_HMAC_SHA_512 1334 AES_256_CBC_HMAC_SHA_512 is based on AES_128_CBC_HMAC_SHA_256, but 1335 with the following differences: 1337 A 256 bit AES CBC key is used instead of 128. 1339 SHA-512 is used in HMAC instead of SHA-256. 1341 ENC_KEY_LEN is 32 octets instead of 16. 1343 MAC_KEY_LEN is 32 octets instead of 16. 1345 The length of the input key K is 64 octets instead of 32. 1347 The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of 1348 16. 1350 4.10.6. Plaintext Encryption with AES_CBC_HMAC_SHA2 1352 The algorithm value "A128CBC-HS256" is used as the "alg" value when 1353 using AES_128_CBC_HMAC_SHA_256 with JWE. The algorithm value 1354 "A192CBC-HS384" is used as the "alg" value when using 1355 AES_192_CBC_HMAC_SHA_384 with JWE. The algorithm value 1356 "A256CBC-HS512" is used as the "alg" value when using 1357 AES_256_CBC_HMAC_SHA_512 with JWE. The Additional Authenticated Data 1358 value used is the octets of the ASCII representation of the Encoded 1359 JWE Header value. The JWE Initialization Vector value used is the IV 1360 value. 1362 4.11. Plaintext Encryption with AES GCM 1364 This section defines the specifics of encrypting the JWE Plaintext 1365 with Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) 1366 [AES] [NIST.800-38D] using 128, 192, or 256 bit keys. The "enc" 1367 header parameter values "A128GCM", "A192GCM", or "A256GCM" are 1368 respectively used in this case. 1370 The CEK is used as the encryption key. 1372 Use of an initialization vector of size 96 bits is REQUIRED with this 1373 algorithm. 1375 The Additional Authenticated Data value used is the octets of the 1376 ASCII representation of the Encoded JWE Header value. 1378 The requested size of the Authentication Tag output MUST be 128 bits, 1379 regardless of the key size. 1381 The JWE Authentication Tag is set to be the Authentication Tag value 1382 produced by the encryption. During decryption, the received JWE 1383 Authentication Tag is used as the Authentication Tag value. 1385 An example using this algorithm is shown in Appendix A.1 of [JWE]. 1387 5. Cryptographic Algorithms for Keys 1389 A JSON Web Key (JWK) [JWK] is a JSON data structure that represents a 1390 cryptographic key. These keys can be either asymmetric or symmetric. 1391 They can hold both public and private information about the key. 1392 This section defines the parameters for keys using the algorithms 1393 specified by this document. 1395 5.1. "kty" (Key Type) Parameter Values 1397 The table below is the set of "kty" (key type) parameter values that 1398 are defined by this specification for use in JWKs. 1400 +--------------+--------------------------------+-------------------+ 1401 | kty | Key Type | Implementation | 1402 | Parameter | | Requirements | 1403 | Value | | | 1404 +--------------+--------------------------------+-------------------+ 1405 | EC | Elliptic Curve [DSS] | Recommended+ | 1406 | RSA | RSA [RFC3447] | Required | 1407 | oct | Octet sequence (used to | Required | 1408 | | represent symmetric keys) | | 1409 +--------------+--------------------------------+-------------------+ 1411 The use of "+" in the Implementation Requirements indicates that the 1412 requirement strength is likely to be increased in a future version of 1413 the specification. 1415 5.2. Parameters for Elliptic Curve Keys 1417 JWKs can represent Elliptic Curve [DSS] keys. In this case, the 1418 "kty" member value MUST be "EC". 1420 5.2.1. Parameters for Elliptic Curve Public Keys 1422 An elliptic curve public key is represented by a pair of coordinates 1423 drawn from a finite field, which together define a point on an 1424 elliptic curve. The following members MUST be present for elliptic 1425 curve public keys: 1427 o "crv" 1429 o "x" 1431 o "y" 1433 5.2.1.1. "crv" (Curve) Parameter 1435 The "crv" (curve) member identifies the cryptographic curve used with 1436 the key. Curve values from [DSS] used by this specification are: 1438 o "P-256" 1440 o "P-384" 1442 o "P-521" 1444 These values are registered in the IANA JSON Web Key Elliptic Curve 1445 registry defined in Section 6.6. Additional "crv" values MAY be 1446 used, provided they are understood by implementations using that 1447 Elliptic Curve key. The "crv" value is a case sensitive string. 1449 5.2.1.2. "x" (X Coordinate) Parameter 1451 The "x" (x coordinate) member contains the x coordinate for the 1452 elliptic curve point. It is represented as the base64url encoding of 1453 the octet string representation of the coordinate, as defined in 1454 Section 2.3.5 of SEC1 [SEC1]. The length of this octet string MUST 1455 be the full size of a coordinate for the curve specified in the "crv" 1456 parameter. For example, if the value of "crv" is "P-521", the octet 1457 string must be 66 octets long. 1459 5.2.1.3. "y" (Y Coordinate) Parameter 1461 The "y" (y coordinate) member contains the y coordinate for the 1462 elliptic curve point. It is represented as the base64url encoding of 1463 the octet string representation of the coordinate, as defined in 1464 Section 2.3.5 of SEC1 [SEC1]. The length of this octet string MUST 1465 be the full size of a coordinate for the curve specified in the "crv" 1466 parameter. For example, if the value of "crv" is "P-521", the octet 1467 string must be 66 octets long. 1469 5.2.2. Parameters for Elliptic Curve Private Keys 1471 In addition to the members used to represent Elliptic Curve public 1472 keys, the following member MUST be present to represent Elliptic 1473 Curve private keys. 1475 5.2.2.1. "d" (ECC Private Key) Parameter 1477 The "d" (ECC private key) member contains the Elliptic Curve private 1478 key value. It is represented as the base64url encoding of the octet 1479 string representation of the private key value, as defined in 1480 Sections C.4 and 2.3.7 of SEC1 [SEC1]. The length of this octet 1481 string MUST be ceiling(log-base-2(n)/8) octets (where n is the order 1482 of the curve). 1484 5.3. Parameters for RSA Keys 1486 JWKs can represent RSA [RFC3447] keys. In this case, the "kty" 1487 member value MUST be "RSA". 1489 5.3.1. Parameters for RSA Public Keys 1491 The following members MUST be present for RSA public keys. 1493 5.3.1.1. "n" (Modulus) Parameter 1495 The "n" (modulus) member contains the modulus value for the RSA 1496 public key. It is represented as the base64url encoding of the 1497 value's unsigned big endian representation as an octet sequence. The 1498 octet sequence MUST utilize the minimum number of octets to represent 1499 the value. 1501 5.3.1.2. "e" (Exponent) Parameter 1503 The "e" (exponent) member contains the exponent value for the RSA 1504 public key. It is represented as the base64url encoding of the 1505 value's unsigned big endian representation as an octet sequence. The 1506 octet sequence MUST utilize the minimum number of octets to represent 1507 the value. For instance, when representing the value 65537, the 1508 octet sequence to be base64url encoded MUST consist of the three 1509 octets [1, 0, 1]. 1511 5.3.2. Parameters for RSA Private Keys 1513 In addition to the members used to represent RSA public keys, the 1514 following members are used to represent RSA private keys. The 1515 parameter "d" is REQUIRED for RSA private keys. The others enable 1516 optimizations and SHOULD be included by producers of JWKs 1517 representing RSA private keys. If the producer includes any of the 1518 other private key parameters, then all of the others MUST be present, 1519 with the exception of "oth", which MUST only be present when more 1520 than two prime factors were used. The consumer of a JWK MAY choose 1521 to accept an RSA private key that does not contain a complete set of 1522 the private key parameters other than "d", including JWKs in which 1523 "d" is the only RSA private key parameter included. 1525 5.3.2.1. "d" (Private Exponent) Parameter 1527 The "d" (private exponent) member contains the private exponent value 1528 for the RSA private key. It is represented as the base64url encoding 1529 of the value's unsigned big endian representation as an octet 1530 sequence. The octet sequence MUST utilize the minimum number of 1531 octets to represent the value. 1533 5.3.2.2. "p" (First Prime Factor) Parameter 1535 The "p" (first prime factor) member contains the first prime factor, 1536 a positive integer. It is represented as the base64url encoding of 1537 the value's unsigned big endian representation as an octet sequence. 1538 The octet sequence MUST utilize the minimum number of octets to 1539 represent the value. 1541 5.3.2.3. "q" (Second Prime Factor) Parameter 1543 The "q" (second prime factor) member contains the second prime 1544 factor, a positive integer. It is represented as the base64url 1545 encoding of the value's unsigned big endian representation as an 1546 octet sequence. The octet sequence MUST utilize the minimum number 1547 of octets to represent the value. 1549 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter 1551 The "dp" (first factor CRT exponent) member contains the Chinese 1552 Remainder Theorem (CRT) exponent of the first factor, a positive 1553 integer. It is represented as the base64url encoding of the value's 1554 unsigned big endian representation as an octet sequence. The octet 1555 sequence MUST utilize the minimum number of octets to represent the 1556 value. 1558 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter 1560 The "dq" (second factor CRT exponent) member contains the Chinese 1561 Remainder Theorem (CRT) exponent of the second factor, a positive 1562 integer. It is represented as the base64url encoding of the value's 1563 unsigned big endian representation as an octet sequence. The octet 1564 sequence MUST utilize the minimum number of octets to represent the 1565 value. 1567 5.3.2.6. "qi" (First CRT Coefficient) Parameter 1569 The "dp" (first CRT coefficient) member contains the Chinese 1570 Remainder Theorem (CRT) coefficient of the second factor, a positive 1571 integer. It is represented as the base64url encoding of the value's 1572 unsigned big endian representation as an octet sequence. The octet 1573 sequence MUST utilize the minimum number of octets to represent the 1574 value. 1576 5.3.2.7. "oth" (Other Primes Info) Parameter 1578 The "oth" (other primes info) member contains an array of information 1579 about any third and subsequent primes, should they exist. When only 1580 two primes have been used (the normal case), this parameter MUST be 1581 omitted. When three or more primes have been used, the number of 1582 array elements MUST be the number of primes used minus two. Each 1583 array element MUST be an object with the following members: 1585 5.3.2.7.1. "r" (Prime Factor) 1587 The "r" (prime factor) parameter within an "oth" array member 1588 represents the value of a subsequent prime factor, a positive 1589 integer. It is represented as the base64url encoding of the value's 1590 unsigned big endian representation as an octet sequence. The octet 1591 sequence MUST utilize the minimum number of octets to represent the 1592 value. 1594 5.3.2.7.2. "d" (Factor CRT Exponent) 1596 The "d" (Factor CRT Exponent) parameter within an "oth" array member 1597 represents the CRT exponent of the corresponding prime factor, a 1598 positive integer. It is represented as the base64url encoding of the 1599 value's unsigned big endian representation as an octet sequence. The 1600 octet sequence MUST utilize the minimum number of octets to represent 1601 the value. 1603 5.3.2.7.3. "t" (Factor CRT Coefficient) 1605 The "t" (factor CRT coefficient) parameter within an "oth" array 1606 member represents the CRT coefficient of the corresponding prime 1607 factor, a positive integer. It is represented as the base64url 1608 encoding of the value's unsigned big endian representation as an 1609 octet sequence. The octet sequence MUST utilize the minimum number 1610 of octets to represent the value. 1612 5.4. Parameters for Symmetric Keys 1614 When the JWK "kty" member value is "oct" (octet sequence), the member 1615 "k" is used to represent a symmetric key (or another key whose value 1616 is a single octet sequence). An "alg" member SHOULD also be present 1617 to identify the algorithm intended to be used with the key, unless 1618 the application uses another means or convention to determine the 1619 algorithm used. 1621 5.4.1. "k" (Key Value) Parameter 1623 The "k" (key value) member contains the value of the symmetric (or 1624 other single-valued) key. It is represented as the base64url 1625 encoding of the octet sequence containing the key value. 1627 6. IANA Considerations 1629 The following registration procedure is used for all the registries 1630 established by this specification. 1632 Values are registered with a Specification Required [RFC5226] after a 1633 two-week review period on the [TBD]@ietf.org mailing list, on the 1634 advice of one or more Designated Experts. However, to allow for the 1635 allocation of values prior to publication, the Designated Expert(s) 1636 may approve registration once they are satisfied that such a 1637 specification will be published. 1639 Registration requests must be sent to the [TBD]@ietf.org mailing list 1640 for review and comment, with an appropriate subject (e.g., "Request 1641 for access token type: example"). [[ Note to the RFC Editor: The name 1642 of the mailing list should be determined in consultation with the 1643 IESG and IANA. Suggested name: jose-reg-review. ]] 1645 Within the review period, the Designated Expert(s) will either 1646 approve or deny the registration request, communicating this decision 1647 to the review list and IANA. Denials should include an explanation 1648 and, if applicable, suggestions as to how to make the request 1649 successful. Registration requests that are undetermined for a period 1650 longer than 21 days can be brought to the IESG's attention (using the 1651 iesg@iesg.org mailing list) for resolution. 1653 Criteria that should be applied by the Designated Expert(s) includes 1654 determining whether the proposed registration duplicates existing 1655 functionality, determining whether it is likely to be of general 1656 applicability or whether it is useful only for a single application, 1657 and whether the registration makes sense. 1659 IANA must only accept registry updates from the Designated Expert(s) 1660 and should direct all requests for registration to the review mailing 1661 list. 1663 It is suggested that multiple Designated Experts be appointed who are 1664 able to represent the perspectives of different applications using 1665 this specification, in order to enable broadly-informed review of 1666 registration decisions. In cases where a registration decision could 1667 be perceived as creating a conflict of interest for a particular 1668 Expert, that Expert should defer to the judgment of the other 1669 Expert(s). 1671 6.1. JSON Web Signature and Encryption Algorithms Registry 1673 This specification establishes the IANA JSON Web Signature and 1674 Encryption Algorithms registry for values of the JWS and JWE "alg" 1675 (algorithm) and "enc" (encryption method) header parameters. The 1676 registry records the algorithm name, the algorithm usage locations 1677 from the set "alg" and "enc", implementation requirements, and a 1678 reference to the specification that defines it. The same algorithm 1679 name MAY be registered multiple times, provided that the sets of 1680 usage locations are disjoint. 1682 It is suggested that when algorithms can use keys of different 1683 lengths, that the length of the key be included in the algorithm 1684 name. This allows readers of the JSON text to easily make security 1685 consideration decisions. 1687 The implementation requirements of an algorithm MAY be changed over 1688 time by the Designated Experts(s) as the cryptographic landscape 1689 evolves, for instance, to change the status of an algorithm to 1690 Deprecated, or to change the status of an algorithm from Optional to 1691 Recommended+ or Required. Changes of implementation requirements are 1692 only permitted on a Specification Required basis, with the new 1693 specification defining the revised implementation requirements level. 1695 6.1.1. Template 1697 Algorithm Name: 1698 The name requested (e.g., "example"). This name is case 1699 sensitive. Names may not match other registered names in a case 1700 insensitive manner unless the Designated Expert(s) state that 1701 there is a compelling reason to allow an exception in this 1702 particular case. 1704 Algorithm Usage Location(s): 1705 The algorithm usage, which must be one or more of the values "alg" 1706 or "enc". 1708 Implementation Requirements: 1709 The algorithm implementation requirements, which must be one the 1710 words Required, Recommended, Optional, or Deprecated. Optionally, 1711 the word can be followed by a "+" or "-". The use of "+" 1712 indicates that the requirement strength is likely to be increased 1713 in a future version of the specification. The use of "-" 1714 indicates that the requirement strength is likely to be decreased 1715 in a future version of the specification. 1717 Change Controller: 1718 For Standards Track RFCs, state "IESG". For others, give the name 1719 of the responsible party. Other details (e.g., postal address, 1720 email address, home page URI) may also be included. 1722 Specification Document(s): 1723 Reference to the document(s) that specify the parameter, 1724 preferably including URI(s) that can be used to retrieve copies of 1725 the document(s). An indication of the relevant sections may also 1726 be included but is not required. 1728 6.1.2. Initial Registry Contents 1730 o Algorithm Name: "HS256" 1731 o Algorithm Usage Location(s): "alg" 1732 o Implementation Requirements: Required 1733 o Change Controller: IESG 1734 o Specification Document(s): Section 3.1 of [[ this document ]] 1735 o Algorithm Name: "HS384" 1736 o Algorithm Usage Location(s): "alg" 1737 o Implementation Requirements: Optional 1738 o Change Controller: IESG 1739 o Specification Document(s): Section 3.1 of [[ this document ]] 1741 o Algorithm Name: "HS512" 1742 o Algorithm Usage Location(s): "alg" 1743 o Implementation Requirements: Optional 1744 o Change Controller: IESG 1745 o Specification Document(s): Section 3.1 of [[ this document ]] 1747 o Algorithm Name: "RS256" 1748 o Algorithm Usage Location(s): "alg" 1749 o Implementation Requirements: Recommended 1750 o Change Controller: IESG 1751 o Specification Document(s): Section 3.1 of [[ this document ]] 1753 o Algorithm Name: "RS384" 1754 o Algorithm Usage Location(s): "alg" 1755 o Implementation Requirements: Optional 1756 o Change Controller: IESG 1757 o Specification Document(s): Section 3.1 of [[ this document ]] 1759 o Algorithm Name: "RS512" 1760 o Algorithm Usage Location(s): "alg" 1761 o Implementation Requirements: Optional 1762 o Change Controller: IESG 1763 o Specification Document(s): Section 3.1 of [[ this document ]] 1765 o Algorithm Name: "ES256" 1766 o Algorithm Usage Location(s): "alg" 1767 o Implementation Requirements: Recommended+ 1768 o Change Controller: IESG 1769 o Specification Document(s): Section 3.1 of [[ this document ]] 1771 o Algorithm Name: "ES384" 1772 o Algorithm Usage Location(s): "alg" 1773 o Implementation Requirements: Optional 1774 o Change Controller: IESG 1775 o Specification Document(s): Section 3.1 of [[ this document ]] 1777 o Algorithm Name: "ES512" 1778 o Algorithm Usage Location(s): "alg" 1779 o Implementation Requirements: Optional 1780 o Change Controller: IESG 1781 o Specification Document(s): Section 3.1 of [[ this document ]] 1783 o Algorithm Name: "PS256" 1784 o Algorithm Usage Location(s): "alg" 1785 o Implementation Requirements: Optional 1786 o Change Controller: IESG 1787 o Specification Document(s): Section 3.1 of [[ this document ]] 1789 o Algorithm Name: "PS384" 1790 o Algorithm Usage Location(s): "alg" 1791 o Implementation Requirements: Optional 1792 o Change Controller: IESG 1793 o Specification Document(s): Section 3.1 of [[ this document ]] 1795 o Algorithm Name: "PS512" 1796 o Algorithm Usage Location(s): "alg" 1797 o Implementation Requirements: Optional 1798 o Change Controller: IESG 1799 o Specification Document(s): Section 3.1 of [[ this document ]] 1801 o Algorithm Name: "none" 1802 o Algorithm Usage Location(s): "alg" 1803 o Implementation Requirements: Optional 1804 o Change Controller: IESG 1805 o Specification Document(s): Section 3.1 of [[ this document ]] 1807 o Algorithm Name: "RSA1_5" 1808 o Algorithm Usage Location(s): "alg" 1809 o Implementation Requirements: Required 1810 o Change Controller: IESG 1811 o Specification Document(s): Section 4.1 of [[ this document ]] 1813 o Algorithm Name: "RSA-OAEP" 1814 o Algorithm Usage Location(s): "alg" 1815 o Implementation Requirements: Optional 1816 o Change Controller: IESG 1817 o Specification Document(s): Section 4.1 of [[ this document ]] 1819 o Algorithm Name: "A128KW" 1820 o Algorithm Usage Location(s): "alg" 1821 o Implementation Requirements: Recommended 1822 o Change Controller: IESG 1823 o Specification Document(s): Section 4.1 of [[ this document ]] 1825 o Algorithm Name: "A192KW" 1826 o Algorithm Usage Location(s): "alg" 1827 o Implementation Requirements: Optional 1828 o Change Controller: IESG 1829 o Specification Document(s): Section 4.1 of [[ this document ]] 1831 o Algorithm Name: "A256KW" 1832 o Algorithm Usage Location(s): "alg" 1833 o Implementation Requirements: Recommended 1834 o Change Controller: IESG 1835 o Specification Document(s): Section 4.1 of [[ this document ]] 1837 o Algorithm Name: "dir" 1838 o Algorithm Usage Location(s): "alg" 1839 o Implementation Requirements: Recommended 1840 o Change Controller: IESG 1841 o Specification Document(s): Section 4.1 of [[ this document ]] 1843 o Algorithm Name: "ECDH-ES" 1844 o Algorithm Usage Location(s): "alg" 1845 o Implementation Requirements: Recommended+ 1846 o Change Controller: IESG 1847 o Specification Document(s): Section 4.1 of [[ this document ]] 1849 o Algorithm Name: "ECDH-ES+A128KW" 1850 o Algorithm Usage Location(s): "alg" 1851 o Implementation Requirements: Recommended 1852 o Change Controller: IESG 1853 o Specification Document(s): Section 4.1 of [[ this document ]] 1855 o Algorithm Name: "ECDH-ES+A192KW" 1856 o Algorithm Usage Location(s): "alg" 1857 o Implementation Requirements: Optional 1858 o Change Controller: IESG 1859 o Specification Document(s): Section 4.1 of [[ this document ]] 1861 o Algorithm Name: "ECDH-ES+A256KW" 1862 o Algorithm Usage Location(s): "alg" 1863 o Implementation Requirements: Recommended 1864 o Change Controller: IESG 1865 o Specification Document(s): Section 4.1 of [[ this document ]] 1867 o Algorithm Name: "A128GCMKW" 1868 o Algorithm Usage Location(s): "alg" 1869 o Implementation Requirements: Optional 1870 o Change Controller: IESG 1871 o Specification Document(s): Section 4.8 of [[ this document ]] 1872 o Algorithm Name: "A192GCMKW" 1873 o Algorithm Usage Location(s): "alg" 1874 o Implementation Requirements: Optional 1875 o Change Controller: IESG 1876 o Specification Document(s): Section 4.8 of [[ this document ]] 1878 o Algorithm Name: "A256GCMKW" 1879 o Algorithm Usage Location(s): "alg" 1880 o Implementation Requirements: Optional 1881 o Change Controller: IESG 1882 o Specification Document(s): Section 4.8 of [[ this document ]] 1884 o Algorithm Name: "PBES2-HS256+A128KW" 1885 o Algorithm Usage Location(s): "alg" 1886 o Implementation Requirements: Optional 1887 o Change Controller: IESG 1888 o Specification Document(s): Section 4.9 of [[ this document ]] 1890 o Algorithm Name: "PBES2-HS384+A192KW" 1891 o Algorithm Usage Location(s): "alg" 1892 o Implementation Requirements: Optional 1893 o Change Controller: IESG 1894 o Specification Document(s): Section 4.9 of [[ this document ]] 1896 o Algorithm Name: "PBES2-HS512+A256KW" 1897 o Algorithm Usage Location(s): "alg" 1898 o Implementation Requirements: Optional 1899 o Change Controller: IESG 1900 o Specification Document(s): Section 4.9 of [[ this document ]] 1902 o Algorithm Name: "A128CBC-HS256" 1903 o Algorithm Usage Location(s): "enc" 1904 o Implementation Requirements: Required 1905 o Change Controller: IESG 1906 o Specification Document(s): Section 4.2 of [[ this document ]] 1908 o Algorithm Name: "A192CBC-HS384" 1909 o Algorithm Usage Location(s): "enc" 1910 o Implementation Requirements: Optional 1911 o Change Controller: IESG 1912 o Specification Document(s): Section 4.2 of [[ this document ]] 1914 o Algorithm Name: "A256CBC-HS512" 1915 o Algorithm Usage Location(s): "enc" 1916 o Implementation Requirements: Required 1917 o Change Controller: IESG 1918 o Specification Document(s): Section 4.2 of [[ this document ]] 1920 o Algorithm Name: "A128GCM" 1921 o Algorithm Usage Location(s): "enc" 1922 o Implementation Requirements: Recommended 1923 o Change Controller: IESG 1924 o Specification Document(s): Section 4.2 of [[ this document ]] 1926 o Algorithm Name: "A192GCM" 1927 o Algorithm Usage Location(s): "enc" 1928 o Implementation Requirements: Optional 1929 o Change Controller: IESG 1930 o Specification Document(s): Section 4.2 of [[ this document ]] 1932 o Algorithm Name: "A256GCM" 1933 o Algorithm Usage Location(s): "enc" 1934 o Implementation Requirements: Recommended 1935 o Change Controller: IESG 1936 o Specification Document(s): Section 4.2 of [[ this document ]] 1938 6.2. JWE Header Parameter Names Registration 1940 This specification registers the Header Parameter Names defined in 1941 Section 4.7.1, Section 4.8.1, and Section 4.9.1 in the IANA JSON Web 1942 Signature and Encryption Header Parameters registry defined in [JWS]. 1944 6.2.1. Registry Contents 1946 o Header Parameter Name: "epk" 1947 o Header Parameter Usage Location(s): JWE 1948 o Change Controller: IESG 1949 o Specification Document(s): Section 4.7.1.1 of [[ this document ]] 1951 o Header Parameter Name: "apu" 1952 o Header Parameter Usage Location(s): JWE 1953 o Change Controller: IESG 1954 o Specification Document(s): Section 4.7.1.2 of [[ this document ]] 1956 o Header Parameter Name: "apv" 1957 o Header Parameter Usage Location(s): JWE 1958 o Change Controller: IESG 1959 o Specification Document(s): Section 4.7.1.3 of [[ this document ]] 1961 o Header Parameter Name: "iv" 1962 o Header Parameter Usage Location(s): JWE 1963 o Change Controller: IESG 1964 o Specification Document(s): Section 4.8.1.1 of [[ this document ]] 1966 o Header Parameter Name: "tag" 1967 o Header Parameter Usage Location(s): JWE 1968 o Change Controller: IESG 1969 o Specification Document(s): Section 4.8.1.2 of [[ this document ]] 1971 o Header Parameter Name: "p2s" 1972 o Header Parameter Usage Location(s): JWE 1973 o Change Controller: IESG 1974 o Specification Document(s): Section 4.9.1.1 of [[ this document ]] 1976 o Header Parameter Name: "p2c" 1977 o Header Parameter Usage Location(s): JWE 1978 o Change Controller: IESG 1979 o Specification Document(s): Section 4.9.1.2 of [[ this document ]] 1981 6.3. JSON Web Encryption Compression Algorithms Registry 1983 This specification establishes the IANA JSON Web Encryption 1984 Compression Algorithms registry for JWE "zip" member values. The 1985 registry records the compression algorithm value and a reference to 1986 the specification that defines it. 1988 6.3.1. Registration Template 1990 Compression Algorithm Value: 1991 The name requested (e.g., "example"). Because a core goal of this 1992 specification is for the resulting representations to be compact, 1993 it is RECOMMENDED that the name be short -- not to exceed 8 1994 characters without a compelling reason to do so. This name is 1995 case sensitive. Names may not match other registered names in a 1996 case insensitive manner unless the Designated Expert(s) state that 1997 there is a compelling reason to allow an exception in this 1998 particular case. 2000 Change Controller: 2001 For Standards Track RFCs, state "IESG". For others, give the name 2002 of the responsible party. Other details (e.g., postal address, 2003 email address, home page URI) may also be included. 2005 Specification Document(s): 2006 Reference to the document(s) that specify the parameter, 2007 preferably including URI(s) that can be used to retrieve copies of 2008 the document(s). An indication of the relevant sections may also 2009 be included but is not required. 2011 6.3.2. Initial Registry Contents 2013 o Compression Algorithm Value: "DEF" 2014 o Change Controller: IESG 2015 o Specification Document(s): JSON Web Encryption (JWE) [JWE] 2017 6.4. JSON Web Key Types Registry 2019 This specification establishes the IANA JSON Web Key Types registry 2020 for values of the JWK "kty" (key type) parameter. The registry 2021 records the "kty" value, implementation requirements, and a reference 2022 to the specification that defines it. 2024 The implementation requirements of a key type MAY be changed over 2025 time by the Designated Experts(s) as the cryptographic landscape 2026 evolves, for instance, to change the status of a key type to 2027 Deprecated, or to change the status of a key type from Optional to 2028 Recommended+ or Required. Changes of implementation requirements are 2029 only permitted on a Specification Required basis, with the new 2030 specification defining the revised implementation requirements level. 2032 6.4.1. Registration Template 2034 "kty" Parameter Value: 2035 The name requested (e.g., "example"). Because a core goal of this 2036 specification is for the resulting representations to be compact, 2037 it is RECOMMENDED that the name be short -- not to exceed 8 2038 characters without a compelling reason to do so. This name is 2039 case sensitive. Names may not match other registered names in a 2040 case insensitive manner unless the Designated Expert(s) state that 2041 there is a compelling reason to allow an exception in this 2042 particular case. 2044 Change Controller: 2045 For Standards Track RFCs, state "IESG". For others, give the name 2046 of the responsible party. Other details (e.g., postal address, 2047 email address, home page URI) may also be included. 2049 Implementation Requirements: 2050 The key type implementation requirements, which must be one the 2051 words Required, Recommended, Optional, or Deprecated. Optionally, 2052 the word can be followed by a "+" or "-". The use of "+" 2053 indicates that the requirement strength is likely to be increased 2054 in a future version of the specification. The use of "-" 2055 indicates that the requirement strength is likely to be decreased 2056 in a future version of the specification. 2058 Specification Document(s): 2059 Reference to the document(s) that specify the parameter, 2060 preferably including URI(s) that can be used to retrieve copies of 2061 the document(s). An indication of the relevant sections may also 2062 be included but is not required. 2064 6.4.2. Initial Registry Contents 2066 This specification registers the values defined in Section 5.1. 2068 o "kty" Parameter Value: "EC" 2069 o Implementation Requirements: Recommended+ 2070 o Change Controller: IESG 2071 o Specification Document(s): Section 5.2 of [[ this document ]] 2073 o "kty" Parameter Value: "RSA" 2074 o Implementation Requirements: Required 2075 o Change Controller: IESG 2076 o Specification Document(s): Section 5.3 of [[ this document ]] 2078 o "kty" Parameter Value: "oct" 2079 o Implementation Requirements: Required 2080 o Change Controller: IESG 2081 o Specification Document(s): Section 5.4 of [[ this document ]] 2083 6.5. JSON Web Key Parameters Registration 2085 This specification registers the parameter names defined in Sections 2086 5.2, 5.3, and 5.4 in the IANA JSON Web Key Parameters registry 2087 defined in [JWK]. 2089 6.5.1. Registry Contents 2091 o Parameter Name: "crv" 2092 o Used with "kty" Value(s): "EC" 2093 o Parameter Information Class: Public 2094 o Change Controller: IESG 2095 o Specification Document(s): Section 5.2.1.1 of [[ this document ]] 2097 o Parameter Name: "x" 2098 o Used with "kty" Value(s): "EC" 2099 o Parameter Information Class: Public 2100 o Change Controller: IESG 2101 o Specification Document(s): Section 5.2.1.2 of [[ this document ]] 2103 o Parameter Name: "y" 2104 o Used with "kty" Value(s): "EC" 2105 o Parameter Information Class: Public 2106 o Change Controller: IESG 2107 o Specification Document(s): Section 5.2.1.3 of [[ this document ]] 2109 o Parameter Name: "d" 2110 o Used with "kty" Value(s): "EC" 2111 o Parameter Information Class: Private 2112 o Change Controller: IESG 2113 o Specification Document(s): Section 5.2.2.1 of [[ this document ]] 2115 o Parameter Name: "n" 2116 o Used with "kty" Value(s): "RSA" 2117 o Parameter Information Class: Public 2118 o Change Controller: IESG 2119 o Specification Document(s): Section 5.3.1.1 of [[ this document ]] 2121 o Parameter Name: "e" 2122 o Used with "kty" Value(s): "RSA" 2123 o Parameter Information Class: Public 2124 o Change Controller: IESG 2125 o Specification Document(s): Section 5.3.1.2 of [[ this document ]] 2127 o Parameter Name: "d" 2128 o Used with "kty" Value(s): "RSA" 2129 o Parameter Information Class: Private 2130 o Change Controller: IESG 2131 o Specification Document(s): Section 5.3.2.1 of [[ this document ]] 2133 o Parameter Name: "p" 2134 o Used with "kty" Value(s): "RSA" 2135 o Parameter Information Class: Private 2136 o Change Controller: IESG 2137 o Specification Document(s): Section 5.3.2.2 of [[ this document ]] 2139 o Parameter Name: "q" 2140 o Used with "kty" Value(s): "RSA" 2141 o Parameter Information Class: Private 2142 o Change Controller: IESG 2143 o Specification Document(s): Section 5.3.2.3 of [[ this document ]] 2145 o Parameter Name: "dp" 2146 o Used with "kty" Value(s): "RSA" 2147 o Parameter Information Class: Private 2148 o Change Controller: IESG 2149 o Specification Document(s): Section 5.3.2.4 of [[ this document ]] 2150 o Parameter Name: "dq" 2151 o Used with "kty" Value(s): "RSA" 2152 o Parameter Information Class: Private 2153 o Change Controller: IESG 2154 o Specification Document(s): Section 5.3.2.5 of [[ this document ]] 2156 o Parameter Name: "qi" 2157 o Used with "kty" Value(s): "RSA" 2158 o Parameter Information Class: Private 2159 o Change Controller: IESG 2160 o Specification Document(s): Section 5.3.2.6 of [[ this document ]] 2162 o Parameter Name: "oth" 2163 o Used with "kty" Value(s): "RSA" 2164 o Parameter Information Class: Private 2165 o Change Controller: IESG 2166 o Specification Document(s): Section 5.3.2.7 of [[ this document ]] 2168 o Parameter Name: "k" 2169 o Used with "kty" Value(s): "oct" 2170 o Parameter Information Class: Private 2171 o Change Controller: IESG 2172 o Specification Document(s): Section 5.4.1 of [[ this document ]] 2174 6.6. JSON Web Key Elliptic Curve Registry 2176 This specification establishes the IANA JSON Web Key Elliptic Curve 2177 registry for JWK "crv" member values. The registry records the curve 2178 name, implementation requirements, and a reference to the 2179 specification that defines it. This specification registers the 2180 parameter names defined in Section 5.2.1.1. 2182 The implementation requirements of a curve MAY be changed over time 2183 by the Designated Experts(s) as the cryptographic landscape evolves, 2184 for instance, to change the status of a curve to Deprecated, or to 2185 change the status of a curve from Optional to Recommended+ or 2186 Required. Changes of implementation requirements are only permitted 2187 on a Specification Required basis, with the new specification 2188 defining the revised implementation requirements level. 2190 6.6.1. Registration Template 2192 Curve Name: 2193 The name requested (e.g., "example"). Because a core goal of this 2194 specification is for the resulting representations to be compact, 2195 it is RECOMMENDED that the name be short -- not to exceed 8 2196 characters without a compelling reason to do so. This name is 2197 case sensitive. Names may not match other registered names in a 2198 case insensitive manner unless the Designated Expert(s) state that 2199 there is a compelling reason to allow an exception in this 2200 particular case. 2202 Implementation Requirements: 2203 The curve implementation requirements, which must be one the words 2204 Required, Recommended, Optional, or Deprecated. Optionally, the 2205 word can be followed by a "+" or "-". The use of "+" indicates 2206 that the requirement strength is likely to be increased in a 2207 future version of the specification. The use of "-" indicates 2208 that the requirement strength is likely to be decreased in a 2209 future version of the specification. 2211 Change Controller: 2212 For Standards Track RFCs, state "IESG". For others, give the name 2213 of the responsible party. Other details (e.g., postal address, 2214 email address, home page URI) may also be included. 2216 Specification Document(s): 2217 Reference to the document(s) that specify the parameter, 2218 preferably including URI(s) that can be used to retrieve copies of 2219 the document(s). An indication of the relevant sections may also 2220 be included but is not required. 2222 6.6.2. Initial Registry Contents 2224 o Curve Name: "P-256" 2225 o Implementation Requirements: Recommended+ 2226 o Change Controller: IESG 2227 o Specification Document(s): Section 5.2.1.1 of [[ this document ]] 2229 o Curve Name: "P-384" 2230 o Implementation Requirements: Optional 2231 o Change Controller: IESG 2232 o Specification Document(s): Section 5.2.1.1 of [[ this document ]] 2234 o Curve Name: "P-521" 2235 o Implementation Requirements: Optional 2236 o Change Controller: IESG 2237 o Specification Document(s): Section 5.2.1.1 of [[ this document ]] 2239 7. Security Considerations 2241 All of the security issues faced by any cryptographic application 2242 must be faced by a JWS/JWE/JWK agent. Among these issues are 2243 protecting the user's private and symmetric keys, preventing various 2244 attacks, and helping the user avoid mistakes such as inadvertently 2245 encrypting a message for the wrong recipient. The entire list of 2246 security considerations is beyond the scope of this document, but 2247 some significant considerations are listed here. 2249 The security considerations in [AES], [DSS], [JWE], [JWK], [JWS], 2250 [NIST.800-38A], [NIST.800-38D], [NIST.800-56A], [RFC2104], [RFC3394], 2251 [RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this 2252 specification. 2254 Algorithms of matching strengths should be used together whenever 2255 possible. For instance, when AES Key Wrap is used with a given key 2256 size, using the same key size is recommended when AES GCM is also 2257 used. 2259 7.1. Algorithms and Key Sizes will be Deprecated 2261 Eventually the algorithms and/or key sizes currently described in 2262 this specification will no longer be considered sufficiently secure 2263 and will be removed. Therefore, implementers and deployments must be 2264 prepared for this eventuality. 2266 7.2. Key Lifetimes 2268 Many algorithms have associated security considerations related to 2269 key lifetimes and/or the number of times that a key may be used. 2270 Those security considerations continue to apply when using those 2271 algorithms with JOSE data structures. 2273 7.3. RSAES-PKCS1-v1_5 Security Considerations 2275 While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not 2276 to adopt RSASSA-PKCS-v1_5 for new applications and instead requests 2277 that people transition to RSASSA-PSS, this specification does include 2278 RSASSA-PKCS-v1_5, for interoperability reasons, because it commonly 2279 implemented. 2281 Keys used with RSAES-PKCS1-v1_5 must follow the constraints in 2282 Section 7.2 of RFC 3447 [RFC3447]. In particular, keys with a low 2283 public key exponent value must not be used. 2285 7.4. AES GCM Security Considerations 2287 Keys used with AES GCM must follow the constraints in Section 8.3 of 2288 [NIST.800-38D], which states: "The total number of invocations of the 2289 authenticated encryption function shall not exceed 2^32, including 2290 all IV lengths and all instances of the authenticated encryption 2291 function with the given key". In accordance with this rule, AES GCM 2292 MUST NOT be used with the same key value more than 2^32 times. 2294 An Initialization Vector value MUST never be used multiple times with 2295 the same AES GCM key. One way to prevent this is to store a counter 2296 with the key and increment it with every use. The counter can also 2297 be used to prevent exceeding the 2^32 limit above. 2299 This security consideration does not apply to the composite AES-CBC 2300 HMAC SHA-2 or AES Key Wrap algorithms. 2302 7.5. Plaintext JWS Security Considerations 2304 Plaintext JWSs (JWSs that use the "alg" value "none") provide no 2305 integrity protection. Thus, they must only be used in contexts where 2306 the payload is secured by means other than a digital signature or MAC 2307 value, or need not be secured. 2309 Implementations that support plaintext JWS objects MUST NOT accept 2310 such objects as valid unless the application specifies that it is 2311 acceptable for a specific object to not be integrity-protected. 2312 Implementations MUST NOT accept plaintext JWS objects by default. 2313 For example, the "verify" method of a hypothetical JWS software 2314 library might have a Boolean "acceptUnsigned" parameter that 2315 indicates "none" is an acceptable "alg" value. As another example, 2316 the "verify" method might take a list of algorithms that are 2317 acceptable to the application as a parameter and would reject 2318 plaintext JWS values if "none" is not in that list. 2320 In order to mitigate downgrade attacks, applications MUST NOT signal 2321 acceptance of plaintext JWS objects at a global level, and SHOULD 2322 signal acceptance on a per-object basis. For example, suppose an 2323 application accepts JWS objects over two channels, (1) HTTP and (2) 2324 HTTPS with client authentication. It requires a JWS signature on 2325 objects received over HTTP, but accepts plaintext JWS objects over 2326 HTTPS. If the application were to globally indicate that "none" is 2327 acceptable, then an attacker could provide it with an unsigned object 2328 over HTTP and still have that object successfully validate. Instead, 2329 the application needs to indicate acceptance of "none" for each 2330 object received over HTTPS (e.g., by setting "acceptUnsigned" to 2331 "true" for the first hypothetical JWS software library above), but 2332 not for each object received over HTTP. 2334 7.6. Denial of Service Attacks 2336 Receiving agents that validate signatures and sending agents that 2337 encrypt messages need to be cautious of cryptographic processing 2338 usage when validating signatures and encrypting messages using keys 2339 larger than those mandated in this specification. An attacker could 2340 send certificates with keys that would result in excessive 2341 cryptographic processing, for example, keys larger than those 2342 mandated in this specification, which could swamp the processing 2343 element. Agents that use such keys without first validating the 2344 certificate to a trust anchor are advised to have some sort of 2345 cryptographic resource management system to prevent such attacks. 2347 7.7. Reusing Key Material when Encrypting Keys 2349 It is NOT RECOMMENDED to reuse the same key material (Key Encryption 2350 Key, Content Encryption Key, Initialization Vector, etc.) to encrypt 2351 multiple JWK or JWK Set objects, or to encrypt the same JWK or JWK 2352 Set object multiple times. One suggestion for preventing re-use is 2353 to always generate a new set key material for each encryption 2354 operation, based on the considerations noted in this document as well 2355 as from [RFC4086]. 2357 7.8. Password Considerations 2359 While convenient for end users, passwords are vulnerable to a number 2360 of attacks. To help mitigate some of these limitations, this 2361 document applies principles from [RFC2898] to derive cryptographic 2362 keys from user-supplied passwords. 2364 However, the strength of the password still has a significant impact. 2365 A high-entry password has greater resistance to dictionary attacks. 2366 [NIST-800-63-1] contains guidelines for estimating password entropy, 2367 which can help applications and users generate stronger passwords. 2369 An ideal password is one that is as large (or larger) than the 2370 derived key length but less than the PRF's block size. Passwords 2371 larger than the PRF's block size are first hashed, which reduces an 2372 attacker's effective search space to the length of the hash algorithm 2373 (32 octets for HMAC SHA-256). It is RECOMMENDED that the password be 2374 no longer than 64 octets long for "PBES2-HS512+A256KW". 2376 Still, care needs to be taken in where and how password-based 2377 encryption is used. Such algorithms MUST NOT be used where the 2378 attacker can make an indefinite number of attempts to circumvent the 2379 protection. 2381 8. Internationalization Considerations 2383 Passwords obtained from users are likely to require preparation and 2384 normalization to account for differences of octet sequences generated 2385 by different input devices, locales, etc. It is RECOMMENDED that 2386 applications to perform the steps outlined in 2387 [I-D.melnikov-precis-saslprepbis] to prepare a password supplied 2388 directly by a user before performing key derivation and encryption. 2390 9. References 2392 9.1. Normative References 2394 [AES] National Institute of Standards and Technology (NIST), 2395 "Advanced Encryption Standard (AES)", FIPS PUB 197, 2396 November 2001. 2398 [DSS] National Institute of Standards and Technology, "Digital 2399 Signature Standard (DSS)", FIPS PUB 186-4, July 2013. 2401 [I-D.melnikov-precis-saslprepbis] 2402 Saint-Andre, P. and A. Melnikov, "Preparation and 2403 Comparison of Internationalized Strings Representing 2404 Simple User Names and Passwords", 2405 draft-melnikov-precis-saslprepbis-04 (work in progress), 2406 September 2012. 2408 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 2409 Encryption (JWE)", draft-ietf-jose-json-web-encryption 2410 (work in progress), September 2013. 2412 [JWK] Jones, M., "JSON Web Key (JWK)", 2413 draft-ietf-jose-json-web-key (work in progress), 2414 September 2013. 2416 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2417 Signature (JWS)", draft-ietf-jose-json-web-signature (work 2418 in progress), September 2013. 2420 [NIST.800-38A] 2421 National Institute of Standards and Technology (NIST), 2422 "Recommendation for Block Cipher Modes of Operation", 2423 NIST PUB 800-38A, December 2001. 2425 [NIST.800-38D] 2426 National Institute of Standards and Technology (NIST), 2427 "Recommendation for Block Cipher Modes of Operation: 2428 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 2429 December 2001. 2431 [NIST.800-56A] 2432 National Institute of Standards and Technology (NIST), 2433 "Recommendation for Pair-Wise Key Establishment Schemes 2434 Using Discrete Logarithm Cryptography", NIST Special 2435 Publication 800-56A, Revision 2, May 2013. 2437 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 2438 Hashing for Message Authentication", RFC 2104, 2439 February 1997. 2441 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2442 Requirement Levels", BCP 14, RFC 2119, March 1997. 2444 [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography 2445 Specification Version 2.0", RFC 2898, September 2000. 2447 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 2448 (AES) Key Wrap Algorithm", RFC 3394, September 2002. 2450 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2451 10646", STD 63, RFC 3629, November 2003. 2453 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 2454 Requirements for Security", BCP 106, RFC 4086, June 2005. 2456 [RFC4627] Crockford, D., "The application/json Media Type for 2457 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2459 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2460 Encodings", RFC 4648, October 2006. 2462 [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA- 2463 384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007. 2465 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 2466 Encryption", RFC 5116, January 2008. 2468 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2469 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2470 May 2008. 2472 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 2473 Curve Cryptography Algorithms", RFC 6090, February 2011. 2475 [SEC1] Standards for Efficient Cryptography Group, "SEC 1: 2476 Elliptic Curve Cryptography", May 2009. 2478 [SHS] National Institute of Standards and Technology, "Secure 2479 Hash Standard (SHS)", FIPS PUB 180-3, October 2008. 2481 [USASCII] American National Standards Institute, "Coded Character 2482 Set -- 7-bit American Standard Code for Information 2483 Interchange", ANSI X3.4, 1986. 2485 9.2. Informative References 2487 [CanvasApp] 2488 Facebook, "Canvas Applications", 2010. 2490 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 2491 McGrew, D., Foley, J., and K. Paterson, "Authenticated 2492 Encryption with AES-CBC and HMAC-SHA", 2493 draft-mcgrew-aead-aes-cbc-hmac-sha2-02 (work in progress), 2494 July 2013. 2496 [I-D.miller-jose-jwe-protected-jwk] 2497 Miller, M., "Using JavaScript Object Notation (JSON) Web 2498 Encryption (JWE) for Protecting JSON Web Key (JWK) 2499 Objects", draft-miller-jose-jwe-protected-jwk-02 (work in 2500 progress), June 2013. 2502 [I-D.rescorla-jsms] 2503 Rescorla, E. and J. Hildebrand, "JavaScript Message 2504 Security Format", draft-rescorla-jsms-00 (work in 2505 progress), March 2011. 2507 [JCA] Oracle, "Java Cryptography Architecture", 2013. 2509 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 2510 Encryption", September 2010. 2512 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 2513 September 2010. 2515 [MagicSignatures] 2516 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 2517 Signatures", January 2011. 2519 [NIST-800-63-1] 2520 National Institute of Standards and Technology (NIST), 2521 "Electronic Authentication Guideline", NIST 800-63-1, 2522 December 2011. 2524 [RFC2631] Rescorla, E., "Diffie-Hellman Key Agreement Method", 2525 RFC 2631, June 1999. 2527 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 2528 Language) XML-Signature Syntax and Processing", RFC 3275, 2529 March 2002. 2531 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 2532 Standards (PKCS) #1: RSA Cryptography Specifications 2533 Version 2.1", RFC 3447, February 2003. 2535 [W3C.CR-xmldsig-core2-20120124] 2536 Eastlake, D., Reagle, J., Yiu, K., Solo, D., Datta, P., 2537 Hirsch, F., Cantor, S., and T. Roessler, "XML Signature 2538 Syntax and Processing Version 2.0", World Wide Web 2539 Consortium CR CR-xmldsig-core2-20120124, January 2012, 2540 . 2542 [W3C.CR-xmlenc-core1-20120313] 2543 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 2544 "XML Encryption Syntax and Processing Version 1.1", World 2545 Wide Web Consortium CR CR-xmlenc-core1-20120313, 2546 March 2012, 2547 . 2549 [W3C.REC-xmlenc-core-20021210] 2550 Eastlake, D. and J. Reagle, "XML Encryption Syntax and 2551 Processing", World Wide Web Consortium Recommendation REC- 2552 xmlenc-core-20021210, December 2002, 2553 . 2555 Appendix A. Digital Signature/MAC Algorithm Identifier Cross-Reference 2557 This appendix contains a table cross-referencing the digital 2558 signature and MAC "alg" (algorithm) values used in this specification 2559 with the equivalent identifiers used by other standards and software 2560 packages. See XML DSIG [RFC3275], XML DSIG 2.0 2561 [W3C.CR-xmldsig-core2-20120124], and Java Cryptography Architecture 2562 [JCA] for more information about the names defined by those 2563 documents. 2565 +-----+---------------------------------+-----------+---------------+ 2566 | JWS | XML DSIG | JCA | OID | 2567 +-----+---------------------------------+-----------+---------------+ 2568 | HS2 | http://www.w3.org/2001/04/xmlds | HmacSHA25 | 1.2.840.11354 | 2569 | 56 | ig-more#hmac-sha256 | 6 | 9.2.9 | 2570 | HS3 | http://www.w3.org/2001/04/xmlds | HmacSHA38 | 1.2.840.11354 | 2571 | 84 | ig-more#hmac-sha384 | 4 | 9.2.10 | 2572 | HS5 | http://www.w3.org/2001/04/xmlds | HmacSHA51 | 1.2.840.11354 | 2573 | 12 | ig-more#hmac-sha512 | 2 | 9.2.11 | 2574 | RS2 | http://www.w3.org/2001/04/xmlds | SHA256wit | 1.2.840.11354 | 2575 | 56 | ig-more#rsa-sha256 | hRSA | 9.1.1.11 | 2576 | RS3 | http://www.w3.org/2001/04/xmlds | SHA384wit | 1.2.840.11354 | 2577 | 84 | ig-more#rsa-sha384 | hRSA | 9.1.1.12 | 2578 | RS5 | http://www.w3.org/2001/04/xmlds | SHA512wit | 1.2.840.11354 | 2579 | 12 | ig-more#rsa-sha512 | hRSA | 9.1.1.13 | 2580 | ES2 | http://www.w3.org/2001/04/xmlds | SHA256wit | 1.2.840.10045 | 2581 | 56 | ig-more#ecdsa-sha256 | hECDSA | .4.3.2 | 2582 | ES3 | http://www.w3.org/2001/04/xmlds | SHA384wit | 1.2.840.10045 | 2583 | 84 | ig-more#ecdsa-sha384 | hECDSA | .4.3.3 | 2584 | ES5 | http://www.w3.org/2001/04/xmlds | SHA512wit | 1.2.840.10045 | 2585 | 12 | ig-more#ecdsa-sha512 | hECDSA | .4.3.4 | 2586 | PS2 | http://www.w3.org/2007/05/xmlds | | 1.2.840.11354 | 2587 | 56 | ig-more#sha256-rsa-MGF1 | | 9.1.1.10 | 2588 | PS3 | http://www.w3.org/2007/05/xmlds | | 1.2.840.11354 | 2589 | 84 | ig-more#sha384-rsa-MGF1 | | 9.1.1.10 | 2590 | PS5 | http://www.w3.org/2007/05/xmlds | | 1.2.840.11354 | 2591 | 12 | ig-more#sha512-rsa-MGF1 | | 9.1.1.10 | 2592 +-----+---------------------------------+-----------+---------------+ 2594 Appendix B. Encryption Algorithm Identifier Cross-Reference 2596 This appendix contains a table cross-referencing the "alg" 2597 (algorithm) and "enc" (encryption method) values used in this 2598 specification with the equivalent identifiers used by other standards 2599 and software packages. See XML Encryption 2600 [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 2601 [W3C.CR-xmlenc-core1-20120313], and Java Cryptography Architecture 2602 [JCA] for more information about the names defined by those 2603 documents. 2605 For the composite algorithms "A128CBC-HS256", "A192CBC-HS384", and 2606 "A256CBC-HS512", the corresponding AES CBC algorithm identifiers are 2607 listed. 2609 +--------+-----------------------+-------------------+--------------+ 2610 | JWE | XML ENC | JCA | OID | 2611 +--------+-----------------------+-------------------+--------------+ 2612 | RSA1_5 | http://www.w3.org/200 | RSA/ECB/PKCS1Padd | 1.2.840.1135 | 2613 | | 1/04/xmlenc#rsa-1_5 | ing | 49.1.1.1 | 2614 | RSA-OA | http://www.w3.org/200 | RSA/ECB/OAEPWithS | 1.2.840.1135 | 2615 | EP | 1/04/xmlenc#rsa-oaep- | HA-1AndMGF1Paddin | 49.1.1.7 | 2616 | | mgf1p | g | | 2617 | ECDH-E | http://www.w3.org/200 | | 1.3.132.1.12 | 2618 | S | 9/xmlenc11#ECDH-ES | | | 2619 | A128KW | http://www.w3.org/200 | | 2.16.840.1.1 | 2620 | | 1/04/xmlenc#kw-aes128 | | 01.3.4.1.5 | 2621 | A192KW | http://www.w3.org/200 | | 2.16.840.1.1 | 2622 | | 1/04/xmlenc#kw-aes192 | | 01.3.4.1.25 | 2623 | A256KW | http://www.w3.org/200 | | 2.16.840.1.1 | 2624 | | 1/04/xmlenc#kw-aes256 | | 01.3.4.1.45 | 2625 | A128CB | http://www.w3.org/200 | AES/CBC/PKCS5Padd | 2.16.840.1.1 | 2626 | C-HS25 | 1/04/xmlenc#aes128-cb | ing | 01.3.4.1.2 | 2627 | 6 | c | | | 2628 | A192CB | http://www.w3.org/200 | AES/CBC/PKCS5Padd | 2.16.840.1.1 | 2629 | C-HS38 | 1/04/xmlenc#aes192-cb | ing | 01.3.4.1.22 | 2630 | 4 | c | | | 2631 | A256CB | http://www.w3.org/200 | AES/CBC/PKCS5Padd | 2.16.840.1.1 | 2632 | C-HS51 | 1/04/xmlenc#aes256-cb | ing | 01.3.4.1.42 | 2633 | 2 | c | | | 2634 | A128GC | http://www.w3.org/200 | AES/GCM/NoPadding | 2.16.840.1.1 | 2635 | M | 9/xmlenc11#aes128-gcm | | 01.3.4.1.6 | 2636 | A192GC | http://www.w3.org/200 | AES/GCM/NoPadding | 2.16.840.1.1 | 2637 | M | 9/xmlenc11#aes192-gcm | | 01.3.4.1.26 | 2638 | A256GC | http://www.w3.org/200 | AES/GCM/NoPadding | 2.16.840.1.1 | 2639 | M | 9/xmlenc11#aes256-gcm | | 01.3.4.1.46 | 2640 +--------+-----------------------+-------------------+--------------+ 2642 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms 2644 The following test cases can be used to validate implementations of 2645 the AES_CBC_HMAC_SHA2 algorithms defined in Section 4.10. They are 2646 also intended to correspond to test cases that may appear in a future 2647 version of [I-D.mcgrew-aead-aes-cbc-hmac-sha2], demonstrating that 2648 the cryptographic computations performed are the same. 2650 The variable names are those defined in Section 4.10. All values are 2651 hexadecimal. 2653 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 2655 AES_128_CBC_HMAC_SHA_256 2657 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2658 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2660 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2662 ENC_KEY = 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2664 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2665 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2666 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2667 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2668 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2669 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2670 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2671 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2673 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2675 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2676 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2677 4b 65 72 63 6b 68 6f 66 66 73 2679 AL = 00 00 00 00 00 00 01 50 2681 E = c8 0e df a3 2d df 39 d5 ef 00 c0 b4 68 83 42 79 2682 a2 e4 6a 1b 80 49 f7 92 f7 6b fe 54 b9 03 a9 c9 2683 a9 4a c9 b4 7a d2 65 5c 5f 10 f9 ae f7 14 27 e2 2684 fc 6f 9b 3f 39 9a 22 14 89 f1 63 62 c7 03 23 36 2685 09 d4 5a c6 98 64 e3 32 1c f8 29 35 ac 40 96 c8 2686 6e 13 33 14 c5 40 19 e8 ca 79 80 df a4 b9 cf 1b 2687 38 4c 48 6f 3a 54 c5 10 78 15 8e e5 d7 9d e5 9f 2688 bd 34 d8 48 b3 d6 95 50 a6 76 46 34 44 27 ad e5 2689 4b 88 51 ff b5 98 f7 f8 00 74 b9 47 3c 82 e2 db 2691 M = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2692 e6 e5 45 82 47 65 15 f0 ad 9f 75 a2 b7 1c 73 ef 2694 T = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2696 C.2. Test Cases for AES_192_CBC_HMAC_SHA_384 2698 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2699 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2700 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2702 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2703 10 11 12 13 14 15 16 17 2705 ENC_KEY = 18 19 1a 1b 1c 1d 1e 1f 20 21 22 23 24 25 26 27 2706 28 29 2a 2b 2c 2d 2e 2f 2708 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2709 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2710 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2711 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2712 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2713 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2714 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2715 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2717 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2719 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2720 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2721 4b 65 72 63 6b 68 6f 66 66 73 2723 AL = 00 00 00 00 00 00 01 50 2725 E = ea 65 da 6b 59 e6 1e db 41 9b e6 2d 19 71 2a e5 2726 d3 03 ee b5 00 52 d0 df d6 69 7f 77 22 4c 8e db 2727 00 0d 27 9b dc 14 c1 07 26 54 bd 30 94 42 30 c6 2728 57 be d4 ca 0c 9f 4a 84 66 f2 2b 22 6d 17 46 21 2729 4b f8 cf c2 40 0a dd 9f 51 26 e4 79 66 3f c9 0b 2730 3b ed 78 7a 2f 0f fc bf 39 04 be 2a 64 1d 5c 21 2731 05 bf e5 91 ba e2 3b 1d 74 49 e5 32 ee f6 0a 9a 2732 c8 bb 6c 6b 01 d3 5d 49 78 7b cd 57 ef 48 49 27 2733 f2 80 ad c9 1a c0 c4 e7 9c 7b 11 ef c6 00 54 e3 2735 M = 84 90 ac 0e 58 94 9b fe 51 87 5d 73 3f 93 ac 20 2736 75 16 80 39 cc c7 33 d7 45 94 f8 86 b3 fa af d4 2737 86 f2 5c 71 31 e3 28 1e 36 c7 a2 d1 30 af de 57 2739 T = 84 90 ac 0e 58 94 9b fe 51 87 5d 73 3f 93 ac 20 2740 75 16 80 39 cc c7 33 d7 2742 C.3. Test Cases for AES_256_CBC_HMAC_SHA_512 2744 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2745 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2746 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2747 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2749 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2750 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2752 ENC_KEY = 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2753 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2755 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2756 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2757 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2758 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2759 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2760 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2761 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2762 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2764 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2766 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2767 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2768 4b 65 72 63 6b 68 6f 66 66 73 2770 AL = 00 00 00 00 00 00 01 50 2772 E = 4a ff aa ad b7 8c 31 c5 da 4b 1b 59 0d 10 ff bd 2773 3d d8 d5 d3 02 42 35 26 91 2d a0 37 ec bc c7 bd 2774 82 2c 30 1d d6 7c 37 3b cc b5 84 ad 3e 92 79 c2 2775 e6 d1 2a 13 74 b7 7f 07 75 53 df 82 94 10 44 6b 2776 36 eb d9 70 66 29 6a e6 42 7e a7 5c 2e 08 46 a1 2777 1a 09 cc f5 37 0d c8 0b fe cb ad 28 c7 3f 09 b3 2778 a3 b7 5e 66 2a 25 94 41 0a e4 96 b2 e2 e6 60 9e 2779 31 e6 e0 2c c8 37 f0 53 d2 1f 37 ff 4f 51 95 0b 2780 be 26 38 d0 9d d7 a4 93 09 30 80 6d 07 03 b1 f6 2782 M = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2783 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2784 fd 30 a5 65 c6 16 ff b2 f3 64 ba ec e6 8f c4 07 2785 53 bc fc 02 5d de 36 93 75 4a a1 f5 c3 37 3b 9c 2787 T = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2788 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2790 Appendix D. Example ECDH-ES Key Agreement Computation 2792 This example uses ECDH-ES Key Agreement and the Concat KDF to derive 2793 the Content Encryption Key (CEK) in the manner described in 2794 Section 4.7. In this example, the ECDH-ES Direct Key Agreement mode 2795 ("alg" value "ECDH-ES") is used to produce an agreed upon key for AES 2796 GCM with 128 bit keys ("enc" value "A128GCM"). 2798 In this example, a sender Alice is encrypting content to a recipient 2799 Bob. The sender (Alice) generates an ephemeral key for the key 2800 agreement computation. Alice's ephemeral key (in JWK format) used 2801 for the key agreement computation in this example (including the 2802 private part) is: 2804 {"kty":"EC", 2805 "crv":"P-256", 2806 "x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0", 2807 "y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps", 2808 "d":"0_NxaRPUMQoAJt50Gz8YiTr8gRTwyEaCumd-MToTmIo" 2809 } 2811 The recipient's (Bob's) key (in JWK format) used for the key 2812 agreement computation in this example (including the private part) 2813 is: 2815 {"kty":"EC", 2816 "crv":"P-256", 2817 "x":"weNJy2HscCSM6AEDTDg04biOvhFhyyWvOHQfeF_PxMQ", 2818 "y":"e8lnCO-AlStT-NJVX-crhB7QRYhiix03illJOVAOyck", 2819 "d":"VEmDZpDXXK8p8N0Cndsxs924q6nS1RXFASRl6BfUqdw" 2820 } 2822 Header parameter values used in this example are as follows. In this 2823 example, the "apu" (agreement PartyUInfo) parameter value is the 2824 base64url encoding of the UTF-8 string "Alice" and the "apv" 2825 (agreement PartyVInfo) parameter value is the base64url encoding of 2826 the UTF-8 string "Bob". The "epk" parameter is used to communicate 2827 the sender's (Alice's) ephemeral public key value to the recipient 2828 (Bob). 2830 {"alg":"ECDH-ES", 2831 "enc":"A128GCM", 2832 "apu":"QWxpY2U", 2833 "apv":"Qm9i", 2834 "epk": 2835 {"kty":"EC", 2836 "crv":"P-256", 2837 "x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0", 2838 "y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps" 2839 } 2840 } 2842 The resulting Concat KDF [NIST.800-56A] parameter values are: 2844 Z This is set to the ECDH-ES key agreement output. (This value is 2845 often not directly exposed by libraries, due to NIST security 2846 requirements, and only serves as an input to a KDF.) In this 2847 example, Z is the octet sequence: 2848 [158, 86, 217, 29, 129, 113, 53, 211, 114, 131, 66, 131, 191, 132, 2849 38, 156, 251, 49, 110, 163, 218, 128, 106, 72, 246, 218, 167, 121, 2850 140, 254, 144, 196]. 2852 keydatalen This value is 128 - the number of bits in the desired 2853 output key (because "A128GCM" uses a 128 bit key). 2855 AlgorithmID This is set to the octets representing the 32 bit big 2856 endian value 7 - [0, 0, 0, 7] - the number of octets in the 2857 AlgorithmID content "A128GCM", followed, by the octets 2858 representing the UTF-8 string "A128GCM" - [65, 49, 50, 56, 71, 67, 2859 77]. 2861 PartyUInfo This is set to the octets representing the 32 bit big 2862 endian value 5 - [0, 0, 0, 5] - the number of octets in the 2863 PartyUInfo content "Alice", followed, by the octets representing 2864 the UTF-8 string "Alice" - [65, 108, 105, 99, 101]. 2866 PartyVInfo This is set to the octets representing the 32 bit big 2867 endian value 3 - [0, 0, 0, 3] - the number of octets in the 2868 PartyUInfo content "Bob", followed, by the octets representing the 2869 UTF-8 string "Bob" - [66, 111, 98]. 2871 SuppPubInfo This is set to the octets representing the 32 bit big 2872 endian value 128 - [0, 0, 0, 128] - the keydatalen value. 2874 SuppPrivInfo This is set to the empty octet sequence. 2876 Concatenating the parameters AlgorithmID through SuppPubInfo results 2877 in an OtherInfo value of: 2879 [0, 0, 0, 7, 65, 49, 50, 56, 71, 67, 77, 0, 0, 0, 5, 65, 108, 105, 2880 99, 101, 0, 0, 0, 3, 66, 111, 98, 0, 0, 0, 128] 2882 Concatenating the round number 1 ([0, 0, 0, 1]), Z, and the OtherInfo 2883 value results in the Concat KDF round 1 hash input of: 2884 [0, 0, 0, 1, 2885 158, 86, 217, 29, 129, 113, 53, 211, 114, 131, 66, 131, 191, 132, 38, 2886 156, 251, 49, 110, 163, 218, 128, 106, 72, 246, 218, 167, 121, 140, 2887 254, 144, 196, 2888 0, 0, 0, 7, 65, 49, 50, 56, 71, 67, 77, 0, 0, 0, 5, 65, 108, 105, 99, 2889 101, 0, 0, 0, 3, 66, 111, 98, 0, 0, 0, 128] 2891 The resulting derived key, which is the first 128 bits of the round 1 2892 hash output is: 2893 [86, 170, 141, 234, 248, 35, 109, 32, 92, 34, 40, 205, 113, 167, 16, 2894 26] 2896 The base64url encoded representation of this derived key is: 2898 usEpwFIC_qrmBExntFwxMA 2900 Appendix E. Acknowledgements 2902 Solutions for signing and encrypting JSON content were previously 2903 explored by Magic Signatures [MagicSignatures], JSON Simple Sign 2904 [JSS], Canvas Applications [CanvasApp], JSON Simple Encryption [JSE], 2905 and JavaScript Message Security Format [I-D.rescorla-jsms], all of 2906 which influenced this draft. 2908 The Authenticated Encryption with AES-CBC and HMAC-SHA 2909 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] specification, upon which the 2910 AES_CBC_HMAC_SHA2 algorithms are based, was written by David A. 2911 McGrew and Kenny Paterson. The test cases for AES_CBC_HMAC_SHA2 are 2912 based upon those for [I-D.mcgrew-aead-aes-cbc-hmac-sha2] by John 2913 Foley. 2915 Matt Miller wrote Using JavaScript Object Notation (JSON) Web 2916 Encryption (JWE) for Protecting JSON Web Key (JWK) Objects 2917 [I-D.miller-jose-jwe-protected-jwk], which the password-based 2918 encryption content of this draft is based upon. 2920 This specification is the work of the JOSE Working Group, which 2921 includes dozens of active and dedicated participants. In particular, 2922 the following individuals contributed ideas, feedback, and wording 2923 that influenced this specification: 2925 Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de 2926 Medeiros, Yaron Y. Goland, Dick Hardt, Jeff Hodges, Edmund Jay, James 2927 Manger, Matt Miller, Tony Nadalin, Axel Nennker, John Panzer, 2928 Emmanuel Raviart, Nat Sakimura, Jim Schaad, Hannes Tschofenig, and 2929 Sean Turner. 2931 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2932 Sean Turner and Stephen Farrell served as Security area directors 2933 during the creation of this specification. 2935 Appendix F. Document History 2937 [[ to be removed by the RFC Editor before publication as an RFC ]] 2939 -16 2941 o Added a DataLen prefix to the AlgorithmID value in the Concat KDF 2942 computation. 2944 o Added OIDs for encryption algorithms, additional signature 2945 algorithm OIDs, and additional XML DSIG/ENC URIs in the algorithm 2946 cross-reference tables. 2948 o Changes to address editorial and minor issues #28, #36, #39, #52, 2949 #53, #55, #127, #128, #136, #137, #141, #150, #151, #152, and 2950 #155. 2952 -15 2954 o Changed statements about rejecting JWSs to statements about 2955 validation failing, addressing issue #35. 2957 o Stated that changes of implementation requirements are only 2958 permitted on a Specification Required basis, addressing issue #38. 2960 o Made "oct" a required key type, addressing issue #40. 2962 o Updated the example ECDH-ES key agreement values. 2964 o Changes to address editorial and minor issues #34, #37, #49, #63, 2965 #123, #124, #125, #130, #132, #133, #138, #139, #140, #142, #143, 2966 #144, #145, #148, #149, #150, and #162. 2968 -14 2970 o Removed "PBKDF2" key type and added "p2s" and "p2c" header 2971 parameters for use with the PBES2 algorithms. 2973 o Made the RSA private key parameters that are there to enable 2974 optimizations be RECOMMENDED rather than REQUIRED. 2976 o Added algorithm identifiers for AES algorithms using 192 bit keys 2977 and for RSASSA-PSS using HMAC SHA-384. 2979 o Added security considerations about key lifetimes, addressing 2980 issue #18. 2982 o Added an example ECDH-ES key agreement computation. 2984 -13 2986 o Added key encryption with AES GCM as specified in 2987 draft-jones-jose-aes-gcm-key-wrap-01, addressing issue #13. 2989 o Added security considerations text limiting the number of times 2990 that an AES GCM key can be used for key encryption or direct 2991 encryption, per Section 8.3 of NIST SP 800-38D, addressing issue 2992 #28. 2994 o Added password-based key encryption as specified in 2995 draft-miller-jose-jwe-protected-jwk-02. 2997 -12 2999 o In the Direct Key Agreement case, the Concat KDF AlgorithmID is 3000 set to the octets of the UTF-8 representation of the "enc" header 3001 parameter value. 3003 o Restored the "apv" (agreement PartyVInfo) parameter. 3005 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 3006 be with the algorithm descriptions that use them. 3008 o Changed terminology from "block encryption" to "content 3009 encryption". 3011 -11 3013 o Removed the Encrypted Key value from the AAD computation since it 3014 is already effectively integrity protected by the encryption 3015 process. The AAD value now only contains the representation of 3016 the JWE Encrypted Header. 3018 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 3020 o Added more information about the use of PartyUInfo during key 3021 agreement. 3023 o Use the keydatalen as the SuppPubInfo value for the Concat KDF 3024 when doing key agreement, as RFC 2631 does. 3026 o Added algorithm identifiers for RSASSA-PSS with SHA-256 and SHA- 3027 512. 3029 o Added a Parameter Information Class value to the JSON Web Key 3030 Parameters registry, which registers whether the parameter conveys 3031 public or private information. 3033 -10 3035 o Changed the JWE processing rules for multiple recipients so that a 3036 single AAD value contains the header parameters and encrypted key 3037 values for all the recipients, enabling AES GCM to be safely used 3038 for multiple recipients. 3040 -09 3042 o Expanded the scope of the JWK parameters to include private and 3043 symmetric key representations, as specified by 3044 draft-jones-jose-json-private-and-symmetric-key-00. 3046 o Changed term "JWS Secured Input" to "JWS Signing Input". 3048 o Changed from using the term "byte" to "octet" when referring to 8 3049 bit values. 3051 o Specified that AES Key Wrap uses the default initial value 3052 specified in Section 2.2.3.1 of RFC 3394. This addressed issue 3053 #19. 3055 o Added Key Management Mode definitions to terminology section and 3056 used the defined terms to provide clearer key management 3057 instructions. This addressed issue #5. 3059 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 3060 and "A256CBC-HS512". The new algorithms perform the same 3061 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 3062 but with the Initialization Vector and Authentication Tag values 3063 remaining separate from the Ciphertext value in the output 3064 representation. Also deleted the header parameters "epu" 3065 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 3066 they are no longer used. 3068 o Changed from using the term "Integrity Value" to "Authentication 3069 Tag". 3071 -08 3073 o Changed the name of the JWK key type parameter from "alg" to 3074 "kty". 3076 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 3077 since the term AEAD in the RFC 5116 sense implied the use of a 3078 particular data representation, rather than just referring to the 3079 class of algorithms that perform authenticated encryption with 3080 associated data. 3082 o Applied editorial improvements suggested by Jeff Hodges. Many of 3083 these simplified the terminology used. 3085 o Added seriesInfo information to Internet Draft references. 3087 -07 3089 o Added a data length prefix to PartyUInfo and PartyVInfo values. 3091 o Changed the name of the JWK RSA modulus parameter from "mod" to 3092 "n" and the name of the JWK RSA exponent parameter from "xpo" to 3093 "e", so that the identifiers are the same as those used in RFC 3094 3447. 3096 o Made several local editorial changes to clean up loose ends left 3097 over from to the decision to only support block encryption methods 3098 providing integrity. 3100 -06 3102 o Removed the "int" and "kdf" parameters and defined the new 3103 composite Authenticated Encryption algorithms "A128CBC+HS256" and 3104 "A256CBC+HS512" to replace the former uses of AES CBC, which 3105 required the use of separate integrity and key derivation 3106 functions. 3108 o Included additional values in the Concat KDF calculation -- the 3109 desired output size and the algorithm value, and optionally 3110 PartyUInfo and PartyVInfo values. Added the optional header 3111 parameters "apu" (agreement PartyUInfo), "apv" (agreement 3112 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 3113 PartyVInfo). 3115 o Changed the name of the JWK RSA exponent parameter from "exp" to 3116 "xpo" so as to allow the potential use of the name "exp" for a 3117 future extension that might define an expiration parameter for 3118 keys. (The "exp" name is already used for this purpose in the JWT 3119 specification.) 3121 o Applied changes made by the RFC Editor to RFC 6749's registry 3122 language to this specification. 3124 -05 3126 o Support both direct encryption using a shared or agreed upon 3127 symmetric key, and the use of a shared or agreed upon symmetric 3128 key to key wrap the CMK. Specifically, added the "alg" values 3129 "dir", "ECDH-ES+A128KW", and "ECDH-ES+A256KW" to finish filling in 3130 this set of capabilities. 3132 o Updated open issues. 3134 -04 3136 o Added text requiring that any leading zero bytes be retained in 3137 base64url encoded key value representations for fixed-length 3138 values. 3140 o Added this language to Registration Templates: "This name is case 3141 sensitive. Names that match other registered names in a case 3142 insensitive manner SHOULD NOT be accepted." 3144 o Described additional open issues. 3146 o Applied editorial suggestions. 3148 -03 3150 o Always use a 128 bit "authentication tag" size for AES GCM, 3151 regardless of the key size. 3153 o Specified that use of a 128 bit IV is REQUIRED with AES CBC. It 3154 was previously RECOMMENDED. 3156 o Removed key size language for ECDSA algorithms, since the key size 3157 is implied by the algorithm being used. 3159 o Stated that the "int" key size must be the same as the hash output 3160 size (and not larger, as was previously allowed) so that its size 3161 is defined for key generation purposes. 3163 o Added the "kdf" (key derivation function) header parameter to 3164 provide crypto agility for key derivation. The default KDF 3165 remains the Concat KDF with the SHA-256 digest function. 3167 o Clarified that the "mod" and "exp" values are unsigned. 3169 o Added Implementation Requirements columns to algorithm tables and 3170 Implementation Requirements entries to algorithm registries. 3172 o Changed AES Key Wrap to RECOMMENDED. 3174 o Moved registries JSON Web Signature and Encryption Header 3175 Parameters and JSON Web Signature and Encryption Type Values to 3176 the JWS specification. 3178 o Moved JSON Web Key Parameters registry to the JWK specification. 3180 o Changed registration requirements from RFC Required to 3181 Specification Required with Expert Review. 3183 o Added Registration Template sections for defined registries. 3185 o Added Registry Contents sections to populate registry values. 3187 o No longer say "the UTF-8 representation of the JWS Secured Input 3188 (which is the same as the ASCII representation)". Just call it 3189 "the ASCII representation of the JWS Secured Input". 3191 o Added "Collision Resistant Namespace" to the terminology section. 3193 o Numerous editorial improvements. 3195 -02 3197 o For AES GCM, use the "additional authenticated data" parameter to 3198 provide integrity for the header, encrypted key, and ciphertext 3199 and use the resulting "authentication tag" value as the JWE 3200 Authentication Tag. 3202 o Defined minimum required key sizes for algorithms without 3203 specified key sizes. 3205 o Defined KDF output key sizes. 3207 o Specified the use of PKCS #5 padding with AES CBC. 3209 o Generalized text to allow key agreement to be employed as an 3210 alternative to key wrapping or key encryption. 3212 o Clarified that ECDH-ES is a key agreement algorithm. 3214 o Required implementation of AES-128-KW and AES-256-KW. 3216 o Removed the use of "A128GCM" and "A256GCM" for key wrapping. 3218 o Removed "A512KW" since it turns out that it's not a standard 3219 algorithm. 3221 o Clarified the relationship between "typ" header parameter values 3222 and MIME types. 3224 o Generalized language to refer to Message Authentication Codes 3225 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 3226 unless in a context specific to HMAC algorithms. 3228 o Established registries: JSON Web Signature and Encryption Header 3229 Parameters, JSON Web Signature and Encryption Algorithms, JSON Web 3230 Signature and Encryption "typ" Values, JSON Web Key Parameters, 3231 and JSON Web Key Algorithm Families. 3233 o Moved algorithm-specific definitions from JWK to JWA. 3235 o Reformatted to give each member definition its own section 3236 heading. 3238 -01 3240 o Moved definition of "alg":"none" for JWSs here from the JWT 3241 specification since this functionality is likely to be useful in 3242 more contexts that just for JWTs. 3244 o Added Advanced Encryption Standard (AES) Key Wrap Algorithm using 3245 512 bit keys ("A512KW"). 3247 o Added text "Alternatively, the Encoded JWS Signature MAY be 3248 base64url decoded to produce the JWS Signature and this value can 3249 be compared with the computed HMAC value, as this comparison 3250 produces the same result as comparing the encoded values". 3252 o Corrected the Magic Signatures reference. 3254 o Made other editorial improvements suggested by JOSE working group 3255 participants. 3257 -00 3258 o Created the initial IETF draft based upon 3259 draft-jones-json-web-signature-04 and 3260 draft-jones-json-web-encryption-02 with no normative changes. 3262 o Changed terminology to no longer call both digital signatures and 3263 HMACs "signatures". 3265 Author's Address 3267 Michael B. Jones 3268 Microsoft 3270 Email: mbj@microsoft.com 3271 URI: http://self-issued.info/