idnits 2.17.1 draft-ietf-jose-json-web-algorithms-12.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 date (July 11, 2013) is 3941 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 1353 -- Looks like a reference, but probably isn't: '0' on line 1353 -- 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 ** 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-01 -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) Summary: 5 errors (**), 0 flaws (~~), 3 warnings (==), 9 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 11, 2013 5 Expires: January 12, 2014 7 JSON Web Algorithms (JWA) 8 draft-ietf-jose-json-web-algorithms-12 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 12, 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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 52 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 53 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 2.1. Terms Incorporated from the JWS Specification . . . . . . 4 55 2.2. Terms Incorporated from the JWE Specification . . . . . . 5 56 2.3. Terms Incorporated from the JWK Specification . . . . . . 8 57 2.4. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 8 58 3. Cryptographic Algorithms for JWS . . . . . . . . . . . . . . . 8 59 3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 8 60 3.2. MAC with HMAC SHA-256, HMAC SHA-384, or HMAC SHA-512 . . . 9 61 3.3. Digital Signature with RSASSA-PKCS1-V1_5 and SHA-256, 62 SHA-384, or SHA-512 . . . . . . . . . . . . . . . . . . . 10 63 3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA 64 P-384 SHA-384, or ECDSA P-521 SHA-512 . . . . . . . . . . 11 65 3.5. Digital Signature with RSASSA-PSS and SHA-256 or 66 SHA-512 . . . . . . . . . . . . . . . . . . . . . . . . . 13 67 3.6. Using the Algorithm "none" . . . . . . . . . . . . . . . . 14 68 3.7. Additional Digital Signature/MAC Algorithms and 69 Parameters . . . . . . . . . . . . . . . . . . . . . . . . 14 70 4. Cryptographic Algorithms for JWE . . . . . . . . . . . . . . . 15 71 4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 15 72 4.2. "enc" (Encryption Method) Header Parameter Values for 73 JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 74 4.3. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 19 75 4.4. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 19 76 4.5. Key Wrapping with AES Key Wrap . . . . . . . . . . . . . . 19 77 4.6. Direct Encryption with a Shared Symmetric Key . . . . . . 19 78 4.7. Key Agreement with Elliptic Curve Diffie-Hellman 79 Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 19 80 4.7.1. Header Parameters Used for ECDH Key Agreement . . . . 20 81 4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter . . 20 82 4.7.1.2. "apu" (Agreement PartyUInfo) Header Parameter . . 20 83 4.7.1.3. "apv" (Agreement PartyVInfo) Header Parameter . . 20 84 4.7.2. Key Derivation for ECDH Key Agreement . . . . . . . . 21 85 4.8. AES_CBC_HMAC_SHA2 Algorithms . . . . . . . . . . . . . . . 22 86 4.8.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 . . . . 22 87 4.8.2. Generic AES_CBC_HMAC_SHA2 Algorithm . . . . . . . . . 23 88 4.8.2.1. AES_CBC_HMAC_SHA2 Encryption . . . . . . . . . . . 23 89 4.8.2.2. AES_CBC_HMAC_SHA2 Decryption . . . . . . . . . . . 24 90 4.8.3. AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . 25 91 4.8.4. AES_256_CBC_HMAC_SHA_512 . . . . . . . . . . . . . . . 25 92 4.8.5. Plaintext Encryption with AES_CBC_HMAC_SHA2 . . . . . 26 93 4.9. Plaintext Encryption with AES GCM . . . . . . . . . . . . 26 94 4.10. Additional Encryption Algorithms and Parameters . . . . . 26 95 5. Cryptographic Algorithms for JWK . . . . . . . . . . . . . . . 27 96 5.1. "kty" (Key Type) Parameter Values for JWK . . . . . . . . 27 97 5.2. JWK Parameters for Elliptic Curve Keys . . . . . . . . . . 28 98 5.2.1. JWK Parameters for Elliptic Curve Public Keys . . . . 28 99 5.2.1.1. "crv" (Curve) Parameter . . . . . . . . . . . . . 28 100 5.2.1.2. "x" (X Coordinate) Parameter . . . . . . . . . . . 28 101 5.2.1.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . 28 102 5.2.2. JWK Parameters for Elliptic Curve Private Keys . . . . 29 103 5.2.2.1. "d" (ECC Private Key) Parameter . . . . . . . . . 29 104 5.3. JWK Parameters for RSA Keys . . . . . . . . . . . . . . . 29 105 5.3.1. JWK Parameters for RSA Public Keys . . . . . . . . . . 29 106 5.3.1.1. "n" (Modulus) Parameter . . . . . . . . . . . . . 29 107 5.3.1.2. "e" (Exponent) Parameter . . . . . . . . . . . . . 29 108 5.3.2. JWK Parameters for RSA Private Keys . . . . . . . . . 30 109 5.3.2.1. "d" (Private Exponent) Parameter . . . . . . . . . 30 110 5.3.2.2. "p" (First Prime Factor) Parameter . . . . . . . . 30 111 5.3.2.3. "q" (Second Prime Factor) Parameter . . . . . . . 30 112 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter . . . . 30 113 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter . . . 30 114 5.3.2.6. "qi" (First CRT Coefficient) Parameter . . . . . . 30 115 5.3.2.7. "oth" (Other Primes Info) Parameter . . . . . . . 31 116 5.3.3. JWK Parameters for Symmetric Keys . . . . . . . . . . 31 117 5.3.3.1. "k" (Key Value) Parameter . . . . . . . . . . . . 31 118 5.4. Additional Key Types and Parameters . . . . . . . . . . . 32 119 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 120 6.1. JSON Web Signature and Encryption Algorithms Registry . . 32 121 6.1.1. Template . . . . . . . . . . . . . . . . . . . . . . . 33 122 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 33 123 6.2. JSON Web Key Types Registry . . . . . . . . . . . . . . . 37 124 6.2.1. Registration Template . . . . . . . . . . . . . . . . 37 125 6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 37 126 6.3. JSON Web Key Parameters Registration . . . . . . . . . . . 38 127 6.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 38 128 6.4. Registration of JWE Header Parameter Names . . . . . . . . 39 129 6.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 40 130 7. Security Considerations . . . . . . . . . . . . . . . . . . . 40 131 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 41 132 8.1. Normative References . . . . . . . . . . . . . . . . . . . 41 133 8.2. Informative References . . . . . . . . . . . . . . . . . . 43 134 Appendix A. Digital Signature/MAC Algorithm Identifier 135 Cross-Reference . . . . . . . . . . . . . . . . . . . 44 136 Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 46 137 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms . . . . . 48 138 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 . . . . . . . . . 49 139 C.2. Test Cases for AES_256_CBC_HMAC_SHA_512 . . . . . . . . . 50 140 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 51 141 Appendix E. Document History . . . . . . . . . . . . . . . . . . 51 142 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 57 144 1. Introduction 146 The JSON Web Algorithms (JWA) specification enumerates cryptographic 147 algorithms and identifiers to be used with the JSON Web Signature 148 (JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK) 149 [JWK] specifications. All these specifications utilize JavaScript 150 Object Notation (JSON) [RFC4627] based data structures. This 151 specification also describes the semantics and operations that are 152 specific to these algorithms and key types. 154 Enumerating the algorithms and identifiers for them in this 155 specification, rather than in the JWS, JWE, and JWK specifications, 156 is intended to allow them to remain unchanged in the face of changes 157 in the set of required, recommended, optional, and deprecated 158 algorithms over time. 160 1.1. Notational Conventions 162 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 163 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 164 document are to be interpreted as described in Key words for use in 165 RFCs to Indicate Requirement Levels [RFC2119]. 167 2. Terminology 169 2.1. Terms Incorporated from the JWS Specification 171 These terms defined by the JSON Web Signature (JWS) [JWS] 172 specification are incorporated into this specification: 174 JSON Web Signature (JWS) A data structure representing a digitally 175 signed or MACed message. The structure represents three values: 176 the JWS Header, the JWS Payload, and the JWS Signature. 178 JSON Text Object A UTF-8 [RFC3629] encoded text string representing 179 a JSON object; the syntax of JSON objects is defined in Section 180 2.2 of [RFC4627]. 182 JWS Header A JSON Text Object (or JSON Text Objects, when using the 183 JWS JSON Serialization) that describes the digital signature or 184 MAC operation applied to create the JWS Signature value. The 185 members of the JWS Header object(s) are Header Parameters. 187 JWS Payload The sequence of octets to be secured -- a.k.a., the 188 message. The payload can contain an arbitrary sequence of octets. 190 JWS Signature A sequence of octets containing the cryptographic 191 material that ensures the integrity of the JWS Protected Header 192 and the JWS Payload. The JWS Signature value is a digital 193 signature or MAC value calculated over the JWS Signing Input using 194 the parameters specified in the JWS Header. 196 JWS Protected Header A JSON Text Object that contains the portion of 197 the JWS Header that is integrity protected. For the JWS Compact 198 Serialization, this comprises the entire JWS Header. For the JWS 199 JSON Serialization, this is one component of the JWS Header. 201 Base64url Encoding The URL- and filename-safe Base64 encoding 202 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 203 safe) '=' padding characters omitted, as permitted by Section 3.2. 204 (See Appendix C of [JWS] for notes on implementing base64url 205 encoding without padding.) 207 Encoded JWS Header Base64url encoding of the JWS Protected Header. 209 Encoded JWS Payload Base64url encoding of the JWS Payload. 211 Encoded JWS Signature Base64url encoding of the JWS Signature. 213 JWS Signing Input The concatenation of the Encoded JWS Header, a 214 period ('.') character, and the Encoded JWS Payload. 216 Collision Resistant Namespace A namespace that allows names to be 217 allocated in a manner such that they are highly unlikely to 218 collide with other names. For instance, collision resistance can 219 be achieved through administrative delegation of portions of the 220 namespace or through use of collision-resistant name allocation 221 functions. Examples of Collision Resistant Namespaces include: 222 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 223 X.660 and X.670 Recommendation series, and Universally Unique 224 IDentifiers (UUIDs) [RFC4122]. When using an administratively 225 delegated namespace, the definer of a name needs to take 226 reasonable precautions to ensure they are in control of the 227 portion of the namespace they use to define the name. 229 2.2. Terms Incorporated from the JWE Specification 231 These terms defined by the JSON Web Encryption (JWE) [JWE] 232 specification are incorporated into this specification: 234 JSON Web Encryption (JWE) A data structure representing an encrypted 235 message. The structure represents five values: the JWE Header, 236 the JWE Encrypted Key, the JWE Initialization Vector, the JWE 237 Ciphertext, and the JWE Authentication Tag. 239 Authenticated Encryption An Authenticated Encryption algorithm is 240 one that provides an integrated content integrity check. 241 Authenticated Encryption algorithms accept two inputs, the 242 Plaintext and the Additional Authenticated Data value, and produce 243 two outputs, the Ciphertext and the Authentication Tag value. AES 244 Galois/Counter Mode (GCM) is one such algorithm. 246 Plaintext The sequence of octets to be encrypted -- a.k.a., the 247 message. The plaintext can contain an arbitrary sequence of 248 octets. 250 Ciphertext An encrypted representation of the Plaintext. 252 Additional Authenticated Data (AAD) An input to an Authenticated 253 Encryption operation that is integrity protected but not 254 encrypted. 256 Authentication Tag An output of an Authenticated Encryption 257 operation that ensures the integrity of the Ciphertext and the 258 Additional Authenticated Data. Note that some algorithms may not 259 use an Authentication Tag, in which case this value is the empty 260 octet sequence. 262 Content Encryption Key (CEK) A symmetric key for the Authenticated 263 Encryption algorithm used to encrypt the Plaintext for the 264 recipient to produce the Ciphertext and the Authentication Tag. 266 JWE Header A JSON Text Object (or JSON Text Objects, when using the 267 JWE JSON Serialization) that describes the encryption operations 268 applied to create the JWE Encrypted Key, the JWE Ciphertext, and 269 the JWE Authentication Tag. The members of the JWE Header 270 object(s) are Header Parameters. 272 JWE Encrypted Key The result of encrypting the Content Encryption 273 Key (CEK) with the intended recipient's key using the specified 274 algorithm. Note that for some algorithms, the JWE Encrypted Key 275 value is specified as being the empty octet sequence. 277 JWE Initialization Vector A sequence of octets containing the 278 Initialization Vector used when encrypting the Plaintext. Note 279 that some algorithms may not use an Initialization Vector, in 280 which case this value is the empty octet sequence. 282 JWE Ciphertext A sequence of octets containing the Ciphertext for a 283 JWE. 285 JWE Authentication Tag A sequence of octets containing the 286 Authentication Tag for a JWE. 288 JWE Protected Header A JSON Text Object that contains the portion of 289 the JWE Header that is integrity protected. For the JWE Compact 290 Serialization, this comprises the entire JWE Header. For the JWE 291 JSON Serialization, this is one component of the JWE Header. 293 Encoded JWE Header Base64url encoding of the JWE Protected Header. 295 Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted 296 Key. 298 Encoded JWE Initialization Vector Base64url encoding of the JWE 299 Initialization Vector. 301 Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. 303 Encoded JWE Authentication Tag Base64url encoding of the JWE 304 Authentication Tag. 306 Key Management Mode A method of determining the Content Encryption 307 Key (CEK) value to use. Each algorithm used for determining the 308 CEK value uses a specific Key Management Mode. Key Management 309 Modes employed by this specification are Key Encryption, Key 310 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 311 and Direct Encryption. 313 Key Encryption A Key Management Mode in which the Content Encryption 314 Key (CEK) value is encrypted to the intended recipient using an 315 asymmetric encryption algorithm. 317 Key Wrapping A Key Management Mode in which the Content Encryption 318 Key (CEK) value is encrypted to the intended recipient using a 319 symmetric key wrapping algorithm. 321 Direct Key Agreement A Key Management Mode in which a key agreement 322 algorithm is used to agree upon the Content Encryption Key (CEK) 323 value. 325 Key Agreement with Key Wrapping A Key Management Mode in which a key 326 agreement algorithm is used to agree upon a symmetric key used to 327 encrypt the Content Encryption Key (CEK) value to the intended 328 recipient using a symmetric key wrapping algorithm. 330 Direct Encryption A Key Management Mode in which the Content 331 Encryption Key (CEK) value used is the secret symmetric key value 332 shared between the parties. 334 2.3. Terms Incorporated from the JWK Specification 336 These terms defined by the JSON Web Key (JWK) [JWK] specification are 337 incorporated into this specification: 339 JSON Web Key (JWK) A JSON object that represents a cryptographic 340 key. 342 JSON Web Key Set (JWK Set) A JSON object that contains an array of 343 JWKs as the value of its "keys" member. 345 2.4. Defined Terms 347 These terms are defined for use by this specification: 349 Header Parameter A name/value pair that is member of a JWS Header or 350 JWE Header. 352 Header Parameter Name The name of a member of a JSON object 353 representing a JWS Header or JWE Header. 355 Header Parameter Value The value of a member of a JSON object 356 representing a JWS Header or JWE Header. 358 3. Cryptographic Algorithms for JWS 360 JWS uses cryptographic algorithms to digitally sign or create a 361 Message Authentication Codes (MAC) of the contents of the JWS Header 362 and the JWS Payload. The use of the following algorithms for 363 producing JWSs is defined in this section. 365 3.1. "alg" (Algorithm) Header Parameter Values for JWS 367 The table below is the set of "alg" (algorithm) header parameter 368 values defined by this specification for use with JWS, each of which 369 is explained in more detail in the following sections: 371 +-----------+--------------------------------------+----------------+ 372 | alg | Digital Signature or MAC Algorithm | Implementation | 373 | Parameter | | Requirements | 374 | Value | | | 375 +-----------+--------------------------------------+----------------+ 376 | HS256 | HMAC using SHA-256 hash algorithm | REQUIRED | 377 | HS384 | HMAC using SHA-384 hash algorithm | OPTIONAL | 378 | HS512 | HMAC using SHA-512 hash algorithm | OPTIONAL | 379 | RS256 | RSASSA-PKCS-v1_5 using SHA-256 hash | RECOMMENDED | 380 | | algorithm | | 381 | RS384 | RSASSA-PKCS-v1_5 using SHA-384 hash | OPTIONAL | 382 | | algorithm | | 383 | RS512 | RSASSA-PKCS-v1_5 using SHA-512 hash | OPTIONAL | 384 | | algorithm | | 385 | ES256 | ECDSA using P-256 curve and SHA-256 | RECOMMENDED+ | 386 | | hash algorithm | | 387 | ES384 | ECDSA using P-384 curve and SHA-384 | OPTIONAL | 388 | | hash algorithm | | 389 | ES512 | ECDSA using P-521 curve and SHA-512 | OPTIONAL | 390 | | hash algorithm | | 391 | PS256 | RSASSA-PSS using SHA-256 hash | OPTIONAL | 392 | | algorithm and MGF1 mask generation | | 393 | | function with SHA-256 | | 394 | PS512 | RSASSA-PSS using SHA-512 hash | OPTIONAL | 395 | | algorithm and MGF1 mask generation | | 396 | | function with SHA-512 | | 397 | none | No digital signature or MAC value | REQUIRED | 398 | | included | | 399 +-----------+--------------------------------------+----------------+ 401 All the names are short because a core goal of JWS is for the 402 representations to be compact. However, there is no a priori length 403 restriction on "alg" values. 405 The use of "+" in the Implementation Requirements indicates that the 406 requirement strength is likely to be increased in a future version of 407 the specification. 409 See Appendix A for a table cross-referencing the digital signature 410 and MAC "alg" (algorithm) values used in this specification with the 411 equivalent identifiers used by other standards and software packages. 413 3.2. MAC with HMAC SHA-256, HMAC SHA-384, or HMAC SHA-512 415 Hash-based Message Authentication Codes (HMACs) enable one to use a 416 secret plus a cryptographic hash function to generate a Message 417 Authentication Code (MAC). This can be used to demonstrate that the 418 MAC matches the hashed content, in this case the JWS Signing Input, 419 which therefore demonstrates that whoever generated the MAC was in 420 possession of the secret. The means of exchanging the shared key is 421 outside the scope of this specification. 423 The algorithm for implementing and validating HMACs is provided in 424 RFC 2104 [RFC2104]. This section defines the use of the HMAC SHA- 425 256, HMAC SHA-384, and HMAC SHA-512 functions [SHS]. The "alg" 426 (algorithm) header parameter values "HS256", "HS384", and "HS512" are 427 used in the JWS Header to indicate that the Encoded JWS Signature 428 contains a base64url encoded HMAC value using the respective hash 429 function. 431 A key of the same size as the hash output (for instance, 256 bits for 432 "HS256") or larger MUST be used with this algorithm. 434 The HMAC SHA-256 MAC is generated per RFC 2104, using SHA-256 as the 435 hash algorithm "H", using the octets of the ASCII [USASCII] 436 representation of the JWS Signing Input as the "text" value, and 437 using the shared key. The HMAC output value is the JWS Signature. 438 The JWS signature is base64url encoded to produce the Encoded JWS 439 Signature. 441 The HMAC SHA-256 MAC for a JWS is validated by computing an HMAC 442 value per RFC 2104, using SHA-256 as the hash algorithm "H", using 443 the octets of the ASCII representation of the received JWS Signing 444 Input as the "text" value, and using the shared key. This computed 445 HMAC value is then compared to the result of base64url decoding the 446 received Encoded JWS signature. Alternatively, the computed HMAC 447 value can be base64url encoded and compared to the received Encoded 448 JWS Signature, as this comparison produces the same result as 449 comparing the unencoded values. In either case, if the values match, 450 the HMAC has been validated. If the validation fails, the JWS MUST 451 be rejected. 453 Securing content with the HMAC SHA-384 and HMAC SHA-512 algorithms is 454 performed identically to the procedure for HMAC SHA-256 - just using 455 the corresponding hash algorithm with correspondingly larger minimum 456 key sizes and result values: 384 bits each for HMAC SHA-384 and 512 457 bits each for HMAC SHA-512. 459 An example using this algorithm is shown in Appendix A.1 of [JWS]. 461 3.3. Digital Signature with RSASSA-PKCS1-V1_5 and SHA-256, SHA-384, or 462 SHA-512 464 This section defines the use of the RSASSA-PKCS1-V1_5 digital 465 signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447] 466 (commonly known as PKCS #1), using SHA-256, SHA-384, or SHA-512 [SHS] 467 as the hash functions. The "alg" (algorithm) header parameter values 468 "RS256", "RS384", and "RS512" are used in the JWS Header to indicate 469 that the Encoded JWS Signature contains a base64url encoded RSASSA- 470 PKCS1-V1_5 digital signature using the respective hash function. 472 A key of size 2048 bits or larger MUST be used with these algorithms. 474 The RSASSA-PKCS1-V1_5 SHA-256 digital signature is generated as 475 follows: 477 1. Generate a digital signature of the octets of the ASCII 478 representation of the JWS Signing Input using RSASSA-PKCS1-V1_5- 479 SIGN and the SHA-256 hash function with the desired private key. 480 The output will be an octet sequence. 482 2. Base64url encode the resulting octet sequence. 484 The output is the Encoded JWS Signature for that JWS. 486 The RSASSA-PKCS1-V1_5 SHA-256 digital signature for a JWS is 487 validated as follows: 489 1. Take the Encoded JWS Signature and base64url decode it into an 490 octet sequence. If decoding fails, the JWS MUST be rejected. 492 2. Submit the octets of the ASCII representation of the JWS Signing 493 Input and the public key corresponding to the private key used by 494 the signer to the RSASSA-PKCS1-V1_5-VERIFY algorithm using SHA- 495 256 as the hash function. 497 3. If the validation fails, the JWS MUST be rejected. 499 Signing with the RSASSA-PKCS1-V1_5 SHA-384 and RSASSA-PKCS1-V1_5 SHA- 500 512 algorithms is performed identically to the procedure for RSASSA- 501 PKCS1-V1_5 SHA-256 - just using the corresponding hash algorithm with 502 correspondingly larger result values: 384 bits for RSASSA-PKCS1-V1_5 503 SHA-384 and 512 bits for RSASSA-PKCS1-V1_5 SHA-512. 505 An example using this algorithm is shown in Appendix A.2 of [JWS]. 507 3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA P-384 SHA-384, 508 or ECDSA P-521 SHA-512 510 The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides 511 for the use of Elliptic Curve cryptography, which is able to provide 512 equivalent security to RSA cryptography but using shorter key sizes 513 and with greater processing speed. This means that ECDSA digital 514 signatures will be substantially smaller in terms of length than 515 equivalently strong RSA digital signatures. 517 This specification defines the use of ECDSA with the P-256 curve and 518 the SHA-256 cryptographic hash function, ECDSA with the P-384 curve 519 and the SHA-384 hash function, and ECDSA with the P-521 curve and the 520 SHA-512 hash function. The P-256, P-384, and P-521 curves are 521 defined in [DSS]. The "alg" (algorithm) header parameter values 522 "ES256", "ES384", and "ES512" are used in the JWS Header to indicate 523 that the Encoded JWS Signature contains a base64url encoded ECDSA 524 P-256 SHA-256, ECDSA P-384 SHA-384, or ECDSA P-521 SHA-512 digital 525 signature, respectively. 527 The ECDSA P-256 SHA-256 digital signature is generated as follows: 529 1. Generate a digital signature of the octets of the ASCII 530 representation of the JWS Signing Input using ECDSA P-256 SHA-256 531 with the desired private key. The output will be the pair (R, 532 S), where R and S are 256 bit unsigned integers. 534 2. Turn R and S into octet sequences in big endian order, with each 535 array being be 32 octets long. The array representations MUST 536 NOT be shortened to omit any leading zero octets contained in the 537 values. 539 3. Concatenate the two octet sequences in the order R and then S. 540 (Note that many ECDSA implementations will directly produce this 541 concatenation as their output.) 543 4. Base64url encode the resulting 64 octet sequence. 545 The output is the Encoded JWS Signature for the JWS. 547 The ECDSA P-256 SHA-256 digital signature for a JWS is validated as 548 follows: 550 1. Take the Encoded JWS Signature and base64url decode it into an 551 octet sequence. If decoding fails, the JWS MUST be rejected. 553 2. The output of the base64url decoding MUST be a 64 octet sequence. 554 If decoding does not result in a 64 octet sequence, the JWS MUST 555 be rejected. 557 3. Split the 64 octet sequence into two 32 octet sequences. The 558 first array will be R and the second S (with both being in big 559 endian octet order). 561 4. Submit the octets of the ASCII representation of the JWS Signing 562 Input R, S and the public key (x, y) to the ECDSA P-256 SHA-256 563 validator. 565 5. If the validation fails, the JWS MUST be rejected. 567 Note that ECDSA digital signature contains a value referred to as K, 568 which is a random number generated for each digital signature 569 instance. This means that two ECDSA digital signatures using exactly 570 the same input parameters will output different signature values 571 because their K values will be different. A consequence of this is 572 that one cannot validate an ECDSA signature by recomputing the 573 signature and comparing the results. 575 Signing with the ECDSA P-384 SHA-384 and ECDSA P-521 SHA-512 576 algorithms is performed identically to the procedure for ECDSA P-256 577 SHA-256 - just using the corresponding hash algorithm with 578 correspondingly larger result values. For ECDSA P-384 SHA-384, R and 579 S will be 384 bits each, resulting in a 96 octet sequence. For ECDSA 580 P-521 SHA-512, R and S will be 521 bits each, resulting in a 132 581 octet sequence. 583 Examples using these algorithms are shown in Appendices A.3 and A.4 584 of [JWS]. 586 3.5. Digital Signature with RSASSA-PSS and SHA-256 or SHA-512 588 This section defines the use of the RSASSA-PSS digital signature 589 algorithm as defined in Section 8.1 of RFC 3447 [RFC3447] with the 590 MGF1 mask generation function, always using the same hash function 591 for both the RSASSA-PSS hash function and the MGF1 hash function. 592 Use of both SHA-256 and SHA-512 as these hash functions is defined. 593 All other algorithm parameters use the defaults specified in Section 594 A.2.3 of RFC 3447. The "alg" (algorithm) header parameter values 595 "PS256" and "PS512" is used in the JWS Header to indicate that the 596 Encoded JWS Signature contains a base64url encoded RSASSA-PSS digital 597 signature using the respective hash function in both roles. 599 A key of size 2048 bits or larger MUST be used with this algorithm. 601 The RSASSA-PSS SHA-256 digital signature is generated as follows: 603 1. Generate a digital signature of the octets of the ASCII 604 representation of the JWS Signing Input using RSASSA-PSS-SIGN, 605 the SHA-256 hash function, and the MGF1 mask generation function 606 with SHA-256 with the desired private key. The output will be an 607 octet sequence. 609 2. Base64url encode the resulting octet sequence. 611 The output is the Encoded JWS Signature for that JWS. 613 The RSASSA-PSS SHA-256 digital signature for a JWS is validated as 614 follows: 616 1. Take the Encoded JWS Signature and base64url decode it into an 617 octet sequence. If decoding fails, the JWS MUST be rejected. 619 2. Submit the octets of the ASCII representation of the JWS Signing 620 Input and the public key corresponding to the private key used by 621 the signer to the RSASSA-PSS-VERIFY algorithm using SHA-256 as 622 the hash function and using MGF1 as the mask generation function 623 with SHA-256. 625 3. If the validation fails, the JWS MUST be rejected. 627 Signing with the RSASSA-PSS SHA-512 algorithm is performed 628 identically to the procedure for RSASSA-PSS SHA-256 - just using the 629 alternative hash algorithm in both roles. 631 3.6. Using the Algorithm "none" 633 JWSs MAY also be created that do not provide integrity protection. 634 Such a JWS is called a "Plaintext JWS". Plaintext JWSs MUST use the 635 "alg" value "none", and are formatted identically to other JWSs, but 636 with the empty string for its JWS Signature value. 638 3.7. Additional Digital Signature/MAC Algorithms and Parameters 640 Additional algorithms MAY be used to protect JWSs with corresponding 641 "alg" (algorithm) header parameter values being defined to refer to 642 them. New "alg" header parameter values SHOULD either be registered 643 in the IANA JSON Web Signature and Encryption Algorithms registry 644 Section 6.1 or be a value that contains a Collision Resistant 645 Namespace. In particular, it is permissible to use the algorithm 646 identifiers defined in XML DSIG [RFC3275], XML DSIG 2.0 647 [W3C.CR-xmldsig-core2-20120124], and related specifications as "alg" 648 values. 650 As indicated by the common registry, JWSs and JWEs share a common 651 "alg" value space. The values used by the two specifications MUST be 652 distinct, as the "alg" value can be used to determine whether the 653 object is a JWS or JWE. 655 Likewise, additional reserved Header Parameter Names can be defined 656 via the IANA JSON Web Signature and Encryption Header Parameters 657 registry [JWS]. As indicated by the common registry, JWSs and JWEs 658 share a common header parameter space; when a parameter is used by 659 both specifications, its usage must be compatible between the 660 specifications. 662 4. Cryptographic Algorithms for JWE 664 JWE uses cryptographic algorithms to encrypt the Content Encryption 665 Key (CEK) and the Plaintext. This section specifies a set of 666 specific algorithms for these purposes. 668 4.1. "alg" (Algorithm) Header Parameter Values for JWE 670 The table below is the set of "alg" (algorithm) header parameter 671 values that are defined by this specification for use with JWE. 672 These algorithms are used to encrypt the CEK, producing the JWE 673 Encrypted Key, or to use key agreement to agree upon the CEK. 675 +----------------+--------------------+------------+----------------+ 676 | alg Parameter | Key Management | Additional | Implementation | 677 | Value | Algorithm | Header | Requirements | 678 | | | Parameters | | 679 +----------------+--------------------+------------+----------------+ 680 | RSA1_5 | RSAES-PKCS1-V1_5 | (none) | REQUIRED | 681 | | [RFC3447] | | | 682 | RSA-OAEP | RSAES using | (none) | OPTIONAL | 683 | | Optimal Asymmetric | | | 684 | | Encryption Padding | | | 685 | | (OAEP) [RFC3447], | | | 686 | | with the default | | | 687 | | parameters | | | 688 | | specified by RFC | | | 689 | | 3447 in Section | | | 690 | | A.2.1 | | | 691 | A128KW | Advanced | (none) | RECOMMENDED | 692 | | Encryption | | | 693 | | Standard (AES) Key | | | 694 | | Wrap Algorithm | | | 695 | | [RFC3394] using | | | 696 | | the default | | | 697 | | initial value | | | 698 | | specified in | | | 699 | | Section 2.2.3.1 | | | 700 | | and using 128 bit | | | 701 | | keys | | | 702 | A256KW | AES Key Wrap | (none) | RECOMMENDED | 703 | | Algorithm using | | | 704 | | the default | | | 705 | | initial value | | | 706 | | specified in | | | 707 | | Section 2.2.3.1 | | | 708 | | and using 256 bit | | | 709 | | keys | | | 710 | dir | Direct use of a | (none) | RECOMMENDED | 711 | | shared symmetric | | | 712 | | key as the Content | | | 713 | | Encryption Key | | | 714 | | (CEK) for the | | | 715 | | content encryption | | | 716 | | step (rather than | | | 717 | | using the | | | 718 | | symmetric key to | | | 719 | | wrap the CEK) | | | 720 | ECDH-ES | Elliptic Curve | "epk", | RECOMMENDED+ | 721 | | Diffie-Hellman | "apu", | | 722 | | Ephemeral Static | "apv" | | 723 | | [RFC6090] key | | | 724 | | agreement using | | | 725 | | the Concat KDF, as | | | 726 | | defined in Section | | | 727 | | 5.8.1 of | | | 728 | | [NIST.800-56A], | | | 729 | | with the | | | 730 | | agreed-upon key | | | 731 | | being used | | | 732 | | directly as the | | | 733 | | Content Encryption | | | 734 | | Key (CEK) (rather | | | 735 | | than being used to | | | 736 | | wrap the CEK), as | | | 737 | | specified in | | | 738 | | Section 4.7 | | | 739 | ECDH-ES+A128KW | Elliptic Curve | "epk", | RECOMMENDED | 740 | | Diffie-Hellman | "apu", | | 741 | | Ephemeral Static | "apv" | | 742 | | key agreement per | | | 743 | | "ECDH-ES" and | | | 744 | | Section 4.7, but | | | 745 | | where the | | | 746 | | agreed-upon key is | | | 747 | | used to wrap the | | | 748 | | Content Encryption | | | 749 | | Key (CEK) with the | | | 750 | | "A128KW" function | | | 751 | | (rather than being | | | 752 | | used directly as | | | 753 | | the CEK) | | | 754 | ECDH-ES+A256KW | Elliptic Curve | "epk", | RECOMMENDED | 755 | | Diffie-Hellman | "apu", | | 756 | | Ephemeral Static | "apv" | | 757 | | key agreement per | | | 758 | | "ECDH-ES" and | | | 759 | | Section 4.7, but | | | 760 | | where the | | | 761 | | agreed-upon key is | | | 762 | | used to wrap the | | | 763 | | Content Encryption | | | 764 | | Key (CEK) with the | | | 765 | | "A256KW" function | | | 766 | | (rather than being | | | 767 | | used directly as | | | 768 | | the CEK) | | | 769 +----------------+--------------------+------------+----------------+ 771 All the names are short because a core goal of JWE is for the 772 representations to be compact. However, there is no a priori length 773 restriction on "alg" values. 775 The Additional Header Parameters column indicates what additional 776 Header Parameters are used by the algorithm, beyond "alg", which all 777 use. All but "dir" and "ECDH-ES" also produce a JWE Encrypted Key 778 value. 780 The use of "+" in the Implementation Requirements indicates that the 781 requirement strength is likely to be increased in a future version of 782 the specification. 784 4.2. "enc" (Encryption Method) Header Parameter Values for JWE 786 The table below is the set of "enc" (encryption method) header 787 parameter values that are defined by this specification for use with 788 JWE. These algorithms are used to encrypt the Plaintext, which 789 produces the Ciphertext. 791 +-------------+------------------------+------------+---------------+ 792 | enc | Content Encryption | Additional | Implementatio | 793 | Parameter | Algorithm | Header | nRequirements | 794 | Value | | Parameters | | 795 +-------------+------------------------+------------+---------------+ 796 | A128CBC-HS2 | The | (none) | REQUIRED | 797 | 56 | AES_128_CBC_HMAC_SHA_2 | | | 798 | | 56 authenticated | | | 799 | | encryption algorithm, | | | 800 | | as defined in | | | 801 | | Section 4.8.3. This | | | 802 | | algorithm uses a 256 | | | 803 | | bit key. | | | 804 | A256CBC-HS5 | The | (none) | REQUIRED | 805 | 12 | AES_256_CBC_HMAC_SHA_5 | | | 806 | | 12 authenticated | | | 807 | | encryption algorithm, | | | 808 | | as defined in | | | 809 | | Section 4.8.4. This | | | 810 | | algorithm uses a 512 | | | 811 | | bit key. | | | 812 | A128GCM | AES in Galois/Counter | (none) | RECOMMENDED | 813 | | Mode (GCM) [AES] | | | 814 | | [NIST.800-38D] using | | | 815 | | 128 bit keys | | | 816 | A256GCM | AES GCM using 256 bit | (none) | RECOMMENDED | 817 | | keys | | | 818 +-------------+------------------------+------------+---------------+ 820 The Additional Header Parameters column indicates what additional 821 Header Parameters are used by the algorithm, beyond "enc", which all 822 use. All also use a JWE Initialization Vector value and and produce 823 JWE Ciphertext and JWE Authentication Tag values. 825 See Appendix B for a table cross-referencing the encryption "alg" 826 (algorithm) and "enc" (encryption method) values used in this 827 specification with the equivalent identifiers used by other standards 828 and software packages. 830 4.3. Key Encryption with RSAES-PKCS1-V1_5 832 This section defines the specifics of encrypting a JWE CEK with 833 RSAES-PKCS1-V1_5 [RFC3447]. The "alg" header parameter value 834 "RSA1_5" is used in this case. 836 A key of size 2048 bits or larger MUST be used with this algorithm. 838 An example using this algorithm is shown in Appendix A.2 of [JWE]. 840 4.4. Key Encryption with RSAES OAEP 842 This section defines the specifics of encrypting a JWE CEK with RSAES 843 using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447], with 844 the default parameters specified by RFC 3447 in Section A.2.1. The 845 "alg" header parameter value "RSA-OAEP" is used in this case. 847 A key of size 2048 bits or larger MUST be used with this algorithm. 849 An example using this algorithm is shown in Appendix A.1 of [JWE]. 851 4.5. Key Wrapping with AES Key Wrap 853 This section defines the specifics of encrypting a JWE CEK with the 854 Advanced Encryption Standard (AES) Key Wrap Algorithm [RFC3394] using 855 the default initial value specified in Section 2.2.3.1 using 128 or 856 256 bit keys. The "alg" header parameter values "A128KW" or "A256KW" 857 are respectively used in this case. 859 An example using this algorithm is shown in Appendix A.3 of [JWE]. 861 4.6. Direct Encryption with a Shared Symmetric Key 863 This section defines the specifics of directly performing symmetric 864 key encryption without performing a key wrapping step. In this case, 865 the shared symmetric key is used directly as the Content Encryption 866 Key (CEK) value for the "enc" algorithm. An empty octet sequence is 867 used as the JWE Encrypted Key value. The "alg" header parameter 868 value "dir" is used in this case. 870 4.7. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static 871 (ECDH-ES) 873 This section defines the specifics of key agreement with Elliptic 874 Curve Diffie-Hellman Ephemeral Static [RFC6090], and using the Concat 875 KDF, as defined in Section 5.8.1 of [NIST.800-56A]. The key 876 agreement result can be used in one of two ways: 878 1. directly as the Content Encryption Key (CEK) for the "enc" 879 algorithm, in the Direct Key Agreement mode, or 881 2. as a symmetric key used to wrap the CEK with either the "A128KW" 882 or "A256KW" algorithms, in the Key Agreement with Key Wrapping 883 mode. 885 The "alg" header parameter value "ECDH-ES" is used in the Direct Key 886 Agreement mode and the values "ECDH-ES+A128KW" and "ECDH-ES+A256KW" 887 are used in the Key Agreement with Key Wrapping mode. 889 In the Direct Key Agreement case, the output of the Concat KDF MUST 890 be a key of the same length as that used by the "enc" algorithm; in 891 this case, the empty octet sequence is used as the JWE Encrypted Key 892 value. In the Key Agreement with Key Wrapping case, the output of 893 the Concat KDF MUST be a key of the length needed for the specified 894 key wrapping algorithm, either 128 or 256 bits respectively. 896 A new ephemeral public key value MUST be generated for each key 897 agreement transaction. 899 4.7.1. Header Parameters Used for ECDH Key Agreement 901 The following Header Parameter Names are reserved and are used for 902 key agreement as defined below. They MAY also be used for other 903 algorithms if so specified by those algorithm parameter definitions. 905 4.7.1.1. "epk" (Ephemeral Public Key) Header Parameter 907 The "epk" (ephemeral public key) value created by the originator for 908 the use in key agreement algorithms. This key is represented as a 909 JSON Web Key [JWK] bare public key value. This Header Parameter is 910 REQUIRED and MUST be understood and processed by implementations when 911 these algorithms are used. 913 4.7.1.2. "apu" (Agreement PartyUInfo) Header Parameter 915 The "apu" (agreement PartyUInfo) value for key agreement algorithms 916 using it (such as "ECDH-ES"), represented as a base64url encoded 917 string. When used, the PartyUInfo value contains information about 918 the sender. Use of this Header Parameter is OPTIONAL. This Header 919 Parameter MUST be understood and processed by implementations when 920 these algorithms are used. 922 4.7.1.3. "apv" (Agreement PartyVInfo) Header Parameter 924 The "apv" (agreement PartyVInfo) value for key agreement algorithms 925 using it (such as "ECDH-ES"), represented as a base64url encoded 926 string. When used, the PartyVInfo value contains information about 927 the receiver. Use of this Header Parameter is OPTIONAL. This Header 928 Parameter MUST be understood and processed by implementations when 929 these algorithms are used. 931 4.7.2. Key Derivation for ECDH Key Agreement 933 The key derivation process derives the agreed upon key from the 934 shared secret Z established through the ECDH algorithm, per Section 935 6.2.2.2 of [NIST.800-56A]. 937 Key derivation is performed using the Concat KDF, as defined in 938 Section 5.8.1 of [NIST.800-56A], where the Digest Method is SHA-256. 939 The Concat KDF parameters are set as follows: 941 Z This is set to the representation of the shared secret Z as an 942 octet sequence. 944 keydatalen This is set to the number of bits in the desired output 945 key. For "ECDH-ES", this is length of the key used by the "enc" 946 algorithm. For "ECDH-ES+A128KW", and "ECDH-ES+A256KW", this is 947 128 and 256, respectively. 949 AlgorithmID In the Direct Key Agreement case, this is set to the 950 octets of the UTF-8 representation of the "enc" header parameter 951 value. In the Key Agreement with Key Wrapping case, this is set 952 to the octets of the UTF-8 representation of the "alg" header 953 parameter value. 955 PartyUInfo The PartyUInfo value is of the form Datalen || Data, 956 where Data is a variable-length string of zero or more octets, and 957 Datalen is a fixed-length, big endian 32 bit counter that 958 indicates the length (in octets) of Data, with || being 959 concatenation. If an "apu" (agreement PartyUInfo) header 960 parameter is present, Data is set to the result of base64url 961 decoding the "apu" value and Datalen is set to the number of 962 octets in Data. Otherwise, Datalen is set to 0 and Data is set to 963 the empty octet sequence. 965 PartyVInfo The PartyVInfo value is of the form Datalen || Data, 966 where Data is a variable-length string of zero or more octets, and 967 Datalen is a fixed-length, big endian 32 bit counter that 968 indicates the length (in octets) of Data, with || being 969 concatenation. If an "apv" (agreement PartyVInfo) header 970 parameter is present, Data is set to the result of base64url 971 decoding the "apv" value and Datalen is set to the number of 972 octets in Data. Otherwise, Datalen is set to 0 and Data is set to 973 the empty octet sequence. 975 SuppPubInfo This is set to the keydatalen represented as a 32 bit 976 big endian integer. 978 SuppPrivInfo This is set to the empty octet sequence. 980 Note: The Diffie-Hellman Key Agreement Method [RFC2631] uses a key 981 derivation function similar to the Concat KDF, but with fewer 982 parameters. Rather than having separate PartyUInfo and PartyVInfo 983 parameters, it uses a single PartyAInfo parameter, which is a random 984 string provided by the sender, that contains 512 bits of information, 985 when provided. It has no suppPrivInfo parameter. Should it be 986 appropriate for the application, key agreement can be performed in a 987 manner akin to RFC 2631 by using the PartyAInfo value as the "apu" 988 (Agreement PartyUInfo) header parameter value, when provided, and by 989 using no "apv" (Agreement PartyVInfo) header parameter. 991 4.8. AES_CBC_HMAC_SHA2 Algorithms 993 This section defines a family of authenticated encryption algorithms 994 built using a composition of Advanced Encryption Standard (AES) in 995 Cipher Block Chaining (CBC) mode with PKCS #5 padding [AES] 996 [NIST.800-38A] operations and HMAC [RFC2104] [SHS] operations. This 997 algorithm family is called AES_CBC_HMAC_SHA2. It also defines two 998 instances of this family, one using 128 bit CBC keys and HMAC SHA-256 999 and the other using 256 bit CBC keys and HMAC SHA-512. Test cases 1000 for these algorithms can be found in Appendix C. 1002 These algorithms are based upon Authenticated Encryption with AES-CBC 1003 and HMAC-SHA [I-D.mcgrew-aead-aes-cbc-hmac-sha2], performing the same 1004 cryptographic computations, but with the Initialization Vector and 1005 Authentication Tag values remaining separate, rather than being 1006 concatenated with the Ciphertext value in the output representation. 1007 This algorithm family is a generalization of the algorithm family in 1008 [I-D.mcgrew-aead-aes-cbc-hmac-sha2], and can be used to implement 1009 those algorithms. 1011 4.8.1. Conventions Used in Defining AES_CBC_HMAC_SHA2 1013 We use the following notational conventions. 1015 CBC-PKCS5-ENC(X, P) denotes the AES CBC encryption of P using PKCS 1016 #5 padding using the cipher with the key X. 1018 MAC(Y, M) denotes the application of the Message Authentication 1019 Code (MAC) to the message M, using the key Y. 1021 The concatenation of two octet strings A and B is denoted as 1022 A || B. 1024 4.8.2. Generic AES_CBC_HMAC_SHA2 Algorithm 1026 This section defines AES_CBC_HMAC_SHA2 in a manner that is 1027 independent of the AES CBC key size or hash function to be used. 1028 Section 4.8.2.1 and Section 4.8.2.2 define the generic encryption and 1029 decryption algorithms. Section 4.8.3 and Section 4.8.4 define 1030 instances of AES_CBC_HMAC_SHA2 that specify those details. 1032 4.8.2.1. AES_CBC_HMAC_SHA2 Encryption 1034 The authenticated encryption algorithm takes as input four octet 1035 strings: a secret key K, a plaintext P, associated data A, and an 1036 initialization vector IV. The authenticated ciphertext value E and 1037 the authentication tag value T are provided as outputs. The data in 1038 the plaintext are encrypted and authenticated, and the associated 1039 data are authenticated, but not encrypted. 1041 The encryption process is as follows, or uses an equivalent set of 1042 steps: 1044 1. The secondary keys MAC_KEY and ENC_KEY are generated from the 1045 input key K as follows. Each of these two keys is an octet 1046 string. 1048 MAC_KEY consists of the initial MAC_KEY_LEN octets of K, in 1049 order. 1051 ENC_KEY consists of the final ENC_KEY_LEN octets of K, in 1052 order. 1054 Here we denote the number of octets in the MAC_KEY as 1055 MAC_KEY_LEN, and the number of octets in ENC_KEY as ENC_KEY_LEN; 1056 the values of these parameters are specified by the AEAD 1057 algorithms (in Section 4.8.3 and Section 4.8.4). The number of 1058 octets in the input key K is the sum of MAC_KEY_LEN and 1059 ENC_KEY_LEN. When generating the secondary keys from K, MAC_KEY 1060 and ENC_KEY MUST NOT overlap. Note that the MAC key comes before 1061 the encryption key in the input key K; this is in the opposite 1062 order of the algorithm names in the identifier 1063 "AES_CBC_HMAC_SHA2". 1065 2. The Initialization Vector (IV) used is a 128 bit value generated 1066 randomly or pseudorandomly for use in the cipher. 1068 3. The plaintext is CBC encrypted using PKCS #5 padding using 1069 ENC_KEY as the key, and the IV. We denote the ciphertext output 1070 from this step as E. 1072 4. The octet string AL is equal to the number of bits in A expressed 1073 as a 64-bit unsigned integer in network byte order. 1075 5. A message authentication tag T is computed by applying HMAC 1076 [RFC2104] to the following data, in order: 1078 the associated data A, 1080 the initialization vector IV, 1082 the ciphertext E computed in the previous step, and 1084 the octet string AL defined above. 1086 The string MAC_KEY is used as the MAC key. We denote the output 1087 of the MAC computed in this step as M. The first T_LEN bits of M 1088 are used as T. 1090 6. The Ciphertext E and the Authentication Tag T are returned as the 1091 outputs of the authenticated encryption. 1093 The encryption process can be illustrated as follows. Here K, P, A, 1094 IV, and E denote the key, plaintext, associated data, initialization 1095 vector, and ciphertext, respectively. 1097 MAC_KEY = initial MAC_KEY_LEN bytes of K, 1099 ENC_KEY = final ENC_KEY_LEN bytes of K, 1101 E = CBC-PKCS5-ENC(ENC_KEY, P), 1103 M = MAC(MAC_KEY, A || IV || E || AL), 1105 T = initial T_LEN bytes of M. 1107 4.8.2.2. AES_CBC_HMAC_SHA2 Decryption 1109 The authenticated decryption operation has four inputs: K, A, E, and 1110 T as defined above. It has only a single output, either a plaintext 1111 value P or a special symbol FAIL that indicates that the inputs are 1112 not authentic. The authenticated decryption algorithm is as follows, 1113 or uses an equivalent set of steps: 1115 1. The secondary keys MAC_KEY and ENC_KEY are generated from the 1116 input key K as in Step 1 of Section 4.8.2.1. 1118 2. The integrity and authenticity of A and E are checked by 1119 computing an HMAC with the inputs as in Step 5 of 1120 Section 4.8.2.1. The value T, from the previous step, is 1121 compared to the first MAC_KEY length bits of the HMAC output. If 1122 those values are identical, then A and E are considered valid, 1123 and processing is continued. Otherwise, all of the data used in 1124 the MAC validation are discarded, and the AEAD decryption 1125 operation returns an indication that it failed, and the operation 1126 halts. (But see Section 10 of [JWE] for security considerations 1127 on thwarting timing attacks.) 1129 3. The value E is decrypted and the PKCS #5 padding is removed. The 1130 value IV is used as the initialization vector. The value ENC_KEY 1131 is used as the decryption key. 1133 4. The plaintext value is returned. 1135 4.8.3. AES_128_CBC_HMAC_SHA_256 1137 This algorithm is a concrete instantiation of the generic 1138 AES_CBC_HMAC_SHA2 algorithm above. It uses the HMAC message 1139 authentication code [RFC2104] with the SHA-256 hash function [SHS] to 1140 provide message authentication, with the HMAC output truncated to 128 1141 bits, corresponding to the HMAC-SHA-256-128 algorithm defined in 1142 [RFC4868]. For encryption, it uses AES in the Cipher Block Chaining 1143 (CBC) mode of operation as defined in Section 6.2 of [NIST.800-38A], 1144 with PKCS #5 padding. 1146 The input key K is 32 octets long. 1148 The AES CBC IV is 16 octets long. ENC_KEY_LEN is 16 octets. 1150 The SHA-256 hash algorithm is used in HMAC. MAC_KEY_LEN is 16 1151 octets. The HMAC-SHA-256 output is truncated to T_LEN=16 octets, by 1152 stripping off the final 16 octets. 1154 4.8.4. AES_256_CBC_HMAC_SHA_512 1156 AES_256_CBC_HMAC_SHA_512 is based on AES_128_CBC_HMAC_SHA_256, but 1157 with the following differences: 1159 A 256 bit AES CBC key is used instead of 128. 1161 SHA-512 is used in HMAC instead of SHA-256. 1163 ENC_KEY_LEN is 32 octets. 1165 MAC_KEY_LEN is 32 octets. 1167 The length of the input key K is 64 octets. 1169 The HMAC SHA-512 value is truncated to T_LEN=32 octets instead of 1170 16 octets. 1172 4.8.5. Plaintext Encryption with AES_CBC_HMAC_SHA2 1174 The algorithm value "A128CBC-HS256" is used as the "alg" value when 1175 using AES_128_CBC_HMAC_SHA_256 with JWE. The algorithm value 1176 "A256CBC-HS512" is used as the "alg" value when using 1177 AES_256_CBC_HMAC_SHA_512 with JWE. The Additional Authenticated Data 1178 value used is the octets of the ASCII representation of the Encoded 1179 JWE Header value. The JWE Initialization Vector value used is the IV 1180 value. 1182 4.9. Plaintext Encryption with AES GCM 1184 This section defines the specifics of encrypting the JWE Plaintext 1185 with Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) 1186 [AES] [NIST.800-38D] using 128 or 256 bit keys. The "enc" header 1187 parameter values "A128GCM" or "A256GCM" are respectively used in this 1188 case. 1190 The CEK is used as the encryption key. 1192 Use of an initialization vector of size 96 bits is REQUIRED with this 1193 algorithm. 1195 The Additional Authenticated Data value used is the octets of the 1196 ASCII representation of the Encoded JWE Header value. 1198 The requested size of the Authentication Tag output MUST be 128 bits, 1199 regardless of the key size. 1201 The JWE Authentication Tag is set to be the Authentication Tag value 1202 produced by the encryption. During decryption, the received JWE 1203 Authentication Tag is used as the Authentication Tag value. 1205 An example using this algorithm is shown in Appendix A.1 of [JWE]. 1207 4.10. Additional Encryption Algorithms and Parameters 1209 Additional algorithms MAY be used to protect JWEs with corresponding 1210 "alg" (algorithm) and "enc" (encryption method) header parameter 1211 values being defined to refer to them. New "alg" and "enc" header 1212 parameter values SHOULD either be registered in the IANA JSON Web 1213 Signature and Encryption Algorithms registry Section 6.1 or be a 1214 value that contains a Collision Resistant Namespace. In particular, 1215 it is permissible to use the algorithm identifiers defined in XML 1216 Encryption [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 1217 [W3C.CR-xmlenc-core1-20120313], and related specifications as "alg" 1218 and "enc" values. 1220 As indicated by the common registry, JWSs and JWEs share a common 1221 "alg" value space. The values used by the two specifications MUST be 1222 distinct, as the "alg" value can be used to determine whether the 1223 object is a JWS or JWE. 1225 Likewise, additional reserved Header Parameter Names can be defined 1226 via the IANA JSON Web Signature and Encryption Header Parameters 1227 registry [JWS]. As indicated by the common registry, JWSs and JWEs 1228 share a common header parameter space; when a parameter is used by 1229 both specifications, its usage must be compatible between the 1230 specifications. 1232 5. Cryptographic Algorithms for JWK 1234 A JSON Web Key (JWK) [JWK] is a JavaScript Object Notation (JSON) 1235 [RFC4627] data structure that represents a cryptographic key. A JSON 1236 Web Key Set (JWK Set) is a JSON data structure for representing a set 1237 of JWKs. This section specifies a set of key types to be used for 1238 those keys and the key type specific parameters for representing 1239 those keys. Parameters are defined for public, private, and 1240 symmetric keys. 1242 5.1. "kty" (Key Type) Parameter Values for JWK 1244 The table below is the set of "kty" (key type) parameter values that 1245 are defined by this specification for use in JWKs. 1247 +-------------+----------------------------------+------------------+ 1248 | kty | Key Type | Implementation | 1249 | Parameter | | Requirements | 1250 | Value | | | 1251 +-------------+----------------------------------+------------------+ 1252 | EC | Elliptic Curve [DSS] key type | RECOMMENDED+ | 1253 | RSA | RSA [RFC3447] key type | REQUIRED | 1254 | oct | Octet sequence key type (used to | RECOMMENDED+ | 1255 | | represent symmetric keys) | | 1256 +-------------+----------------------------------+------------------+ 1258 All the names are short because a core goal of JWK is for the 1259 representations to be compact. However, there is no a priori length 1260 restriction on "kty" values. 1262 The use of "+" in the Implementation Requirements indicates that the 1263 requirement strength is likely to be increased in a future version of 1264 the specification. 1266 5.2. JWK Parameters for Elliptic Curve Keys 1268 JWKs can represent Elliptic Curve [DSS] keys. In this case, the 1269 "kty" member value MUST be "EC". 1271 5.2.1. JWK Parameters for Elliptic Curve Public Keys 1273 These members MUST be present for Elliptic Curve public keys: 1275 5.2.1.1. "crv" (Curve) Parameter 1277 The "crv" (curve) member identifies the cryptographic curve used with 1278 the key. Curve values from [DSS] used by this specification are: 1280 o "P-256" 1282 o "P-384" 1284 o "P-521" 1286 Additional "crv" values MAY be used, provided they are understood by 1287 implementations using that Elliptic Curve key. The "crv" value is a 1288 case sensitive string. 1290 5.2.1.2. "x" (X Coordinate) Parameter 1292 The "x" (x coordinate) member contains the x coordinate for the 1293 elliptic curve point. It is represented as the base64url encoding of 1294 the coordinate's big endian representation as an octet sequence. The 1295 array representation MUST NOT be shortened to omit any leading zero 1296 octets contained in the value. For instance, when representing 521 1297 bit integers, the octet sequence to be base64url encoded MUST contain 1298 66 octets, including any leading zero octets. 1300 5.2.1.3. "y" (Y Coordinate) Parameter 1302 The "y" (y coordinate) member contains the y coordinate for the 1303 elliptic curve point. It is represented as the base64url encoding of 1304 the coordinate's big endian representation as an octet sequence. The 1305 array representation MUST NOT be shortened to omit any leading zero 1306 octets contained in the value. For instance, when representing 521 1307 bit integers, the octet sequence to be base64url encoded MUST contain 1308 66 octets, including any leading zero octets. 1310 5.2.2. JWK Parameters for Elliptic Curve Private Keys 1312 In addition to the members used to represent Elliptic Curve public 1313 keys, the following member MUST be present to represent Elliptic 1314 Curve private keys: 1316 5.2.2.1. "d" (ECC Private Key) Parameter 1318 The "d" (ECC private key) member contains the Elliptic Curve private 1319 key value. It is represented as the base64url encoding of the 1320 value's unsigned big endian representation as an octet sequence. The 1321 array representation MUST NOT be shortened to omit any leading zero 1322 octets. For instance, when representing 521 bit integers, the octet 1323 sequence to be base64url encoded MUST contain 66 octets, including 1324 any leading zero octets. 1326 5.3. JWK Parameters for RSA Keys 1328 JWKs can represent RSA [RFC3447] keys. In this case, the "kty" 1329 member value MUST be "RSA". 1331 5.3.1. JWK Parameters for RSA Public Keys 1333 These members MUST be present for RSA public keys: 1335 5.3.1.1. "n" (Modulus) Parameter 1337 The "n" (modulus) member contains the modulus value for the RSA 1338 public key. It is represented as the base64url encoding of the 1339 value's unsigned big endian representation as an octet sequence. The 1340 array representation MUST NOT be shortened to omit any leading zero 1341 octets. For instance, when representing 2048 bit integers, the octet 1342 sequence to be base64url encoded MUST contain 256 octets, including 1343 any leading zero octets. 1345 5.3.1.2. "e" (Exponent) Parameter 1347 The "e" (exponent) member contains the exponent value for the RSA 1348 public key. It is represented as the base64url encoding of the 1349 value's unsigned big endian representation as an octet sequence. The 1350 array representation MUST utilize the minimum number of octets to 1351 represent the value. For instance, when representing the value 1352 65537, the octet sequence to be base64url encoded MUST consist of the 1353 three octets [1, 0, 1]. 1355 5.3.2. JWK Parameters for RSA Private Keys 1357 In addition to the members used to represent RSA public keys, the 1358 following members are used to represent RSA private keys. All are 1359 REQUIRED for RSA private keys except for "oth", which is sometimes 1360 REQUIRED and sometimes MUST NOT be present, as described below. 1362 5.3.2.1. "d" (Private Exponent) Parameter 1364 The "d" (private exponent) member contains the private exponent value 1365 for the RSA private key. It is represented as the base64url encoding 1366 of the value's unsigned big endian representation as an octet 1367 sequence. The array representation MUST NOT be shortened to omit any 1368 leading zero octets. For instance, when representing 2048 bit 1369 integers, the octet sequence to be base64url encoded MUST contain 256 1370 octets, including any leading zero octets. 1372 5.3.2.2. "p" (First Prime Factor) Parameter 1374 The "p" (first prime factor) member contains the first prime factor, 1375 a positive integer. It is represented as the base64url encoding of 1376 the value's unsigned big endian representation as an octet sequence. 1378 5.3.2.3. "q" (Second Prime Factor) Parameter 1380 The "q" (second prime factor) member contains the second prime 1381 factor, a positive integer. It is represented as the base64url 1382 encoding of the value's unsigned big endian representation as an 1383 octet sequence. 1385 5.3.2.4. "dp" (First Factor CRT Exponent) Parameter 1387 The "dp" (first factor CRT exponent) member contains the Chinese 1388 Remainder Theorem (CRT) exponent of the first factor, a positive 1389 integer. It is represented as the base64url encoding of the value's 1390 unsigned big endian representation as an octet sequence. 1392 5.3.2.5. "dq" (Second Factor CRT Exponent) Parameter 1394 The "dq" (second factor CRT exponent) member contains the Chinese 1395 Remainder Theorem (CRT) exponent of the second factor, a positive 1396 integer. It is represented as the base64url encoding of the value's 1397 unsigned big endian representation as an octet sequence. 1399 5.3.2.6. "qi" (First CRT Coefficient) Parameter 1401 The "dp" (first CRT coefficient) member contains the Chinese 1402 Remainder Theorem (CRT) coefficient of the second factor, a positive 1403 integer. It is represented as the base64url encoding of the value's 1404 unsigned big endian representation as an octet sequence. 1406 5.3.2.7. "oth" (Other Primes Info) Parameter 1408 The "oth" (other primes info) member contains an array of information 1409 about any third and subsequent primes, should they exist. When only 1410 two primes have been used (the normal case), this parameter MUST be 1411 omitted. When three or more primes have been used, the number of 1412 array elements MUST be the number of primes used minus two. Each 1413 array element MUST be an object with the following members: 1415 5.3.2.7.1. "r" (Prime Factor) 1417 The "r" (prime factor) parameter within an "oth" array member 1418 represents the value of a subsequent prime factor, a positive 1419 integer. It is represented as the base64url encoding of the value's 1420 unsigned big endian representation as an octet sequence. 1422 5.3.2.7.2. "d" (Factor CRT Exponent) 1424 The "d" (Factor CRT Exponent) parameter within an "oth" array member 1425 represents the CRT exponent of the corresponding prime factor, a 1426 positive integer. It is represented as the base64url encoding of the 1427 value's unsigned big endian representation as an octet sequence. 1429 5.3.2.7.3. "t" (Factor CRT Coefficient) 1431 The "t" (factor CRT coefficient) parameter within an "oth" array 1432 member represents the CRT coefficient of the corresponding prime 1433 factor, a positive integer. It is represented as the base64url 1434 encoding of the value's unsigned big endian representation as an 1435 octet sequence. 1437 5.3.3. JWK Parameters for Symmetric Keys 1439 When the JWK "kty" member value is "oct" (octet sequence), the 1440 following member is used to represent a symmetric key (or another key 1441 whose value is a single octet sequence): 1443 5.3.3.1. "k" (Key Value) Parameter 1445 The "k" (key value) member contains the value of the symmetric (or 1446 other single-valued) key. It is represented as the base64url 1447 encoding of the octet sequence containing the key value. 1449 5.4. Additional Key Types and Parameters 1451 Keys using additional key types can be represented using JWK data 1452 structures with corresponding "kty" (key type) parameter values being 1453 defined to refer to them. New "kty" parameter values SHOULD either 1454 be registered in the IANA JSON Web Key Types registry Section 6.2 or 1455 be a value that contains a Collision Resistant Namespace. 1457 Likewise, parameters for representing keys for additional key types 1458 or additional key properties SHOULD either be registered in the IANA 1459 JSON Web Key Parameters registry [JWK] or be a value that contains a 1460 Collision Resistant Namespace. 1462 6. IANA Considerations 1464 The following registration procedure is used for all the registries 1465 established by this specification. 1467 Values are registered with a Specification Required [RFC5226] after a 1468 two-week review period on the [TBD]@ietf.org mailing list, on the 1469 advice of one or more Designated Experts. However, to allow for the 1470 allocation of values prior to publication, the Designated Expert(s) 1471 may approve registration once they are satisfied that such a 1472 specification will be published. 1474 Registration requests must be sent to the [TBD]@ietf.org mailing list 1475 for review and comment, with an appropriate subject (e.g., "Request 1476 for access token type: example"). [[ Note to RFC-EDITOR: The name of 1477 the mailing list should be determined in consultation with the IESG 1478 and IANA. Suggested name: jose-reg-review. ]] 1480 Within the review period, the Designated Expert(s) will either 1481 approve or deny the registration request, communicating this decision 1482 to the review list and IANA. Denials should include an explanation 1483 and, if applicable, suggestions as to how to make the request 1484 successful. 1486 IANA must only accept registry updates from the Designated Expert(s) 1487 and should direct all requests for registration to the review mailing 1488 list. 1490 6.1. JSON Web Signature and Encryption Algorithms Registry 1492 This specification establishes the IANA JSON Web Signature and 1493 Encryption Algorithms registry for values of the JWS and JWE "alg" 1494 (algorithm) and "enc" (encryption method) header parameters. The 1495 registry records the algorithm name, the algorithm usage locations 1496 from the set "alg" and "enc", implementation requirements, and a 1497 reference to the specification that defines it. The same algorithm 1498 name MAY be registered multiple times, provided that the sets of 1499 usage locations are disjoint. The implementation requirements of an 1500 algorithm MAY be changed over time by the Designated Experts(s) as 1501 the cryptographic landscape evolves, for instance, to change the 1502 status of an algorithm to DEPRECATED, or to change the status of an 1503 algorithm from OPTIONAL to RECOMMENDED or REQUIRED. 1505 6.1.1. Template 1507 Algorithm Name: 1508 The name requested (e.g., "example"). This name is case 1509 sensitive. Names that match other registered names in a case 1510 insensitive manner SHOULD NOT be accepted. 1512 Algorithm Usage Location(s): 1513 The algorithm usage, which must be one or more of the values "alg" 1514 or "enc". 1516 Implementation Requirements: 1517 The algorithm implementation requirements, which must be one the 1518 words REQUIRED, RECOMMENDED, OPTIONAL, or DEPRECATED. Optionally, 1519 the word can be followed by a "+" or "-". The use of "+" 1520 indicates that the requirement strength is likely to be increased 1521 in a future version of the specification. The use of "-" 1522 indicates that the requirement strength is likely to be decreased 1523 in a future version of the specification. 1525 Change Controller: 1526 For Standards Track RFCs, state "IETF". For others, give the name 1527 of the responsible party. Other details (e.g., postal address, 1528 email address, home page URI) may also be included. 1530 Specification Document(s): 1531 Reference to the document(s) that specify the parameter, 1532 preferably including URI(s) that can be used to retrieve copies of 1533 the document(s). An indication of the relevant sections may also 1534 be included but is not required. 1536 6.1.2. Initial Registry Contents 1538 o Algorithm Name: "HS256" 1539 o Algorithm Usage Location(s): "alg" 1540 o Implementation Requirements: REQUIRED 1541 o Change Controller: IETF 1542 o Specification Document(s): Section 3.1 of [[ this document ]] 1544 o Algorithm Name: "HS384" 1545 o Algorithm Usage Location(s): "alg" 1546 o Implementation Requirements: OPTIONAL 1547 o Change Controller: IETF 1548 o Specification Document(s): Section 3.1 of [[ this document ]] 1550 o Algorithm Name: "HS512" 1551 o Algorithm Usage Location(s): "alg" 1552 o Implementation Requirements: OPTIONAL 1553 o Change Controller: IETF 1554 o Specification Document(s): Section 3.1 of [[ this document ]] 1556 o Algorithm Name: "RS256" 1557 o Algorithm Usage Location(s): "alg" 1558 o Implementation Requirements: RECOMMENDED 1559 o Change Controller: IETF 1560 o Specification Document(s): Section 3.1 of [[ this document ]] 1562 o Algorithm Name: "RS384" 1563 o Algorithm Usage Location(s): "alg" 1564 o Implementation Requirements: OPTIONAL 1565 o Change Controller: IETF 1566 o Specification Document(s): Section 3.1 of [[ this document ]] 1568 o Algorithm Name: "RS512" 1569 o Algorithm Usage Location(s): "alg" 1570 o Implementation Requirements: OPTIONAL 1571 o Change Controller: IETF 1572 o Specification Document(s): Section 3.1 of [[ this document ]] 1574 o Algorithm Name: "ES256" 1575 o Algorithm Usage Location(s): "alg" 1576 o Implementation Requirements: RECOMMENDED+ 1577 o Change Controller: IETF 1578 o Specification Document(s): Section 3.1 of [[ this document ]] 1580 o Algorithm Name: "ES384" 1581 o Algorithm Usage Location(s): "alg" 1582 o Implementation Requirements: OPTIONAL 1583 o Change Controller: IETF 1584 o Specification Document(s): Section 3.1 of [[ this document ]] 1586 o Algorithm Name: "ES512" 1587 o Algorithm Usage Location(s): "alg" 1588 o Implementation Requirements: OPTIONAL 1589 o Change Controller: IETF 1590 o Specification Document(s): Section 3.1 of [[ this document ]] 1592 o Algorithm Name: "PS256" 1593 o Algorithm Usage Location(s): "alg" 1594 o Implementation Requirements: RECOMMENDED 1595 o Change Controller: IETF 1596 o Specification Document(s): Section 3.1 of [[ this document ]] 1598 o Algorithm Name: "PS512" 1599 o Algorithm Usage Location(s): "alg" 1600 o Implementation Requirements: RECOMMENDED 1601 o Change Controller: IETF 1602 o Specification Document(s): Section 3.1 of [[ this document ]] 1604 o Algorithm Name: "none" 1605 o Algorithm Usage Location(s): "alg" 1606 o Implementation Requirements: REQUIRED 1607 o Change Controller: IETF 1608 o Specification Document(s): Section 3.1 of [[ this document ]] 1610 o Algorithm Name: "RSA1_5" 1611 o Algorithm Usage Location(s): "alg" 1612 o Implementation Requirements: REQUIRED 1613 o Change Controller: IETF 1614 o Specification Document(s): Section 4.1 of [[ this document ]] 1616 o Algorithm Name: "RSA-OAEP" 1617 o Algorithm Usage Location(s): "alg" 1618 o Implementation Requirements: OPTIONAL 1619 o Change Controller: IETF 1620 o Specification Document(s): Section 4.1 of [[ this document ]] 1622 o Algorithm Name: "A128KW" 1623 o Algorithm Usage Location(s): "alg" 1624 o Implementation Requirements: RECOMMENDED 1625 o Change Controller: IETF 1626 o Specification Document(s): Section 4.1 of [[ this document ]] 1628 o Algorithm Name: "A256KW" 1629 o Algorithm Usage Location(s): "alg" 1630 o Implementation Requirements: RECOMMENDED 1631 o Change Controller: IETF 1632 o Specification Document(s): Section 4.1 of [[ this document ]] 1633 o Algorithm Name: "dir" 1634 o Algorithm Usage Location(s): "alg" 1635 o Implementation Requirements: RECOMMENDED 1636 o Change Controller: IETF 1637 o Specification Document(s): Section 4.1 of [[ this document ]] 1639 o Algorithm Name: "ECDH-ES" 1640 o Algorithm Usage Location(s): "alg" 1641 o Implementation Requirements: RECOMMENDED+ 1642 o Change Controller: IETF 1643 o Specification Document(s): Section 4.1 of [[ this document ]] 1645 o Algorithm Name: "ECDH-ES+A128KW" 1646 o Algorithm Usage Location(s): "alg" 1647 o Implementation Requirements: RECOMMENDED 1648 o Change Controller: IETF 1649 o Specification Document(s): Section 4.1 of [[ this document ]] 1651 o Algorithm Name: "ECDH-ES+A256KW" 1652 o Algorithm Usage Location(s): "alg" 1653 o Implementation Requirements: RECOMMENDED 1654 o Change Controller: IETF 1655 o Specification Document(s): Section 4.1 of [[ this document ]] 1657 o Algorithm Name: "A128CBC-HS256" 1658 o Algorithm Usage Location(s): "enc" 1659 o Implementation Requirements: REQUIRED 1660 o Change Controller: IETF 1661 o Specification Document(s): Section 4.2 of [[ this document ]] 1663 o Algorithm Name: "A256CBC-HS512" 1664 o Algorithm Usage Location(s): "enc" 1665 o Implementation Requirements: REQUIRED 1666 o Change Controller: IETF 1667 o Specification Document(s): Section 4.2 of [[ this document ]] 1669 o Algorithm Name: "A128GCM" 1670 o Algorithm Usage Location(s): "enc" 1671 o Implementation Requirements: RECOMMENDED 1672 o Change Controller: IETF 1673 o Specification Document(s): Section 4.2 of [[ this document ]] 1675 o Algorithm Name: "A256GCM" 1676 o Algorithm Usage Location(s): "enc" 1677 o Implementation Requirements: RECOMMENDED 1678 o Change Controller: IETF 1679 o Specification Document(s): Section 4.2 of [[ this document ]] 1681 6.2. JSON Web Key Types Registry 1683 This specification establishes the IANA JSON Web Key Types registry 1684 for values of the JWK "kty" (key type) parameter. The registry 1685 records the "kty" value and a reference to the specification that 1686 defines it. This specification registers the values defined in 1687 Section 5.1. 1689 6.2.1. Registration Template 1691 "kty" Parameter Value: 1692 The name requested (e.g., "example"). This name is case 1693 sensitive. Names that match other registered names in a case 1694 insensitive manner SHOULD NOT be accepted. 1696 Change Controller: 1697 For Standards Track RFCs, state "IETF". For others, give the name 1698 of the responsible party. Other details (e.g., postal address, 1699 email address, home page URI) may also be included. 1701 Implementation Requirements: 1702 The algorithm implementation requirements, which must be one the 1703 words REQUIRED, RECOMMENDED, OPTIONAL, or DEPRECATED. Optionally, 1704 the word can be followed by a "+" or "-". The use of "+" 1705 indicates that the requirement strength is likely to be increased 1706 in a future version of the specification. The use of "-" 1707 indicates that the requirement strength is likely to be decreased 1708 in a future version of the specification. 1710 Specification Document(s): 1711 Reference to the document(s) that specify the parameter, 1712 preferably including URI(s) that can be used to retrieve copies of 1713 the document(s). An indication of the relevant sections may also 1714 be included but is not required. 1716 6.2.2. Initial Registry Contents 1718 o "kty" Parameter Value: "EC" 1719 o Implementation Requirements: RECOMMENDED+ 1720 o Change Controller: IETF 1721 o Specification Document(s): Section 5.1 of [[ this document ]] 1723 o "kty" Parameter Value: "RSA" 1724 o Implementation Requirements: REQUIRED 1725 o Change Controller: IETF 1726 o Specification Document(s): Section 5.1 of [[ this document ]] 1728 o "kty" Parameter Value: "oct" 1729 o Implementation Requirements: RECOMMENDED+ 1730 o Change Controller: IETF 1731 o Specification Document(s): Section 5.1 of [[ this document ]] 1733 6.3. JSON Web Key Parameters Registration 1735 This specification registers the parameter names defined in Sections 1736 5.2, 5.3, and 5.3.3 in the IANA JSON Web Key Parameters registry 1737 [JWK]. 1739 6.3.1. Registry Contents 1741 o Parameter Name: "crv" 1742 o Parameter Information Class: Public 1743 o Change Controller: IETF 1744 o Specification Document(s): Section 5.2.1.1 of [[ this document ]] 1746 o Parameter Name: "x" 1747 o Parameter Information Class: Public 1748 o Change Controller: IETF 1749 o Specification Document(s): Section 5.2.1.2 of [[ this document ]] 1751 o Parameter Name: "y" 1752 o Parameter Information Class: Public 1753 o Change Controller: IETF 1754 o Specification Document(s): Section 5.2.1.3 of [[ this document ]] 1756 o Parameter Name: "d" 1757 o Parameter Information Class: Private 1758 o Change Controller: IETF 1759 o Specification Document(s): Section 5.2.2.1 of [[ this document ]] 1761 o Parameter Name: "n" 1762 o Parameter Information Class: Public 1763 o Change Controller: IETF 1764 o Specification Document(s): Section 5.3.1.1 of [[ this document ]] 1766 o Parameter Name: "e" 1767 o Parameter Information Class: Public 1768 o Change Controller: IETF 1769 o Specification Document(s): Section 5.3.1.2 of [[ this document ]] 1770 o Parameter Name: "d" 1771 o Parameter Information Class: Private 1772 o Change Controller: IETF 1773 o Specification Document(s): Section 5.3.2.1 of [[ this document ]] 1775 o Parameter Name: "p" 1776 o Parameter Information Class: Private 1777 o Change Controller: IETF 1778 o Specification Document(s): Section 5.3.2.2 of [[ this document ]] 1780 o Parameter Name: "q" 1781 o Parameter Information Class: Private 1782 o Change Controller: IETF 1783 o Specification Document(s): Section 5.3.2.3 of [[ this document ]] 1785 o Parameter Name: "dp" 1786 o Parameter Information Class: Private 1787 o Change Controller: IETF 1788 o Specification Document(s): Section 5.3.2.4 of [[ this document ]] 1790 o Parameter Name: "dq" 1791 o Parameter Information Class: Private 1792 o Change Controller: IETF 1793 o Specification Document(s): Section 5.3.2.5 of [[ this document ]] 1795 o Parameter Name: "qi" 1796 o Parameter Information Class: Private 1797 o Change Controller: IETF 1798 o Specification Document(s): Section 5.3.2.6 of [[ this document ]] 1800 o Parameter Name: "oth" 1801 o Parameter Information Class: Private 1802 o Change Controller: IETF 1803 o Specification Document(s): Section 5.3.2.7 of [[ this document ]] 1805 o Parameter Name: "k" 1806 o Parameter Information Class: Private 1807 o Change Controller: IETF 1808 o Specification Document(s): Section 5.3.3.1 of [[ this document ]] 1810 6.4. Registration of JWE Header Parameter Names 1812 This specification registers the Header Parameter Names defined in 1813 Section 4.7.1 in the IANA JSON Web Signature and Encryption Header 1814 Parameters registry [JWS]. 1816 6.4.1. Registry Contents 1818 o Header Parameter Name: "epk" 1819 o Header Parameter Usage Location(s): JWE 1820 o Change Controller: IETF 1821 o Specification Document(s): Section 4.7.1.1 of [[ this document ]] 1823 o Header Parameter Name: "apu" 1824 o Header Parameter Usage Location(s): JWE 1825 o Change Controller: IETF 1826 o Specification Document(s): Section 4.7.1.2 of [[ this document ]] 1828 o Header Parameter Name: "apv" 1829 o Header Parameter Usage Location(s): JWE 1830 o Change Controller: IETF 1831 o Specification Document(s): Section 4.7.1.3 of [[ this document ]] 1833 7. Security Considerations 1835 All of the security issues faced by any cryptographic application 1836 must be faced by a JWS/JWE/JWK agent. Among these issues are 1837 protecting the user's private and symmetric keys, preventing various 1838 attacks, and helping the user avoid mistakes such as inadvertently 1839 encrypting a message for the wrong recipient. The entire list of 1840 security considerations is beyond the scope of this document, but 1841 some significant considerations are listed here. 1843 The security considerations in [AES], [DSS], [JWE], [JWK], [JWS], 1844 [NIST.800-38A], [NIST.800-38D], [NIST.800-56A], [RFC2104], [RFC3394], 1845 [RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this 1846 specification. 1848 Eventually the algorithms and/or key sizes currently described in 1849 this specification will no longer be considered sufficiently secure 1850 and will be removed. Therefore, implementers and deployments must be 1851 prepared for this eventuality. 1853 Algorithms of matching strengths should be used together whenever 1854 possible. For instance, when AES Key Wrap is used with a given key 1855 size, using the same key size is recommended when AES GCM is also 1856 used. 1858 While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not 1859 to adopt RSASSA-PKCS-v1_5 for new applications and instead requests 1860 that people transition to RSASSA-PSS, this specification does include 1861 RSASSA-PKCS-v1_5, for interoperability reasons, because it commonly 1862 implemented. 1864 Keys used with RSAES-PKCS1-v1_5 must follow the constraints in 1865 Section 7.2 of RFC 3447 [RFC3447]. In particular, keys with a low 1866 public key exponent value must not be used. 1868 Plaintext JWSs (JWSs that use the "alg" value "none") provide no 1869 integrity protection. Thus, they must only be used in contexts where 1870 the payload is secured by means other than a digital signature or MAC 1871 value, or need not be secured. 1873 Receiving agents that validate signatures and sending agents that 1874 encrypt messages need to be cautious of cryptographic processing 1875 usage when validating signatures and encrypting messages using keys 1876 larger than those mandated in this specification. An attacker could 1877 send certificates with keys that would result in excessive 1878 cryptographic processing, for example, keys larger than those 1879 mandated in this specification, which could swamp the processing 1880 element. Agents that use such keys without first validating the 1881 certificate to a trust anchor are advised to have some sort of 1882 cryptographic resource management system to prevent such attacks. 1884 8. References 1886 8.1. Normative References 1888 [AES] National Institute of Standards and Technology (NIST), 1889 "Advanced Encryption Standard (AES)", FIPS PUB 197, 1890 November 2001. 1892 [DSS] National Institute of Standards and Technology, "Digital 1893 Signature Standard (DSS)", FIPS PUB 186-3, June 2009. 1895 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 1896 Encryption (JWE)", draft-ietf-jose-json-web-encryption 1897 (work in progress), July 2013. 1899 [JWK] Jones, M., "JSON Web Key (JWK)", 1900 draft-ietf-jose-json-web-key (work in progress), 1901 July 2013. 1903 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1904 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1905 in progress), July 2013. 1907 [NIST.800-38A] 1908 National Institute of Standards and Technology (NIST), 1909 "Recommendation for Block Cipher Modes of Operation", 1910 NIST PUB 800-38A, December 2001. 1912 [NIST.800-38D] 1913 National Institute of Standards and Technology (NIST), 1914 "Recommendation for Block Cipher Modes of Operation: 1915 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 1916 December 2001. 1918 [NIST.800-56A] 1919 National Institute of Standards and Technology (NIST), 1920 "Recommendation for Pair-Wise Key Establishment Schemes 1921 Using Discrete Logarithm Cryptography", NIST Special 1922 Publication 800-56A, Revision 2, May 2013. 1924 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1925 Hashing for Message Authentication", RFC 2104, 1926 February 1997. 1928 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1929 Requirement Levels", BCP 14, RFC 2119, March 1997. 1931 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 1932 (AES) Key Wrap Algorithm", RFC 3394, September 2002. 1934 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1935 10646", STD 63, RFC 3629, November 2003. 1937 [RFC4627] Crockford, D., "The application/json Media Type for 1938 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1940 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1941 Encodings", RFC 4648, October 2006. 1943 [RFC4868] Kelly, S. and S. Frankel, "Using HMAC-SHA-256, HMAC-SHA- 1944 384, and HMAC-SHA-512 with IPsec", RFC 4868, May 2007. 1946 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 1947 Encryption", RFC 5116, January 2008. 1949 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1950 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1951 May 2008. 1953 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 1954 Curve Cryptography Algorithms", RFC 6090, February 2011. 1956 [SHS] National Institute of Standards and Technology, "Secure 1957 Hash Standard (SHS)", FIPS PUB 180-3, October 2008. 1959 [USASCII] American National Standards Institute, "Coded Character 1960 Set -- 7-bit American Standard Code for Information 1961 Interchange", ANSI X3.4, 1986. 1963 8.2. Informative References 1965 [CanvasApp] 1966 Facebook, "Canvas Applications", 2010. 1968 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1969 McGrew, D. and K. Paterson, "Authenticated Encryption with 1970 AES-CBC and HMAC-SHA", 1971 draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), 1972 October 2012. 1974 [I-D.rescorla-jsms] 1975 Rescorla, E. and J. Hildebrand, "JavaScript Message 1976 Security Format", draft-rescorla-jsms-00 (work in 1977 progress), March 2011. 1979 [JCA] Oracle, "Java Cryptography Architecture", 2011. 1981 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1982 Encryption", September 2010. 1984 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 1985 September 2010. 1987 [MagicSignatures] 1988 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 1989 Signatures", January 2011. 1991 [RFC2631] Rescorla, E., "Diffie-Hellman Key Agreement Method", 1992 RFC 2631, June 1999. 1994 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 1995 Language) XML-Signature Syntax and Processing", RFC 3275, 1996 March 2002. 1998 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1999 Standards (PKCS) #1: RSA Cryptography Specifications 2000 Version 2.1", RFC 3447, February 2003. 2002 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2003 Unique IDentifier (UUID) URN Namespace", RFC 4122, 2004 July 2005. 2006 [W3C.CR-xmldsig-core2-20120124] 2007 Eastlake, D., Reagle, J., Yiu, K., Solo, D., Datta, P., 2008 Hirsch, F., Cantor, S., and T. Roessler, "XML Signature 2009 Syntax and Processing Version 2.0", World Wide Web 2010 Consortium CR CR-xmldsig-core2-20120124, January 2012, 2011 . 2013 [W3C.CR-xmlenc-core1-20120313] 2014 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 2015 "XML Encryption Syntax and Processing Version 1.1", World 2016 Wide Web Consortium CR CR-xmlenc-core1-20120313, 2017 March 2012, 2018 . 2020 [W3C.REC-xmlenc-core-20021210] 2021 Eastlake, D. and J. Reagle, "XML Encryption Syntax and 2022 Processing", World Wide Web Consortium Recommendation REC- 2023 xmlenc-core-20021210, December 2002, 2024 . 2026 Appendix A. Digital Signature/MAC Algorithm Identifier Cross-Reference 2028 This appendix contains a table cross-referencing the digital 2029 signature and MAC "alg" (algorithm) values used in this specification 2030 with the equivalent identifiers used by other standards and software 2031 packages. See XML DSIG [RFC3275], XML DSIG 2.0 2032 [W3C.CR-xmldsig-core2-20120124], and Java Cryptography Architecture 2033 [JCA] for more information about the names defined by those 2034 documents. 2036 +---------+----+---------------------------+----------+-------------+ 2037 | Algorit | JW | XML DSIG | JCA | OID | 2038 | hm | S | | | | 2039 +---------+----+---------------------------+----------+-------------+ 2040 | HMAC | HS | http://www.w3.org/2001/04 | HmacSHA2 | 1.2.840.113 | 2041 | using | 25 | /xmldsig-more#hmac-sha256 | 56 | 549.2.9 | 2042 | SHA-256 | 6 | | | | 2043 | hash | | | | | 2044 | algorit | | | | | 2045 | hm | | | | | 2046 | HMAC | HS | http://www.w3.org/2001/04 | HmacSHA3 | 1.2.840.113 | 2047 | using | 38 | /xmldsig-more#hmac-sha384 | 84 | 549.2.10 | 2048 | SHA-384 | 4 | | | | 2049 | hash | | | | | 2050 | algorit | | | | | 2051 | hm | | | | | 2052 | HMAC | HS | http://www.w3.org/2001/04 | HmacSHA5 | 1.2.840.113 | 2053 | using | 51 | /xmldsig-more#hmac-sha512 | 12 | 549.2.11 | 2054 | SHA-512 | 2 | | | | 2055 | hash | | | | | 2056 | algorit | | | | | 2057 | hm | | | | | 2058 | RSASSA- | RS | http://www.w3.org/2001/04 | SHA256wi | 1.2.840.113 | 2059 | PKCS-v1 | 25 | /xmldsig-more#rsa-sha256 | thRSA | 549.1.1.11 | 2060 | _5using | 6 | | | | 2061 | SHA-2 | | | | | 2062 | 56hash | | | | | 2063 | algor | | | | | 2064 | ithm | | | | | 2065 | RSASSA- | RS | http://www.w3.org/2001/04 | SHA384wi | 1.2.840.113 | 2066 | PKCS-v1 | 38 | /xmldsig-more#rsa-sha384 | thRSA | 549.1.1.12 | 2067 | _5using | 4 | | | | 2068 | SHA-3 | | | | | 2069 | 84hash | | | | | 2070 | algor | | | | | 2071 | ithm | | | | | 2072 | RSASSA- | RS | http://www.w3.org/2001/04 | SHA512wi | 1.2.840.113 | 2073 | PKCS-v1 | 51 | /xmldsig-more#rsa-sha512 | thRSA | 549.1.1.13 | 2074 | _5using | 2 | | | | 2075 | SHA-5 | | | | | 2076 | 12hash | | | | | 2077 | algor | | | | | 2078 | ithm | | | | | 2079 | ECDSA | ES | http://www.w3.org/2001/04 | SHA256wi | 1.2.840.100 | 2080 | using | 25 | /xmldsig-more#ecdsa-sha25 | thECDSA | 45.4.3.2 | 2081 | P-256 | 6 | 6 | | | 2082 | curve | | | | | 2083 | and | | | | | 2084 | SHA-256 | | | | | 2085 | hash | | | | | 2086 | algorit | | | | | 2087 | hm | | | | | 2088 | ECDSA | ES | http://www.w3.org/2001/04 | SHA384wi | 1.2.840.100 | 2089 | using | 38 | /xmldsig-more#ecdsa-sha38 | thECDSA | 45.4.3.3 | 2090 | P-384 | 4 | 4 | | | 2091 | curve | | | | | 2092 | and | | | | | 2093 | SHA-384 | | | | | 2094 | hash | | | | | 2095 | algorit | | | | | 2096 | hm | | | | | 2097 | ECDSA | ES | http://www.w3.org/2001/04 | SHA512wi | 1.2.840.100 | 2098 | using | 51 | /xmldsig-more#ecdsa-sha51 | thECDSA | 45.4.3.4 | 2099 | P-521 | 2 | 2 | | | 2100 | curve | | | | | 2101 | and | | | | | 2102 | SHA-512 | | | | | 2103 | hash | | | | | 2104 | algorit | | | | | 2105 | hm | | | | | 2106 | RSASSA- | PS | | | | 2107 | PSS | 25 | | | | 2108 | using | 6 | | | | 2109 | SHA-25 | | | | | 2110 | 6hash | | | | | 2111 | algori | | | | | 2112 | thm and | | | | | 2113 | MGF1 | | | | | 2114 | mask | | | | | 2115 | gener | | | | | 2116 | ation | | | | | 2117 | func | | | | | 2118 | tionwit | | | | | 2119 | h SHA | | | | | 2120 | -256 | | | | | 2121 | RSASSA- | PS | | | | 2122 | PSS | 51 | | | | 2123 | using | 2 | | | | 2124 | SHA-51 | | | | | 2125 | 2hash | | | | | 2126 | algori | | | | | 2127 | thm and | | | | | 2128 | MGF1 | | | | | 2129 | mask | | | | | 2130 | gener | | | | | 2131 | ation | | | | | 2132 | func | | | | | 2133 | tionwit | | | | | 2134 | h SHA | | | | | 2135 | -512 | | | | | 2136 +---------+----+---------------------------+----------+-------------+ 2138 Appendix B. Encryption Algorithm Identifier Cross-Reference 2140 This appendix contains a table cross-referencing the "alg" 2141 (algorithm) and "enc" (encryption method) values used in this 2142 specification with the equivalent identifiers used by other standards 2143 and software packages. See XML Encryption 2145 [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 2146 [W3C.CR-xmlenc-core1-20120313], and Java Cryptography Architecture 2147 [JCA] for more information about the names defined by those 2148 documents. 2150 For the composite algorithms "A128CBC-HS256" and "A256CBC-HS512", the 2151 corresponding AES CBC algorithm identifiers are listed. 2153 +----------+--------+--------------------------+--------------------+ 2154 | Algorith | JWE | XML ENC | JCA | 2155 | m | | | | 2156 +----------+--------+--------------------------+--------------------+ 2157 | RSAES-PK | RSA1_5 | http://www.w3.org/2001/0 | RSA/ECB/PKCS1Paddi | 2158 | CS1-V1_5 | | 4/xmlenc#rsa-1_5 | ng | 2159 | RSAES | RSA-OA | http://www.w3.org/2001/0 | RSA/ECB/OAEPWithSH | 2160 | using | EP | 4/xmlenc#rsa-oaep-mgf1p | A-1AndMGF1Padding | 2161 | Optimal | | | | 2162 | Asymmetr | | | | 2163 | ic | | | | 2164 | Encrypt | | | | 2165 | ion | | | | 2166 | Paddin | | | | 2167 | g (OAEP) | | | | 2168 | Elliptic | ECDH-E | http://www.w3.org/2009/x | | 2169 | Curve | S | mlenc11#ECDH-ES | | 2170 | Diffie-H | | | | 2171 | ellman | | | | 2172 | Ephemer | | | | 2173 | alStatic | | | | 2174 | Advanced | A128KW | http://www.w3.org/2001/0 | | 2175 | Encrypti | | 4/xmlenc#kw-aes128 | | 2176 | on | | | | 2177 | Standar | | | | 2178 | d(AES) | | | | 2179 | Key Wra | | | | 2180 | pAlgorit | | | | 2181 | hmusing | | | | 2182 | 128 bi | | | | 2183 | t keys | | | | 2184 | AES Key | A256KW | http://www.w3.org/2001/0 | | 2185 | Wrap | | 4/xmlenc#kw-aes256 | | 2186 | Algorith | | | | 2187 | musing | | | | 2188 | 256 bit | | | | 2189 | keys | | | | 2190 | AES in | A128CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 2191 | Cipher | C-HS25 | 4/xmlenc#aes128-cbc | ng | 2192 | Block | 6 | | | 2193 | Chaining | | | | 2194 | (CBC) | | | | 2195 | mode | | | | 2196 | with | | | | 2197 | PKCS #5 | | | | 2198 | padding | | | | 2199 | using | | | | 2200 | 128 bit | | | | 2201 | keys | | | | 2202 | AES in | A256CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 2203 | CBC mode | C-HS51 | 4/xmlenc#aes256-cbc | ng | 2204 | with | 2 | | | 2205 | PKCS #5 | | | | 2206 | padding | | | | 2207 | using | | | | 2208 | 256 bit | | | | 2209 | keys | | | | 2210 | AES in | A128GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 2211 | Galois/C | M | mlenc11#aes128-gcm | | 2212 | ounter | | | | 2213 | Mode | | | | 2214 | (GCM) | | | | 2215 | using | | | | 2216 | 128 bit | | | | 2217 | keys | | | | 2218 | AES GCM | A256GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 2219 | using | M | mlenc11#aes256-gcm | | 2220 | 256 bit | | | | 2221 | keys | | | | 2222 +----------+--------+--------------------------+--------------------+ 2224 Appendix C. Test Cases for AES_CBC_HMAC_SHA2 Algorithms 2226 The following test cases can be used to validate implementations of 2227 the AES_CBC_HMAC_SHA2 algorithms defined in Section 4.8. They are 2228 also intended to correspond to test cases that may appear in a future 2229 version of [I-D.mcgrew-aead-aes-cbc-hmac-sha2], demonstrating that 2230 the cryptographic computations performed are the same. 2232 The variable names are those defined in Section 4.8. All values are 2233 hexadecimal. 2235 C.1. Test Cases for AES_128_CBC_HMAC_SHA_256 2237 AES_128_CBC_HMAC_SHA_256 2239 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2240 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2242 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2244 ENC_KEY = 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2246 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2247 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2248 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2249 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2250 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2251 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2252 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2253 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2255 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2257 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2258 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2259 4b 65 72 63 6b 68 6f 66 66 73 2261 AL = 00 00 00 00 00 00 01 50 2263 E = c8 0e df a3 2d df 39 d5 ef 00 c0 b4 68 83 42 79 2264 a2 e4 6a 1b 80 49 f7 92 f7 6b fe 54 b9 03 a9 c9 2265 a9 4a c9 b4 7a d2 65 5c 5f 10 f9 ae f7 14 27 e2 2266 fc 6f 9b 3f 39 9a 22 14 89 f1 63 62 c7 03 23 36 2267 09 d4 5a c6 98 64 e3 32 1c f8 29 35 ac 40 96 c8 2268 6e 13 33 14 c5 40 19 e8 ca 79 80 df a4 b9 cf 1b 2269 38 4c 48 6f 3a 54 c5 10 78 15 8e e5 d7 9d e5 9f 2270 bd 34 d8 48 b3 d6 95 50 a6 76 46 34 44 27 ad e5 2271 4b 88 51 ff b5 98 f7 f8 00 74 b9 47 3c 82 e2 db 2273 M = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2274 e6 e5 45 82 47 65 15 f0 ad 9f 75 a2 b7 1c 73 ef 2276 T = 65 2c 3f a3 6b 0a 7c 5b 32 19 fa b3 a3 0b c1 c4 2278 C.2. Test Cases for AES_256_CBC_HMAC_SHA_512 2280 K = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2281 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2282 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2283 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2285 MAC_KEY = 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 2286 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f 2288 ENC_KEY = 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 2289 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 2291 P = 41 20 63 69 70 68 65 72 20 73 79 73 74 65 6d 20 2292 6d 75 73 74 20 6e 6f 74 20 62 65 20 72 65 71 75 2293 69 72 65 64 20 74 6f 20 62 65 20 73 65 63 72 65 2294 74 2c 20 61 6e 64 20 69 74 20 6d 75 73 74 20 62 2295 65 20 61 62 6c 65 20 74 6f 20 66 61 6c 6c 20 69 2296 6e 74 6f 20 74 68 65 20 68 61 6e 64 73 20 6f 66 2297 20 74 68 65 20 65 6e 65 6d 79 20 77 69 74 68 6f 2298 75 74 20 69 6e 63 6f 6e 76 65 6e 69 65 6e 63 65 2300 IV = 1a f3 8c 2d c2 b9 6f fd d8 66 94 09 23 41 bc 04 2302 A = 54 68 65 20 73 65 63 6f 6e 64 20 70 72 69 6e 63 2303 69 70 6c 65 20 6f 66 20 41 75 67 75 73 74 65 20 2304 4b 65 72 63 6b 68 6f 66 66 73 2306 AL = 00 00 00 00 00 00 01 50 2308 E = 4a ff aa ad b7 8c 31 c5 da 4b 1b 59 0d 10 ff bd 2309 3d d8 d5 d3 02 42 35 26 91 2d a0 37 ec bc c7 bd 2310 82 2c 30 1d d6 7c 37 3b cc b5 84 ad 3e 92 79 c2 2311 e6 d1 2a 13 74 b7 7f 07 75 53 df 82 94 10 44 6b 2312 36 eb d9 70 66 29 6a e6 42 7e a7 5c 2e 08 46 a1 2313 1a 09 cc f5 37 0d c8 0b fe cb ad 28 c7 3f 09 b3 2314 a3 b7 5e 66 2a 25 94 41 0a e4 96 b2 e2 e6 60 9e 2315 31 e6 e0 2c c8 37 f0 53 d2 1f 37 ff 4f 51 95 0b 2316 be 26 38 d0 9d d7 a4 93 09 30 80 6d 07 03 b1 f6 2318 M = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2319 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2320 fd 30 a5 65 c6 16 ff b2 f3 64 ba ec e6 8f c4 07 2321 53 bc fc 02 5d de 36 93 75 4a a1 f5 c3 37 3b 9c 2323 T = 4d d3 b4 c0 88 a7 f4 5c 21 68 39 64 5b 20 12 bf 2324 2e 62 69 a8 c5 6a 81 6d bc 1b 26 77 61 95 5b c5 2326 Appendix D. Acknowledgements 2328 Solutions for signing and encrypting JSON content were previously 2329 explored by Magic Signatures [MagicSignatures], JSON Simple Sign 2330 [JSS], Canvas Applications [CanvasApp], JSON Simple Encryption [JSE], 2331 and JavaScript Message Security Format [I-D.rescorla-jsms], all of 2332 which influenced this draft. 2334 The Authenticated Encryption with AES-CBC and HMAC-SHA 2335 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] specification, upon which the 2336 AES_CBC_HMAC_SHA2 algorithms are based, was written by David A. 2337 McGrew and Kenny Paterson. The test cases for AES_CBC_HMAC_SHA2 are 2338 based upon those for [I-D.mcgrew-aead-aes-cbc-hmac-sha2] by John 2339 Foley. 2341 This specification is the work of the JOSE Working Group, which 2342 includes dozens of active and dedicated participants. In particular, 2343 the following individuals contributed ideas, feedback, and wording 2344 that influenced this specification: 2346 Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de 2347 Medeiros, Yaron Y. Goland, Dick Hardt, Jeff Hodges, Edmund Jay, James 2348 Manger, Tony Nadalin, Axel Nennker, John Panzer, Emmanuel Raviart, 2349 Nat Sakimura, Jim Schaad, Hannes Tschofenig, and Sean Turner. 2351 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2352 Sean Turner and Stephen Farrell served as Security area directors 2353 during the creation of this specification. 2355 Appendix E. Document History 2357 [[ to be removed by the RFC editor before publication as an RFC ]] 2359 -12 2361 o In the Direct Key Agreement case, the Concat KDF AlgorithmID is 2362 set to the octets of the UTF-8 representation of the "enc" header 2363 parameter value. 2365 o Restored the "apv" (agreement PartyVInfo) parameter. 2367 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2368 be with the algorithm descriptions that use them. 2370 o Changed terminology from "block encryption" to "content 2371 encryption". 2373 -11 2375 o Removed the Encrypted Key value from the AAD computation since it 2376 is already effectively integrity protected by the encryption 2377 process. The AAD value now only contains the representation of 2378 the JWE Encrypted Header. 2380 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2382 o Added more information about the use of PartyUInfo during key 2383 agreement. 2385 o Use the keydatalen as the SuppPubInfo value for the Concat KDF 2386 when doing key agreement, as RFC 2631 does. 2388 o Added algorithm identifiers for RSASSA-PSS with SHA-256 and SHA- 2389 512. 2391 o Added a Parameter Information Class value to the JSON Web Key 2392 Parameters registry, which registers whether the parameter conveys 2393 public or private information. 2395 -10 2397 o Changed the JWE processing rules for multiple recipients so that a 2398 single AAD value contains the header parameters and encrypted key 2399 values for all the recipients, enabling AES GCM to be safely used 2400 for multiple recipients. 2402 -09 2404 o Expanded the scope of the JWK parameters to include private and 2405 symmetric key representations, as specified by 2406 draft-jones-jose-json-private-and-symmetric-key-00. 2408 o Changed term "JWS Secured Input" to "JWS Signing Input". 2410 o Changed from using the term "byte" to "octet" when referring to 8 2411 bit values. 2413 o Specified that AES Key Wrap uses the default initial value 2414 specified in Section 2.2.3.1 of RFC 3394. This addressed issue 2415 #19. 2417 o Added Key Management Mode definitions to terminology section and 2418 used the defined terms to provide clearer key management 2419 instructions. This addressed issue #5. 2421 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2422 and "A256CBC-HS512". The new algorithms perform the same 2423 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2424 but with the Initialization Vector and Authentication Tag values 2425 remaining separate from the Ciphertext value in the output 2426 representation. Also deleted the header parameters "epu" 2427 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2428 they are no longer used. 2430 o Changed from using the term "Integrity Value" to "Authentication 2431 Tag". 2433 -08 2435 o Changed the name of the JWK key type parameter from "alg" to 2436 "kty". 2438 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2439 since the term AEAD in the RFC 5116 sense implied the use of a 2440 particular data representation, rather than just referring to the 2441 class of algorithms that perform authenticated encryption with 2442 associated data. 2444 o Applied editorial improvements suggested by Jeff Hodges. Many of 2445 these simplified the terminology used. 2447 o Added seriesInfo information to Internet Draft references. 2449 -07 2451 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2453 o Changed the name of the JWK RSA modulus parameter from "mod" to 2454 "n" and the name of the JWK RSA exponent parameter from "xpo" to 2455 "e", so that the identifiers are the same as those used in RFC 2456 3447. 2458 o Made several local editorial changes to clean up loose ends left 2459 over from to the decision to only support block encryption methods 2460 providing integrity. 2462 -06 2464 o Removed the "int" and "kdf" parameters and defined the new 2465 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2466 "A256CBC+HS512" to replace the former uses of AES CBC, which 2467 required the use of separate integrity and key derivation 2468 functions. 2470 o Included additional values in the Concat KDF calculation -- the 2471 desired output size and the algorithm value, and optionally 2472 PartyUInfo and PartyVInfo values. Added the optional header 2473 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2474 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2475 PartyVInfo). 2477 o Changed the name of the JWK RSA exponent parameter from "exp" to 2478 "xpo" so as to allow the potential use of the name "exp" for a 2479 future extension that might define an expiration parameter for 2480 keys. (The "exp" name is already used for this purpose in the JWT 2481 specification.) 2483 o Applied changes made by the RFC Editor to RFC 6749's registry 2484 language to this specification. 2486 -05 2488 o Support both direct encryption using a shared or agreed upon 2489 symmetric key, and the use of a shared or agreed upon symmetric 2490 key to key wrap the CMK. Specifically, added the "alg" values 2491 "dir", "ECDH-ES+A128KW", and "ECDH-ES+A256KW" to finish filling in 2492 this set of capabilities. 2494 o Updated open issues. 2496 -04 2498 o Added text requiring that any leading zero bytes be retained in 2499 base64url encoded key value representations for fixed-length 2500 values. 2502 o Added this language to Registration Templates: "This name is case 2503 sensitive. Names that match other registered names in a case 2504 insensitive manner SHOULD NOT be accepted." 2506 o Described additional open issues. 2508 o Applied editorial suggestions. 2510 -03 2512 o Always use a 128 bit "authentication tag" size for AES GCM, 2513 regardless of the key size. 2515 o Specified that use of a 128 bit IV is REQUIRED with AES CBC. It 2516 was previously RECOMMENDED. 2518 o Removed key size language for ECDSA algorithms, since the key size 2519 is implied by the algorithm being used. 2521 o Stated that the "int" key size must be the same as the hash output 2522 size (and not larger, as was previously allowed) so that its size 2523 is defined for key generation purposes. 2525 o Added the "kdf" (key derivation function) header parameter to 2526 provide crypto agility for key derivation. The default KDF 2527 remains the Concat KDF with the SHA-256 digest function. 2529 o Clarified that the "mod" and "exp" values are unsigned. 2531 o Added Implementation Requirements columns to algorithm tables and 2532 Implementation Requirements entries to algorithm registries. 2534 o Changed AES Key Wrap to RECOMMENDED. 2536 o Moved registries JSON Web Signature and Encryption Header 2537 Parameters and JSON Web Signature and Encryption Type Values to 2538 the JWS specification. 2540 o Moved JSON Web Key Parameters registry to the JWK specification. 2542 o Changed registration requirements from RFC Required to 2543 Specification Required with Expert Review. 2545 o Added Registration Template sections for defined registries. 2547 o Added Registry Contents sections to populate registry values. 2549 o No longer say "the UTF-8 representation of the JWS Secured Input 2550 (which is the same as the ASCII representation)". Just call it 2551 "the ASCII representation of the JWS Secured Input". 2553 o Added "Collision Resistant Namespace" to the terminology section. 2555 o Numerous editorial improvements. 2557 -02 2559 o For AES GCM, use the "additional authenticated data" parameter to 2560 provide integrity for the header, encrypted key, and ciphertext 2561 and use the resulting "authentication tag" value as the JWE 2562 Authentication Tag. 2564 o Defined minimum required key sizes for algorithms without 2565 specified key sizes. 2567 o Defined KDF output key sizes. 2569 o Specified the use of PKCS #5 padding with AES CBC. 2571 o Generalized text to allow key agreement to be employed as an 2572 alternative to key wrapping or key encryption. 2574 o Clarified that ECDH-ES is a key agreement algorithm. 2576 o Required implementation of AES-128-KW and AES-256-KW. 2578 o Removed the use of "A128GCM" and "A256GCM" for key wrapping. 2580 o Removed "A512KW" since it turns out that it's not a standard 2581 algorithm. 2583 o Clarified the relationship between "typ" header parameter values 2584 and MIME types. 2586 o Generalized language to refer to Message Authentication Codes 2587 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2588 unless in a context specific to HMAC algorithms. 2590 o Established registries: JSON Web Signature and Encryption Header 2591 Parameters, JSON Web Signature and Encryption Algorithms, JSON Web 2592 Signature and Encryption "typ" Values, JSON Web Key Parameters, 2593 and JSON Web Key Algorithm Families. 2595 o Moved algorithm-specific definitions from JWK to JWA. 2597 o Reformatted to give each member definition its own section 2598 heading. 2600 -01 2602 o Moved definition of "alg":"none" for JWSs here from the JWT 2603 specification since this functionality is likely to be useful in 2604 more contexts that just for JWTs. 2606 o Added Advanced Encryption Standard (AES) Key Wrap Algorithm using 2607 512 bit keys ("A512KW"). 2609 o Added text "Alternatively, the Encoded JWS Signature MAY be 2610 base64url decoded to produce the JWS Signature and this value can 2611 be compared with the computed HMAC value, as this comparison 2612 produces the same result as comparing the encoded values". 2614 o Corrected the Magic Signatures reference. 2616 o Made other editorial improvements suggested by JOSE working group 2617 participants. 2619 -00 2621 o Created the initial IETF draft based upon 2622 draft-jones-json-web-signature-04 and 2623 draft-jones-json-web-encryption-02 with no normative changes. 2625 o Changed terminology to no longer call both digital signatures and 2626 HMACs "signatures". 2628 Author's Address 2630 Michael B. Jones 2631 Microsoft 2633 Email: mbj@microsoft.com 2634 URI: http://self-issued.info/