idnits 2.17.1 draft-ietf-jose-json-web-algorithms-14.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 5 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (July 29, 2013) is 3922 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 1572 -- Looks like a reference, but probably isn't: '0' on line 2867 -- Looks like a reference, but probably isn't: '65' on line 2859 -- Looks like a reference, but probably isn't: '49' on line 2854 -- Looks like a reference, but probably isn't: '50' on line 2854 -- Looks like a reference, but probably isn't: '56' on line 2854 -- Looks like a reference, but probably isn't: '71' on line 2854 -- Looks like a reference, but probably isn't: '67' on line 2854 -- Looks like a reference, but probably isn't: '77' on line 2854 -- Looks like a reference, but probably isn't: '5' on line 2857 -- Looks like a reference, but probably isn't: '108' on line 2859 -- Looks like a reference, but probably isn't: '105' on line 2859 -- Looks like a reference, but probably isn't: '99' on line 2859 -- Looks like a reference, but probably isn't: '101' on line 2859 -- Looks like a reference, but probably isn't: '3' on line 2862 -- Looks like a reference, but probably isn't: '66' on line 2864 -- Looks like a reference, but probably isn't: '111' on line 2864 -- Looks like a reference, but probably isn't: '98' on line 2864 -- Looks like a reference, but probably isn't: '128' on line 2867 -- Possible downref: Non-RFC (?) normative reference: ref. 'AES' -- Possible downref: Non-RFC (?) normative reference: ref. 'DSS' ** Downref: Normative reference to an Informational RFC: RFC 2104 ** Obsolete normative reference: RFC 2898 (Obsoleted by RFC 8018) ** Downref: Normative reference to an Informational RFC: RFC 3394 ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Downref: Normative reference to an Informational RFC: RFC 6090 -- Possible downref: Non-RFC (?) normative reference: ref. 'SHS' -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' == Outdated reference: A later version (-05) exists of draft-mcgrew-aead-aes-cbc-hmac-sha2-02 -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) Summary: 6 errors (**), 0 flaws (~~), 4 warnings (==), 26 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track July 29, 2013 5 Expires: January 30, 2014 7 JSON Web Algorithms (JWA) 8 draft-ietf-jose-json-web-algorithms-14 10 Abstract 12 The JSON Web Algorithms (JWA) specification enumerates cryptographic 13 algorithms and identifiers to be used with the JSON Web Signature 14 (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) 15 specifications. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on January 30, 2014. 34 Copyright Notice 36 Copyright (c) 2013 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 52 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 53 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 54 2.1. Terms Incorporated from the JWS Specification . . . . . . 5 55 2.2. Terms Incorporated from the JWE Specification . . . . . . 6 56 2.3. Terms Incorporated from the JWK Specification . . . . . . 9 57 2.4. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 9 58 3. Cryptographic Algorithms for JWS . . . . . . . . . . . . . . . 9 59 3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 9 60 3.2. MAC with HMAC SHA-2 Functions . . . . . . . . . . . . . . 11 61 3.3. Digital Signature with RSASSA-PKCS1-V1_5 . . . . . . . . . 12 62 3.4. Digital Signature with ECDSA . . . . . . . . . . . . . . . 13 63 3.5. Digital Signature with RSASSA-PSS . . . . . . . . . . . . 14 64 3.6. Using the Algorithm "none" . . . . . . . . . . . . . . . . 15 65 3.7. Additional Digital Signature/MAC Algorithms and 66 Parameters . . . . . . . . . . . . . . . . . . . . . . . . 15 67 4. Cryptographic Algorithms for JWE . . . . . . . . . . . . . . . 16 68 4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 16 69 4.2. "enc" (Encryption Method) Header Parameter Values for 70 JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 71 4.3. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 22 72 4.4. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 22 73 4.5. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 22 74 4.6. Direct Encryption with a Shared Symmetric Key . . . . . . 22 75 4.7. Key Agreement with Elliptic Curve Diffie-Hellman 76 Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 22 77 4.7.1. Header Parameters Used for ECDH Key Agreement . . . . 23 78 4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 23 79 4.7.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 23 80 4.7.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 24 81 4.7.2. Key Derivation for ECDH Key Agreement . . . . . . . . 24 82 4.8. Key Encryption with AES GCM . . . . . . . . . . . . . . . 25 83 4.8.1. Header Parameters Used for AES GCM Key Encryption . . 26 84 4.8.1.1. "iv" (Initialization Vector) Header Parameter . . 26 85 4.8.1.2. "tag" (Authentication Tag) Header Parameter . . . 26 86 4.9. Key Encryption with PBES2 . . . . . . . . . . . . . . . . 26 87 4.9.1. Header Parameters Used for PBES2 Key Encryption . . . 26 88 4.9.1.1. "p2s" (PBES2 salt) Parameter . . . . . . . . . . . 26 89 4.9.1.2. "p2c" (PBES2 count) Parameter . . . . . . . . . . 27 90 4.10. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 27 91 4.10.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 27 92 4.10.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 28 93 4.10.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 28 94 4.10.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 30 95 4.10.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 30 96 4.10.4. AES_192_CBC_HMAC_SHA_384 . . . . . . . . . . . . . . . 31 97 4.10.5. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 31 98 4.10.6. Plaintext Encryption with AES_CBC_HMAC_SHA2 . . . . . 31 99 4.11. Plaintext Encryption with AES GCM . . . . . . . . . . . . 32 100 4.12. Additional Encryption Algorithms and Parameters . . . . . 32 101 5. Cryptographic Algorithms for JWK . . . . . . . . . . . . . . . 33 102 5.1. "kty" (Key Type) Parameter Values for JWK . . . . . . . . 33 103 5.2. JWK Parameters for Elliptic Curve Keys . . . . . . . . . . 33 104 5.2.1. JWK Parameters for Elliptic Curve Public Keys . . . . 33 105 5.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 34 106 5.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 34 107 5.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 34 108 5.2.2. JWK Parameters for Elliptic Curve Private Keys . . . . 34 109 5.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 34 110 5.3. JWK Parameters for RSA Keys . . . . . . . . . . . . . . . 35 111 5.3.1. JWK Parameters for RSA Public Keys . . . . . . . . . . 35 112 5.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 35 113 5.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 35 114 5.3.2. JWK Parameters for RSA Private Keys . . . . . . . . . 35 115 5.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 35 116 5.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 36 117 5.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 36 118 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 36 119 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 36 120 5.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 36 121 5.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 36 122 5.3.3. JWK Parameters for Symmetric Keys . . . . . . . . . . 37 123 5.3.3.1. "k" (Key Value) Parameter . . . . . . . . . . . . 37 124 5.4. Additional Key Types and Parameters . . . . . . . . . . . 37 125 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 126 6.1. JSON Web Signature and Encryption Algorithms Registry . . 38 127 6.1.1. Template . . . . . . . . . . . . . . . . . . . . . . . 38 128 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 39 129 6.2. JSON Web Key Types Registry . . . . . . . . . . . . . . . 44 130 6.2.1. Registration Template . . . . . . . . . . . . . . . . 44 131 6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 45 132 6.3. JSON Web Key Parameters Registration . . . . . . . . . . . 45 133 6.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 45 134 6.4. Registration of JWE Header Parameter Names . . . . . . . . 47 135 6.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 47 136 7. Security Considerations . . . . . . . . . . . . . . . . . . . 48 137 7.1. Reusing Key Material when Encrypting Keys . . . . . . . . 49 138 7.2. Password Considerations . . . . . . . . . . . . . . . . . 49 139 8. Internationalization Considerations . . . . . . . . . . . . . 50 140 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 50 141 9.1. Normative References . . . . . . . . . . . . . . . . . . . 50 142 9.2. Informative References . . . . . . . . . . . . . . . . . . 52 143 Appendix A. Digital Signature/MAC Algorithm Identifier 144 Cross-Reference . . . . . . . . . . . . . . . . . . . 53 146 Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 56 147 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 59 148 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 60 149 C.2. Test Cases for AES_192_CBC_HMAC_SHA_384 . . . . . . . . . 61 150 C.3. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 62 151 Appendix D. Example ECDH-ES Key Agreement Computation . . . . . . 63 152 Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 65 153 Appendix F. Document History . . . . . . . . . . . . . . . . . . 65 154 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 72 156 1. Introduction 158 The JSON Web Algorithms (JWA) specification enumerates cryptographic 159 algorithms and identifiers to be used with the JSON Web Signature 160 (JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK) 161 [JWK] specifications. All these specifications utilize JavaScript 162 Object Notation (JSON) [RFC4627] based data structures. This 163 specification also describes the semantics and operations that are 164 specific to these algorithms and key types. 166 Enumerating the algorithms and identifiers for them in this 167 specification, rather than in the JWS, JWE, and JWK specifications, 168 is intended to allow them to remain unchanged in the face of changes 169 in the set of required, recommended, optional, and deprecated 170 algorithms over time. 172 1.1. Notational Conventions 174 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 175 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 176 document are to be interpreted as described in Key words for use in 177 RFCs to Indicate Requirement Levels [RFC2119]. 179 2. Terminology 181 2.1. Terms Incorporated from the JWS Specification 183 These terms defined by the JSON Web Signature (JWS) [JWS] 184 specification are incorporated into this specification: 186 JSON Web Signature (JWS) A data structure representing a digitally 187 signed or MACed message. The structure represents three values: 188 the JWS Header, the JWS Payload, and the JWS Signature. 190 JSON Text Object A UTF-8 [RFC3629] encoded text string representing 191 a JSON object; the syntax of JSON objects is defined in Section 192 2.2 of [RFC4627]. 194 JWS Header A JSON Text Object (or JSON Text Objects, when using the 195 JWS JSON Serialization) that describes the digital signature or 196 MAC operation applied to create the JWS Signature value. The 197 members of the JWS Header object(s) are Header Parameters. 199 JWS Payload The sequence of octets to be secured -- a.k.a., the 200 message. The payload can contain an arbitrary sequence of octets. 202 JWS Signature A sequence of octets containing the cryptographic 203 material that ensures the integrity of the JWS Protected Header 204 and the JWS Payload. The JWS Signature value is a digital 205 signature or MAC value calculated over the JWS Signing Input using 206 the parameters specified in the JWS Header. 208 JWS Protected Header A JSON Text Object that contains the portion of 209 the JWS Header that is integrity protected. For the JWS Compact 210 Serialization, this comprises the entire JWS Header. For the JWS 211 JSON Serialization, this is one component of the JWS Header. 213 Base64url Encoding The URL- and filename-safe Base64 encoding 214 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 215 safe) '=' padding characters omitted, as permitted by Section 3.2. 216 (See Appendix C of [JWS] for notes on implementing base64url 217 encoding without padding.) 219 Encoded JWS Header Base64url encoding of the JWS Protected Header. 221 Encoded JWS Payload Base64url encoding of the JWS Payload. 223 Encoded JWS Signature Base64url encoding of the JWS Signature. 225 JWS Signing Input The concatenation of the Encoded JWS Header, a 226 period ('.') character, and the Encoded JWS Payload. 228 Collision Resistant Namespace A namespace that allows names to be 229 allocated in a manner such that they are highly unlikely to 230 collide with other names. For instance, collision resistance can 231 be achieved through administrative delegation of portions of the 232 namespace or through use of collision-resistant name allocation 233 functions. Examples of Collision Resistant Namespaces include: 234 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 235 X.660 and X.670 Recommendation series, and Universally Unique 236 IDentifiers (UUIDs) [RFC4122]. When using an administratively 237 delegated namespace, the definer of a name needs to take 238 reasonable precautions to ensure they are in control of the 239 portion of the namespace they use to define the name. 241 2.2. Terms Incorporated from the JWE Specification 243 These terms defined by the JSON Web Encryption (JWE) [JWE] 244 specification are incorporated into this specification: 246 JSON Web Encryption (JWE) A data structure representing an encrypted 247 message. The structure represents five values: the JWE Header, 248 the JWE Encrypted Key, the JWE Initialization Vector, the JWE 249 Ciphertext, and the JWE Authentication Tag. 251 Authenticated Encryption An Authenticated Encryption algorithm is 252 one that provides an integrated content integrity check. 253 Authenticated Encryption algorithms accept two inputs, the 254 Plaintext and the Additional Authenticated Data value, and produce 255 two outputs, the Ciphertext and the Authentication Tag value. AES 256 Galois/Counter Mode (GCM) is one such algorithm. 258 Plaintext The sequence of octets to be encrypted -- a.k.a., the 259 message. The plaintext can contain an arbitrary sequence of 260 octets. 262 Ciphertext An encrypted representation of the Plaintext. 264 Additional Authenticated Data (AAD) An input to an Authenticated 265 Encryption operation that is integrity protected but not 266 encrypted. 268 Authentication Tag An output of an Authenticated Encryption 269 operation that ensures the integrity of the Ciphertext and the 270 Additional Authenticated Data. Note that some algorithms may not 271 use an Authentication Tag, in which case this value is the empty 272 octet sequence. 274 Content Encryption Key (CEK) A symmetric key for the Authenticated 275 Encryption algorithm used to encrypt the Plaintext for the 276 recipient to produce the Ciphertext and the Authentication Tag. 278 JWE Header A JSON Text Object (or JSON Text Objects, when using the 279 JWE JSON Serialization) that describes the encryption operations 280 applied to create the JWE Encrypted Key, the JWE Ciphertext, and 281 the JWE Authentication Tag. The members of the JWE Header 282 object(s) are Header Parameters. 284 JWE Encrypted Key The result of encrypting the Content Encryption 285 Key (CEK) with the intended recipient's key using the specified 286 algorithm. Note that for some algorithms, the JWE Encrypted Key 287 value is specified as being the empty octet sequence. 289 JWE Initialization Vector A sequence of octets containing the 290 Initialization Vector used when encrypting the Plaintext. Note 291 that some algorithms may not use an Initialization Vector, in 292 which case this value is the empty octet sequence. 294 JWE Ciphertext A sequence of octets containing the Ciphertext for a 295 JWE. 297 JWE Authentication Tag A sequence of octets containing the 298 Authentication Tag for a JWE. 300 JWE Protected Header A JSON Text Object that contains the portion of 301 the JWE Header that is integrity protected. For the JWE Compact 302 Serialization, this comprises the entire JWE Header. For the JWE 303 JSON Serialization, this is one component of the JWE Header. 305 Encoded JWE Header Base64url encoding of the JWE Protected Header. 307 Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted 308 Key. 310 Encoded JWE Initialization Vector Base64url encoding of the JWE 311 Initialization Vector. 313 Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. 315 Encoded JWE Authentication Tag Base64url encoding of the JWE 316 Authentication Tag. 318 Key Management Mode A method of determining the Content Encryption 319 Key (CEK) value to use. Each algorithm used for determining the 320 CEK value uses a specific Key Management Mode. Key Management 321 Modes employed by this specification are Key Encryption, Key 322 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 323 and Direct Encryption. 325 Key Encryption A Key Management Mode in which the Content Encryption 326 Key (CEK) value is encrypted to the intended recipient using an 327 asymmetric encryption algorithm. 329 Key Wrapping A Key Management Mode in which the Content Encryption 330 Key (CEK) value is encrypted to the intended recipient using a 331 symmetric key wrapping algorithm. 333 Direct Key Agreement A Key Management Mode in which a key agreement 334 algorithm is used to agree upon the Content Encryption Key (CEK) 335 value. 337 Key Agreement with Key Wrapping A Key Management Mode in which a key 338 agreement algorithm is used to agree upon a symmetric key used to 339 encrypt the Content Encryption Key (CEK) value to the intended 340 recipient using a symmetric key wrapping algorithm. 342 Direct Encryption A Key Management Mode in which the Content 343 Encryption Key (CEK) value used is the secret symmetric key value 344 shared between the parties. 346 2.3. Terms Incorporated from the JWK Specification 348 These terms defined by the JSON Web Key (JWK) [JWK] specification are 349 incorporated into this specification: 351 JSON Web Key (JWK) A JSON object that represents a cryptographic 352 key. 354 JSON Web Key Set (JWK Set) A JSON object that contains an array of 355 JWKs as the value of its "keys" member. 357 2.4. Defined Terms 359 These terms are defined for use by this specification: 361 Header Parameter A name/value pair that is member of a JWS Header or 362 JWE Header. 364 Header Parameter Name The name of a member of a JSON object 365 representing a JWS Header or JWE Header. 367 Header Parameter Value The value of a member of a JSON object 368 representing a JWS Header or JWE Header. 370 3. Cryptographic Algorithms for JWS 372 JWS uses cryptographic algorithms to digitally sign or create a 373 Message Authentication Codes (MAC) of the contents of the JWS Header 374 and the JWS Payload. The use of the following algorithms for 375 producing JWSs is defined in this section. 377 3.1. "alg" (Algorithm) Header Parameter Values for JWS 379 The table below is the set of "alg" (algorithm) header parameter 380 values defined by this specification for use with JWS, each of which 381 is explained in more detail in the following sections: 383 +-----------+--------------------------------------+----------------+ 384 | alg | Digital Signature or MAC Algorithm | Implementation | 385 | Parameter | | Requirements | 386 | Value | | | 387 +-----------+--------------------------------------+----------------+ 388 | HS256 | HMAC using SHA-256 hash algorithm | REQUIRED | 389 | HS384 | HMAC using SHA-384 hash algorithm | OPTIONAL | 390 | HS512 | HMAC using SHA-512 hash algorithm | OPTIONAL | 391 | RS256 | RSASSA-PKCS-v1_5 using SHA-256 hash | RECOMMENDED | 392 | | algorithm | | 393 | RS384 | RSASSA-PKCS-v1_5 using SHA-384 hash | OPTIONAL | 394 | | algorithm | | 395 | RS512 | RSASSA-PKCS-v1_5 using SHA-512 hash | OPTIONAL | 396 | | algorithm | | 397 | ES256 | ECDSA using P-256 curve and SHA-256 | RECOMMENDED+ | 398 | | hash algorithm | | 399 | ES384 | ECDSA using P-384 curve and SHA-384 | OPTIONAL | 400 | | hash algorithm | | 401 | ES512 | ECDSA using P-521 curve and SHA-512 | OPTIONAL | 402 | | hash algorithm | | 403 | PS256 | RSASSA-PSS using SHA-256 hash | OPTIONAL | 404 | | algorithm and MGF1 mask generation | | 405 | | function with SHA-256 | | 406 | PS384 | RSASSA-PSS using SHA-384 hash | OPTIONAL | 407 | | algorithm and MGF1 mask generation | | 408 | | function with SHA-384 | | 409 | PS512 | RSASSA-PSS using SHA-512 hash | OPTIONAL | 410 | | algorithm and MGF1 mask generation | | 411 | | function with SHA-512 | | 412 | none | No digital signature or MAC value | REQUIRED | 413 | | included | | 414 +-----------+--------------------------------------+----------------+ 416 All the names are short because a core goal of JWS is for the 417 representations to be compact. However, there is no a priori length 418 restriction on "alg" values. 420 The use of "+" in the Implementation Requirements indicates that the 421 requirement strength is likely to be increased in a future version of 422 the specification. 424 See Appendix A for a table cross-referencing the digital signature 425 and MAC "alg" (algorithm) values used in this specification with the 426 equivalent identifiers used by other standards and software packages. 428 3.2. MAC with HMAC SHA-2 Functions 430 Hash-based Message Authentication Codes (HMACs) enable one to use a 431 secret plus a cryptographic hash function to generate a Message 432 Authentication Code (MAC). This can be used to demonstrate that the 433 MAC matches the hashed content, in this case the JWS Signing Input, 434 which therefore demonstrates that whoever generated the MAC was in 435 possession of the secret. The means of exchanging the shared key is 436 outside the scope of this specification. 438 The algorithm for implementing and validating HMACs is provided in 439 RFC 2104 [RFC2104]. This section defines the use of the HMAC SHA- 440 256, HMAC SHA-384, and HMAC SHA-512 functions [SHS]. The "alg" 441 (algorithm) header parameter values "HS256", "HS384", and "HS512" are 442 used in the JWS Header to indicate that the Encoded JWS Signature 443 contains a base64url encoded HMAC value using the respective hash 444 function. 446 A key of the same size as the hash output (for instance, 256 bits for 447 "HS256") or larger MUST be used with this algorithm. 449 The HMAC SHA-256 MAC is generated per RFC 2104, using SHA-256 as the 450 hash algorithm "H", using the octets of the ASCII [USASCII] 451 representation of the JWS Signing Input as the "text" value, and 452 using the shared key. The HMAC output value is the JWS Signature. 453 The JWS signature is base64url encoded to produce the Encoded JWS 454 Signature. 456 The HMAC SHA-256 MAC for a JWS is validated by computing an HMAC 457 value per RFC 2104, using SHA-256 as the hash algorithm "H", using 458 the octets of the ASCII representation of the received JWS Signing 459 Input as the "text" value, and using the shared key. This computed 460 HMAC value is then compared to the result of base64url decoding the 461 received Encoded JWS signature. Alternatively, the computed HMAC 462 value can be base64url encoded and compared to the received Encoded 463 JWS Signature, as this comparison produces the same result as 464 comparing the unencoded values. In either case, if the values match, 465 the HMAC has been validated. If the validation fails, the JWS MUST 466 be rejected. 468 Securing content with the HMAC SHA-384 and HMAC SHA-512 algorithms is 469 performed identically to the procedure for HMAC SHA-256 - just using 470 the corresponding hash algorithm with correspondingly larger minimum 471 key sizes and result values: 384 bits each for HMAC SHA-384 and 512 472 bits each for HMAC SHA-512. 474 An example using this algorithm is shown in Appendix A.1 of [JWS]. 476 3.3. Digital Signature with RSASSA-PKCS1-V1_5 478 This section defines the use of the RSASSA-PKCS1-V1_5 digital 479 signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447] 480 (commonly known as PKCS #1), using SHA-256, SHA-384, or SHA-512 [SHS] 481 as the hash functions. The "alg" (algorithm) header parameter values 482 "RS256", "RS384", and "RS512" are used in the JWS Header to indicate 483 that the Encoded JWS Signature contains a base64url encoded RSASSA- 484 PKCS1-V1_5 digital signature using the respective hash function. 486 A key of size 2048 bits or larger MUST be used with these algorithms. 488 The RSASSA-PKCS1-V1_5 SHA-256 digital signature is generated as 489 follows: 491 1. Generate a digital signature of the octets of the ASCII 492 representation of the JWS Signing Input using RSASSA-PKCS1-V1_5- 493 SIGN and the SHA-256 hash function with the desired private key. 494 The output will be an octet sequence. 496 2. Base64url encode the resulting octet sequence. 498 The output is the Encoded JWS Signature for that JWS. 500 The RSASSA-PKCS1-V1_5 SHA-256 digital signature for a JWS is 501 validated as follows: 503 1. Take the Encoded JWS Signature and base64url decode it into an 504 octet sequence. If decoding fails, the JWS MUST be rejected. 506 2. Submit the octets of the ASCII representation of the JWS Signing 507 Input and the public key corresponding to the private key used by 508 the signer to the RSASSA-PKCS1-V1_5-VERIFY algorithm using SHA- 509 256 as the hash function. 511 3. If the validation fails, the JWS MUST be rejected. 513 Signing with the RSASSA-PKCS1-V1_5 SHA-384 and RSASSA-PKCS1-V1_5 SHA- 514 512 algorithms is performed identically to the procedure for RSASSA- 515 PKCS1-V1_5 SHA-256 - just using the corresponding hash algorithm with 516 correspondingly larger result values: 384 bits for RSASSA-PKCS1-V1_5 517 SHA-384 and 512 bits for RSASSA-PKCS1-V1_5 SHA-512. 519 An example using this algorithm is shown in Appendix A.2 of [JWS]. 521 3.4. Digital Signature with ECDSA 523 The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides 524 for the use of Elliptic Curve cryptography, which is able to provide 525 equivalent security to RSA cryptography but using shorter key sizes 526 and with greater processing speed. This means that ECDSA digital 527 signatures will be substantially smaller in terms of length than 528 equivalently strong RSA digital signatures. 530 This specification defines the use of ECDSA with the P-256 curve and 531 the SHA-256 cryptographic hash function, ECDSA with the P-384 curve 532 and the SHA-384 hash function, and ECDSA with the P-521 curve and the 533 SHA-512 hash function. The P-256, P-384, and P-521 curves are 534 defined in [DSS]. The "alg" (algorithm) header parameter values 535 "ES256", "ES384", and "ES512" are used in the JWS Header to indicate 536 that the Encoded JWS Signature contains a base64url encoded ECDSA 537 P-256 SHA-256, ECDSA P-384 SHA-384, or ECDSA P-521 SHA-512 digital 538 signature, respectively. 540 The ECDSA P-256 SHA-256 digital signature is generated as follows: 542 1. Generate a digital signature of the octets of the ASCII 543 representation of the JWS Signing Input using ECDSA P-256 SHA-256 544 with the desired private key. The output will be the pair (R, 545 S), where R and S are 256 bit unsigned integers. 547 2. Turn R and S into octet sequences in big endian order, with each 548 array being be 32 octets long. The array representations MUST 549 NOT be shortened to omit any leading zero octets contained in the 550 values. 552 3. Concatenate the two octet sequences in the order R and then S. 553 (Note that many ECDSA implementations will directly produce this 554 concatenation as their output.) 556 4. Base64url encode the resulting 64 octet sequence. 558 The output is the Encoded JWS Signature for the JWS. 560 The ECDSA P-256 SHA-256 digital signature for a JWS is validated as 561 follows: 563 1. Take the Encoded JWS Signature and base64url decode it into an 564 octet sequence. If decoding fails, the JWS MUST be rejected. 566 2. The output of the base64url decoding MUST be a 64 octet sequence. 567 If decoding does not result in a 64 octet sequence, the JWS MUST 568 be rejected. 570 3. Split the 64 octet sequence into two 32 octet sequences. The 571 first array will be R and the second S (with both being in big 572 endian octet order). 574 4. Submit the octets of the ASCII representation of the JWS Signing 575 Input R, S and the public key (x, y) to the ECDSA P-256 SHA-256 576 validator. 578 5. If the validation fails, the JWS MUST be rejected. 580 Note that ECDSA digital signature contains a value referred to as K, 581 which is a random number generated for each digital signature 582 instance. This means that two ECDSA digital signatures using exactly 583 the same input parameters will output different signature values 584 because their K values will be different. A consequence of this is 585 that one cannot validate an ECDSA signature by recomputing the 586 signature and comparing the results. 588 Signing with the ECDSA P-384 SHA-384 and ECDSA P-521 SHA-512 589 algorithms is performed identically to the procedure for ECDSA P-256 590 SHA-256 - just using the corresponding hash algorithm with 591 correspondingly larger result values. For ECDSA P-384 SHA-384, R and 592 S will be 384 bits each, resulting in a 96 octet sequence. For ECDSA 593 P-521 SHA-512, R and S will be 521 bits each, resulting in a 132 594 octet sequence. 596 Examples using these algorithms are shown in Appendices A.3 and A.4 597 of [JWS]. 599 3.5. Digital Signature with RSASSA-PSS 601 This section defines the use of the RSASSA-PSS digital signature 602 algorithm as defined in Section 8.1 of RFC 3447 [RFC3447] with the 603 MGF1 mask generation function, always using the same hash function 604 for both the RSASSA-PSS hash function and the MGF1 hash function. 605 Use of SHA-256, SHA-384, and SHA-512 as these hash functions is 606 defined. All other algorithm parameters use the defaults specified 607 in Section A.2.3 of RFC 3447. The "alg" (algorithm) header parameter 608 values "PS256", "PS384", and "PS512" are used in the JWS Header to 609 indicate that the Encoded JWS Signature contains a base64url encoded 610 RSASSA-PSS digital signature using the respective hash function in 611 both roles. 613 A key of size 2048 bits or larger MUST be used with this algorithm. 615 The RSASSA-PSS SHA-256 digital signature is generated as follows: 617 1. Generate a digital signature of the octets of the ASCII 618 representation of the JWS Signing Input using RSASSA-PSS-SIGN, 619 the SHA-256 hash function, and the MGF1 mask generation function 620 with SHA-256 with the desired private key. The output will be an 621 octet sequence. 623 2. Base64url encode the resulting octet sequence. 625 The output is the Encoded JWS Signature for that JWS. 627 The RSASSA-PSS SHA-256 digital signature for a JWS is validated as 628 follows: 630 1. Take the Encoded JWS Signature and base64url decode it into an 631 octet sequence. If decoding fails, the JWS MUST be rejected. 633 2. Submit the octets of the ASCII representation of the JWS Signing 634 Input and the public key corresponding to the private key used by 635 the signer to the RSASSA-PSS-VERIFY algorithm using SHA-256 as 636 the hash function and using MGF1 as the mask generation function 637 with SHA-256. 639 3. If the validation fails, the JWS MUST be rejected. 641 Signing with the RSASSA-PSS SHA-384 and RSASSA-PSS SHA-512 algorithms 642 is performed identically to the procedure for RSASSA-PSS SHA-256 - 643 just using the alternative hash algorithm in both roles. 645 3.6. Using the Algorithm "none" 647 JWSs MAY also be created that do not provide integrity protection. 648 Such a JWS is called a "Plaintext JWS". Plaintext JWSs MUST use the 649 "alg" value "none", and are formatted identically to other JWSs, but 650 with the empty string for its JWS Signature value. 652 3.7. Additional Digital Signature/MAC Algorithms and Parameters 654 Additional algorithms MAY be used to protect JWSs with corresponding 655 "alg" (algorithm) header parameter values being defined to refer to 656 them. New "alg" header parameter values SHOULD either be registered 657 in the IANA JSON Web Signature and Encryption Algorithms registry 658 Section 6.1 or be a value that contains a Collision Resistant 659 Namespace. In particular, it is permissible to use the algorithm 660 identifiers defined in XML DSIG [RFC3275], XML DSIG 2.0 661 [W3C.CR-xmldsig-core2-20120124], and related specifications as "alg" 662 values. 664 As indicated by the common registry, JWSs and JWEs share a common 665 "alg" value space. The values used by the two specifications MUST be 666 distinct, as the "alg" value can be used to determine whether the 667 object is a JWS or JWE. 669 Likewise, additional reserved Header Parameter Names can be defined 670 via the IANA JSON Web Signature and Encryption Header Parameters 671 registry [JWS]. As indicated by the common registry, JWSs and JWEs 672 share a common header parameter space; when a parameter is used by 673 both specifications, its usage must be compatible between the 674 specifications. 676 4. Cryptographic Algorithms for JWE 678 JWE uses cryptographic algorithms to encrypt the Content Encryption 679 Key (CEK) and the Plaintext. This section specifies a set of 680 specific algorithms for these purposes. 682 4.1. "alg" (Algorithm) Header Parameter Values for JWE 684 The table below is the set of "alg" (algorithm) header parameter 685 values that are defined by this specification for use with JWE. 686 These algorithms are used to encrypt the CEK, producing the JWE 687 Encrypted Key, or to use key agreement to agree upon the CEK. 689 +-------------------+-----------------+------------+----------------+ 690 | alg Parameter | Key Management | Additional | Implementation | 691 | Value | Algorithm | Header | Requirements | 692 | | | Parameters | | 693 +-------------------+-----------------+------------+----------------+ 694 | RSA1_5 | RSAES-PKCS1-V1_ | (none) | REQUIRED | 695 | | 5[RFC3447] | | | 696 | RSA-OAEP | RSAES using | (none) | OPTIONAL | 697 | | Optimal | | | 698 | | Asymmetric | | | 699 | | Encryption | | | 700 | | Padding (OAEP) | | | 701 | | [RFC3447], with | | | 702 | | the default | | | 703 | | parameters | | | 704 | | specified by | | | 705 | | RFC 3447 in | | | 706 | | Section A.2.1 | | | 707 | A128KW | Advanced | (none) | RECOMMENDED | 708 | | Encryption | | | 709 | | Standard (AES) | | | 710 | | Key Wrap | | | 711 | | Algorithm | | | 712 | | [RFC3394] using | | | 713 | | the default | | | 714 | | initial value | | | 715 | | specified in | | | 716 | | Section 2.2.3.1 | | | 717 | | and using 128 | | | 718 | | bit keys | | | 719 | A192KW | AES Key Wrap | (none) | OPTIONAL | 720 | | Algorithm using | | | 721 | | the default | | | 722 | | initial value | | | 723 | | specified in | | | 724 | | Section 2.2.3.1 | | | 725 | | and using 192 | | | 726 | | bit keys | | | 727 | A256KW | AES Key Wrap | (none) | RECOMMENDED | 728 | | Algorithm using | | | 729 | | the default | | | 730 | | initial value | | | 731 | | specified in | | | 732 | | Section 2.2.3.1 | | | 733 | | and using 256 | | | 734 | | bit keys | | | 735 | dir | Direct use of a | (none) | RECOMMENDED | 736 | | shared | | | 737 | | symmetric key | | | 738 | | as the Content | | | 739 | | Encryption Key | | | 740 | | (CEK) for the | | | 741 | | content | | | 742 | | encryption step | | | 743 | | (rather than | | | 744 | | using the | | | 745 | | symmetric key | | | 746 | | to wrap the | | | 747 | | CEK) | | | 748 | ECDH-ES | Elliptic Curve | "epk", | RECOMMENDED+ | 749 | | Diffie-Hellman | "apu", | | 750 | | Ephemeral | "apv" | | 751 | | Static | | | 752 | | [RFC6090] key | | | 753 | | agreement using | | | 754 | | the Concat KDF, | | | 755 | | as defined in | | | 756 | | Section 5.8.1 | | | 757 | | of | | | 758 | | [NIST.800-56A], | | | 759 | | with the | | | 760 | | agreed-upon key | | | 761 | | being used | | | 762 | | directly as the | | | 763 | | Content | | | 764 | | Encryption Key | | | 765 | | (CEK) (rather | | | 766 | | than being used | | | 767 | | to wrap the | | | 768 | | CEK), as | | | 769 | | specified in | | | 770 | | Section 4.7 | | | 771 | ECDH-ES+A128KW | Elliptic Curve | "epk", | RECOMMENDED | 772 | | Diffie-Hellman | "apu", | | 773 | | Ephemeral | "apv" | | 774 | | Static key | | | 775 | | agreement per | | | 776 | | "ECDH-ES" and | | | 777 | | Section 4.7, | | | 778 | | where the | | | 779 | | agreed-upon key | | | 780 | | is used to wrap | | | 781 | | the Content | | | 782 | | Encryption Key | | | 783 | | (CEK) with the | | | 784 | | "A128KW" | | | 785 | | function | | | 786 | | (rather than | | | 787 | | being used | | | 788 | | directly as the | | | 789 | | CEK) | | | 790 | ECDH-ES+A192KW | Elliptic Curve | "epk", | OPTIONAL | 791 | | Diffie-Hellman | "apu", | | 792 | | Ephemeral | "apv" | | 793 | | Static key | | | 794 | | agreement, | | | 795 | | where the | | | 796 | | agreed-upon key | | | 797 | | is used to wrap | | | 798 | | the Content | | | 799 | | Encryption Key | | | 800 | | (CEK) with the | | | 801 | | "A192KW" | | | 802 | | function | | | 803 | | (rather than | | | 804 | | being used | | | 805 | | directly as the | | | 806 | | CEK) | | | 807 | ECDH-ES+A256KW | Elliptic Curve | "epk", | RECOMMENDED | 808 | | Diffie-Hellman | "apu", | | 809 | | Ephemeral | "apv" | | 810 | | Static key | | | 811 | | agreement, | | | 812 | | where the | | | 813 | | agreed-upon key | | | 814 | | is used to wrap | | | 815 | | the Content | | | 816 | | Encryption Key | | | 817 | | (CEK) with the | | | 818 | | "A256KW" | | | 819 | | function | | | 820 | | (rather than | | | 821 | | being used | | | 822 | | directly as the | | | 823 | | CEK) | | | 824 | A128GCMKW | AES in | "iv", | OPTIONAL | 825 | | Galois/Counter | "tag" | | 826 | | Mode (GCM) | | | 827 | | [AES] | | | 828 | | [NIST.800-38D] | | | 829 | | using 128 bit | | | 830 | | keys | | | 831 | A192GCMKW | AES GCM using | "iv", | OPTIONAL | 832 | | 192 bit keys | "tag" | | 833 | A256GCMKW | AES GCM using | "iv", | OPTIONAL | 834 | | 256 bit keys | "tag" | | 835 | PBES2-HS256+A128K | PBES2 [RFC2898] | "p2s", | OPTIONAL | 836 | W | with HMAC | "p2c" | | 837 | | SHA-256 as the | | | 838 | | PRF and AES Key | | | 839 | | Wrap [RFC3394] | | | 840 | | using 128 bit | | | 841 | | keys for the | | | 842 | | encryption | | | 843 | | scheme | | | 844 | PBES2-HS256+A192K | PBES2 with HMAC | "p2s", | OPTIONAL | 845 | W | SHA-256 as the | "p2c" | | 846 | | PRF and AES Key | | | 847 | | Wrap using 192 | | | 848 | | bit keys for | | | 849 | | the encryption | | | 850 | | scheme | | | 851 | PBES2-HS256+A256K | PBES2 with HMAC | "p2s", | OPTIONAL | 852 | W | SHA-256 as the | "p2c" | | 853 | | PRF and AES Key | | | 854 | | Wrap using 256 | | | 855 | | bit keys for | | | 856 | | the encryption | | | 857 | | scheme | | | 858 +-------------------+-----------------+------------+----------------+ 860 All the names are short because a core goal of JWE is for the 861 representations to be compact. However, there is no a priori length 862 restriction on "alg" values. 864 The Additional Header Parameters column indicates what additional 865 Header Parameters are used by the algorithm, beyond "alg", which all 866 use. All but "dir" and "ECDH-ES" also produce a JWE Encrypted Key 867 value. 869 The use of "+" in the Implementation Requirements indicates that the 870 requirement strength is likely to be increased in a future version of 871 the specification. 873 4.2. "enc" (Encryption Method) Header Parameter Values for JWE 875 The table below is the set of "enc" (encryption method) header 876 parameter values that are defined by this specification for use with 877 JWE. These algorithms are used to encrypt the Plaintext, which 878 produces the Ciphertext. 880 +-------------+------------------------+------------+---------------+ 881 | enc | Content Encryption | Additional | Implementatio | 882 | Parameter | Algorithm | Header | nRequirements | 883 | Value | | Parameters | | 884 +-------------+------------------------+------------+---------------+ 885 | A128CBC-HS2 | The | (none) | REQUIRED | 886 | 56 | AES_128_CBC_HMAC_SHA_2 | | | 887 | | 56 authenticated | | | 888 | | encryption algorithm, | | | 889 | | as defined in | | | 890 | | Section 4.10.3. This | | | 891 | | algorithm uses a 256 | | | 892 | | bit key. | | | 893 | A192CBC-HS3 | The | (none) | OPTIONAL | 894 | 84 | AES_192_CBC_HMAC_SHA_3 | | | 895 | | 84 authenticated | | | 896 | | encryption algorithm, | | | 897 | | as defined in | | | 898 | | Section 4.10.4. This | | | 899 | | algorithm uses a 384 | | | 900 | | bit key. | | | 901 | A256CBC-HS5 | The | (none) | REQUIRED | 902 | 12 | AES_256_CBC_HMAC_SHA_5 | | | 903 | | 12 authenticated | | | 904 | | encryption algorithm, | | | 905 | | as defined in | | | 906 | | Section 4.10.5. This | | | 907 | | algorithm uses a 512 | | | 908 | | bit key. | | | 909 | A128GCM | AES in Galois/Counter | (none) | RECOMMENDED | 910 | | Mode (GCM) [AES] | | | 911 | | [NIST.800-38D] using | | | 912 | | 128 bit keys | | | 913 | A192GCM | AES GCM using 192 bit | (none) | OPTIONAL | 914 | | keys | | | 915 | A256GCM | AES GCM using 256 bit | (none) | RECOMMENDED | 916 | | keys | | | 917 +-------------+------------------------+------------+---------------+ 919 The Additional Header Parameters column indicates what additional 920 Header Parameters are used by the algorithm, beyond "enc", which all 921 use. All also use a JWE Initialization Vector value and produce JWE 922 Ciphertext and JWE Authentication Tag values. 924 See Appendix B for a table cross-referencing the encryption "alg" 925 (algorithm) and "enc" (encryption method) values used in this 926 specification with the equivalent identifiers used by other standards 927 and software packages. 929 4.3. Key Encryption with RSAES-PKCS1-V1_5 931 This section defines the specifics of encrypting a JWE CEK with 932 RSAES-PKCS1-V1_5 [RFC3447]. The "alg" header parameter value 933 "RSA1_5" is used in this case. 935 A key of size 2048 bits or larger MUST be used with this algorithm. 937 An example using this algorithm is shown in Appendix A.2 of [JWE]. 939 4.4. Key Encryption with RSAES OAEP 941 This section defines the specifics of encrypting a JWE CEK with RSAES 942 using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447], with 943 the default parameters specified by RFC 3447 in Section A.2.1. The 944 "alg" header parameter value "RSA-OAEP" is used in this case. 946 A key of size 2048 bits or larger MUST be used with this algorithm. 948 An example using this algorithm is shown in Appendix A.1 of [JWE]. 950 4.5. Key Wrapping with AES Key Wrap 952 This section defines the specifics of encrypting a JWE CEK with the 953 Advanced Encryption Standard (AES) Key Wrap Algorithm [RFC3394] using 954 the default initial value specified in Section 2.2.3.1 using 128, 955 192, or 256 bit keys. The "alg" header parameter values "A128KW", 956 "A192KW", or "A256KW" are respectively used in this case. 958 An example using this algorithm is shown in Appendix A.3 of [JWE]. 960 4.6. Direct Encryption with a Shared Symmetric Key 962 This section defines the specifics of directly performing symmetric 963 key encryption without performing a key wrapping step. In this case, 964 the shared symmetric key is used directly as the Content Encryption 965 Key (CEK) value for the "enc" algorithm. An empty octet sequence is 966 used as the JWE Encrypted Key value. The "alg" header parameter 967 value "dir" is used in this case. 969 4.7. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static 970 (ECDH-ES) 972 This section defines the specifics of key agreement with Elliptic 973 Curve Diffie-Hellman Ephemeral Static [RFC6090], and using the Concat 974 KDF, as defined in Section 5.8.1 of [NIST.800-56A]. The key 975 agreement result can be used in one of two ways: 977 1. directly as the Content Encryption Key (CEK) for the "enc" 978 algorithm, in the Direct Key Agreement mode, or 980 2. as a symmetric key used to wrap the CEK with either the "A128KW", 981 "A192KW", or "A256KW" algorithms, in the Key Agreement with Key 982 Wrapping mode. 984 The "alg" header parameter value "ECDH-ES" is used in the Direct Key 985 Agreement mode and the values "ECDH-ES+A128KW", "ECDH-ES+A192KW", or 986 "ECDH-ES+A256KW" are used in the Key Agreement with Key Wrapping 987 mode. 989 In the Direct Key Agreement case, the output of the Concat KDF MUST 990 be a key of the same length as that used by the "enc" algorithm; in 991 this case, the empty octet sequence is used as the JWE Encrypted Key 992 value. In the Key Agreement with Key Wrapping case, the output of 993 the Concat KDF MUST be a key of the length needed for the specified 994 key wrapping algorithm, one of 128, 192, or 256 bits respectively. 996 A new ephemeral public key value MUST be generated for each key 997 agreement transaction. 999 4.7.1. Header Parameters Used for ECDH Key Agreement 1001 The following Header Parameter Names are reserved and are used for 1002 key agreement as defined below. They MAY also be used for other 1003 algorithms if so specified by those algorithm parameter definitions. 1005 4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter 1007 The "epk" (ephemeral public key) value created by the originator for 1008 the use in key agreement algorithms. This key is represented as a 1009 JSON Web Key [JWK] bare public key value. This Header Parameter is 1010 REQUIRED and MUST be understood and processed by implementations when 1011 these algorithms are used. 1013 4.7.1.2. "apu" (Agreement PartyUInfo) Header Parameter 1015 The "apu" (agreement PartyUInfo) value for key agreement algorithms 1016 using it (such as "ECDH-ES"), represented as a base64url encoded 1017 string. When used, the PartyUInfo value contains information about 1018 the sender. Use of this Header Parameter is OPTIONAL. This Header 1019 Parameter MUST be understood and processed by implementations when 1020 these algorithms are used. 1022 4.7.1.3. "apv" (Agreement PartyVInfo) Header Parameter 1024 The "apv" (agreement PartyVInfo) value for key agreement algorithms 1025 using it (such as "ECDH-ES"), represented as a base64url encoded 1026 string. When used, the PartyVInfo value contains information about 1027 the receiver. Use of this Header Parameter is OPTIONAL. This Header 1028 Parameter MUST be understood and processed by implementations when 1029 these algorithms are used. 1031 4.7.2. Key Derivation for ECDH Key Agreement 1033 The key derivation process derives the agreed upon key from the 1034 shared secret Z established through the ECDH algorithm, per Section 1035 6.2.2.2 of [NIST.800-56A]. 1037 Key derivation is performed using the Concat KDF, as defined in 1038 Section 5.8.1 of [NIST.800-56A], where the Digest Method is SHA-256. 1039 The Concat KDF parameters are set as follows: 1041 Z This is set to the representation of the shared secret Z as an 1042 octet sequence. 1044 keydatalen This is set to the number of bits in the desired output 1045 key. For "ECDH-ES", this is length of the key used by the "enc" 1046 algorithm. For "ECDH-ES+A128KW", "ECDH-ES+A192KW", and 1047 "ECDH-ES+A256KW", this is 128, 192, and 256, respectively. 1049 AlgorithmID In the Direct Key Agreement case, this is set to the 1050 octets of the UTF-8 representation of the "enc" header parameter 1051 value. In the Key Agreement with Key Wrapping case, this is set 1052 to the octets of the UTF-8 representation of the "alg" header 1053 parameter value. 1055 PartyUInfo The PartyUInfo value is of the form Datalen || Data, 1056 where Data is a variable-length string of zero or more octets, and 1057 Datalen is a fixed-length, big endian 32 bit counter that 1058 indicates the length (in octets) of Data, with || being 1059 concatenation. If an "apu" (agreement PartyUInfo) header 1060 parameter is present, Data is set to the result of base64url 1061 decoding the "apu" value and Datalen is set to the number of 1062 octets in Data. Otherwise, Datalen is set to 0 and Data is set to 1063 the empty octet sequence. 1065 PartyVInfo The PartyVInfo value is of the form Datalen || Data, 1066 where Data is a variable-length string of zero or more octets, and 1067 Datalen is a fixed-length, big endian 32 bit counter that 1068 indicates the length (in octets) of Data, with || being 1069 concatenation. If an "apv" (agreement PartyVInfo) header 1070 parameter is present, Data is set to the result of base64url 1071 decoding the "apv" value and Datalen is set to the number of 1072 octets in Data. Otherwise, Datalen is set to 0 and Data is set to 1073 the empty octet sequence. 1075 SuppPubInfo This is set to the keydatalen represented as a 32 bit 1076 big endian integer. 1078 SuppPrivInfo This is set to the empty octet sequence. 1080 See Appendix D for an example key agreement computation using this 1081 method. 1083 Note: The Diffie-Hellman Key Agreement Method [RFC2631] uses a key 1084 derivation function similar to the Concat KDF, but with fewer 1085 parameters. Rather than having separate PartyUInfo and PartyVInfo 1086 parameters, it uses a single PartyAInfo parameter, which is a random 1087 string provided by the sender, that contains 512 bits of information, 1088 when provided. It has no SuppPrivInfo parameter. Should it be 1089 appropriate for the application, key agreement can be performed in a 1090 manner akin to RFC 2631 by using the PartyAInfo value as the "apu" 1091 (Agreement PartyUInfo) header parameter value, when provided, and by 1092 using no "apv" (Agreement PartyVInfo) header parameter. 1094 4.8. Key Encryption with AES GCM 1096 This section defines the specifics of encrypting a JWE Content 1097 Encryption Key (CEK) with Advanced Encryption Standard (AES) in 1098 Galois/Counter Mode (GCM) [AES] [NIST.800-38D] using 128, 192, or 256 1099 bit keys. The "alg" header parameter values "A128GCMKW", 1100 "A192GCMKW", or "A256GCMKW" are respectively used in this case. 1102 Use of an Initialization Vector of size 96 bits is REQUIRED with this 1103 algorithm. The Initialization Vector is represented in base64url 1104 encoded form as the "iv" (initialization vector) header parameter 1105 value. 1107 The Additional Authenticated Data value used is the empty octet 1108 string. 1110 The requested size of the Authentication Tag output MUST be 128 bits, 1111 regardless of the key size. 1113 The JWE Encrypted Key value is the Ciphertext output. 1115 The Authentication Tag output is represented in base64url encoded 1116 form as the "tag" (authentication tag) header parameter value. 1118 4.8.1. Header Parameters Used for AES GCM Key Encryption 1120 The following Header Parameters are used for AES GCM key encryption. 1121 They MAY also be used by other algorithms if so specified by those 1122 algorithm parameter definitions. 1124 4.8.1.1. "iv" (Initialization Vector) Header Parameter 1126 The "iv" (initialization vector) header parameter value is the 1127 base64url encoded representation of the Initialization Vector value 1128 used for the key encryption operation. This Header Parameter is 1129 REQUIRED and MUST be understood and processed by implementations when 1130 these algorithms are used. 1132 4.8.1.2. "tag" (Authentication Tag) Header Parameter 1134 The "tag" (authentication tag) header parameter value is the 1135 base64url encoded representation of the Authentication Tag value 1136 resulting from the key encryption operation. This Header Parameter 1137 is REQUIRED and MUST be understood and processed by implementations 1138 when these algorithms are used. 1140 4.9. Key Encryption with PBES2 1142 The "PBES2-HS256+A128KW", "PBES2-HS256+A192KW", and 1143 "PBES2-HS256+A256KW" algorithms are used to encrypt a JWE Content 1144 Master Key using a user-supplied password to derive the key 1145 encryption key. With these algorithms, the derived key is used to 1146 encrypt the JWE Content Master Key. These algorithms combine a key 1147 derivation function with an encryption scheme to encrypt the JWE 1148 Content Master Key according to PBES2 from Section 6.2 of [RFC2898]. 1150 These algorithms use HMAC SHA-256 as the Pseudo-Random Function (PRF) 1151 and AES Key Wrap [RFC3394] for the encryption scheme. The salt (s) 1152 and iteration count (c) parameters MUST be provided as the "p2s" and 1153 "p2c" header parameter values. The algorithms respectively use 128, 1154 192, and 256 bit AES Key Wrap keys. Their derived-key lengths 1155 (dkLen) respectively are 16, 24, and 32 octets. 1157 4.9.1. Header Parameters Used for PBES2 Key Encryption 1159 The following Header Parameters are used for Key Encryption with 1160 PBES2. 1162 4.9.1.1. "p2s" (PBES2 salt) Parameter 1164 The "p2s" (PBES2 salt) header parameter contains the PBKDF2 salt 1165 value (s) as a base64url encoded string. This value MUST NOT be the 1166 empty string. This Header Parameter is REQUIRED and MUST be 1167 understood and processed by implementations when these algorithms are 1168 used. 1170 The salt expands the possible keys that can be derived from a given 1171 password. [RFC2898] originally recommended a minimum salt length of 1172 8 octets (since there is no concern here of a derived key being re- 1173 used for different purposes). The salt MUST be generated randomly; 1174 see [RFC4086] for considerations on generating random values. 1176 4.9.1.2. "p2c" (PBES2 count) Parameter 1178 The "p2c" (PBES2 count) header parameter contains the PBKDF2 1179 iteration count (c), as an integer. This value MUST NOT be less than 1180 1, as per [RFC2898]. This Header Parameter is REQUIRED and MUST be 1181 understood and processed by implementations when these algorithms are 1182 used. 1184 The iteration count adds computational expense, ideally compounded by 1185 the possible range of keys introduced by the salt. [RFC2898] 1186 originally recommended a minimum iteration count of 1000. 1188 4.10. AES_CBC_HMAC_SHA2 Algorithms 1190 This section defines a family of authenticated encryption algorithms 1191 built using a composition of Advanced Encryption Standard (AES) in 1192 Cipher Block Chaining (CBC) mode with PKCS #5 padding [AES] 1193 [NIST.800-38A] operations and HMAC [RFC2104] [SHS] operations. This 1194 algorithm family is called AES_CBC_HMAC_SHA2. It also defines three 1195 instances of this family, the first using 128 bit CBC keys and HMAC 1196 SHA-256, the second using 192 bit CBC keys and HMAC SHA-384, and the 1197 third using 256 bit CBC keys and HMAC SHA-512. Test cases for these 1198 algorithms can be found in Appendix C. 1200 These algorithms are based upon Authenticated Encryption with AES-CBC 1201 and HMAC-SHA [I-D.mcgrew-aead-aes-cbc-hmac-sha2], performing the same 1202 cryptographic computations, but with the Initialization Vector and 1203 Authentication Tag values remaining separate, rather than being 1204 concatenated with the Ciphertext value in the output representation. 1205 This option is discussed in Appendix B of that specification. This 1206 algorithm family is a generalization of the algorithm family in 1207 [I-D.mcgrew-aead-aes-cbc-hmac-sha2], and can be used to implement 1208 those algorithms. 1210 4.10.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 1212 We use the following notational conventions. 1214 CBC-PKCS5-ENC(X, P) denotes the AES CBC encryption of P using PKCS 1215 #5 padding using the cipher with the key X. 1217 MAC(Y, M) denotes the application of the Message Authentication 1218 Code (MAC) to the message M, using the key Y. 1220 The concatenation of two octet strings A and B is denoted as 1221 A || B. 1223 4.10.2. Generic AES_CBC_HMAC_SHA2 Algorithm 1225 This section defines AES_CBC_HMAC_SHA2 in a manner that is 1226 independent of the AES CBC key size or hash function to be used. 1227 Section 4.10.2.1 and Section 4.10.2.2 define the generic encryption 1228 and decryption algorithms. Section 4.10.3 and Section 4.10.5 define 1229 instances of AES_CBC_HMAC_SHA2 that specify those details. 1231 4.10.2.1. AES_CBC_HMAC_SHA2 Encryption 1233 The authenticated encryption algorithm takes as input four octet 1234 strings: a secret key K, a plaintext P, associated data A, and an 1235 initialization vector IV. The authenticated ciphertext value E and 1236 the authentication tag value T are provided as outputs. The data in 1237 the plaintext are encrypted and authenticated, and the associated 1238 data are authenticated, but not encrypted. 1240 The encryption process is as follows, or uses an equivalent set of 1241 steps: 1243 1. The secondary keys MAC_KEY and ENC_KEY are generated from the 1244 input key K as follows. Each of these two keys is an octet 1245 string. 1247 MAC_KEY consists of the initial MAC_KEY_LEN octets of K, in 1248 order. 1250 ENC_KEY consists of the final ENC_KEY_LEN octets of K, in 1251 order. 1253 Here we denote the number of octets in the MAC_KEY as 1254 MAC_KEY_LEN, and the number of octets in ENC_KEY as ENC_KEY_LEN; 1255 the values of these parameters are specified by the AEAD 1256 algorithms (in Section 4.10.3 and Section 4.10.5). The number of 1257 octets in the input key K is the sum of MAC_KEY_LEN and 1258 ENC_KEY_LEN. When generating the secondary keys from K, MAC_KEY 1259 and ENC_KEY MUST NOT overlap. Note that the MAC key comes before 1260 the encryption key in the input key K; this is in the opposite 1261 order of the algorithm names in the identifier 1262 "AES_CBC_HMAC_SHA2". 1264 2. The Initialization Vector (IV) used is a 128 bit value generated 1265 randomly or pseudorandomly for use in the cipher. 1267 3. The plaintext is CBC encrypted using PKCS #5 padding using 1268 ENC_KEY as the key, and the IV. We denote the ciphertext output 1269 from this step as E. 1271 4. The octet string AL is equal to the number of bits in A expressed 1272 as a 64-bit unsigned integer in network byte order. 1274 5. A message authentication tag T is computed by applying HMAC 1275 [RFC2104] to the following data, in order: 1277 the associated data A, 1279 the initialization vector IV, 1281 the ciphertext E computed in the previous step, and 1283 the octet string AL defined above. 1285 The string MAC_KEY is used as the MAC key. We denote the output 1286 of the MAC computed in this step as M. The first T_LEN bits of M 1287 are used as T. 1289 6. The Ciphertext E and the Authentication Tag T are returned as the 1290 outputs of the authenticated encryption. 1292 The encryption process can be illustrated as follows. Here K, P, A, 1293 IV, and E denote the key, plaintext, associated data, initialization 1294 vector, and ciphertext, respectively. 1296 MAC_KEY = initial MAC_KEY_LEN bytes of K, 1298 ENC_KEY = final ENC_KEY_LEN bytes of K, 1300 E = CBC-PKCS5-ENC(ENC_KEY, P), 1302 M = MAC(MAC_KEY, A || IV || E || AL), 1304 T = initial T_LEN bytes of M. 1306 4.10.2.2. AES_CBC_HMAC_SHA2 Decryption 1308 The authenticated decryption operation has four inputs: K, A, E, and 1309 T as defined above. It has only a single output, either a plaintext 1310 value P or a special symbol FAIL that indicates that the inputs are 1311 not authentic. The authenticated decryption algorithm is as follows, 1312 or uses an equivalent set of steps: 1314 1. The secondary keys MAC_KEY and ENC_KEY are generated from the 1315 input key K as in Step 1 of Section 4.10.2.1. 1317 2. The integrity and authenticity of A and E are checked by 1318 computing an HMAC with the inputs as in Step 5 of 1319 Section 4.10.2.1. The value T, from the previous step, is 1320 compared to the first MAC_KEY length bits of the HMAC output. If 1321 those values are identical, then A and E are considered valid, 1322 and processing is continued. Otherwise, all of the data used in 1323 the MAC validation are discarded, and the AEAD decryption 1324 operation returns an indication that it failed, and the operation 1325 halts. (But see Section 10 of [JWE] for security considerations 1326 on thwarting timing attacks.) 1328 3. The value E is decrypted and the PKCS #5 padding is removed. The 1329 value IV is used as the initialization vector. The value ENC_KEY 1330 is used as the decryption key. 1332 4. The plaintext value is returned. 1334 4.10.3. AES_128_CBC_HMAC_SHA_256 1336 This algorithm is a concrete instantiation of the generic 1337 AES_CBC_HMAC_SHA2 algorithm above. It uses the HMAC message 1338 authentication code [RFC2104] with the SHA-256 hash function [SHS] to 1339 provide message authentication, with the HMAC output truncated to 128 1340 bits, corresponding to the HMAC-SHA-256-128 algorithm defined in 1341 [RFC4868]. For encryption, it uses AES in the Cipher Block Chaining 1342 (CBC) mode of operation as defined in Section 6.2 of [NIST.800-38A], 1343 with PKCS #5 padding. 1345 The input key K is 32 octets long. 1347 The AES CBC IV is 16 octets long. ENC_KEY_LEN is 16 octets. 1349 The SHA-256 hash algorithm is used in HMAC. MAC_KEY_LEN is 16 1350 octets. The HMAC-SHA-256 output is truncated to T_LEN=16 octets, by 1351 stripping off the final 16 octets. 1353 4.10.4. AES_192_CBC_HMAC_SHA_384 1355 AES_192_CBC_HMAC_SHA_384 is based on AES_128_CBC_HMAC_SHA_256, but 1356 with the following differences: 1358 A 192 bit AES CBC key is used instead of 128. 1360 SHA-384 is used in HMAC instead of SHA-256. 1362 ENC_KEY_LEN is 24 octets instead of 16. 1364 MAC_KEY_LEN is 24 octets instead of 16. 1366 The length of the input key K is 48 octets instead of 32. 1368 The HMAC SHA-384 value is truncated to T_LEN=24 octets instead of 1369 16. 1371 4.10.5. AES_256_CBC_HMAC_SHA_512 1373 AES_256_CBC_HMAC_SHA_512 is based on AES_128_CBC_HMAC_SHA_256, but 1374 with the following differences: 1376 A 256 bit AES CBC key is used instead of 128. 1378 SHA-512 is used in HMAC instead of SHA-256. 1380 ENC_KEY_LEN is 32 octets instead of 16. 1382 MAC_KEY_LEN is 32 octets instead of 16. 1384 The length of the input key K is 64 octets instead of 32. 1386 The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of 1387 16. 1389 4.10.6. Plaintext Encryption with AES_CBC_HMAC_SHA2 1391 The algorithm value "A128CBC-HS256" is used as the "alg" value when 1392 using AES_128_CBC_HMAC_SHA_256 with JWE. The algorithm value 1393 "A192CBC-HS384" is used as the "alg" value when using 1394 AES_192_CBC_HMAC_SHA_384 with JWE. The algorithm value 1395 "A256CBC-HS512" is used as the "alg" value when using 1396 AES_256_CBC_HMAC_SHA_512 with JWE. The Additional Authenticated Data 1397 value used is the octets of the ASCII representation of the Encoded 1398 JWE Header value. The JWE Initialization Vector value used is the IV 1399 value. 1401 4.11. Plaintext Encryption with AES GCM 1403 This section defines the specifics of encrypting the JWE Plaintext 1404 with Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) 1405 [AES] [NIST.800-38D] using 128, 192, or 256 bit keys. The "enc" 1406 header parameter values "A128GCM", "A192GCM", or "A256GCM" are 1407 respectively used in this case. 1409 The CEK is used as the encryption key. 1411 Use of an initialization vector of size 96 bits is REQUIRED with this 1412 algorithm. 1414 The Additional Authenticated Data value used is the octets of the 1415 ASCII representation of the Encoded JWE Header value. 1417 The requested size of the Authentication Tag output MUST be 128 bits, 1418 regardless of the key size. 1420 The JWE Authentication Tag is set to be the Authentication Tag value 1421 produced by the encryption. During decryption, the received JWE 1422 Authentication Tag is used as the Authentication Tag value. 1424 An example using this algorithm is shown in Appendix A.1 of [JWE]. 1426 4.12. Additional Encryption Algorithms and Parameters 1428 Additional algorithms MAY be used to protect JWEs with corresponding 1429 "alg" (algorithm) and "enc" (encryption method) header parameter 1430 values being defined to refer to them. New "alg" and "enc" header 1431 parameter values SHOULD either be registered in the IANA JSON Web 1432 Signature and Encryption Algorithms registry Section 6.1 or be a 1433 value that contains a Collision Resistant Namespace. In particular, 1434 it is permissible to use the algorithm identifiers defined in XML 1435 Encryption [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 1436 [W3C.CR-xmlenc-core1-20120313], and related specifications as "alg" 1437 and "enc" values. 1439 As indicated by the common registry, JWSs and JWEs share a common 1440 "alg" value space. The values used by the two specifications MUST be 1441 distinct, as the "alg" value can be used to determine whether the 1442 object is a JWS or JWE. 1444 Likewise, additional reserved Header Parameter Names can be defined 1445 via the IANA JSON Web Signature and Encryption Header Parameters 1446 registry [JWS]. As indicated by the common registry, JWSs and JWEs 1447 share a common header parameter space; when a parameter is used by 1448 both specifications, its usage must be compatible between the 1449 specifications. 1451 5. Cryptographic Algorithms for JWK 1453 A JSON Web Key (JWK) [JWK] is a JavaScript Object Notation (JSON) 1454 [RFC4627] data structure that represents a cryptographic key. A JSON 1455 Web Key Set (JWK Set) is a JSON data structure for representing a set 1456 of JWKs. This section specifies a set of key types to be used for 1457 those keys and the key type specific parameters for representing 1458 those keys. Parameters are defined for public, private, and 1459 symmetric keys. 1461 5.1. "kty" (Key Type) Parameter Values for JWK 1463 The table below is the set of "kty" (key type) parameter values that 1464 are defined by this specification for use in JWKs. 1466 +-------------+----------------------------------+------------------+ 1467 | kty | Key Type | Implementation | 1468 | Parameter | | Requirements | 1469 | Value | | | 1470 +-------------+----------------------------------+------------------+ 1471 | EC | Elliptic Curve [DSS] key type | RECOMMENDED+ | 1472 | RSA | RSA [RFC3447] key type | REQUIRED | 1473 | oct | Octet sequence key type (used to | RECOMMENDED+ | 1474 | | represent symmetric keys) | | 1475 +-------------+----------------------------------+------------------+ 1477 All the names are short because a core goal of JWK is for the 1478 representations to be compact. However, there is no a priori length 1479 restriction on "kty" values. 1481 The use of "+" in the Implementation Requirements indicates that the 1482 requirement strength is likely to be increased in a future version of 1483 the specification. 1485 5.2. JWK Parameters for Elliptic Curve Keys 1487 JWKs can represent Elliptic Curve [DSS] keys. In this case, the 1488 "kty" member value MUST be "EC". 1490 5.2.1. JWK Parameters for Elliptic Curve Public Keys 1492 These members MUST be present for Elliptic Curve public keys: 1494 5.2.1.1. "crv" (Curve) Parameter 1496 The "crv" (curve) member identifies the cryptographic curve used with 1497 the key. Curve values from [DSS] used by this specification are: 1499 o "P-256" 1501 o "P-384" 1503 o "P-521" 1505 Additional "crv" values MAY be used, provided they are understood by 1506 implementations using that Elliptic Curve key. The "crv" value is a 1507 case sensitive string. 1509 5.2.1.2. "x" (X Coordinate) Parameter 1511 The "x" (x coordinate) member contains the x coordinate for the 1512 elliptic curve point. It is represented as the base64url encoding of 1513 the coordinate's big endian representation as an octet sequence. The 1514 array representation MUST NOT be shortened to omit any leading zero 1515 octets contained in the value. For instance, when representing 521 1516 bit integers, the octet sequence to be base64url encoded MUST contain 1517 66 octets, including any leading zero octets. 1519 5.2.1.3. "y" (Y Coordinate) Parameter 1521 The "y" (y coordinate) member contains the y coordinate for the 1522 elliptic curve point. It is represented as the base64url encoding of 1523 the coordinate's big endian representation as an octet sequence. The 1524 array representation MUST NOT be shortened to omit any leading zero 1525 octets contained in the value. For instance, when representing 521 1526 bit integers, the octet sequence to be base64url encoded MUST contain 1527 66 octets, including any leading zero octets. 1529 5.2.2. JWK Parameters for Elliptic Curve Private Keys 1531 In addition to the members used to represent Elliptic Curve public 1532 keys, the following member MUST be present to represent Elliptic 1533 Curve private keys: 1535 5.2.2.1. "d" (ECC Private Key) Parameter 1537 The "d" (ECC private key) member contains the Elliptic Curve private 1538 key value. It is represented as the base64url encoding of the 1539 value's unsigned big endian representation as an octet sequence. The 1540 array representation MUST NOT be shortened to omit any leading zero 1541 octets. For instance, when representing 521 bit integers, the octet 1542 sequence to be base64url encoded MUST contain 66 octets, including 1543 any leading zero octets. 1545 5.3. JWK Parameters for RSA Keys 1547 JWKs can represent RSA [RFC3447] keys. In this case, the "kty" 1548 member value MUST be "RSA". 1550 5.3.1. JWK Parameters for RSA Public Keys 1552 These members MUST be present for RSA public keys: 1554 5.3.1.1. "n" (Modulus) Parameter 1556 The "n" (modulus) member contains the modulus value for the RSA 1557 public key. It is represented as the base64url encoding of the 1558 value's unsigned big endian representation as an octet sequence. The 1559 array representation MUST NOT be shortened to omit any leading zero 1560 octets. For instance, when representing 2048 bit integers, the octet 1561 sequence to be base64url encoded MUST contain 256 octets, including 1562 any leading zero octets. 1564 5.3.1.2. "e" (Exponent) Parameter 1566 The "e" (exponent) member contains the exponent value for the RSA 1567 public key. It is represented as the base64url encoding of the 1568 value's unsigned big endian representation as an octet sequence. The 1569 array representation MUST utilize the minimum number of octets to 1570 represent the value. For instance, when representing the value 1571 65537, the octet sequence to be base64url encoded MUST consist of the 1572 three octets [1, 0, 1]. 1574 5.3.2. JWK Parameters for RSA Private Keys 1576 In addition to the members used to represent RSA public keys, the 1577 following members are used to represent RSA private keys. The 1578 parameter "d" is REQUIRED for RSA private keys. The others enable 1579 optimizations and are RECOMMENDED. If any of the others are present 1580 then all MUST be present, with the exception of "oth", which MUST 1581 only be present when more than two prime factors were used. 1583 5.3.2.1. "d" (Private Exponent) Parameter 1585 The "d" (private exponent) member contains the private exponent value 1586 for the RSA private key. It is represented as the base64url encoding 1587 of the value's unsigned big endian representation as an octet 1588 sequence. The array representation MUST NOT be shortened to omit any 1589 leading zero octets. For instance, when representing 2048 bit 1590 integers, the octet sequence to be base64url encoded MUST contain 256 1591 octets, including any leading zero octets. 1593 5.3.2.2. "p" (First Prime Factor) Parameter 1595 The "p" (first prime factor) member contains the first prime factor, 1596 a positive integer. It is represented as the base64url encoding of 1597 the value's unsigned big endian representation as an octet sequence. 1599 5.3.2.3. "q" (Second Prime Factor) Parameter 1601 The "q" (second prime factor) member contains the second prime 1602 factor, a positive integer. It is represented as the base64url 1603 encoding of the value's unsigned big endian representation as an 1604 octet sequence. 1606 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter 1608 The "dp" (first factor CRT exponent) member contains the Chinese 1609 Remainder Theorem (CRT) exponent of the first factor, a positive 1610 integer. It is represented as the base64url encoding of the value's 1611 unsigned big endian representation as an octet sequence. 1613 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter 1615 The "dq" (second factor CRT exponent) member contains the Chinese 1616 Remainder Theorem (CRT) exponent of the second factor, a positive 1617 integer. It is represented as the base64url encoding of the value's 1618 unsigned big endian representation as an octet sequence. 1620 5.3.2.6. "qi" (First CRT Coefficient) Parameter 1622 The "dp" (first CRT coefficient) member contains the Chinese 1623 Remainder Theorem (CRT) coefficient of the second factor, a positive 1624 integer. It is represented as the base64url encoding of the value's 1625 unsigned big endian representation as an octet sequence. 1627 5.3.2.7. "oth" (Other Primes Info) Parameter 1629 The "oth" (other primes info) member contains an array of information 1630 about any third and subsequent primes, should they exist. When only 1631 two primes have been used (the normal case), this parameter MUST be 1632 omitted. When three or more primes have been used, the number of 1633 array elements MUST be the number of primes used minus two. Each 1634 array element MUST be an object with the following members: 1636 5.3.2.7.1. "r" (Prime Factor) 1638 The "r" (prime factor) parameter within an "oth" array member 1639 represents the value of a subsequent prime factor, a positive 1640 integer. It is represented as the base64url encoding of the value's 1641 unsigned big endian representation as an octet sequence. 1643 5.3.2.7.2. "d" (Factor CRT Exponent) 1645 The "d" (Factor CRT Exponent) parameter within an "oth" array member 1646 represents the CRT exponent of the corresponding prime factor, a 1647 positive integer. It is represented as the base64url encoding of the 1648 value's unsigned big endian representation as an octet sequence. 1650 5.3.2.7.3. "t" (Factor CRT Coefficient) 1652 The "t" (factor CRT coefficient) parameter within an "oth" array 1653 member represents the CRT coefficient of the corresponding prime 1654 factor, a positive integer. It is represented as the base64url 1655 encoding of the value's unsigned big endian representation as an 1656 octet sequence. 1658 5.3.3. JWK Parameters for Symmetric Keys 1660 When the JWK "kty" member value is "oct" (octet sequence), the 1661 following member is used to represent a symmetric key (or another key 1662 whose value is a single octet sequence): 1664 5.3.3.1. "k" (Key Value) Parameter 1666 The "k" (key value) member contains the value of the symmetric (or 1667 other single-valued) key. It is represented as the base64url 1668 encoding of the octet sequence containing the key value. 1670 5.4. Additional Key Types and Parameters 1672 Keys using additional key types can be represented using JWK data 1673 structures with corresponding "kty" (key type) parameter values being 1674 defined to refer to them. New "kty" parameter values SHOULD either 1675 be registered in the IANA JSON Web Key Types registry Section 6.2 or 1676 be a value that contains a Collision Resistant Namespace. 1678 Likewise, parameters for representing keys for additional key types 1679 or additional key properties SHOULD either be registered in the IANA 1680 JSON Web Key Parameters registry [JWK] or be a value that contains a 1681 Collision Resistant Namespace. 1683 6. IANA Considerations 1685 The following registration procedure is used for all the registries 1686 established by this specification. 1688 Values are registered with a Specification Required [RFC5226] after a 1689 two-week review period on the [TBD]@ietf.org mailing list, on the 1690 advice of one or more Designated Experts. However, to allow for the 1691 allocation of values prior to publication, the Designated Expert(s) 1692 may approve registration once they are satisfied that such a 1693 specification will be published. 1695 Registration requests must be sent to the [TBD]@ietf.org mailing list 1696 for review and comment, with an appropriate subject (e.g., "Request 1697 for access token type: example"). [[ Note to RFC-EDITOR: The name of 1698 the mailing list should be determined in consultation with the IESG 1699 and IANA. Suggested name: jose-reg-review. ]] 1701 Within the review period, the Designated Expert(s) will either 1702 approve or deny the registration request, communicating this decision 1703 to the review list and IANA. Denials should include an explanation 1704 and, if applicable, suggestions as to how to make the request 1705 successful. 1707 IANA must only accept registry updates from the Designated Expert(s) 1708 and should direct all requests for registration to the review mailing 1709 list. 1711 6.1. JSON Web Signature and Encryption Algorithms Registry 1713 This specification establishes the IANA JSON Web Signature and 1714 Encryption Algorithms registry for values of the JWS and JWE "alg" 1715 (algorithm) and "enc" (encryption method) header parameters. The 1716 registry records the algorithm name, the algorithm usage locations 1717 from the set "alg" and "enc", implementation requirements, and a 1718 reference to the specification that defines it. The same algorithm 1719 name MAY be registered multiple times, provided that the sets of 1720 usage locations are disjoint. The implementation requirements of an 1721 algorithm MAY be changed over time by the Designated Experts(s) as 1722 the cryptographic landscape evolves, for instance, to change the 1723 status of an algorithm to DEPRECATED, or to change the status of an 1724 algorithm from OPTIONAL to RECOMMENDED or REQUIRED. 1726 6.1.1. Template 1727 Algorithm Name: 1728 The name requested (e.g., "example"). This name is case 1729 sensitive. Names that match other registered names in a case 1730 insensitive manner SHOULD NOT be accepted. 1732 Algorithm Usage Location(s): 1733 The algorithm usage, which must be one or more of the values "alg" 1734 or "enc". 1736 Implementation Requirements: 1737 The algorithm implementation requirements, which must be one the 1738 words REQUIRED, RECOMMENDED, OPTIONAL, or DEPRECATED. Optionally, 1739 the word can be followed by a "+" or "-". The use of "+" 1740 indicates that the requirement strength is likely to be increased 1741 in a future version of the specification. The use of "-" 1742 indicates that the requirement strength is likely to be decreased 1743 in a future version of the specification. 1745 Change Controller: 1746 For Standards Track RFCs, state "IETF". For others, give the name 1747 of the responsible party. Other details (e.g., postal address, 1748 email address, home page URI) may also be included. 1750 Specification Document(s): 1751 Reference to the document(s) that specify the parameter, 1752 preferably including URI(s) that can be used to retrieve copies of 1753 the document(s). An indication of the relevant sections may also 1754 be included but is not required. 1756 6.1.2. Initial Registry Contents 1758 o Algorithm Name: "HS256" 1759 o Algorithm Usage Location(s): "alg" 1760 o Implementation Requirements: REQUIRED 1761 o Change Controller: IETF 1762 o Specification Document(s): Section 3.1 of [[ this document ]] 1764 o Algorithm Name: "HS384" 1765 o Algorithm Usage Location(s): "alg" 1766 o Implementation Requirements: OPTIONAL 1767 o Change Controller: IETF 1768 o Specification Document(s): Section 3.1 of [[ this document ]] 1770 o Algorithm Name: "HS512" 1771 o Algorithm Usage Location(s): "alg" 1772 o Implementation Requirements: OPTIONAL 1773 o Change Controller: IETF 1774 o Specification Document(s): Section 3.1 of [[ this document ]] 1776 o Algorithm Name: "RS256" 1777 o Algorithm Usage Location(s): "alg" 1778 o Implementation Requirements: RECOMMENDED 1779 o Change Controller: IETF 1780 o Specification Document(s): Section 3.1 of [[ this document ]] 1782 o Algorithm Name: "RS384" 1783 o Algorithm Usage Location(s): "alg" 1784 o Implementation Requirements: OPTIONAL 1785 o Change Controller: IETF 1786 o Specification Document(s): Section 3.1 of [[ this document ]] 1788 o Algorithm Name: "RS512" 1789 o Algorithm Usage Location(s): "alg" 1790 o Implementation Requirements: OPTIONAL 1791 o Change Controller: IETF 1792 o Specification Document(s): Section 3.1 of [[ this document ]] 1794 o Algorithm Name: "ES256" 1795 o Algorithm Usage Location(s): "alg" 1796 o Implementation Requirements: RECOMMENDED+ 1797 o Change Controller: IETF 1798 o Specification Document(s): Section 3.1 of [[ this document ]] 1800 o Algorithm Name: "ES384" 1801 o Algorithm Usage Location(s): "alg" 1802 o Implementation Requirements: OPTIONAL 1803 o Change Controller: IETF 1804 o Specification Document(s): Section 3.1 of [[ this document ]] 1806 o Algorithm Name: "ES512" 1807 o Algorithm Usage Location(s): "alg" 1808 o Implementation Requirements: OPTIONAL 1809 o Change Controller: IETF 1810 o Specification Document(s): Section 3.1 of [[ this document ]] 1812 o Algorithm Name: "PS256" 1813 o Algorithm Usage Location(s): "alg" 1814 o Implementation Requirements: OPTIONAL 1815 o Change Controller: IETF 1816 o Specification Document(s): Section 3.1 of [[ this document ]] 1818 o Algorithm Name: "PS384" 1819 o Algorithm Usage Location(s): "alg" 1820 o Implementation Requirements: OPTIONAL 1821 o Change Controller: IETF 1822 o Specification Document(s): Section 3.1 of [[ this document ]] 1824 o Algorithm Name: "PS512" 1825 o Algorithm Usage Location(s): "alg" 1826 o Implementation Requirements: OPTIONAL 1827 o Change Controller: IETF 1828 o Specification Document(s): Section 3.1 of [[ this document ]] 1830 o Algorithm Name: "none" 1831 o Algorithm Usage Location(s): "alg" 1832 o Implementation Requirements: REQUIRED 1833 o Change Controller: IETF 1834 o Specification Document(s): Section 3.1 of [[ this document ]] 1836 o Algorithm Name: "RSA1_5" 1837 o Algorithm Usage Location(s): "alg" 1838 o Implementation Requirements: REQUIRED 1839 o Change Controller: IETF 1840 o Specification Document(s): Section 4.1 of [[ this document ]] 1842 o Algorithm Name: "RSA-OAEP" 1843 o Algorithm Usage Location(s): "alg" 1844 o Implementation Requirements: OPTIONAL 1845 o Change Controller: IETF 1846 o Specification Document(s): Section 4.1 of [[ this document ]] 1848 o Algorithm Name: "A128KW" 1849 o Algorithm Usage Location(s): "alg" 1850 o Implementation Requirements: RECOMMENDED 1851 o Change Controller: IETF 1852 o Specification Document(s): Section 4.1 of [[ this document ]] 1854 o Algorithm Name: "A192KW" 1855 o Algorithm Usage Location(s): "alg" 1856 o Implementation Requirements: OPTIONAL 1857 o Change Controller: IETF 1858 o Specification Document(s): Section 4.1 of [[ this document ]] 1860 o Algorithm Name: "A256KW" 1861 o Algorithm Usage Location(s): "alg" 1862 o Implementation Requirements: RECOMMENDED 1863 o Change Controller: IETF 1864 o Specification Document(s): Section 4.1 of [[ this document ]] 1865 o Algorithm Name: "dir" 1866 o Algorithm Usage Location(s): "alg" 1867 o Implementation Requirements: RECOMMENDED 1868 o Change Controller: IETF 1869 o Specification Document(s): Section 4.1 of [[ this document ]] 1871 o Algorithm Name: "ECDH-ES" 1872 o Algorithm Usage Location(s): "alg" 1873 o Implementation Requirements: RECOMMENDED+ 1874 o Change Controller: IETF 1875 o Specification Document(s): Section 4.1 of [[ this document ]] 1877 o Algorithm Name: "ECDH-ES+A128KW" 1878 o Algorithm Usage Location(s): "alg" 1879 o Implementation Requirements: RECOMMENDED 1880 o Change Controller: IETF 1881 o Specification Document(s): Section 4.1 of [[ this document ]] 1883 o Algorithm Name: "ECDH-ES+A192KW" 1884 o Algorithm Usage Location(s): "alg" 1885 o Implementation Requirements: OPTIONAL 1886 o Change Controller: IETF 1887 o Specification Document(s): Section 4.1 of [[ this document ]] 1889 o Algorithm Name: "ECDH-ES+A256KW" 1890 o Algorithm Usage Location(s): "alg" 1891 o Implementation Requirements: RECOMMENDED 1892 o Change Controller: IETF 1893 o Specification Document(s): Section 4.1 of [[ this document ]] 1895 o Algorithm Name: "A128GCMKW" 1896 o Algorithm Usage Location(s): "alg" 1897 o Implementation Requirements: OPTIONAL 1898 o Change Controller: IETF 1899 o Specification Document(s): Section 4.8 of [[ this document ]] 1901 o Algorithm Name: "A192GCMKW" 1902 o Algorithm Usage Location(s): "alg" 1903 o Implementation Requirements: OPTIONAL 1904 o Change Controller: IETF 1905 o Specification Document(s): Section 4.8 of [[ this document ]] 1907 o Algorithm Name: "A256GCMKW" 1908 o Algorithm Usage Location(s): "alg" 1909 o Implementation Requirements: OPTIONAL 1910 o Change Controller: IETF 1911 o Specification Document(s): Section 4.8 of [[ this document ]] 1913 o Algorithm Name: "PBES2-HS256+A128KW" 1914 o Algorithm Usage Location(s): "alg" 1915 o Implementation Requirements: OPTIONAL 1916 o Change Controller: IETF 1917 o Specification Document(s): Section 4.9 of [[ this document ]] 1919 o Algorithm Name: "PBES2-HS256+A192KW" 1920 o Algorithm Usage Location(s): "alg" 1921 o Implementation Requirements: OPTIONAL 1922 o Change Controller: IETF 1923 o Specification Document(s): Section 4.9 of [[ this document ]] 1925 o Algorithm Name: "PBES2-HS256+A256KW" 1926 o Algorithm Usage Location(s): "alg" 1927 o Implementation Requirements: OPTIONAL 1928 o Change Controller: IETF 1929 o Specification Document(s): Section 4.9 of [[ this document ]] 1931 o Algorithm Name: "A128CBC-HS256" 1932 o Algorithm Usage Location(s): "enc" 1933 o Implementation Requirements: REQUIRED 1934 o Change Controller: IETF 1935 o Specification Document(s): Section 4.2 of [[ this document ]] 1937 o Algorithm Name: "A192CBC-HS384" 1938 o Algorithm Usage Location(s): "enc" 1939 o Implementation Requirements: OPTIONAL 1940 o Change Controller: IETF 1941 o Specification Document(s): Section 4.2 of [[ this document ]] 1943 o Algorithm Name: "A256CBC-HS512" 1944 o Algorithm Usage Location(s): "enc" 1945 o Implementation Requirements: REQUIRED 1946 o Change Controller: IETF 1947 o Specification Document(s): Section 4.2 of [[ this document ]] 1949 o Algorithm Name: "A128GCM" 1950 o Algorithm Usage Location(s): "enc" 1951 o Implementation Requirements: RECOMMENDED 1952 o Change Controller: IETF 1953 o Specification Document(s): Section 4.2 of [[ this document ]] 1955 o Algorithm Name: "A192GCM" 1956 o Algorithm Usage Location(s): "enc" 1957 o Implementation Requirements: OPTIONAL 1958 o Change Controller: IETF 1959 o Specification Document(s): Section 4.2 of [[ this document ]] 1961 o Algorithm Name: "A256GCM" 1962 o Algorithm Usage Location(s): "enc" 1963 o Implementation Requirements: RECOMMENDED 1964 o Change Controller: IETF 1965 o Specification Document(s): Section 4.2 of [[ this document ]] 1967 6.2. JSON Web Key Types Registry 1969 This specification establishes the IANA JSON Web Key Types registry 1970 for values of the JWK "kty" (key type) parameter. The registry 1971 records the "kty" value and a reference to the specification that 1972 defines it. This specification registers the values defined in 1973 Section 5.1. 1975 6.2.1. Registration Template 1977 "kty" Parameter Value: 1978 The name requested (e.g., "example"). This name is case 1979 sensitive. Names that match other registered names in a case 1980 insensitive manner SHOULD NOT be accepted. 1982 Change Controller: 1983 For Standards Track RFCs, state "IETF". For others, give the name 1984 of the responsible party. Other details (e.g., postal address, 1985 email address, home page URI) may also be included. 1987 Implementation Requirements: 1988 The algorithm implementation requirements, which must be one the 1989 words REQUIRED, RECOMMENDED, OPTIONAL, or DEPRECATED. Optionally, 1990 the word can be followed by a "+" or "-". The use of "+" 1991 indicates that the requirement strength is likely to be increased 1992 in a future version of the specification. The use of "-" 1993 indicates that the requirement strength is likely to be decreased 1994 in a future version of the specification. 1996 Specification Document(s): 1997 Reference to the document(s) that specify the parameter, 1998 preferably including URI(s) that can be used to retrieve copies of 1999 the document(s). An indication of the relevant sections may also 2000 be included but is not required. 2002 6.2.2. Initial Registry Contents 2004 o "kty" Parameter Value: "EC" 2005 o Implementation Requirements: RECOMMENDED+ 2006 o Change Controller: IETF 2007 o Specification Document(s): Section 5.2 of [[ this document ]] 2009 o "kty" Parameter Value: "RSA" 2010 o Implementation Requirements: REQUIRED 2011 o Change Controller: IETF 2012 o Specification Document(s): Section 5.3 of [[ this document ]] 2014 o "kty" Parameter Value: "oct" 2015 o Implementation Requirements: RECOMMENDED+ 2016 o Change Controller: IETF 2017 o Specification Document(s): Section 5.3.3 of [[ this document ]] 2019 6.3. JSON Web Key Parameters Registration 2021 This specification registers the parameter names defined in Sections 2022 5.2, 5.3, and 5.3.3 in the IANA JSON Web Key Parameters registry 2023 [JWK]. 2025 6.3.1. Registry Contents 2027 o Parameter Name: "crv" 2028 o Parameter Information Class: Public 2029 o Change Controller: IETF 2030 o Specification Document(s): Section 5.2.1.1 of [[ this document ]] 2032 o Parameter Name: "x" 2033 o Parameter Information Class: Public 2034 o Change Controller: IETF 2035 o Specification Document(s): Section 5.2.1.2 of [[ this document ]] 2037 o Parameter Name: "y" 2038 o Parameter Information Class: Public 2039 o Change Controller: IETF 2040 o Specification Document(s): Section 5.2.1.3 of [[ this document ]] 2042 o Parameter Name: "d" 2043 o Parameter Information Class: Private 2044 o Change Controller: IETF 2045 o Specification Document(s): Section 5.2.2.1 of [[ this document ]] 2047 o Parameter Name: "n" 2048 o Parameter Information Class: Public 2049 o Change Controller: IETF 2050 o Specification Document(s): Section 5.3.1.1 of [[ this document ]] 2052 o Parameter Name: "e" 2053 o Parameter Information Class: Public 2054 o Change Controller: IETF 2055 o Specification Document(s): Section 5.3.1.2 of [[ this document ]] 2057 o Parameter Name: "d" 2058 o Parameter Information Class: Private 2059 o Change Controller: IETF 2060 o Specification Document(s): Section 5.3.2.1 of [[ this document ]] 2062 o Parameter Name: "p" 2063 o Parameter Information Class: Private 2064 o Change Controller: IETF 2065 o Specification Document(s): Section 5.3.2.2 of [[ this document ]] 2067 o Parameter Name: "q" 2068 o Parameter Information Class: Private 2069 o Change Controller: IETF 2070 o Specification Document(s): Section 5.3.2.3 of [[ this document ]] 2072 o Parameter Name: "dp" 2073 o Parameter Information Class: Private 2074 o Change Controller: IETF 2075 o Specification Document(s): Section 5.3.2.4 of [[ this document ]] 2077 o Parameter Name: "dq" 2078 o Parameter Information Class: Private 2079 o Change Controller: IETF 2080 o Specification Document(s): Section 5.3.2.5 of [[ this document ]] 2082 o Parameter Name: "qi" 2083 o Parameter Information Class: Private 2084 o Change Controller: IETF 2085 o Specification Document(s): Section 5.3.2.6 of [[ this document ]] 2087 o Parameter Name: "oth" 2088 o Parameter Information Class: Private 2089 o Change Controller: IETF 2090 o Specification Document(s): Section 5.3.2.7 of [[ this document ]] 2092 o Parameter Name: "k" 2093 o Parameter Information Class: Private 2094 o Change Controller: IETF 2095 o Specification Document(s): Section 5.3.3.1 of [[ this document ]] 2097 6.4. Registration of JWE Header Parameter Names 2099 This specification registers the Header Parameter Names defined in 2100 Section 4.7.1, Section 4.8.1, and Section 4.9.1 in the IANA JSON Web 2101 Signature and Encryption Header Parameters registry [JWS]. 2103 6.4.1. Registry Contents 2105 o Header Parameter Name: "epk" 2106 o Header Parameter Usage Location(s): JWE 2107 o Change Controller: IETF 2108 o Specification Document(s): Section 4.7.1.1 of [[ this document ]] 2110 o Header Parameter Name: "apu" 2111 o Header Parameter Usage Location(s): JWE 2112 o Change Controller: IETF 2113 o Specification Document(s): Section 4.7.1.2 of [[ this document ]] 2115 o Header Parameter Name: "apv" 2116 o Header Parameter Usage Location(s): JWE 2117 o Change Controller: IETF 2118 o Specification Document(s): Section 4.7.1.3 of [[ this document ]] 2120 o Header Parameter Name: "iv" 2121 o Header Parameter Usage Location(s): JWE 2122 o Change Controller: IETF 2123 o Specification Document(s): Section 4.8.1.1 of [[ this document ]] 2125 o Header Parameter Name: "tag" 2126 o Header Parameter Usage Location(s): JWE 2127 o Change Controller: IETF 2128 o Specification Document(s): Section 4.8.1.2 of [[ this document ]] 2130 o Header Parameter Name: "p2s" 2131 o Header Parameter Usage Location(s): JWE 2132 o Change Controller: IETF 2133 o Specification Document(s): Section 4.9.1.1 of [[ this document ]] 2135 o Header Parameter Name: "p2c" 2136 o Header Parameter Usage Location(s): JWE 2137 o Change Controller: IETF 2138 o Specification Document(s): Section 4.9.1.2 of [[ this document ]] 2140 7. Security Considerations 2142 All of the security issues faced by any cryptographic application 2143 must be faced by a JWS/JWE/JWK agent. Among these issues are 2144 protecting the user's private and symmetric keys, preventing various 2145 attacks, and helping the user avoid mistakes such as inadvertently 2146 encrypting a message for the wrong recipient. The entire list of 2147 security considerations is beyond the scope of this document, but 2148 some significant considerations are listed here. 2150 The security considerations in [AES], [DSS], [JWE], [JWK], [JWS], 2151 [NIST.800-38A], [NIST.800-38D], [NIST.800-56A], [RFC2104], [RFC3394], 2152 [RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this 2153 specification. 2155 Eventually the algorithms and/or key sizes currently described in 2156 this specification will no longer be considered sufficiently secure 2157 and will be removed. Therefore, implementers and deployments must be 2158 prepared for this eventuality. 2160 Many algorithms have associated security considerations related to 2161 key lifetimes and/or the number of times that a key may be used. 2162 Those security considerations continue to apply when using those 2163 algorithms with JOSE data structures. 2165 Algorithms of matching strengths should be used together whenever 2166 possible. For instance, when AES Key Wrap is used with a given key 2167 size, using the same key size is recommended when AES GCM is also 2168 used. 2170 While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not 2171 to adopt RSASSA-PKCS-v1_5 for new applications and instead requests 2172 that people transition to RSASSA-PSS, this specification does include 2173 RSASSA-PKCS-v1_5, for interoperability reasons, because it commonly 2174 implemented. 2176 Keys used with RSAES-PKCS1-v1_5 must follow the constraints in 2177 Section 7.2 of RFC 3447 [RFC3447]. In particular, keys with a low 2178 public key exponent value must not be used. 2180 Keys used with AES GCM must follow the constraints in Section 8.3 of 2181 [NIST.800-38D], which states: "The total number of invocations of the 2182 authenticated encryption function shall not exceed 2^32, including 2183 all IV lengths and all instances of the authenticated encryption 2184 function with the given key". In accordance with this rule, AES GCM 2185 MUST NOT be used with the same key encryption key or with the same 2186 direct encryption key more than 2^32 times. 2188 Plaintext JWSs (JWSs that use the "alg" value "none") provide no 2189 integrity protection. Thus, they must only be used in contexts where 2190 the payload is secured by means other than a digital signature or MAC 2191 value, or need not be secured. 2193 Receiving agents that validate signatures and sending agents that 2194 encrypt messages need to be cautious of cryptographic processing 2195 usage when validating signatures and encrypting messages using keys 2196 larger than those mandated in this specification. An attacker could 2197 send certificates with keys that would result in excessive 2198 cryptographic processing, for example, keys larger than those 2199 mandated in this specification, which could swamp the processing 2200 element. Agents that use such keys without first validating the 2201 certificate to a trust anchor are advised to have some sort of 2202 cryptographic resource management system to prevent such attacks. 2204 7.1. Reusing Key Material when Encrypting Keys 2206 It is NOT RECOMMENDED to reuse the same key material (Key Encryption 2207 Key, Content Master Key, Initialization Vector, etc.) to encrypt 2208 multiple JWK or JWK Set objects, or to encrypt the same JWK or JWK 2209 Set object multiple times. One suggestion for preventing re-use is 2210 to always generate a new set key material for each encryption 2211 operation, based on the considerations noted in this document as well 2212 as from [RFC4086]. 2214 7.2. Password Considerations 2216 While convenient for end users, passwords are vulnerable to a number 2217 of attacks. To help mitigate some of these limitations, this 2218 document applies principles from [RFC2898] to derive cryptographic 2219 keys from user-supplied passwords. 2221 However, the strength of the password still has a significant impact. 2222 A high-entry password has greater resistance to dictionary attacks. 2223 [NIST-800-63-1] contains guidelines for estimating password entropy, 2224 which can help applications and users generate stronger passwords. 2226 An ideal password is one that is as large (or larger) than the 2227 derived key length but less than the PRF's block size. Passwords 2228 larger than the PRF's block size are first hashed, which reduces an 2229 attacker's effective search space to the length of the hash algorithm 2230 (32 octets for HMAC SHA-256). It is RECOMMENDED that the password be 2231 no longer than 64 octets long for "PBES2-HS256+A256KW". 2233 Still, care needs to be taken in where and how password-based 2234 encryption is used. Such algorithms MUST NOT be used where the 2235 attacker can make an indefinite number of attempts to circumvent the 2236 protection. 2238 8. Internationalization Considerations 2240 Passwords obtained from users are likely to require preparation and 2241 normalization to account for differences of octet sequences generated 2242 by different input devices, locales, etc. It is RECOMMENDED that 2243 applications to perform the steps outlined in 2244 [I-D.melnikov-precis-saslprepbis] to prepare a password supplied 2245 directly by a user before performing key derivation and encryption. 2247 9. References 2249 9.1. Normative References 2251 [AES] National Institute of Standards and Technology (NIST), 2252 "Advanced Encryption Standard (AES)", FIPS PUB 197, 2253 November 2001. 2255 [DSS] National Institute of Standards and Technology, "Digital 2256 Signature Standard (DSS)", FIPS PUB 186-3, June 2009. 2258 [I-D.melnikov-precis-saslprepbis] 2259 Saint-Andre, P. and A. Melnikov, "Preparation and 2260 Comparison of Internationalized Strings Representing 2261 Simple User Names and Passwords", 2262 draft-melnikov-precis-saslprepbis-04 (work in progress), 2263 September 2012. 2265 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 2266 Encryption (JWE)", draft-ietf-jose-json-web-encryption 2267 (work in progress), July 2013. 2269 [JWK] Jones, M., "JSON Web Key (JWK)", 2270 draft-ietf-jose-json-web-key (work in progress), 2271 July 2013. 2273 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 2274 Signature (JWS)", draft-ietf-jose-json-web-signature (work 2275 in progress), July 2013. 2277 [NIST.800-38A] 2278 National Institute of Standards and Technology (NIST), 2279 "Recommendation for Block Cipher Modes of Operation", 2280 NIST PUB 800-38A, December 2001. 2282 [NIST.800-38D] 2283 National Institute of Standards and Technology (NIST), 2284 "Recommendation for Block Cipher Modes of Operation: 2285 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 2286 December 2001. 2288 [NIST.800-56A] 2289 National Institute of Standards and Technology (NIST), 2290 "Recommendation for Pair-Wise Key Establishment Schemes 2291 Using Discrete Logarithm Cryptography", NIST Special 2292 Publication 800-56A, Revision 2, May 2013. 2294 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 2295 Hashing for Message Authentication", RFC 2104, 2296 February 1997. 2298 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2299 Requirement Levels", BCP 14, RFC 2119, March 1997. 2301 [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography 2302 Specification Version 2.0", RFC 2898, September 2000. 2304 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 2305 (AES) Key Wrap Algorithm", RFC 3394, September 2002. 2307 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2308 10646", STD 63, RFC 3629, November 2003. 2310 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 2311 Requirements for Security", BCP 106, RFC 4086, June 2005. 2313 [RFC4627] Crockford, D., "The application/json Media Type for 2314 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2316 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2317 Encodings", RFC 4648, October 2006. 2319 [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA- 2320 384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007. 2322 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 2323 Encryption", RFC 5116, January 2008. 2325 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2326 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2327 May 2008. 2329 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 2330 Curve Cryptography Algorithms", RFC 6090, February 2011. 2332 [SHS] National Institute of Standards and Technology, "Secure 2333 Hash Standard (SHS)", FIPS PUB 180-3, October 2008. 2335 [USASCII] American National Standards Institute, "Coded Character 2336 Set -- 7-bit American Standard Code for Information 2337 Interchange", ANSI X3.4, 1986. 2339 9.2. Informative References 2341 [CanvasApp] 2342 Facebook, "Canvas Applications", 2010. 2344 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 2345 McGrew, D., Foley, J., and K. Paterson, "Authenticated 2346 Encryption with AES-CBC and HMAC-SHA", 2347 draft-mcgrew-aead-aes-cbc-hmac-sha2-02 (work in progress), 2348 July 2013. 2350 [I-D.miller-jose-jwe-protected-jwk] 2351 Miller, M., "Using JavaScript Object Notation (JSON) Web 2352 Encryption (JWE) for Protecting JSON Web Key (JWK) 2353 Objects", draft-miller-jose-jwe-protected-jwk-02 (work in 2354 progress), June 2013. 2356 [I-D.rescorla-jsms] 2357 Rescorla, E. and J. Hildebrand, "JavaScript Message 2358 Security Format", draft-rescorla-jsms-00 (work in 2359 progress), March 2011. 2361 [JCA] Oracle, "Java Cryptography Architecture", 2011. 2363 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 2364 Encryption", September 2010. 2366 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 2367 September 2010. 2369 [MagicSignatures] 2370 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 2371 Signatures", January 2011. 2373 [NIST-800-63-1] 2374 National Institute of Standards and Technology (NIST), 2375 "Electronic Authentication Guideline", NIST 800-63-1, 2376 December 2011. 2378 [RFC2631] Rescorla, E., "Diffie-Hellman Key Agreement Method", 2379 RFC 2631, June 1999. 2381 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 2382 Language) XML-Signature Syntax and Processing", RFC 3275, 2383 March 2002. 2385 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 2386 Standards (PKCS) #1: RSA Cryptography Specifications 2387 Version 2.1", RFC 3447, February 2003. 2389 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2390 Unique IDentifier (UUID) URN Namespace", RFC 4122, 2391 July 2005. 2393 [W3C.CR-xmldsig-core2-20120124] 2394 Eastlake, D., Reagle, J., Yiu, K., Solo, D., Datta, P., 2395 Hirsch, F., Cantor, S., and T. Roessler, "XML Signature 2396 Syntax and Processing Version 2.0", World Wide Web 2397 Consortium CR CR-xmldsig-core2-20120124, January 2012, 2398 . 2400 [W3C.CR-xmlenc-core1-20120313] 2401 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 2402 "XML Encryption Syntax and Processing Version 1.1", World 2403 Wide Web Consortium CR CR-xmlenc-core1-20120313, 2404 March 2012, 2405 . 2407 [W3C.REC-xmlenc-core-20021210] 2408 Eastlake, D. and J. Reagle, "XML Encryption Syntax and 2409 Processing", World Wide Web Consortium Recommendation REC- 2410 xmlenc-core-20021210, December 2002, 2411 . 2413 Appendix A. Digital Signature/MAC Algorithm Identifier Cross-Reference 2415 This appendix contains a table cross-referencing the digital 2416 signature and MAC "alg" (algorithm) values used in this specification 2417 with the equivalent identifiers used by other standards and software 2418 packages. See XML DSIG [RFC3275], XML DSIG 2.0 2419 [W3C.CR-xmldsig-core2-20120124], and Java Cryptography Architecture 2420 [JCA] for more information about the names defined by those 2421 documents. 2423 +---------+----+---------------------------+----------+-------------+ 2424 | Algorit | JW | XML DSIG | JCA | OID | 2425 | hm | S | | | | 2426 +---------+----+---------------------------+----------+-------------+ 2427 | HMAC | HS | http://www.w3.org/2001/04 | HmacSHA2 | 1.2.840.113 | 2428 | using | 25 | /xmldsig-more#hmac-sha256 | 56 | 549.2.9 | 2429 | SHA-256 | 6 | | | | 2430 | hash | | | | | 2431 | algorit | | | | | 2432 | hm | | | | | 2433 | HMAC | HS | http://www.w3.org/2001/04 | HmacSHA3 | 1.2.840.113 | 2434 | using | 38 | /xmldsig-more#hmac-sha384 | 84 | 549.2.10 | 2435 | SHA-384 | 4 | | | | 2436 | hash | | | | | 2437 | algorit | | | | | 2438 | hm | | | | | 2439 | HMAC | HS | http://www.w3.org/2001/04 | HmacSHA5 | 1.2.840.113 | 2440 | using | 51 | /xmldsig-more#hmac-sha512 | 12 | 549.2.11 | 2441 | SHA-512 | 2 | | | | 2442 | hash | | | | | 2443 | algorit | | | | | 2444 | hm | | | | | 2445 | RSASSA- | RS | http://www.w3.org/2001/04 | SHA256wi | 1.2.840.113 | 2446 | PKCS-v1 | 25 | /xmldsig-more#rsa-sha256 | thRSA | 549.1.1.11 | 2447 | _5using | 6 | | | | 2448 | SHA-2 | | | | | 2449 | 56hash | | | | | 2450 | algor | | | | | 2451 | ithm | | | | | 2452 | RSASSA- | RS | http://www.w3.org/2001/04 | SHA384wi | 1.2.840.113 | 2453 | PKCS-v1 | 38 | /xmldsig-more#rsa-sha384 | thRSA | 549.1.1.12 | 2454 | _5using | 4 | | | | 2455 | SHA-3 | | | | | 2456 | 84hash | | | | | 2457 | algor | | | | | 2458 | ithm | | | | | 2459 | RSASSA- | RS | http://www.w3.org/2001/04 | SHA512wi | 1.2.840.113 | 2460 | PKCS-v1 | 51 | /xmldsig-more#rsa-sha512 | thRSA | 549.1.1.13 | 2461 | _5using | 2 | | | | 2462 | SHA-5 | | | | | 2463 | 12hash | | | | | 2464 | algor | | | | | 2465 | ithm | | | | | 2466 | ECDSA | ES | http://www.w3.org/2001/04 | SHA256wi | 1.2.840.100 | 2467 | using | 25 | /xmldsig-more#ecdsa-sha25 | thECDSA | 45.4.3.2 | 2468 | P-256 | 6 | 6 | | | 2469 | curve | | | | | 2470 | and | | | | | 2471 | SHA-256 | | | | | 2472 | hash | | | | | 2473 | algorit | | | | | 2474 | hm | | | | | 2475 | ECDSA | ES | http://www.w3.org/2001/04 | SHA384wi | 1.2.840.100 | 2476 | using | 38 | /xmldsig-more#ecdsa-sha38 | thECDSA | 45.4.3.3 | 2477 | P-384 | 4 | 4 | | | 2478 | curve | | | | | 2479 | and | | | | | 2480 | SHA-384 | | | | | 2481 | hash | | | | | 2482 | algorit | | | | | 2483 | hm | | | | | 2484 | ECDSA | ES | http://www.w3.org/2001/04 | SHA512wi | 1.2.840.100 | 2485 | using | 51 | /xmldsig-more#ecdsa-sha51 | thECDSA | 45.4.3.4 | 2486 | P-521 | 2 | 2 | | | 2487 | curve | | | | | 2488 | and | | | | | 2489 | SHA-512 | | | | | 2490 | hash | | | | | 2491 | algorit | | | | | 2492 | hm | | | | | 2493 | RSASSA- | PS | | | | 2494 | PSS | 25 | | | | 2495 | using | 6 | | | | 2496 | SHA-25 | | | | | 2497 | 6hash | | | | | 2498 | algori | | | | | 2499 | thm and | | | | | 2500 | MGF1 | | | | | 2501 | mask | | | | | 2502 | gener | | | | | 2503 | ation | | | | | 2504 | func | | | | | 2505 | tionwit | | | | | 2506 | h SHA | | | | | 2507 | -256 | | | | | 2508 | RSASSA- | PS | | | | 2509 | PSS | 38 | | | | 2510 | using | 4 | | | | 2511 | SHA-38 | | | | | 2512 | 4hash | | | | | 2513 | algori | | | | | 2514 | thm and | | | | | 2515 | MGF1 | | | | | 2516 | mask | | | | | 2517 | gener | | | | | 2518 | ation | | | | | 2519 | func | | | | | 2520 | tionwit | | | | | 2521 | h SHA | | | | | 2522 | -384 | | | | | 2523 | RSASSA- | PS | | | | 2524 | PSS | 51 | | | | 2525 | using | 2 | | | | 2526 | SHA-51 | | | | | 2527 | 2hash | | | | | 2528 | algori | | | | | 2529 | thm and | | | | | 2530 | MGF1 | | | | | 2531 | mask | | | | | 2532 | gener | | | | | 2533 | ation | | | | | 2534 | func | | | | | 2535 | tionwit | | | | | 2536 | h SHA | | | | | 2537 | -512 | | | | | 2538 +---------+----+---------------------------+----------+-------------+ 2540 Appendix B. Encryption Algorithm Identifier Cross-Reference 2542 This appendix contains a table cross-referencing the "alg" 2543 (algorithm) and "enc" (encryption method) values used in this 2544 specification with the equivalent identifiers used by other standards 2545 and software packages. See XML Encryption 2546 [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 2547 [W3C.CR-xmlenc-core1-20120313], and Java Cryptography Architecture 2548 [JCA] for more information about the names defined by those 2549 documents. 2551 For the composite algorithms "A128CBC-HS256", "A192CBC-HS384", and 2552 "A256CBC-HS512", the corresponding AES CBC algorithm identifiers are 2553 listed. 2555 +----------+--------+--------------------------+--------------------+ 2556 | Algorith | JWE | XML ENC | JCA | 2557 | m | | | | 2558 +----------+--------+--------------------------+--------------------+ 2559 | RSAES-PK | RSA1_5 | http://www.w3.org/2001/0 | RSA/ECB/PKCS1Paddi | 2560 | CS1-V1_5 | | 4/xmlenc#rsa-1_5 | ng | 2561 | RSAES | RSA-OA | http://www.w3.org/2001/0 | RSA/ECB/OAEPWithSH | 2562 | using | EP | 4/xmlenc#rsa-oaep-mgf1p | A-1AndMGF1Padding | 2563 | Optimal | | | | 2564 | Asymmetr | | | | 2565 | ic | | | | 2566 | Encrypt | | | | 2567 | ion | | | | 2568 | Paddin | | | | 2569 | g (OAEP) | | | | 2570 | Elliptic | ECDH-E | http://www.w3.org/2009/x | | 2571 | Curve | S | mlenc11#ECDH-ES | | 2572 | Diffie-H | | | | 2573 | ellman | | | | 2574 | Ephemer | | | | 2575 | alStatic | | | | 2576 | Advanced | A128KW | http://www.w3.org/2001/0 | | 2577 | Encrypti | | 4/xmlenc#kw-aes128 | | 2578 | on | | | | 2579 | Standar | | | | 2580 | d(AES) | | | | 2581 | Key Wra | | | | 2582 | pAlgorit | | | | 2583 | hmusing | | | | 2584 | 128 bi | | | | 2585 | t keys | | | | 2586 | AES Key | A192KW | http://www.w3.org/2001/0 | | 2587 | Wrap | | 4/xmlenc#kw-aes192 | | 2588 | Algorith | | | | 2589 | musing | | | | 2590 | 192 bit | | | | 2591 | keys | | | | 2592 | AES Key | A256KW | http://www.w3.org/2001/0 | | 2593 | Wrap | | 4/xmlenc#kw-aes256 | | 2594 | Algorith | | | | 2595 | musing | | | | 2596 | 256 bit | | | | 2597 | keys | | | | 2598 | AES in | A128CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 2599 | Cipher | C-HS25 | 4/xmlenc#aes128-cbc | ng | 2600 | Block | 6 | | | 2601 | Chaining | | | | 2602 | (CBC) | | | | 2603 | mode | | | | 2604 | with | | | | 2605 | PKCS #5 | | | | 2606 | padding | | | | 2607 | using | | | | 2608 | 128 bit | | | | 2609 | keys | | | | 2610 | AES in | A192CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 2611 | CBC mode | C-HS38 | 4/xmlenc#aes192-cbc | ng | 2612 | with | 4 | | | 2613 | PKCS #5 | | | | 2614 | padding | | | | 2615 | using | | | | 2616 | 192 bit | | | | 2617 | keys | | | | 2618 | AES in | A256CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 2619 | CBC mode | C-HS51 | 4/xmlenc#aes256-cbc | ng | 2620 | with | 2 | | | 2621 | PKCS #5 | | | | 2622 | padding | | | | 2623 | using | | | | 2624 | 256 bit | | | | 2625 | keys | | | | 2626 | AES in | A128GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 2627 | Galois/C | M | mlenc11#aes128-gcm | | 2628 | ounter | | | | 2629 | Mode | | | | 2630 | (GCM) | | | | 2631 | using | | | | 2632 | 128 bit | | | | 2633 | keys | | | | 2634 | AES GCM | A192GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 2635 | using | M | mlenc11#aes192-gcm | | 2636 | 192 bit | | | | 2637 | keys | | | | 2638 | AES GCM | A256GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 2639 | using | M | mlenc11#aes256-gcm | | 2640 | 256 bit | | | | 2641 | keys | | | | 2642 +----------+--------+--------------------------+--------------------+ 2644 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms 2646 The following test cases can be used to validate implementations of 2647 the AES_CBC_HMAC_SHA2 algorithms defined in Section 4.10. They are 2648 also intended to correspond to test cases that may appear in a future 2649 version of [I-D.mcgrew-aead-aes-cbc-hmac-sha2], demonstrating that 2650 the cryptographic computations performed are the same. 2652 The variable names are those defined in Section 4.10. All values are 2653 hexadecimal. 2655 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 2657 AES_128_CBC_HMAC_SHA_256 2659 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2660 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2662 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2664 ENC_KEY = 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2666 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2667 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2668 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2669 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2670 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2671 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2672 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2673 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2675 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2677 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2678 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2679 4b 65 72 63 6b 68 6f 66 66 73 2681 AL = 00 00 00 00 00 00 01 50 2683 E = c8 0e df a3 2d df 39 d5 ef 00 c0 b4 68 83 42 79 2684 a2 e4 6a 1b 80 49 f7 92 f7 6b fe 54 b9 03 a9 c9 2685 a9 4a c9 b4 7a d2 65 5c 5f 10 f9 ae f7 14 27 e2 2686 fc 6f 9b 3f 39 9a 22 14 89 f1 63 62 c7 03 23 36 2687 09 d4 5a c6 98 64 e3 32 1c f8 29 35 ac 40 96 c8 2688 6e 13 33 14 c5 40 19 e8 ca 79 80 df a4 b9 cf 1b 2689 38 4c 48 6f 3a 54 c5 10 78 15 8e e5 d7 9d e5 9f 2690 bd 34 d8 48 b3 d6 95 50 a6 76 46 34 44 27 ad e5 2691 4b 88 51 ff b5 98 f7 f8 00 74 b9 47 3c 82 e2 db 2693 M = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2694 e6 e5 45 82 47 65 15 f0 ad 9f 75 a2 b7 1c 73 ef 2696 T = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2698 C.2. Test Cases for AES_192_CBC_HMAC_SHA_384 2700 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2701 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2702 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2704 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2705 10 11 12 13 14 15 16 17 2707 ENC_KEY = 18 19 1a 1b 1c 1d 1e 1f 20 21 22 23 24 25 26 27 2708 28 29 2a 2b 2c 2d 2e 2f 2710 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2711 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2712 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2713 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2714 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2715 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2716 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2717 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2719 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2721 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2722 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2723 4b 65 72 63 6b 68 6f 66 66 73 2725 AL = 00 00 00 00 00 00 01 50 2727 E = ea 65 da 6b 59 e6 1e db 41 9b e6 2d 19 71 2a e5 2728 d3 03 ee b5 00 52 d0 df d6 69 7f 77 22 4c 8e db 2729 00 0d 27 9b dc 14 c1 07 26 54 bd 30 94 42 30 c6 2730 57 be d4 ca 0c 9f 4a 84 66 f2 2b 22 6d 17 46 21 2731 4b f8 cf c2 40 0a dd 9f 51 26 e4 79 66 3f c9 0b 2732 3b ed 78 7a 2f 0f fc bf 39 04 be 2a 64 1d 5c 21 2733 05 bf e5 91 ba e2 3b 1d 74 49 e5 32 ee f6 0a 9a 2734 c8 bb 6c 6b 01 d3 5d 49 78 7b cd 57 ef 48 49 27 2735 f2 80 ad c9 1a c0 c4 e7 9c 7b 11 ef c6 00 54 e3 2737 M = 84 90 ac 0e 58 94 9b fe 51 87 5d 73 3f 93 ac 20 2738 75 16 80 39 cc c7 33 d7 45 94 f8 86 b3 fa af d4 2739 86 f2 5c 71 31 e3 28 1e 36 c7 a2 d1 30 af de 57 2741 T = 84 90 ac 0e 58 94 9b fe 51 87 5d 73 3f 93 ac 20 2742 75 16 80 39 cc c7 33 d7 2744 C.3. Test Cases for AES_256_CBC_HMAC_SHA_512 2746 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2747 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2748 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2749 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2751 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2752 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2754 ENC_KEY = 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2755 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2757 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2758 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2759 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2760 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2761 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2762 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2763 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2764 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2766 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2768 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2769 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2770 4b 65 72 63 6b 68 6f 66 66 73 2772 AL = 00 00 00 00 00 00 01 50 2774 E = 4a ff aa ad b7 8c 31 c5 da 4b 1b 59 0d 10 ff bd 2775 3d d8 d5 d3 02 42 35 26 91 2d a0 37 ec bc c7 bd 2776 82 2c 30 1d d6 7c 37 3b cc b5 84 ad 3e 92 79 c2 2777 e6 d1 2a 13 74 b7 7f 07 75 53 df 82 94 10 44 6b 2778 36 eb d9 70 66 29 6a e6 42 7e a7 5c 2e 08 46 a1 2779 1a 09 cc f5 37 0d c8 0b fe cb ad 28 c7 3f 09 b3 2780 a3 b7 5e 66 2a 25 94 41 0a e4 96 b2 e2 e6 60 9e 2781 31 e6 e0 2c c8 37 f0 53 d2 1f 37 ff 4f 51 95 0b 2782 be 26 38 d0 9d d7 a4 93 09 30 80 6d 07 03 b1 f6 2784 M = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2785 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2786 fd 30 a5 65 c6 16 ff b2 f3 64 ba ec e6 8f c4 07 2787 53 bc fc 02 5d de 36 93 75 4a a1 f5 c3 37 3b 9c 2789 T = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2790 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2792 Appendix D. Example ECDH-ES Key Agreement Computation 2794 This example uses ECDH-ES Key Agreement and the Concat KDF to derive 2795 the Content Encryption Key (CEK) in the manner described in 2796 Section 4.7. In this example, the ECDH-ES Direct Key Agreement mode 2797 ("alg" value "ECDH-ES") is used to produce an agreed upon key for AES 2798 GCM with 128 bit keys ("enc" value "A128GCM"). 2800 In this example, a sender Alice is encrypting content to a recipient 2801 Bob. The sender (Alice) generates an ephemeral key for the key 2802 agreement computation. Alice's ephemeral key (in JWK format) used 2803 for the key agreement computation in this example (including the 2804 private part) is: 2806 {"kty":"EC", 2807 "crv":"P-256", 2808 "x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0", 2809 "y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps", 2810 "d":"0_NxaRPUMQoAJt50Gz8YiTr8gRTwyEaCumd-MToTmIo" 2811 } 2813 The recipient's (Bob's) key (in JWK format) used for the key 2814 agreement computation in this example (including the private part) 2815 is: 2817 {"kty":"EC", 2818 "crv":"P-256", 2819 "x":"weNJy2HscCSM6AEDTDg04biOvhFhyyWvOHQfeF_PxMQ", 2820 "y":"e8lnCO-AlStT-NJVX-crhB7QRYhiix03illJOVAOyck", 2821 "d":"VEmDZpDXXK8p8N0Cndsxs924q6nS1RXFASRl6BfUqdw" 2822 } 2824 Header parameter values used in this example are as follows. In this 2825 example, the "apu" (agreement PartyUInfo) parameter value is the 2826 base64url encoding of the UTF-8 string "Alice" and the "apv" 2827 (agreement PartyVInfo) parameter value is the base64url encoding of 2828 the UTF-8 string "Bob". The "epk" parameter is used to communicate 2829 the sender's (Alice's) ephemeral public key value to the recipient 2830 (Bob). 2832 {"alg":"ECDH-ES", 2833 "enc":"A128GCM", 2834 "apu":"QWxpY2U", 2835 "apv":"Qm9i", 2836 "epk": 2837 {"kty":"EC", 2838 "crv":"P-256", 2839 "x":"gI0GAILBdu7T53akrFmMyGcsF3n5dO7MmwNBHKW5SV0", 2840 "y":"SLW_xSffzlPWrHEVI30DHM_4egVwt3NQqeUD7nMFpps" 2841 } 2842 } 2844 The resulting Concat KDF [NIST.800-56A] parameter values are: 2846 Z This is set to the ECDH-ES key agreement output. (This value is 2847 often not directly exposed by libraries, due to NIST security 2848 requirements, and only serves as an input to a KDF.) 2850 keydatalen This value is 128 - the number of bits in the desired 2851 output key (because "A128GCM" uses a 128 bit key). 2853 AlgorithmID This is set to the octets representing the UTF-8 string 2854 "A128GCM" - [65, 49, 50, 56, 71, 67, 77]. 2856 PartyUInfo This is set to the octets representing the 32 bit big 2857 endian value 5 - [0, 0, 0, 5] - the number of octets in the 2858 PartyUInfo content "Alice", followed, by the octets representing 2859 the UTF-8 string "Alice" - [65, 108, 105, 99, 101]. 2861 PartyVInfo This is set to the octets representing the 32 bit big 2862 endian value 3 - [0, 0, 0, 3] - the number of octets in the 2863 PartyUInfo content "Bob", followed, by the octets representing the 2864 UTF-8 string "Bob" - [66, 111, 98]. 2866 SuppPubInfo This is set to the octets representing the 32 bit big 2867 endian value 128 - [0, 0, 0, 128] - the keydatalen value. 2869 SuppPrivInfo This is set to the empty octet sequence. 2871 The resulting derived key, represented as a base64url encoded value 2872 is: 2874 jSNmj9QK9ZGQJ2xg5_TJpA 2876 Appendix E. Acknowledgements 2878 Solutions for signing and encrypting JSON content were previously 2879 explored by Magic Signatures [MagicSignatures], JSON Simple Sign 2880 [JSS], Canvas Applications [CanvasApp], JSON Simple Encryption [JSE], 2881 and JavaScript Message Security Format [I-D.rescorla-jsms], all of 2882 which influenced this draft. 2884 The Authenticated Encryption with AES-CBC and HMAC-SHA 2885 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] specification, upon which the 2886 AES_CBC_HMAC_SHA2 algorithms are based, was written by David A. 2887 McGrew and Kenny Paterson. The test cases for AES_CBC_HMAC_SHA2 are 2888 based upon those for [I-D.mcgrew-aead-aes-cbc-hmac-sha2] by John 2889 Foley. 2891 Matt Miller wrote Using JavaScript Object Notation (JSON) Web 2892 Encryption (JWE) for Protecting JSON Web Key (JWK) Objects 2893 [I-D.miller-jose-jwe-protected-jwk], which the password-based 2894 encryption content of this draft is based upon. 2896 This specification is the work of the JOSE Working Group, which 2897 includes dozens of active and dedicated participants. In particular, 2898 the following individuals contributed ideas, feedback, and wording 2899 that influenced this specification: 2901 Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de 2902 Medeiros, Yaron Y. Goland, Dick Hardt, Jeff Hodges, Edmund Jay, James 2903 Manger, Matt Miller, Tony Nadalin, Axel Nennker, John Panzer, 2904 Emmanuel Raviart, Nat Sakimura, Jim Schaad, Hannes Tschofenig, and 2905 Sean Turner. 2907 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2908 Sean Turner and Stephen Farrell served as Security area directors 2909 during the creation of this specification. 2911 Appendix F. Document History 2913 [[ to be removed by the RFC editor before publication as an RFC ]] 2915 -14 2917 o Removed "PBKDF2" key type and added "p2s" and "p2c" header 2918 parameters for use with the PBES2 algorithms. 2920 o Made the RSA private key parameters that are there to enable 2921 optimizations be RECOMMENDED rather than REQUIRED. 2923 o Added algorithm identifiers for AES algorithms using 192 bit keys 2924 and for RSASSA-PSS using HMAC SHA-384. 2926 o Added security considerations about key lifetimes, addressing 2927 issue #18. 2929 o Added an example ECDH-ES key agreement computation. 2931 -13 2933 o Added key encryption with AES GCM as specified in 2934 draft-jones-jose-aes-gcm-key-wrap-01, addressing issue #13. 2936 o Added security considerations text limiting the number of times 2937 that an AES GCM key can be used for key encryption or direct 2938 encryption, per Section 8.3 of NIST SP 800-38D, addressing issue 2939 #28. 2941 o Added password-based key encryption as specified in 2942 draft-miller-jose-jwe-protected-jwk-02. 2944 -12 2946 o In the Direct Key Agreement case, the Concat KDF AlgorithmID is 2947 set to the octets of the UTF-8 representation of the "enc" header 2948 parameter value. 2950 o Restored the "apv" (agreement PartyVInfo) parameter. 2952 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2953 be with the algorithm descriptions that use them. 2955 o Changed terminology from "block encryption" to "content 2956 encryption". 2958 -11 2960 o Removed the Encrypted Key value from the AAD computation since it 2961 is already effectively integrity protected by the encryption 2962 process. The AAD value now only contains the representation of 2963 the JWE Encrypted Header. 2965 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2967 o Added more information about the use of PartyUInfo during key 2968 agreement. 2970 o Use the keydatalen as the SuppPubInfo value for the Concat KDF 2971 when doing key agreement, as RFC 2631 does. 2973 o Added algorithm identifiers for RSASSA-PSS with SHA-256 and SHA- 2974 512. 2976 o Added a Parameter Information Class value to the JSON Web Key 2977 Parameters registry, which registers whether the parameter conveys 2978 public or private information. 2980 -10 2982 o Changed the JWE processing rules for multiple recipients so that a 2983 single AAD value contains the header parameters and encrypted key 2984 values for all the recipients, enabling AES GCM to be safely used 2985 for multiple recipients. 2987 -09 2989 o Expanded the scope of the JWK parameters to include private and 2990 symmetric key representations, as specified by 2991 draft-jones-jose-json-private-and-symmetric-key-00. 2993 o Changed term "JWS Secured Input" to "JWS Signing Input". 2995 o Changed from using the term "byte" to "octet" when referring to 8 2996 bit values. 2998 o Specified that AES Key Wrap uses the default initial value 2999 specified in Section 2.2.3.1 of RFC 3394. This addressed issue 3000 #19. 3002 o Added Key Management Mode definitions to terminology section and 3003 used the defined terms to provide clearer key management 3004 instructions. This addressed issue #5. 3006 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 3007 and "A256CBC-HS512". The new algorithms perform the same 3008 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 3009 but with the Initialization Vector and Authentication Tag values 3010 remaining separate from the Ciphertext value in the output 3011 representation. Also deleted the header parameters "epu" 3012 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 3013 they are no longer used. 3015 o Changed from using the term "Integrity Value" to "Authentication 3016 Tag". 3018 -08 3020 o Changed the name of the JWK key type parameter from "alg" to 3021 "kty". 3023 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 3024 since the term AEAD in the RFC 5116 sense implied the use of a 3025 particular data representation, rather than just referring to the 3026 class of algorithms that perform authenticated encryption with 3027 associated data. 3029 o Applied editorial improvements suggested by Jeff Hodges. Many of 3030 these simplified the terminology used. 3032 o Added seriesInfo information to Internet Draft references. 3034 -07 3036 o Added a data length prefix to PartyUInfo and PartyVInfo values. 3038 o Changed the name of the JWK RSA modulus parameter from "mod" to 3039 "n" and the name of the JWK RSA exponent parameter from "xpo" to 3040 "e", so that the identifiers are the same as those used in RFC 3041 3447. 3043 o Made several local editorial changes to clean up loose ends left 3044 over from to the decision to only support block encryption methods 3045 providing integrity. 3047 -06 3049 o Removed the "int" and "kdf" parameters and defined the new 3050 composite Authenticated Encryption algorithms "A128CBC+HS256" and 3051 "A256CBC+HS512" to replace the former uses of AES CBC, which 3052 required the use of separate integrity and key derivation 3053 functions. 3055 o Included additional values in the Concat KDF calculation -- the 3056 desired output size and the algorithm value, and optionally 3057 PartyUInfo and PartyVInfo values. Added the optional header 3058 parameters "apu" (agreement PartyUInfo), "apv" (agreement 3059 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 3060 PartyVInfo). 3062 o Changed the name of the JWK RSA exponent parameter from "exp" to 3063 "xpo" so as to allow the potential use of the name "exp" for a 3064 future extension that might define an expiration parameter for 3065 keys. (The "exp" name is already used for this purpose in the JWT 3066 specification.) 3068 o Applied changes made by the RFC Editor to RFC 6749's registry 3069 language to this specification. 3071 -05 3073 o Support both direct encryption using a shared or agreed upon 3074 symmetric key, and the use of a shared or agreed upon symmetric 3075 key to key wrap the CMK. Specifically, added the "alg" values 3076 "dir", "ECDH-ES+A128KW", and "ECDH-ES+A256KW" to finish filling in 3077 this set of capabilities. 3079 o Updated open issues. 3081 -04 3083 o Added text requiring that any leading zero bytes be retained in 3084 base64url encoded key value representations for fixed-length 3085 values. 3087 o Added this language to Registration Templates: "This name is case 3088 sensitive. Names that match other registered names in a case 3089 insensitive manner SHOULD NOT be accepted." 3091 o Described additional open issues. 3093 o Applied editorial suggestions. 3095 -03 3097 o Always use a 128 bit "authentication tag" size for AES GCM, 3098 regardless of the key size. 3100 o Specified that use of a 128 bit IV is REQUIRED with AES CBC. It 3101 was previously RECOMMENDED. 3103 o Removed key size language for ECDSA algorithms, since the key size 3104 is implied by the algorithm being used. 3106 o Stated that the "int" key size must be the same as the hash output 3107 size (and not larger, as was previously allowed) so that its size 3108 is defined for key generation purposes. 3110 o Added the "kdf" (key derivation function) header parameter to 3111 provide crypto agility for key derivation. The default KDF 3112 remains the Concat KDF with the SHA-256 digest function. 3114 o Clarified that the "mod" and "exp" values are unsigned. 3116 o Added Implementation Requirements columns to algorithm tables and 3117 Implementation Requirements entries to algorithm registries. 3119 o Changed AES Key Wrap to RECOMMENDED. 3121 o Moved registries JSON Web Signature and Encryption Header 3122 Parameters and JSON Web Signature and Encryption Type Values to 3123 the JWS specification. 3125 o Moved JSON Web Key Parameters registry to the JWK specification. 3127 o Changed registration requirements from RFC Required to 3128 Specification Required with Expert Review. 3130 o Added Registration Template sections for defined registries. 3132 o Added Registry Contents sections to populate registry values. 3134 o No longer say "the UTF-8 representation of the JWS Secured Input 3135 (which is the same as the ASCII representation)". Just call it 3136 "the ASCII representation of the JWS Secured Input". 3138 o Added "Collision Resistant Namespace" to the terminology section. 3140 o Numerous editorial improvements. 3142 -02 3144 o For AES GCM, use the "additional authenticated data" parameter to 3145 provide integrity for the header, encrypted key, and ciphertext 3146 and use the resulting "authentication tag" value as the JWE 3147 Authentication Tag. 3149 o Defined minimum required key sizes for algorithms without 3150 specified key sizes. 3152 o Defined KDF output key sizes. 3154 o Specified the use of PKCS #5 padding with AES CBC. 3156 o Generalized text to allow key agreement to be employed as an 3157 alternative to key wrapping or key encryption. 3159 o Clarified that ECDH-ES is a key agreement algorithm. 3161 o Required implementation of AES-128-KW and AES-256-KW. 3163 o Removed the use of "A128GCM" and "A256GCM" for key wrapping. 3165 o Removed "A512KW" since it turns out that it's not a standard 3166 algorithm. 3168 o Clarified the relationship between "typ" header parameter values 3169 and MIME types. 3171 o Generalized language to refer to Message Authentication Codes 3172 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 3173 unless in a context specific to HMAC algorithms. 3175 o Established registries: JSON Web Signature and Encryption Header 3176 Parameters, JSON Web Signature and Encryption Algorithms, JSON Web 3177 Signature and Encryption "typ" Values, JSON Web Key Parameters, 3178 and JSON Web Key Algorithm Families. 3180 o Moved algorithm-specific definitions from JWK to JWA. 3182 o Reformatted to give each member definition its own section 3183 heading. 3185 -01 3187 o Moved definition of "alg":"none" for JWSs here from the JWT 3188 specification since this functionality is likely to be useful in 3189 more contexts that just for JWTs. 3191 o Added Advanced Encryption Standard (AES) Key Wrap Algorithm using 3192 512 bit keys ("A512KW"). 3194 o Added text "Alternatively, the Encoded JWS Signature MAY be 3195 base64url decoded to produce the JWS Signature and this value can 3196 be compared with the computed HMAC value, as this comparison 3197 produces the same result as comparing the encoded values". 3199 o Corrected the Magic Signatures reference. 3201 o Made other editorial improvements suggested by JOSE working group 3202 participants. 3204 -00 3206 o Created the initial IETF draft based upon 3207 draft-jones-json-web-signature-04 and 3208 draft-jones-json-web-encryption-02 with no normative changes. 3210 o Changed terminology to no longer call both digital signatures and 3211 HMACs "signatures". 3213 Author's Address 3215 Michael B. Jones 3216 Microsoft 3218 Email: mbj@microsoft.com 3219 URI: http://self-issued.info/