idnits 2.17.1 draft-ietf-jose-json-web-algorithms-08.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 == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: 2. Turn R and S into byte arrays in big endian order, with each array being be 32 bytes long. The array representations MUST not be shortened to omit any leading zero bytes contained in the values. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The "x" (x coordinate) member contains the x coordinate for the elliptic curve point. It is represented as the base64url encoding of the coordinate's big endian representation as a byte array. The array representation MUST not be shortened to omit any leading zero bytes contained in the value. For instance, when representing 521 bit integers, the byte array to be base64url encoded MUST contain 66 bytes, including any leading zero bytes. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The "y" (y coordinate) member contains the y coordinate for the elliptic curve point. It is represented as the base64url encoding of the coordinate's big endian representation as a byte array. The array representation MUST not be shortened to omit any leading zero bytes contained in the value. For instance, when representing 521 bit integers, the byte array to be base64url encoded MUST contain 66 bytes, including any leading zero bytes. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The "n" (modulus) member contains the modulus value for the RSA public key. It is represented as the base64url encoding of the value's unsigned big endian representation as a byte array. The array representation MUST not be shortened to omit any leading zero bytes. For instance, when representing 2048 bit integers, the byte array to be base64url encoded MUST contain 256 bytes, including any leading zero bytes. -- The document date (December 27, 2012) is 4131 days in the past. Is this intentional? 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: '69' on line 820 -- Looks like a reference, but probably isn't: '110' on line 821 -- Looks like a reference, but probably isn't: '99' on line 820 -- Looks like a reference, but probably isn't: '114' on line 821 -- Looks like a reference, but probably isn't: '121' on line 821 -- Looks like a reference, but probably isn't: '112' on line 820 -- Looks like a reference, but probably isn't: '116' on line 821 -- Looks like a reference, but probably isn't: '105' on line 821 -- Looks like a reference, but probably isn't: '111' on line 820 -- Looks like a reference, but probably isn't: '73' on line 821 -- Looks like a reference, but probably isn't: '101' on line 821 -- Looks like a reference, but probably isn't: '103' on line 821 -- Looks like a reference, but probably isn't: '1' on line 1030 -- Looks like a reference, but probably isn't: '0' on line 1030 == Unused Reference: 'RFC3629' is defined on line 1431, but no explicit reference was found in the text -- 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 3447 (Obsoleted by RFC 8017) ** 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' Summary: 6 errors (**), 0 flaws (~~), 7 warnings (==), 19 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 December 27, 2012 5 Expires: June 30, 2013 7 JSON Web Algorithms (JWA) 8 draft-ietf-jose-json-web-algorithms-08 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 June 30, 2013. 34 Copyright Notice 36 Copyright (c) 2012 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 . . . . . . 7 57 2.4. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 7 58 3. Cryptographic Algorithms for JWS . . . . . . . . . . . . . . . 7 59 3.1. "alg" (Algorithm) Header Parameter Values for JWS . . . . 7 60 3.2. MAC with HMAC SHA-256, HMAC SHA-384, or HMAC SHA-512 . . . 8 61 3.3. Digital Signature with RSA SHA-256, RSA SHA-384, or 62 RSA SHA-512 . . . . . . . . . . . . . . . . . . . . . . . 9 63 3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA 64 P-384 SHA-384, or ECDSA P-521 SHA-512 . . . . . . . . . . 10 65 3.5. Using the Algorithm "none" . . . . . . . . . . . . . . . . 12 66 3.6. Additional Digital Signature/MAC Algorithms and 67 Parameters . . . . . . . . . . . . . . . . . . . . . . . . 12 68 4. Cryptographic Algorithms for JWE . . . . . . . . . . . . . . . 13 69 4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 13 70 4.2. "enc" (Encryption Method) Header Parameter Values for 71 JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 72 4.3. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 15 73 4.4. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 15 74 4.5. Key Encryption with AES Key Wrap . . . . . . . . . . . . . 15 75 4.6. Direct Encryption with a Shared Symmetric Key . . . . . . 16 76 4.7. Key Agreement with Elliptic Curve Diffie-Hellman 77 Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 16 78 4.7.1. Key Derivation for "ECDH-ES" . . . . . . . . . . . . . 16 79 4.8. Composite Plaintext Encryption Algorithms 80 "A128CBC+HS256" and "A256CBC+HS512" . . . . . . . . . . . 17 81 4.8.1. Key Derivation for "A128CBC+HS256" and 82 "A256CBC+HS512" . . . . . . . . . . . . . . . . . . . 18 83 4.8.2. Encryption Calculation for "A128CBC+HS256" and 84 "A256CBC+HS512" . . . . . . . . . . . . . . . . . . . 19 85 4.8.3. Integrity Calculation for "A128CBC+HS256" and 86 "A256CBC+HS512" . . . . . . . . . . . . . . . . . . . 19 87 4.9. Plaintext Encryption with AES GCM . . . . . . . . . . . . 20 88 4.10. Additional Encryption Algorithms and Parameters . . . . . 20 89 5. Cryptographic Algorithms for JWK . . . . . . . . . . . . . . . 21 90 5.1. "kty" (Key Type) Parameter Values for JWK . . . . . . . . 21 91 5.2. JWK Parameters for Elliptic Curve Keys . . . . . . . . . . 22 92 5.2.1. "crv" (Curve) Parameter . . . . . . . . . . . . . . . 22 93 5.2.2. "x" (X Coordinate) Parameter . . . . . . . . . . . . . 22 94 5.2.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . . . 22 95 5.3. JWK Parameters for RSA Keys . . . . . . . . . . . . . . . 22 96 5.3.1. "n" (Modulus) Parameter . . . . . . . . . . . . . . . 23 97 5.3.2. "e" (Exponent) Parameter . . . . . . . . . . . . . . . 23 98 5.4. Additional Key Types and Parameters . . . . . . . . . . . 23 99 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 100 6.1. JSON Web Signature and Encryption Algorithms Registry . . 24 101 6.1.1. Registration Template . . . . . . . . . . . . . . . . 24 102 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 25 103 6.2. JSON Web Key Types Registry . . . . . . . . . . . . . . . 28 104 6.2.1. Registration Template . . . . . . . . . . . . . . . . 28 105 6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 29 106 6.3. JSON Web Key Parameters Registration . . . . . . . . . . . 29 107 6.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 29 108 7. Security Considerations . . . . . . . . . . . . . . . . . . . 29 109 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31 110 8.1. Normative References . . . . . . . . . . . . . . . . . . . 31 111 8.2. Informative References . . . . . . . . . . . . . . . . . . 32 112 Appendix A. Digital Signature/MAC Algorithm Identifier 113 Cross-Reference . . . . . . . . . . . . . . . . . . . 33 114 Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 35 115 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 37 116 Appendix D. Open Issues . . . . . . . . . . . . . . . . . . . . . 38 117 Appendix E. Document History . . . . . . . . . . . . . . . . . . 38 118 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 42 120 1. Introduction 122 The JSON Web Algorithms (JWA) specification enumerates cryptographic 123 algorithms and identifiers to be used with the JSON Web Signature 124 (JWS) [JWS], JSON Web Encryption (JWE) [JWE], and JSON Web Key (JWK) 125 [JWK] specifications. All these specifications utilize JavaScript 126 Object Notation (JSON) [RFC4627] based data structures. This 127 specification also describes the semantics and operations that are 128 specific to these algorithms and key types. 130 Enumerating the algorithms and identifiers for them in this 131 specification, rather than in the JWS, JWE, and JWK specifications, 132 is intended to allow them to remain unchanged in the face of changes 133 in the set of required, recommended, optional, and deprecated 134 algorithms over time. 136 1.1. Notational Conventions 138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 140 document are to be interpreted as described in Key words for use in 141 RFCs to Indicate Requirement Levels [RFC2119]. 143 2. Terminology 145 2.1. Terms Incorporated from the JWS Specification 147 These terms defined by the JSON Web Signature (JWS) [JWS] 148 specification are incorporated into this specification: 150 JSON Web Signature (JWS) A data structure representing a digitally 151 signed or MACed message. The structure consists of three parts: 152 the JWS Header, the JWS Payload, and the JWS Signature value. 154 JSON Text Object A UTF-8 encoded text string representing a JSON 155 object; the syntax of JSON objects is defined in Section 2.2 of 156 [RFC4627]. 158 JWS Header A JSON Text Object that describes the digital signature 159 or MAC operation applied to create the JWS Signature value. 161 JWS Payload The bytes to be secured -- a.k.a., the message. The 162 payload can contain an arbitrary sequence of bytes. 164 JWS Signature A byte array containing the cryptographic material 165 that secures the contents of the JWS Header and the JWS Payload. 167 Base64url Encoding The URL- and filename-safe Base64 encoding 168 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 169 safe) '=' padding characters omitted, as permitted by Section 3.2. 170 (See Appendix C of [JWS] for notes on implementing base64url 171 encoding without padding.) 173 Encoded JWS Header Base64url encoding of the JWS Header. 175 Encoded JWS Payload Base64url encoding of the JWS Payload. 177 Encoded JWS Signature Base64url encoding of the JWS Signature. 179 JWS Secured Input The concatenation of the Encoded JWS Header, a 180 period ('.') character, and the Encoded JWS Payload. 182 Collision Resistant Namespace A namespace that allows names to be 183 allocated in a manner such that they are highly unlikely to 184 collide with other names. For instance, collision resistance can 185 be achieved through administrative delegation of portions of the 186 namespace or through use of collision-resistant name allocation 187 functions. Examples of Collision Resistant Namespaces include: 188 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 189 X.660 and X.670 Recommendation series, and Universally Unique 190 IDentifiers (UUIDs) [RFC4122]. When using an administratively 191 delegated namespace, the definer of a name needs to take 192 reasonable precautions to ensure they are in control of the 193 portion of the namespace they use to define the name. 195 2.2. Terms Incorporated from the JWE Specification 197 These terms defined by the JSON Web Encryption (JWE) [JWE] 198 specification are incorporated into this specification: 200 JSON Web Encryption (JWE) A data structure representing an encrypted 201 message. The structure consists of five parts: the JWE Header, 202 the JWE Encrypted Key, the JWE Initialization Vector, the JWE 203 Ciphertext, and the JWE Integrity Value. 205 Plaintext The bytes to be encrypted -- a.k.a., the message. The 206 plaintext can contain an arbitrary sequence of bytes. 208 Ciphertext An encrypted representation of the Plaintext. 210 Content Encryption Key (CEK) A symmetric key used to encrypt the 211 Plaintext for the recipient to produce the Ciphertext. 213 Content Integrity Key (CIK) A key used with a MAC function to ensure 214 the integrity of the Ciphertext and the parameters used to create 215 it. 217 Content Master Key (CMK) A key from which the CEK and CIK are 218 derived. When key wrapping or key encryption are employed, the 219 CMK is randomly generated and encrypted to the recipient as the 220 JWE Encrypted Key. When direct encryption with a shared symmetric 221 key is employed, the CMK is the shared key. When key agreement 222 without key wrapping is employed, the CMK is the result of the key 223 agreement algorithm. 225 JSON Text Object A UTF-8 encoded text string representing a JSON 226 object; the syntax of JSON objects is defined in Section 2.2 of 227 [RFC4627]. 229 JWE Header A JSON Text Object that describes the encryption 230 operations applied to create the JWE Encrypted Key, the JWE 231 Ciphertext, and the JWE Integrity Value. 233 JWE Encrypted Key When key wrapping or key encryption are employed, 234 the Content Master Key (CMK) is encrypted with the intended 235 recipient's key and the resulting encrypted content is recorded as 236 a byte array, which is referred to as the JWE Encrypted Key. 237 Otherwise, when direct encryption with a shared or agreed upon 238 symmetric key is employed, the JWE Encrypted Key is the empty byte 239 array. 241 JWE Initialization Vector A byte array containing the Initialization 242 Vector used when encrypting the Plaintext. 244 JWE Ciphertext A byte array containing the Ciphertext. 246 JWE Integrity Value A byte array containing a MAC value that ensures 247 the integrity of the Ciphertext and the parameters used to create 248 it. 250 Encoded JWE Header Base64url encoding of the JWE Header. 252 Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted 253 Key. 255 Encoded JWE Initialization Vector Base64url encoding of the JWE 256 Initialization Vector. 258 Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. 260 Encoded JWE Integrity Value Base64url encoding of the JWE Integrity 261 Value. 263 Authenticated Encryption An Authenticated Encryption algorithm is 264 one that provides an integrated content integrity check. 265 Authenticated Encryption algorithms accept two inputs, the 266 plaintext and the "additional authenticated data" value, and 267 produce two outputs, the ciphertext and the "authentication tag" 268 value. AES Galois/Counter Mode (GCM) is one such algorithm. 270 2.3. Terms Incorporated from the JWK Specification 272 These terms defined by the JSON Web Key (JWK) [JWK] specification are 273 incorporated into this specification: 275 JSON Web Key (JWK) A JSON data structure that represents a public 276 key. 278 JSON Web Key Set (JWK Set) A JSON object that contains an array of 279 JWKs as the value of its "keys" member. 281 2.4. Defined Terms 283 These terms are defined for use by this specification: 285 Header Parameter Name The name of a member of the JSON object 286 representing a JWS Header or JWE Header. 288 Header Parameter Value The value of a member of the JSON object 289 representing a JWS Header or JWE Header. 291 3. Cryptographic Algorithms for JWS 293 JWS uses cryptographic algorithms to digitally sign or create a 294 Message Authentication Codes (MAC) of the contents of the JWS Header 295 and the JWS Payload. The use of the following algorithms for 296 producing JWSs is defined in this section. 298 3.1. "alg" (Algorithm) Header Parameter Values for JWS 300 The table below is the set of "alg" (algorithm) header parameter 301 values defined by this specification for use with JWS, each of which 302 is explained in more detail in the following sections: 304 +--------------+--------------------------------+-------------------+ 305 | alg | Digital Signature or MAC | Implementation | 306 | Parameter | Algorithm | Requirements | 307 | Value | | | 308 +--------------+--------------------------------+-------------------+ 309 | HS256 | HMAC using SHA-256 hash | REQUIRED | 310 | | algorithm | | 311 | HS384 | HMAC using SHA-384 hash | OPTIONAL | 312 | | algorithm | | 313 | HS512 | HMAC using SHA-512 hash | OPTIONAL | 314 | | algorithm | | 315 | RS256 | RSASSA using SHA-256 hash | RECOMMENDED | 316 | | algorithm | | 317 | RS384 | RSASSA using SHA-384 hash | OPTIONAL | 318 | | algorithm | | 319 | RS512 | RSASSA using SHA-512 hash | OPTIONAL | 320 | | algorithm | | 321 | ES256 | ECDSA using P-256 curve and | RECOMMENDED+ | 322 | | SHA-256 hash algorithm | | 323 | ES384 | ECDSA using P-384 curve and | OPTIONAL | 324 | | SHA-384 hash algorithm | | 325 | ES512 | ECDSA using P-521 curve and | OPTIONAL | 326 | | SHA-512 hash algorithm | | 327 | none | No digital signature or MAC | REQUIRED | 328 | | value included | | 329 +--------------+--------------------------------+-------------------+ 331 All the names are short because a core goal of JWS is for the 332 representations to be compact. However, there is no a priori length 333 restriction on "alg" values. 335 The use of "+" in the Implementation Requirements indicates that the 336 requirement strength is likely to be increased in a future version of 337 the specification. 339 See Appendix A for a table cross-referencing the digital signature 340 and MAC "alg" (algorithm) values used in this specification with the 341 equivalent identifiers used by other standards and software packages. 343 3.2. MAC with HMAC SHA-256, HMAC SHA-384, or HMAC SHA-512 345 Hash-based Message Authentication Codes (HMACs) enable one to use a 346 secret plus a cryptographic hash function to generate a Message 347 Authentication Code (MAC). This can be used to demonstrate that the 348 MAC matches the hashed content, in this case the JWS Secured Input, 349 which therefore demonstrates that whoever generated the MAC was in 350 possession of the secret. The means of exchanging the shared key is 351 outside the scope of this specification. 353 The algorithm for implementing and validating HMACs is provided in 354 RFC 2104 [RFC2104]. This section defines the use of the HMAC SHA- 355 256, HMAC SHA-384, and HMAC SHA-512 functions [SHS]. The "alg" 356 (algorithm) header parameter values "HS256", "HS384", and "HS512" are 357 used in the JWS Header to indicate that the Encoded JWS Signature 358 contains a base64url encoded HMAC value using the respective hash 359 function. 361 A key of the same size as the hash output (for instance, 256 bits for 362 "HS256") or larger MUST be used with this algorithm. 364 The HMAC SHA-256 MAC is generated per RFC 2104, using SHA-256 as the 365 hash algorithm "H", using the bytes of the ASCII [USASCII] 366 representation of the JWS Secured Input as the "text" value, and 367 using the shared key. The HMAC output value is the JWS Signature. 368 The JWS signature is base64url encoded to produce the Encoded JWS 369 Signature. 371 The HMAC SHA-256 MAC for a JWS is validated by computing an HMAC 372 value per RFC 2104, using SHA-256 as the hash algorithm "H", using 373 the bytes of the ASCII representation of the received JWS Secured 374 input as the "text" value, and using the shared key. This computed 375 HMAC value is then compared to the result of base64url decoding the 376 received Encoded JWS signature. Alternatively, the computed HMAC 377 value can be base64url encoded and compared to the received Encoded 378 JWS Signature, as this comparison produces the same result as 379 comparing the unencoded values. In either case, if the values match, 380 the HMAC has been validated. If the validation fails, the JWS MUST 381 be rejected. 383 Securing content with the HMAC SHA-384 and HMAC SHA-512 algorithms is 384 performed identically to the procedure for HMAC SHA-256 - just using 385 the corresponding hash algorithm with correspondingly larger minimum 386 key sizes and result values: 384 bits each for HMAC SHA-384 and 512 387 bits each for HMAC SHA-512. 389 An example using this algorithm is shown in Appendix A.1 of [JWS]. 391 3.3. Digital Signature with RSA SHA-256, RSA SHA-384, or RSA SHA-512 393 This section defines the use of the RSASSA-PKCS1-V1_5 digital 394 signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447], 395 (commonly known as PKCS #1), using SHA-256, SHA-384, or SHA-512 [SHS] 396 as the hash functions. The "alg" (algorithm) header parameter values 397 "RS256", "RS384", and "RS512" are used in the JWS Header to indicate 398 that the Encoded JWS Signature contains a base64url encoded RSA 399 digital signature using the respective hash function. 401 A key of size 2048 bits or larger MUST be used with these algorithms. 403 The RSA SHA-256 digital signature is generated as follows: 405 1. Generate a digital signature of the bytes of the ASCII 406 representation of the JWS Secured Input using RSASSA-PKCS1-V1_5- 407 SIGN and the SHA-256 hash function with the desired private key. 408 The output will be a byte array. 410 2. Base64url encode the resulting byte array. 412 The output is the Encoded JWS Signature for that JWS. 414 The RSA SHA-256 digital signature for a JWS is validated as follows: 416 1. Take the Encoded JWS Signature and base64url decode it into a 417 byte array. If decoding fails, the JWS MUST be rejected. 419 2. Submit the bytes of the ASCII representation of the JWS Secured 420 Input and the public key corresponding to the private key used by 421 the signer to the RSASSA-PKCS1-V1_5-VERIFY algorithm using SHA- 422 256 as the hash function. 424 3. If the validation fails, the JWS MUST be rejected. 426 Signing with the RSA SHA-384 and RSA SHA-512 algorithms is performed 427 identically to the procedure for RSA SHA-256 - just using the 428 corresponding hash algorithm with correspondingly larger result 429 values: 384 bits for RSA SHA-384 and 512 bits for RSA SHA-512. 431 An example using this algorithm is shown in Appendix A.2 of [JWS]. 433 3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA P-384 SHA-384, 434 or ECDSA P-521 SHA-512 436 The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides 437 for the use of Elliptic Curve cryptography, which is able to provide 438 equivalent security to RSA cryptography but using shorter key sizes 439 and with greater processing speed. This means that ECDSA digital 440 signatures will be substantially smaller in terms of length than 441 equivalently strong RSA digital signatures. 443 This specification defines the use of ECDSA with the P-256 curve and 444 the SHA-256 cryptographic hash function, ECDSA with the P-384 curve 445 and the SHA-384 hash function, and ECDSA with the P-521 curve and the 446 SHA-512 hash function. The P-256, P-384, and P-521 curves are 447 defined in [DSS]. The "alg" (algorithm) header parameter values 448 "ES256", "ES384", and "ES512" are used in the JWS Header to indicate 449 that the Encoded JWS Signature contains a base64url encoded ECDSA 450 P-256 SHA-256, ECDSA P-384 SHA-384, or ECDSA P-521 SHA-512 digital 451 signature, respectively. 453 The ECDSA P-256 SHA-256 digital signature is generated as follows: 455 1. Generate a digital signature of the bytes of the ASCII 456 representation of the JWS Secured Input using ECDSA P-256 SHA-256 457 with the desired private key. The output will be the pair (R, 458 S), where R and S are 256 bit unsigned integers. 460 2. Turn R and S into byte arrays in big endian order, with each 461 array being be 32 bytes long. The array representations MUST not 462 be shortened to omit any leading zero bytes contained in the 463 values. 465 3. Concatenate the two byte arrays in the order R and then S. (Note 466 that many ECDSA implementations will directly produce this 467 concatenation as their output.) 469 4. Base64url encode the resulting 64 byte array. 471 The output is the Encoded JWS Signature for the JWS. 473 The ECDSA P-256 SHA-256 digital signature for a JWS is validated as 474 follows: 476 1. Take the Encoded JWS Signature and base64url decode it into a 477 byte array. If decoding fails, the JWS MUST be rejected. 479 2. The output of the base64url decoding MUST be a 64 byte array. If 480 decoding does not result in a 64 byte array, the JWS MUST be 481 rejected. 483 3. Split the 64 byte array into two 32 byte arrays. The first array 484 will be R and the second S (with both being in big endian byte 485 order). 487 4. Submit the bytes of the ASCII representation of the JWS Secured 488 Input R, S and the public key (x, y) to the ECDSA P-256 SHA-256 489 validator. 491 5. If the validation fails, the JWS MUST be rejected. 493 Note that ECDSA digital signature contains a value referred to as K, 494 which is a random number generated for each digital signature 495 instance. This means that two ECDSA digital signatures using exactly 496 the same input parameters will output different signature values 497 because their K values will be different. A consequence of this is 498 that one cannot validate an ECDSA signature by recomputing the 499 signature and comparing the results. 501 Signing with the ECDSA P-384 SHA-384 and ECDSA P-521 SHA-512 502 algorithms is performed identically to the procedure for ECDSA P-256 503 SHA-256 - just using the corresponding hash algorithm with 504 correspondingly larger result values. For ECDSA P-384 SHA-384, R and 505 S will be 384 bits each, resulting in a 96 byte array. For ECDSA 506 P-521 SHA-512, R and S will be 521 bits each, resulting in a 132 byte 507 array. 509 Examples using these algorithms are shown in Appendices A.3 and A.4 510 of [JWS]. 512 3.5. Using the Algorithm "none" 514 JWSs MAY also be created that do not provide integrity protection. 515 Such a JWS is called a "Plaintext JWS". Plaintext JWSs MUST use the 516 "alg" value "none", and are formatted identically to other JWSs, but 517 with the empty string for its JWS Signature value. 519 3.6. Additional Digital Signature/MAC Algorithms and Parameters 521 Additional algorithms MAY be used to protect JWSs with corresponding 522 "alg" (algorithm) header parameter values being defined to refer to 523 them. New "alg" header parameter values SHOULD either be registered 524 in the IANA JSON Web Signature and Encryption Algorithms registry 525 Section 6.1 or be a value that contains a Collision Resistant 526 Namespace. In particular, it is permissible to use the algorithm 527 identifiers defined in XML DSIG [RFC3275], XML DSIG 2.0 528 [W3C.CR-xmldsig-core2-20120124], and related specifications as "alg" 529 values. 531 As indicated by the common registry, JWSs and JWEs share a common 532 "alg" value space. The values used by the two specifications MUST be 533 distinct, as the "alg" value MAY be used to determine whether the 534 object is a JWS or JWE. 536 Likewise, additional reserved Header Parameter Names MAY be defined 537 via the IANA JSON Web Signature and Encryption Header Parameters 538 registry [JWS]. As indicated by the common registry, JWSs and JWEs 539 share a common header parameter space; when a parameter is used by 540 both specifications, its usage must be compatible between the 541 specifications. 543 4. Cryptographic Algorithms for JWE 545 JWE uses cryptographic algorithms to encrypt the Content Master Key 546 (CMK) and the Plaintext. This section specifies a set of specific 547 algorithms for these purposes. 549 4.1. "alg" (Algorithm) Header Parameter Values for JWE 551 The table below is the set of "alg" (algorithm) header parameter 552 values that are defined by this specification for use with JWE. 553 These algorithms are used to encrypt the CMK, producing the JWE 554 Encrypted Key, or to use key agreement to agree upon the CMK. 556 +----------------+---------------------------------+----------------+ 557 | alg Parameter | Key Encryption or Agreement | Implementation | 558 | Value | Algorithm | Requirements | 559 +----------------+---------------------------------+----------------+ 560 | RSA1_5 | RSAES-PKCS1-V1_5 [RFC3447] | REQUIRED | 561 | RSA-OAEP | RSAES using Optimal Asymmetric | OPTIONAL | 562 | | Encryption Padding (OAEP) | | 563 | | [RFC3447], with the default | | 564 | | parameters specified by RFC | | 565 | | 3447 in Section A.2.1 | | 566 | A128KW | Advanced Encryption Standard | RECOMMENDED | 567 | | (AES) Key Wrap Algorithm | | 568 | | [RFC3394] using 128 bit keys | | 569 | A256KW | AES Key Wrap Algorithm using | RECOMMENDED | 570 | | 256 bit keys | | 571 | dir | Direct use of a shared | RECOMMENDED | 572 | | symmetric key as the Content | | 573 | | Master Key (CMK) for the block | | 574 | | encryption step (rather than | | 575 | | using the symmetric key to wrap | | 576 | | the CMK) | | 577 | ECDH-ES | Elliptic Curve Diffie-Hellman | RECOMMENDED+ | 578 | | Ephemeral Static [RFC6090] key | | 579 | | agreement using the Concat KDF, | | 580 | | as defined in Section 5.8.1 of | | 581 | | [NIST.800-56A], with the | | 582 | | agreed-upon key being used | | 583 | | directly as the Content Master | | 584 | | Key (CMK) (rather than being | | 585 | | used to wrap the CMK), as | | 586 | | specified in Section 4.7 | | 587 | ECDH-ES+A128KW | Elliptic Curve Diffie-Hellman | RECOMMENDED | 588 | | Ephemeral Static key agreement | | 589 | | per "ECDH-ES" and Section 4.7, | | 590 | | but where the agreed-upon key | | 591 | | is used to wrap the Content | | 592 | | Master Key (CMK) with the | | 593 | | "A128KW" function (rather than | | 594 | | being used directly as the CMK) | | 595 | ECDH-ES+A256KW | Elliptic Curve Diffie-Hellman | RECOMMENDED | 596 | | Ephemeral Static key agreement | | 597 | | per "ECDH-ES" and Section 4.7, | | 598 | | but where the agreed-upon key | | 599 | | is used to wrap the Content | | 600 | | Master Key (CMK) with the | | 601 | | "A256KW" function (rather than | | 602 | | being used directly as the CMK) | | 603 +----------------+---------------------------------+----------------+ 605 The use of "+" in the Implementation Requirements indicates that the 606 requirement strength is likely to be increased in a future version of 607 the specification. 609 4.2. "enc" (Encryption Method) Header Parameter Values for JWE 611 The table below is the set of "enc" (encryption method) header 612 parameter values that are defined by this specification for use with 613 JWE. These algorithms are used to encrypt the Plaintext, which 614 produces the Ciphertext. 616 +---------------+----------------------------------+----------------+ 617 | enc Parameter | Block Encryption Algorithm | Implementation | 618 | Value | | Requirements | 619 +---------------+----------------------------------+----------------+ 620 | A128CBC+HS256 | Composite Authenticated | REQUIRED | 621 | | Encryption algorithm using | | 622 | | Advanced Encryption Standard | | 623 | | (AES) in Cipher Block Chaining | | 624 | | (CBC) mode with PKCS #5 padding | | 625 | | [AES] [NIST.800-38A] with an | | 626 | | integrity calculation using HMAC | | 627 | | SHA-256, using a 256 bit CMK | | 628 | | (and 128 bit CEK) as specified | | 629 | | in Section 4.8 | | 630 | A256CBC+HS512 | Composite Authenticated | REQUIRED | 631 | | Encryption algorithm using AES | | 632 | | in CBC mode with PKCS #5 padding | | 633 | | with an integrity calculation | | 634 | | using HMAC SHA-512, using a 512 | | 635 | | bit CMK (and 256 bit CEK) as | | 636 | | specified in Section 4.8 | | 637 | A128GCM | AES in Galois/Counter Mode (GCM) | RECOMMENDED | 638 | | [AES] [NIST.800-38D] using 128 | | 639 | | bit keys | | 640 | A256GCM | AES GCM using 256 bit keys | RECOMMENDED | 641 +---------------+----------------------------------+----------------+ 643 All the names are short because a core goal of JWE is for the 644 representations to be compact. However, there is no a priori length 645 restriction on "alg" values. 647 See Appendix B for a table cross-referencing the encryption "alg" 648 (algorithm) and "enc" (encryption method) values used in this 649 specification with the equivalent identifiers used by other standards 650 and software packages. 652 4.3. Key Encryption with RSAES-PKCS1-V1_5 654 This section defines the specifics of encrypting a JWE CMK with 655 RSAES-PKCS1-V1_5 [RFC3447]. The "alg" header parameter value 656 "RSA1_5" is used in this case. 658 A key of size 2048 bits or larger MUST be used with this algorithm. 660 An example using this algorithm is shown in Appendix A.2 of [JWE]. 662 4.4. Key Encryption with RSAES OAEP 664 This section defines the specifics of encrypting a JWE CMK with RSAES 665 using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447], with 666 the default parameters specified by RFC 3447 in Section A.2.1. The 667 "alg" header parameter value "RSA-OAEP" is used in this case. 669 A key of size 2048 bits or larger MUST be used with this algorithm. 671 An example using this algorithm is shown in Appendix A.1 of [JWE]. 673 4.5. Key Encryption with AES Key Wrap 675 This section defines the specifics of encrypting a JWE CMK with the 676 Advanced Encryption Standard (AES) Key Wrap Algorithm [RFC3394] using 677 128 or 256 bit keys. The "alg" header parameter values "A128KW" or 678 "A256KW" are used in this case. 680 An example using this algorithm is shown in Appendix A.3 of [JWE]. 682 4.6. Direct Encryption with a Shared Symmetric Key 684 This section defines the specifics of directly performing symmetric 685 key encryption without performing a key wrapping step. In this case, 686 the shared symmetric key is used directly as the Content Master Key 687 (CMK) value for the "enc" algorithm. An empty byte array is used as 688 the JWE Encrypted Key value. The "alg" header parameter value "dir" 689 is used in this case. 691 4.7. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static 692 (ECDH-ES) 694 This section defines the specifics of key agreement with Elliptic 695 Curve Diffie-Hellman Ephemeral Static [RFC6090], and using the Concat 696 KDF, as defined in Section 5.8.1 of [NIST.800-56A]. The key 697 agreement result can be used in one of two ways: (1) directly as the 698 Content Master Key (CMK) for the "enc" algorithm, or (2) as a 699 symmetric key used to wrap the CMK with either the "A128KW" or 700 "A256KW" algorithms. The "alg" header parameter values "ECDH-ES", 701 "ECDH-ES+A128KW", and "ECDH-ES+A256KW" are respectively used in this 702 case. 704 In the direct case, the output of the Concat KDF MUST be a key of the 705 same length as that used by the "enc" algorithm; in this case, the 706 empty byte array is used as the JWE Encrypted Key value. In the key 707 wrap case, the output of the Concat KDF MUST be a key of the length 708 needed for the specified key wrap algorithm, either 128 or 256 bits 709 respectively. 711 A new "epk" (ephemeral public key) value MUST be generated for each 712 key agreement transaction. 714 4.7.1. Key Derivation for "ECDH-ES" 716 The key derivation process derives the agreed upon key from the 717 shared secret Z established through the ECDH algorithm, per Section 718 6.2.2.2 of [NIST.800-56A]. 720 Key derivation is performed using the Concat KDF, as defined in 721 Section 5.8.1 of [NIST.800-56A], where the Digest Method is SHA-256. 722 The Concat KDF parameters are set as follows: 724 Z This is set to the representation of the shared secret Z as a byte 725 array. 727 keydatalen This is set to the number of bits in the desired output 728 key. For "ECDH-ES", this is length of the key used by the "enc" 729 algorithm. For "ECDH-ES+A128KW", and "ECDH-ES+A256KW", this is 730 128 and 256, respectively. 732 AlgorithmID This is set to the concatenation of keydatalen 733 represented as a 32 bit big endian integer and the bytes of the 734 UTF-8 representation of the "alg" header parameter value. 736 PartyUInfo The PartyUInfo value is of the form Datalen || Data, 737 where Data is a variable-length string of zero or more bytes, and 738 Datalen is a fixed-length, big endian 32 bit counter that 739 indicates the length (in bytes) of Data, with || being 740 concatenation. If an "apu" (agreement PartyUInfo) header 741 parameter is present, Data is set to the result of base64url 742 decoding the "apu" value and Datalen is set to the number of bytes 743 in Data. Otherwise, Datalen is set to 0 and Data is set to the 744 empty byte string. 746 PartyVInfo The PartyVInfo value is of the form Datalen || Data, 747 where Data is a variable-length string of zero or more bytes, and 748 Datalen is a fixed-length, big endian 32 bit counter that 749 indicates the length (in bytes) of Data, with || being 750 concatenation. If an "apv" (agreement PartyVInfo) header 751 parameter is present, Data is set to the result of base64url 752 decoding the "apv" value and Datalen is set to the number of bytes 753 in Data. Otherwise, Datalen is set to 0 and Data is set to the 754 empty byte string. 756 SuppPubInfo This is set to the empty byte string. 758 SuppPrivInfo This is set to the empty byte string. 760 4.8. Composite Plaintext Encryption Algorithms "A128CBC+HS256" and 761 "A256CBC+HS512" 763 This section defines two composite "enc" algorithms that perform 764 plaintext encryption using non-Authenticated Encryption algorithms 765 and add an integrity check calculation, so that the resulting 766 composite algorithms perform Authenticated Encryption. These 767 composite algorithms derive a Content Encryption Key (CEK) and a 768 Content Integrity Key (CIK) from a Content Master Key, per 769 Section 4.8.1. They perform block encryption with AES CBC, per 770 Section 4.8.2. Finally, they add an integrity check using HMAC SHA-2 771 algorithms of matching strength, per Section 4.8.3. 773 A 256 bit Content Master Key (CMK) value is used with the 774 "A128CBC+HS256" algorithm. A 512 bit Content Master Key (CMK) value 775 is used with the "A256CBC+HS512" algorithm. 777 An example using this algorithm is shown in Appendix A.2 of [JWE]. 779 4.8.1. Key Derivation for "A128CBC+HS256" and "A256CBC+HS512" 781 The key derivation process derives CEK and CIK values from the CMK. 782 This section defines the specifics of deriving keys for the "enc" 783 algorithms "A128CBC+HS256" and "A256CBC+HS512". 785 Key derivation is performed using the Concat KDF, as defined in 786 Section 5.8.1 of [NIST.800-56A], where the Digest Method is SHA-256 787 or SHA-512, respectively. The Concat KDF parameters are set as 788 follows: 790 Z This is set to the Content Master Key (CMK). 792 keydatalen This is set to the number of bits in the desired output 793 key. 795 AlgorithmID This is set to the concatenation of keydatalen 796 represented as a 32 bit big endian integer and the bytes of the 797 UTF-8 representation of the "enc" header parameter value. 799 PartyUInfo The PartyUInfo value is of the form Datalen || Data, 800 where Data is a variable-length string of zero or more bytes, and 801 Datalen is a fixed-length, big endian 32 bit counter that 802 indicates the length (in bytes) of Data, with || being 803 concatenation. If an "epu" (encryption PartyUInfo) header 804 parameter is present, Data is set to the result of base64url 805 decoding the "epu" value and Datalen is set to the number of bytes 806 in Data. Otherwise, Datalen is set to 0 and Data is set to the 807 empty byte string. 809 PartyVInfo The PartyVInfo value is of the form Datalen || Data, 810 where Data is a variable-length string of zero or more bytes, and 811 Datalen is a fixed-length, big endian 32 bit counter that 812 indicates the length (in bytes) of Data, with || being 813 concatenation. If an "epv" (encryption PartyVInfo) header 814 parameter is present, Data is set to the result of base64url 815 decoding the "epv" value and Datalen is set to the number of bytes 816 in Data. Otherwise, Datalen is set to 0 and Data is set to the 817 empty byte string. 819 SuppPubInfo This is set to the bytes of one of the ASCII strings 820 "Encryption" ([69, 110, 99, 114, 121, 112, 116, 105, 111, 110]) or 821 "Integrity" ([73, 110, 116, 101, 103, 114, 105, 116, 121]) 822 respectively, depending upon whether the CEK or CIK is being 823 generated. 825 SuppPrivInfo This is set to the empty byte string. 827 To compute the CEK from the CMK, the ASCII label "Encryption" is used 828 for the SuppPubInfo value. For "A128CBC+HS256", the keydatalen is 829 128 and the digest function used is SHA-256. For "A256CBC+HS512", 830 the keydatalen is 256 and the digest function used is SHA-512. 832 To compute the CIK from the CMK, the ASCII label "Integrity" is used 833 for the SuppPubInfo value. For "A128CBC+HS256", the keydatalen is 834 256 and the digest function used is SHA-256. For "A256CBC+HS512", 835 the keydatalen is 512 and the digest function used is SHA-512. 837 Example derivation computations are shown in Appendices A.4 and A.5 838 of [JWE]. 840 4.8.2. Encryption Calculation for "A128CBC+HS256" and "A256CBC+HS512" 842 This section defines the specifics of encrypting the JWE Plaintext 843 with Advanced Encryption Standard (AES) in Cipher Block Chaining 844 (CBC) mode with PKCS #5 padding [AES] [NIST.800-38A] using 128 or 256 845 bit keys. The "enc" header parameter values "A128CBC+HS256" or 846 "A256CBC+HS512" are respectively used in this case. 848 The CEK is used as the encryption key. 850 Use of an initialization vector of size 128 bits is REQUIRED with 851 these algorithms. 853 4.8.3. Integrity Calculation for "A128CBC+HS256" and "A256CBC+HS512" 855 This section defines the specifics of computing the JWE Integrity 856 Value for the "enc" algorithms "A128CBC+HS256" and "A256CBC+HS512". 857 This value is computed as a MAC of the JWE parameters to be secured. 859 The MAC input value is the bytes of the ASCII representation of the 860 concatenation of the Encoded JWE Header, a period ('.') character, 861 the Encoded JWE Encrypted Key, a second period character ('.'), the 862 Encoded JWE Initialization Vector, a third period ('.') character, 863 and the Encoded JWE Ciphertext. (Equivalently, this input value is 864 the concatenation of the "additional authenticated data" value, a 865 byte containing an ASCII period character, and the bytes of the ASCII 866 representation of the Encoded JWE Ciphertext.) 867 The CIK is used as the MAC key. 869 For "A128CBC+HS256", HMAC SHA-256 is used as the MAC algorithm. For 870 "A256CBC+HS512", HMAC SHA-512 is used as the MAC algorithm. 872 The resulting MAC value is used as the JWE Integrity Value. 873 (Equivalently, this value is the "authentication tag" output for the 874 algorithm.) The same integrity calculation is performed during 875 decryption. During decryption, the computed integrity value must 876 match the received JWE Integrity Value. 878 4.9. Plaintext Encryption with AES GCM 880 This section defines the specifics of encrypting the JWE Plaintext 881 with Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) 882 [AES] [NIST.800-38D] using 128 or 256 bit keys. The "enc" header 883 parameter values "A128GCM" or "A256GCM" are used in this case. 885 The CMK is used as the encryption key. 887 Use of an initialization vector of size 96 bits is REQUIRED with this 888 algorithm. 890 The "additional authenticated data" parameter is used to secure the 891 header and key values. (The "additional authenticated data" value 892 used is the bytes of the ASCII representation of the concatenation of 893 the Encoded JWE Header, a period ('.') character, the Encoded JWE 894 Encrypted Key, a second period character ('.'), and the Encoded JWE 895 Initialization Vector, per Section 5 of the JWE specification.) This 896 same "additional authenticated data" value is used when decrypting as 897 well. 899 The requested size of the "authentication tag" output MUST be 128 900 bits, regardless of the key size. 902 The JWE Integrity Value is set to be the "authentication tag" value 903 produced by the encryption. During decryption, the received JWE 904 Integrity Value is used as the "authentication tag" value. 906 Examples using this algorithm are shown in Appendices A.1 and A.3 of 907 [JWE]. 909 4.10. Additional Encryption Algorithms and Parameters 911 Additional algorithms MAY be used to protect JWEs with corresponding 912 "alg" (algorithm) and "enc" (encryption method) header parameter 913 values being defined to refer to them. New "alg" and "enc" header 914 parameter values SHOULD either be registered in the IANA JSON Web 915 Signature and Encryption Algorithms registry Section 6.1 or be a 916 value that contains a Collision Resistant Namespace. In particular, 917 it is permissible to use the algorithm identifiers defined in XML 918 Encryption [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 919 [W3C.CR-xmlenc-core1-20120313], and related specifications as "alg" 920 and "enc" values. 922 As indicated by the common registry, JWSs and JWEs share a common 923 "alg" value space. The values used by the two specifications MUST be 924 distinct, as the "alg" value MAY be used to determine whether the 925 object is a JWS or JWE. 927 Likewise, additional reserved Header Parameter Names MAY be defined 928 via the IANA JSON Web Signature and Encryption Header Parameters 929 registry [JWS]. As indicated by the common registry, JWSs and JWEs 930 share a common header parameter space; when a parameter is used by 931 both specifications, its usage must be compatible between the 932 specifications. 934 5. Cryptographic Algorithms for JWK 936 A JSON Web Key (JWK) [JWK] is a JavaScript Object Notation (JSON) 937 [RFC4627] data structure that represents a public key. A JSON Web 938 Key Set (JWK Set) is a JSON data structure for representing a set of 939 JWKs. This section specifies a set of key types to be used for those 940 public keys and the key type specific parameters for representing 941 those keys. 943 5.1. "kty" (Key Type) Parameter Values for JWK 945 The table below is the set of "kty" (key type) parameter values that 946 are defined by this specification for use in JWKs. 948 +-----------------+------------------------+------------------------+ 949 | kty Parameter | Key Type | Implementation | 950 | Value | | Requirements | 951 +-----------------+------------------------+------------------------+ 952 | EC | Elliptic Curve [DSS] | RECOMMENDED+ | 953 | | key type | | 954 | RSA | RSA [RFC3447] key type | REQUIRED | 955 +-----------------+------------------------+------------------------+ 957 All the names are short because a core goal of JWK is for the 958 representations to be compact. However, there is no a priori length 959 restriction on "kty" values. 961 The use of "+" in the Implementation Requirements indicates that the 962 requirement strength is likely to be increased in a future version of 963 the specification. 965 5.2. JWK Parameters for Elliptic Curve Keys 967 JWKs can represent Elliptic Curve [DSS] keys. In this case, the 968 "kty" member value MUST be "EC". Furthermore, these additional 969 members MUST be present: 971 5.2.1. "crv" (Curve) Parameter 973 The "crv" (curve) member identifies the cryptographic curve used with 974 the key. Curve values from [DSS] used by this specification are: 976 o "P-256" 978 o "P-384" 980 o "P-521" 982 Additional "crv" values MAY be used, provided they are understood by 983 implementations using that Elliptic Curve key. The "crv" value is a 984 case sensitive string. 986 5.2.2. "x" (X Coordinate) Parameter 988 The "x" (x coordinate) member contains the x coordinate for the 989 elliptic curve point. It is represented as the base64url encoding of 990 the coordinate's big endian representation as a byte array. The 991 array representation MUST not be shortened to omit any leading zero 992 bytes contained in the value. For instance, when representing 521 993 bit integers, the byte array to be base64url encoded MUST contain 66 994 bytes, including any leading zero bytes. 996 5.2.3. "y" (Y Coordinate) Parameter 998 The "y" (y coordinate) member contains the y coordinate for the 999 elliptic curve point. It is represented as the base64url encoding of 1000 the coordinate's big endian representation as a byte array. The 1001 array representation MUST not be shortened to omit any leading zero 1002 bytes contained in the value. For instance, when representing 521 1003 bit integers, the byte array to be base64url encoded MUST contain 66 1004 bytes, including any leading zero bytes. 1006 5.3. JWK Parameters for RSA Keys 1008 JWKs can represent RSA [RFC3447] keys. In this case, the "kty" 1009 member value MUST be "RSA". Furthermore, these additional members 1010 MUST be present: 1012 5.3.1. "n" (Modulus) Parameter 1014 The "n" (modulus) member contains the modulus value for the RSA 1015 public key. It is represented as the base64url encoding of the 1016 value's unsigned big endian representation as a byte array. The 1017 array representation MUST not be shortened to omit any leading zero 1018 bytes. For instance, when representing 2048 bit integers, the byte 1019 array to be base64url encoded MUST contain 256 bytes, including any 1020 leading zero bytes. 1022 5.3.2. "e" (Exponent) Parameter 1024 The "e" (exponent) member contains the exponent value for the RSA 1025 public key. It is represented as the base64url encoding of the 1026 value's unsigned big endian representation as a byte array. The 1027 array representation MUST utilize the minimum number of bytes to 1028 represent the value. For instance, when representing the value 1029 65537, the byte array to be base64url encoded MUST consist of the 1030 three bytes [1, 0, 1]. 1032 5.4. Additional Key Types and Parameters 1034 Public keys using additional key types MAY be represented using JWK 1035 data structures with corresponding "kty" (key type) parameter values 1036 being defined to refer to them. New "kty" parameter values SHOULD 1037 either be registered in the IANA JSON Web Key Types registry 1038 Section 6.2 or be a value that contains a Collision Resistant 1039 Namespace. 1041 Likewise, parameters for representing keys for additional key types 1042 or additional key properties SHOULD either be registered in the IANA 1043 JSON Web Key Parameters registry [JWK] or be a value that contains a 1044 Collision Resistant Namespace. 1046 6. IANA Considerations 1048 The following registration procedure is used for all the registries 1049 established by this specification. 1051 Values are registered with a Specification Required [RFC5226] after a 1052 two-week review period on the [TBD]@ietf.org mailing list, on the 1053 advice of one or more Designated Experts. However, to allow for the 1054 allocation of values prior to publication, the Designated Expert(s) 1055 may approve registration once they are satisfied that such a 1056 specification will be published. 1058 Registration requests must be sent to the [TBD]@ietf.org mailing list 1059 for review and comment, with an appropriate subject (e.g., "Request 1060 for access token type: example"). [[ Note to RFC-EDITOR: The name of 1061 the mailing list should be determined in consultation with the IESG 1062 and IANA. Suggested name: jose-reg-review. ]] 1064 Within the review period, the Designated Expert(s) will either 1065 approve or deny the registration request, communicating this decision 1066 to the review list and IANA. Denials should include an explanation 1067 and, if applicable, suggestions as to how to make the request 1068 successful. 1070 IANA must only accept registry updates from the Designated Expert(s) 1071 and should direct all requests for registration to the review mailing 1072 list. 1074 6.1. JSON Web Signature and Encryption Algorithms Registry 1076 This specification establishes the IANA JSON Web Signature and 1077 Encryption Algorithms registry for values of the JWS and JWE "alg" 1078 (algorithm) and "enc" (encryption method) header parameters. The 1079 registry records the algorithm name, the algorithm usage locations 1080 from the set "alg" and "enc", implementation requirements, and a 1081 reference to the specification that defines it. The same algorithm 1082 name may be registered multiple times, provided that the sets of 1083 usage locations are disjoint. The implementation requirements of an 1084 algorithm may be changed over time by the Designated Experts(s) as 1085 the cryptographic landscape evolves, for instance, to change the 1086 status of an algorithm to DEPRECATED, or to change the status of an 1087 algorithm from OPTIONAL to RECOMMENDED or REQUIRED. 1089 6.1.1. Registration Template 1091 Algorithm Name: 1092 The name requested (e.g., "example"). This name is case 1093 sensitive. Names that match other registered names in a case 1094 insensitive manner SHOULD NOT be accepted. 1096 Algorithm Usage Location(s): 1097 The algorithm usage, which must be one or more of the values "alg" 1098 or "enc". 1100 Implementation Requirements: 1101 The algorithm implementation requirements, which must be one the 1102 words REQUIRED, RECOMMENDED, OPTIONAL, or DEPRECATED. Optionally, 1103 the word may be followed by a "+" or "-". The use of "+" 1104 indicates that the requirement strength is likely to be increased 1105 in a future version of the specification. The use of "-" 1106 indicates that the requirement strength is likely to be decreased 1107 in a future version of the specification. 1109 Change Controller: 1110 For Standards Track RFCs, state "IETF". For others, give the name 1111 of the responsible party. Other details (e.g., postal address, 1112 email address, home page URI) may also be included. 1114 Specification Document(s): 1115 Reference to the document(s) that specify the parameter, 1116 preferably including URI(s) that can be used to retrieve copies of 1117 the document(s). An indication of the relevant sections may also 1118 be included but is not required. 1120 6.1.2. Initial Registry Contents 1122 o Algorithm Name: "HS256" 1123 o Algorithm Usage Location(s): "alg" 1124 o Implementation Requirements: REQUIRED 1125 o Change Controller: IETF 1126 o Specification Document(s): Section 3.1 of [[ this document ]] 1128 o Algorithm Name: "HS384" 1129 o Algorithm Usage Location(s): "alg" 1130 o Implementation Requirements: OPTIONAL 1131 o Change Controller: IETF 1132 o Specification Document(s): Section 3.1 of [[ this document ]] 1134 o Algorithm Name: "HS512" 1135 o Algorithm Usage Location(s): "alg" 1136 o Implementation Requirements: OPTIONAL 1137 o Change Controller: IETF 1138 o Specification Document(s): Section 3.1 of [[ this document ]] 1140 o Algorithm Name: "RS256" 1141 o Algorithm Usage Location(s): "alg" 1142 o Implementation Requirements: RECOMMENDED 1143 o Change Controller: IETF 1144 o Specification Document(s): Section 3.1 of [[ this document ]] 1146 o Algorithm Name: "RS384" 1147 o Algorithm Usage Location(s): "alg" 1148 o Implementation Requirements: OPTIONAL 1149 o Change Controller: IETF 1150 o Specification Document(s): Section 3.1 of [[ this document ]] 1151 o Algorithm Name: "RS512" 1152 o Algorithm Usage Location(s): "alg" 1153 o Implementation Requirements: OPTIONAL 1154 o Change Controller: IETF 1155 o Specification Document(s): Section 3.1 of [[ this document ]] 1157 o Algorithm Name: "ES256" 1158 o Algorithm Usage Location(s): "alg" 1159 o Implementation Requirements: RECOMMENDED+ 1160 o Change Controller: IETF 1161 o Specification Document(s): Section 3.1 of [[ this document ]] 1163 o Algorithm Name: "ES384" 1164 o Algorithm Usage Location(s): "alg" 1165 o Implementation Requirements: OPTIONAL 1166 o Change Controller: IETF 1167 o Specification Document(s): Section 3.1 of [[ this document ]] 1169 o Algorithm Name: "ES512" 1170 o Algorithm Usage Location(s): "alg" 1171 o Implementation Requirements: OPTIONAL 1172 o Change Controller: IETF 1173 o Specification Document(s): Section 3.1 of [[ this document ]] 1175 o Algorithm Name: "none" 1176 o Algorithm Usage Location(s): "alg" 1177 o Implementation Requirements: REQUIRED 1178 o Change Controller: IETF 1179 o Specification Document(s): Section 3.1 of [[ this document ]] 1181 o Algorithm Name: "RSA1_5" 1182 o Algorithm Usage Location(s): "alg" 1183 o Implementation Requirements: REQUIRED 1184 o Change Controller: IETF 1185 o Specification Document(s): Section 4.1 of [[ this document ]] 1187 o Algorithm Name: "RSA-OAEP" 1188 o Algorithm Usage Location(s): "alg" 1189 o Implementation Requirements: OPTIONAL 1190 o Change Controller: IETF 1191 o Specification Document(s): Section 4.1 of [[ this document ]] 1193 o Algorithm Name: "A128KW" 1194 o Algorithm Usage Location(s): "alg" 1195 o Implementation Requirements: RECOMMENDED 1196 o Change Controller: IETF 1197 o Specification Document(s): Section 4.1 of [[ this document ]] 1199 o Algorithm Name: "A256KW" 1200 o Algorithm Usage Location(s): "alg" 1201 o Implementation Requirements: RECOMMENDED 1202 o Change Controller: IETF 1203 o Specification Document(s): Section 4.1 of [[ this document ]] 1205 o Algorithm Name: "dir" 1206 o Algorithm Usage Location(s): "alg" 1207 o Implementation Requirements: RECOMMENDED 1208 o Change Controller: IETF 1209 o Specification Document(s): Section 4.1 of [[ this document ]] 1211 o Algorithm Name: "ECDH-ES" 1212 o Algorithm Usage Location(s): "alg" 1213 o Implementation Requirements: RECOMMENDED+ 1214 o Change Controller: IETF 1215 o Specification Document(s): Section 4.1 of [[ this document ]] 1217 o Algorithm Name: "ECDH-ES+A128KW" 1218 o Algorithm Usage Location(s): "alg" 1219 o Implementation Requirements: RECOMMENDED 1220 o Change Controller: IETF 1221 o Specification Document(s): Section 4.1 of [[ this document ]] 1223 o Algorithm Name: "ECDH-ES+A256KW" 1224 o Algorithm Usage Location(s): "alg" 1225 o Implementation Requirements: RECOMMENDED 1226 o Change Controller: IETF 1227 o Specification Document(s): Section 4.1 of [[ this document ]] 1229 o Algorithm Name: "A128CBC+HS256" 1230 o Algorithm Usage Location(s): "enc" 1231 o Implementation Requirements: REQUIRED 1232 o Change Controller: IETF 1233 o Specification Document(s): Section 4.2 of [[ this document ]] 1235 o Algorithm Name: "A256CBC+HS512" 1236 o Algorithm Usage Location(s): "enc" 1237 o Implementation Requirements: REQUIRED 1238 o Change Controller: IETF 1239 o Specification Document(s): Section 4.2 of [[ this document ]] 1241 o Algorithm Name: "A128GCM" 1242 o Algorithm Usage Location(s): "enc" 1243 o Implementation Requirements: RECOMMENDED 1244 o Change Controller: IETF 1245 o Specification Document(s): Section 4.2 of [[ this document ]] 1247 o Algorithm Name: "A256GCM" 1248 o Algorithm Usage Location(s): "enc" 1249 o Implementation Requirements: RECOMMENDED 1250 o Change Controller: IETF 1251 o Specification Document(s): Section 4.2 of [[ this document ]] 1253 6.2. JSON Web Key Types Registry 1255 This specification establishes the IANA JSON Web Key Types registry 1256 for values of the JWK "kty" (key type) parameter. The registry 1257 records the "kty" value and a reference to the specification that 1258 defines it. This specification registers the values defined in 1259 Section 5.1. 1261 6.2.1. Registration Template 1263 "kty" Parameter Value: 1264 The name requested (e.g., "example"). This name is case 1265 sensitive. Names that match other registered names in a case 1266 insensitive manner SHOULD NOT be accepted. 1268 Change Controller: 1269 For Standards Track RFCs, state "IETF". For others, give the name 1270 of the responsible party. Other details (e.g., postal address, 1271 email address, home page URI) may also be included. 1273 Implementation Requirements: 1274 The algorithm implementation requirements, which must be one the 1275 words REQUIRED, RECOMMENDED, OPTIONAL, or DEPRECATED. Optionally, 1276 the word may be followed by a "+" or "-". The use of "+" 1277 indicates that the requirement strength is likely to be increased 1278 in a future version of the specification. The use of "-" 1279 indicates that the requirement strength is likely to be decreased 1280 in a future version of the specification. 1282 Specification Document(s): 1283 Reference to the document(s) that specify the parameter, 1284 preferably including URI(s) that can be used to retrieve copies of 1285 the document(s). An indication of the relevant sections may also 1286 be included but is not required. 1288 6.2.2. Initial Registry Contents 1290 o "kty" Parameter Value: "EC" 1291 o Implementation Requirements: RECOMMENDED+ 1292 o Change Controller: IETF 1293 o Specification Document(s): Section 5.1 of [[ this document ]] 1295 o "kty" Parameter Value: "RSA" 1296 o Implementation Requirements: REQUIRED 1297 o Change Controller: IETF 1298 o Specification Document(s): Section 5.1 of [[ this document ]] 1300 6.3. JSON Web Key Parameters Registration 1302 This specification registers the parameter names defined in Sections 1303 5.2 and 5.3 in the IANA JSON Web Key Parameters registry [JWK]. 1305 6.3.1. Registry Contents 1307 o Parameter Name: "crv" 1308 o Change Controller: IETF 1309 o Specification Document(s): Section 5.2.1 of [[ this document ]] 1311 o Parameter Name: "x" 1312 o Change Controller: IETF 1313 o Specification Document(s): Section 5.2.2 of [[ this document ]] 1315 o Parameter Name: "y" 1316 o Change Controller: IETF 1317 o Specification Document(s): Section 5.2.3 of [[ this document ]] 1319 o Parameter Name: "n" 1320 o Change Controller: IETF 1321 o Specification Document(s): Section 5.3.1 of [[ this document ]] 1323 o Parameter Name: "e" 1324 o Change Controller: IETF 1325 o Specification Document(s): Section 5.3.2 of [[ this document ]] 1327 7. Security Considerations 1329 All of the security issues faced by any cryptographic application 1330 must be faced by a JWS/JWE/JWK agent. Among these issues are 1331 protecting the user's private and symmetric keys, preventing various 1332 attacks, and helping the user avoid mistakes such as inadvertently 1333 encrypting a message for the wrong recipient. The entire list of 1334 security considerations is beyond the scope of this document, but 1335 some significant concerns are listed here. 1337 The security considerations in [AES], [DSS], [JWE], [JWK], [JWS], 1338 [NIST.800-38A], [NIST.800-38D], [NIST.800-56A], [RFC2104], [RFC3394], 1339 [RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this 1340 specification. 1342 Eventually the algorithms and/or key sizes currently described in 1343 this specification will no longer be considered sufficiently secure 1344 and will be removed. Therefore, implementers and deployments must be 1345 prepared for this eventuality. 1347 Algorithms of matching strength should be used together whenever 1348 possible. For instance, when AES Key Wrap is used with a given key 1349 size, using the same key size is recommended when AES GCM is also 1350 used. 1352 While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not 1353 to adopt RSASSA-PKCS1 for new applications and instead requests that 1354 people transition to RSASSA-PSS, this specification does include 1355 RSASSA-PKCS1, for interoperability reasons, because it commonly 1356 implemented. 1358 Keys used with RSAES-PKCS1-v1_5 must follow the constraints in 1359 Section 7.2 of RFC 3447 [RFC3447]. In particular, keys with a low 1360 public key exponent value must not be used. 1362 Plaintext JWSs (JWSs that use the "alg" value "none") provide no 1363 integrity protection. Thus, they must only be used in contexts where 1364 the payload is secured by means other than a digital signature or MAC 1365 value, or need not be secured. 1367 Receiving agents that validate signatures and sending agents that 1368 encrypt messages need to be cautious of cryptographic processing 1369 usage when validating signatures and encrypting messages using keys 1370 larger than those mandated in this specification. An attacker could 1371 send certificates with keys that would result in excessive 1372 cryptographic processing, for example, keys larger than those 1373 mandated in this specification, which could swamp the processing 1374 element. Agents that use such keys without first validating the 1375 certificate to a trust anchor are advised to have some sort of 1376 cryptographic resource management system to prevent such attacks. 1378 8. References 1379 8.1. Normative References 1381 [AES] National Institute of Standards and Technology (NIST), 1382 "Advanced Encryption Standard (AES)", FIPS PUB 197, 1383 November 2001. 1385 [DSS] National Institute of Standards and Technology, "Digital 1386 Signature Standard (DSS)", FIPS PUB 186-3, June 2009. 1388 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 1389 Encryption (JWE)", draft-ietf-jose-json-web-encryption 1390 (work in progress), December 2012. 1392 [JWK] Jones, M., "JSON Web Key (JWK)", 1393 draft-ietf-jose-json-web-key (work in progress), 1394 December 2012. 1396 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1397 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1398 in progress), December 2012. 1400 [NIST.800-38A] 1401 National Institute of Standards and Technology (NIST), 1402 "Recommendation for Block Cipher Modes of Operation", 1403 NIST PUB 800-38A, December 2001. 1405 [NIST.800-38D] 1406 National Institute of Standards and Technology (NIST), 1407 "Recommendation for Block Cipher Modes of Operation: 1408 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 1409 December 2001. 1411 [NIST.800-56A] 1412 National Institute of Standards and Technology (NIST), 1413 "Recommendation for Pair-Wise Key Establishment Schemes 1414 Using Discrete Logarithm Cryptography (Revised)", NIST PUB 1415 800-56A, March 2007. 1417 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1418 Hashing for Message Authentication", RFC 2104, 1419 February 1997. 1421 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1422 Requirement Levels", BCP 14, RFC 2119, March 1997. 1424 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 1425 (AES) Key Wrap Algorithm", RFC 3394, September 2002. 1427 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1428 Standards (PKCS) #1: RSA Cryptography Specifications 1429 Version 2.1", RFC 3447, February 2003. 1431 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1432 10646", STD 63, RFC 3629, November 2003. 1434 [RFC4627] Crockford, D., "The application/json Media Type for 1435 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1437 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1438 Encodings", RFC 4648, October 2006. 1440 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 1441 Encryption", RFC 5116, January 2008. 1443 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1444 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1445 May 2008. 1447 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 1448 Curve Cryptography Algorithms", RFC 6090, February 2011. 1450 [SHS] National Institute of Standards and Technology, "Secure 1451 Hash Standard (SHS)", FIPS PUB 180-3, October 2008. 1453 [USASCII] American National Standards Institute, "Coded Character 1454 Set -- 7-bit American Standard Code for Information 1455 Interchange", ANSI X3.4, 1986. 1457 8.2. Informative References 1459 [CanvasApp] 1460 Facebook, "Canvas Applications", 2010. 1462 [I-D.rescorla-jsms] 1463 Rescorla, E. and J. Hildebrand, "JavaScript Message 1464 Security Format", draft-rescorla-jsms-00 (work in 1465 progress), March 2011. 1467 [JCA] Oracle, "Java Cryptography Architecture", 2011. 1469 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1470 Encryption", September 2010. 1472 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 1473 September 2010. 1475 [MagicSignatures] 1476 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 1477 Signatures", January 2011. 1479 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 1480 Language) XML-Signature Syntax and Processing", RFC 3275, 1481 March 2002. 1483 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1484 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1485 July 2005. 1487 [W3C.CR-xmldsig-core2-20120124] 1488 Yiu, K., Solo, D., Eastlake, D., Datta, P., Hirsch, F., 1489 Reagle, J., Cantor, S., and T. Roessler, "XML Signature 1490 Syntax and Processing Version 2.0", World Wide Web 1491 Consortium CR CR-xmldsig-core2-20120124, January 2012, 1492 . 1494 [W3C.CR-xmlenc-core1-20120313] 1495 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 1496 "XML Encryption Syntax and Processing Version 1.1", World 1497 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1498 March 2012, 1499 . 1501 [W3C.REC-xmlenc-core-20021210] 1502 Eastlake, D. and J. Reagle, "XML Encryption Syntax and 1503 Processing", World Wide Web Consortium Recommendation REC- 1504 xmlenc-core-20021210, December 2002, 1505 . 1507 Appendix A. Digital Signature/MAC Algorithm Identifier Cross-Reference 1509 This appendix contains a table cross-referencing the digital 1510 signature and MAC "alg" (algorithm) values used in this specification 1511 with the equivalent identifiers used by other standards and software 1512 packages. See XML DSIG [RFC3275], XML DSIG 2.0 1513 [W3C.CR-xmldsig-core2-20120124], and Java Cryptography Architecture 1514 [JCA] for more information about the names defined by those 1515 documents. 1517 +-------+-----+----------------------------+----------+-------------+ 1518 | Algor | JWS | XML DSIG | JCA | OID | 1519 | ithm | | | | | 1520 +-------+-----+----------------------------+----------+-------------+ 1521 | HMAC | HS2 | http://www.w3.org/2001/04/ | HmacSHA2 | 1.2.840.113 | 1522 | using | 56 | xmldsig-more#hmac-sha256 | 56 | 549.2.9 | 1523 | SHA-2 | | | | | 1524 | 56 | | | | | 1525 | hash | | | | | 1526 | algo | | | | | 1527 | rithm | | | | | 1528 | HMAC | HS3 | http://www.w3.org/2001/04/ | HmacSHA3 | 1.2.840.113 | 1529 | using | 84 | xmldsig-more#hmac-sha384 | 84 | 549.2.10 | 1530 | SHA-3 | | | | | 1531 | 84 | | | | | 1532 | hash | | | | | 1533 | algo | | | | | 1534 | rithm | | | | | 1535 | HMAC | HS5 | http://www.w3.org/2001/04/ | HmacSHA5 | 1.2.840.113 | 1536 | using | 12 | xmldsig-more#hmac-sha512 | 12 | 549.2.11 | 1537 | SHA-5 | | | | | 1538 | 12 | | | | | 1539 | hash | | | | | 1540 | algo | | | | | 1541 | rithm | | | | | 1542 | RSASS | RS2 | http://www.w3.org/2001/04/ | SHA256wi | 1.2.840.113 | 1543 | A | 56 | xmldsig-more#rsa-sha256 | thRSA | 549.1.1.11 | 1544 | usin | | | | | 1545 | gSHA- | | | | | 1546 | 256 | | | | | 1547 | has | | | | | 1548 | h alg | | | | | 1549 | orith | | | | | 1550 | m | | | | | 1551 | RSASS | RS3 | http://www.w3.org/2001/04/ | SHA384wi | 1.2.840.113 | 1552 | A | 84 | xmldsig-more#rsa-sha384 | thRSA | 549.1.1.12 | 1553 | usin | | | | | 1554 | gSHA- | | | | | 1555 | 384 | | | | | 1556 | has | | | | | 1557 | h alg | | | | | 1558 | orith | | | | | 1559 | m | | | | | 1560 | RSASS | RS5 | http://www.w3.org/2001/04/ | SHA512wi | 1.2.840.113 | 1561 | A | 12 | xmldsig-more#rsa-sha512 | thRSA | 549.1.1.13 | 1562 | usin | | | | | 1563 | gSHA- | | | | | 1564 | 512 | | | | | 1565 | has | | | | | 1566 | h alg | | | | | 1567 | orith | | | | | 1568 | m | | | | | 1569 | ECDSA | ES2 | http://www.w3.org/2001/04/ | SHA256wi | 1.2.840.100 | 1570 | using | 56 | xmldsig-more#ecdsa-sha256 | thECDSA | 45.4.3.2 | 1571 | P-256 | | | | | 1572 | curve | | | | | 1573 | and | | | | | 1574 | SHA-2 | | | | | 1575 | 56 | | | | | 1576 | hash | | | | | 1577 | algo | | | | | 1578 | rithm | | | | | 1579 | ECDSA | ES3 | http://www.w3.org/2001/04/ | SHA384wi | 1.2.840.100 | 1580 | using | 84 | xmldsig-more#ecdsa-sha384 | thECDSA | 45.4.3.3 | 1581 | P-384 | | | | | 1582 | curve | | | | | 1583 | and | | | | | 1584 | SHA-3 | | | | | 1585 | 84 | | | | | 1586 | hash | | | | | 1587 | algo | | | | | 1588 | rithm | | | | | 1589 | ECDSA | ES5 | http://www.w3.org/2001/04/ | SHA512wi | 1.2.840.100 | 1590 | using | 12 | xmldsig-more#ecdsa-sha512 | thECDSA | 45.4.3.4 | 1591 | P-521 | | | | | 1592 | curve | | | | | 1593 | and | | | | | 1594 | SHA-5 | | | | | 1595 | 12 | | | | | 1596 | hash | | | | | 1597 | algo | | | | | 1598 | rithm | | | | | 1599 +-------+-----+----------------------------+----------+-------------+ 1601 Appendix B. Encryption Algorithm Identifier Cross-Reference 1603 This appendix contains a table cross-referencing the "alg" 1604 (algorithm) and "enc" (encryption method) values used in this 1605 specification with the equivalent identifiers used by other standards 1606 and software packages. See XML Encryption 1608 [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 1609 [W3C.CR-xmlenc-core1-20120313], and Java Cryptography Architecture 1610 [JCA] for more information about the names defined by those 1611 documents. 1613 For the composite algorithms "A128CBC+HS256" and "A256CBC+HS512", the 1614 corresponding AES CBC algorithm identifiers are listed. 1616 +----------+--------+--------------------------+--------------------+ 1617 | Algorith | JWE | XML ENC | JCA | 1618 | m | | | | 1619 +----------+--------+--------------------------+--------------------+ 1620 | RSAES-PK | RSA1_5 | http://www.w3.org/2001/0 | RSA/ECB/PKCS1Paddi | 1621 | CS1-V1_5 | | 4/xmlenc#rsa-1_5 | ng | 1622 | RSAES | RSA-OA | http://www.w3.org/2001/0 | RSA/ECB/OAEPWithSH | 1623 | using | EP | 4/xmlenc#rsa-oaep-mgf1p | A-1AndMGF1Padding | 1624 | Optimal | | | | 1625 | Asymmetr | | | | 1626 | ic | | | | 1627 | Encrypt | | | | 1628 | ion | | | | 1629 | Paddin | | | | 1630 | g (OAEP) | | | | 1631 | Elliptic | ECDH-E | http://www.w3.org/2009/x | | 1632 | Curve | S | mlenc11#ECDH-ES | | 1633 | Diffie-H | | | | 1634 | ellman | | | | 1635 | Ephemer | | | | 1636 | alStatic | | | | 1637 | Advanced | A128KW | http://www.w3.org/2001/0 | | 1638 | Encrypti | | 4/xmlenc#kw-aes128 | | 1639 | on | | | | 1640 | Standar | | | | 1641 | d(AES) | | | | 1642 | Key Wra | | | | 1643 | pAlgorit | | | | 1644 | hmusing | | | | 1645 | 128 bi | | | | 1646 | t keys | | | | 1647 | AES Key | A256KW | http://www.w3.org/2001/0 | | 1648 | Wrap | | 4/xmlenc#kw-aes256 | | 1649 | Algorith | | | | 1650 | musing | | | | 1651 | 256 bit | | | | 1652 | keys | | | | 1653 | AES in | A128CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 1654 | Cipher | C+HS25 | 4/xmlenc#aes128-cbc | ng | 1655 | Block | 6 | | | 1656 | Chaining | | | | 1657 | (CBC) | | | | 1658 | mode | | | | 1659 | with | | | | 1660 | PKCS #5 | | | | 1661 | padding | | | | 1662 | using | | | | 1663 | 128 bit | | | | 1664 | keys | | | | 1665 | AES in | A256CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 1666 | CBC mode | C+HS51 | 4/xmlenc#aes256-cbc | ng | 1667 | with | 2 | | | 1668 | PKCS #5 | | | | 1669 | padding | | | | 1670 | using | | | | 1671 | 256 bit | | | | 1672 | keys | | | | 1673 | AES in | A128GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 1674 | Galois/C | M | mlenc11#aes128-gcm | | 1675 | ounter | | | | 1676 | Mode | | | | 1677 | (GCM) | | | | 1678 | using | | | | 1679 | 128 bit | | | | 1680 | keys | | | | 1681 | AES GCM | A256GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 1682 | using | M | mlenc11#aes256-gcm | | 1683 | 256 bit | | | | 1684 | keys | | | | 1685 +----------+--------+--------------------------+--------------------+ 1687 Appendix C. Acknowledgements 1689 Solutions for signing and encrypting JSON content were previously 1690 explored by Magic Signatures [MagicSignatures], JSON Simple Sign 1691 [JSS], Canvas Applications [CanvasApp], JSON Simple Encryption [JSE], 1692 and JavaScript Message Security Format [I-D.rescorla-jsms], all of 1693 which influenced this draft. 1695 This specification is the work of the JOSE Working Group, which 1696 includes dozens of active and dedicated participants. In particular, 1697 the following individuals contributed ideas, feedback, and wording 1698 that influenced this specification: 1700 Dirk Balfanz, Richard Barnes, John Bradley, Brian Campbell, Breno de 1701 Medeiros, Yaron Y. Goland, Dick Hardt, Jeff Hodges, Edmund Jay, James 1702 Manger, Tony Nadalin, Axel Nennker, John Panzer, Emmanuel Raviart, 1703 Nat Sakimura, Jim Schaad, Hannes Tschofenig, and Sean Turner. 1705 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 1706 Sean Turner and Stephen Farrell served as Security area directors 1707 during the creation of this specification. 1709 Appendix D. Open Issues 1711 [[ to be removed by the RFC editor before publication as an RFC ]] 1713 The following items remain to be considered or done in this draft: 1715 o No known open issues. 1717 Appendix E. Document History 1719 [[ to be removed by the RFC editor before publication as an RFC ]] 1721 -08 1723 o Changed the name of the JWK key type parameter from "alg" to 1724 "kty". 1726 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 1727 since the term AEAD in the RFC 5116 sense implied the use of a 1728 particular data representation, rather than just referring to the 1729 class of algorithms that perform authenticated encryption with 1730 associated data. 1732 o Applied editorial improvements suggested by Jeff Hodges. Many of 1733 these simplified the terminology used. 1735 o Added seriesInfo information to Internet Draft references. 1737 -07 1739 o Added a data length prefix to PartyUInfo and PartyVInfo values. 1741 o Changed the name of the JWK RSA modulus parameter from "mod" to 1742 "n" and the name of the JWK RSA exponent parameter from "xpo" to 1743 "e", so that the identifiers are the same as those used in RFC 1744 3447. 1746 o Made several local editorial changes to clean up loose ends left 1747 over from to the decision to only support block encryption methods 1748 providing integrity. 1750 -06 1752 o Removed the "int" and "kdf" parameters and defined the new 1753 composite Authenticated Encryption algorithms "A128CBC+HS256" and 1754 "A256CBC+HS512" to replace the former uses of AES CBC, which 1755 required the use of separate integrity and key derivation 1756 functions. 1758 o Included additional values in the Concat KDF calculation -- the 1759 desired output size and the algorithm value, and optionally 1760 PartyUInfo and PartyVInfo values. Added the optional header 1761 parameters "apu" (agreement PartyUInfo), "apv" (agreement 1762 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 1763 PartyVInfo). 1765 o Changed the name of the JWK RSA exponent parameter from "exp" to 1766 "xpo" so as to allow the potential use of the name "exp" for a 1767 future extension that might define an expiration parameter for 1768 keys. (The "exp" name is already used for this purpose in the JWT 1769 specification.) 1771 o Applied changes made by the RFC Editor to RFC 6749's registry 1772 language to this specification. 1774 -05 1776 o Support both direct encryption using a shared or agreed upon 1777 symmetric key, and the use of a shared or agreed upon symmetric 1778 key to key wrap the CMK. Specifically, added the "alg" values 1779 "dir", "ECDH-ES+A128KW", and "ECDH-ES+A256KW" to finish filling in 1780 this set of capabilities. 1782 o Updated open issues. 1784 -04 1786 o Added text requiring that any leading zero bytes be retained in 1787 base64url encoded key value representations for fixed-length 1788 values. 1790 o Added this language to Registration Templates: "This name is case 1791 sensitive. Names that match other registered names in a case 1792 insensitive manner SHOULD NOT be accepted." 1794 o Described additional open issues. 1796 o Applied editorial suggestions. 1798 -03 1800 o Always use a 128 bit "authentication tag" size for AES GCM, 1801 regardless of the key size. 1803 o Specified that use of a 128 bit IV is REQUIRED with AES CBC. It 1804 was previously RECOMMENDED. 1806 o Removed key size language for ECDSA algorithms, since the key size 1807 is implied by the algorithm being used. 1809 o Stated that the "int" key size must be the same as the hash output 1810 size (and not larger, as was previously allowed) so that its size 1811 is defined for key generation purposes. 1813 o Added the "kdf" (key derivation function) header parameter to 1814 provide crypto agility for key derivation. The default KDF 1815 remains the Concat KDF with the SHA-256 digest function. 1817 o Clarified that the "mod" and "exp" values are unsigned. 1819 o Added Implementation Requirements columns to algorithm tables and 1820 Implementation Requirements entries to algorithm registries. 1822 o Changed AES Key Wrap to RECOMMENDED. 1824 o Moved registries JSON Web Signature and Encryption Header 1825 Parameters and JSON Web Signature and Encryption Type Values to 1826 the JWS specification. 1828 o Moved JSON Web Key Parameters registry to the JWK specification. 1830 o Changed registration requirements from RFC Required to 1831 Specification Required with Expert Review. 1833 o Added Registration Template sections for defined registries. 1835 o Added Registry Contents sections to populate registry values. 1837 o No longer say "the UTF-8 representation of the JWS Secured Input 1838 (which is the same as the ASCII representation)". Just call it 1839 "the ASCII representation of the JWS Secured Input". 1841 o Added "Collision Resistant Namespace" to the terminology section. 1843 o Numerous editorial improvements. 1845 -02 1847 o For AES GCM, use the "additional authenticated data" parameter to 1848 provide integrity for the header, encrypted key, and ciphertext 1849 and use the resulting "authentication tag" value as the JWE 1850 Integrity Value. 1852 o Defined minimum required key sizes for algorithms without 1853 specified key sizes. 1855 o Defined KDF output key sizes. 1857 o Specified the use of PKCS #5 padding with AES CBC. 1859 o Generalized text to allow key agreement to be employed as an 1860 alternative to key wrapping or key encryption. 1862 o Clarified that ECDH-ES is a key agreement algorithm. 1864 o Required implementation of AES-128-KW and AES-256-KW. 1866 o Removed the use of "A128GCM" and "A256GCM" for key wrapping. 1868 o Removed "A512KW" since it turns out that it's not a standard 1869 algorithm. 1871 o Clarified the relationship between "typ" header parameter values 1872 and MIME types. 1874 o Generalized language to refer to Message Authentication Codes 1875 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 1876 unless in a context specific to HMAC algorithms. 1878 o Established registries: JSON Web Signature and Encryption Header 1879 Parameters, JSON Web Signature and Encryption Algorithms, JSON Web 1880 Signature and Encryption "typ" Values, JSON Web Key Parameters, 1881 and JSON Web Key Algorithm Families. 1883 o Moved algorithm-specific definitions from JWK to JWA. 1885 o Reformatted to give each member definition its own section 1886 heading. 1888 -01 1889 o Moved definition of "alg":"none" for JWSs here from the JWT 1890 specification since this functionality is likely to be useful in 1891 more contexts that just for JWTs. 1893 o Added Advanced Encryption Standard (AES) Key Wrap Algorithm using 1894 512 bit keys ("A512KW"). 1896 o Added text "Alternatively, the Encoded JWS Signature MAY be 1897 base64url decoded to produce the JWS Signature and this value can 1898 be compared with the computed HMAC value, as this comparison 1899 produces the same result as comparing the encoded values". 1901 o Corrected the Magic Signatures reference. 1903 o Made other editorial improvements suggested by JOSE working group 1904 participants. 1906 -00 1908 o Created the initial IETF draft based upon 1909 draft-jones-json-web-signature-04 and 1910 draft-jones-json-web-encryption-02 with no normative changes. 1912 o Changed terminology to no longer call both digital signatures and 1913 HMACs "signatures". 1915 Author's Address 1917 Michael B. Jones 1918 Microsoft 1920 Email: mbj@microsoft.com 1921 URI: http://self-issued.info/