idnits 2.17.1 draft-ietf-jose-json-web-algorithms-04.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 4 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 "mod" (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 (July 16, 2012) is 4273 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: '1' on line 875 -- Looks like a reference, but probably isn't: '0' on line 875 -- Possible downref: Non-RFC (?) normative reference: ref. 'AES' -- Possible downref: Non-RFC (?) normative reference: ref. 'DSS' -- Possible downref: Non-RFC (?) normative reference: ref. 'JWE' -- Possible downref: Non-RFC (?) normative reference: ref. 'JWK' -- Possible downref: Non-RFC (?) normative reference: ref. 'JWS' ** 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 (~~), 6 warnings (==), 10 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 16, 2012 5 Expires: January 17, 2013 7 JSON Web Algorithms (JWA) 8 draft-ietf-jose-json-web-algorithms-04 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 17, 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 . . . . . . 6 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" . . . . . . . . . . . . . . . . 11 66 3.6. Additional Digital Signature/MAC Algorithms and 67 Parameters . . . . . . . . . . . . . . . . . . . . . . . . 12 68 4. Cryptographic Algorithms for JWE . . . . . . . . . . . . . . . 12 69 4.1. "alg" (Algorithm) Header Parameter Values for JWE . . . . 12 70 4.2. "enc" (Encryption Method) Header Parameter Values for 71 JWE . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 72 4.3. "int" (Integrity Algorithm) Header Parameter Values 73 for JWE . . . . . . . . . . . . . . . . . . . . . . . . . 14 74 4.4. "kdf" (Key Derivation Function) Header Parameter 75 Values for JWE . . . . . . . . . . . . . . . . . . . . . . 14 76 4.5. Key Encryption with RSAES-PKCS1-V1_5 . . . . . . . . . . . 15 77 4.6. Key Encryption with RSAES OAEP . . . . . . . . . . . . . . 15 78 4.7. Key Agreement with Elliptic Curve Diffie-Hellman 79 Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 15 80 4.8. Key Encryption with AES Key Wrap . . . . . . . . . . . . . 15 81 4.9. Plaintext Encryption with AES CBC Mode . . . . . . . . . . 15 82 4.10. Plaintext Encryption with AES GCM . . . . . . . . . . . . 16 83 4.11. Integrity Calculation with HMAC SHA-256, HMAC SHA-384, 84 or HMAC SHA-512 . . . . . . . . . . . . . . . . . . . . . 16 85 4.12. Key Derivation with Concat KDF and SHA-256, SHA-384, 86 or SHA-512 . . . . . . . . . . . . . . . . . . . . . . . . 16 87 4.13. Additional Encryption Algorithms and Parameters . . . . . 17 88 5. Cryptographic Algorithms for JWK . . . . . . . . . . . . . . . 18 89 5.1. "alg" (Algorithm Family) Parameter Values for JWK . . . . 18 90 5.2. JWK Parameters for Elliptic Curve Keys . . . . . . . . . . 18 91 5.2.1. "crv" (Curve) Parameter . . . . . . . . . . . . . . . 18 92 5.2.2. "x" (X Coordinate) Parameter . . . . . . . . . . . . . 19 93 5.2.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . . . 19 94 5.3. JWK Parameters for RSA Keys . . . . . . . . . . . . . . . 19 95 5.3.1. "mod" (Modulus) Parameter . . . . . . . . . . . . . . 19 96 5.3.2. "exp" (Exponent) Parameter . . . . . . . . . . . . . . 20 98 5.4. Additional Key Algorithm Families and Parameters . . . . . 20 99 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 100 6.1. JSON Web Signature and Encryption Algorithms Registry . . 21 101 6.1.1. Registration Template . . . . . . . . . . . . . . . . 21 102 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 22 103 6.2. JSON Web Key Algorithm Families Registry . . . . . . . . . 26 104 6.2.1. Registration Template . . . . . . . . . . . . . . . . 27 105 6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 27 106 6.3. JSON Web Key Parameters Registration . . . . . . . . . . . 28 107 6.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 28 108 7. Security Considerations . . . . . . . . . . . . . . . . . . . 28 109 8. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 29 110 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 111 9.1. Normative References . . . . . . . . . . . . . . . . . . . 30 112 9.2. Informative References . . . . . . . . . . . . . . . . . . 32 113 Appendix A. Digital Signature/MAC Algorithm Identifier 114 Cross-Reference . . . . . . . . . . . . . . . . . . . 33 115 Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 35 116 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 37 117 Appendix D. Document History . . . . . . . . . . . . . . . . . . 38 118 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 40 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 algorithm families. 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 cryptographically securing 151 a JWS Header and a JWS Payload with a JWS Signature value. 153 JWS Header A string representing a JavaScript Object Notation (JSON) 154 [RFC4627] object that describes the digital signature or MAC 155 operation applied to create the JWS Signature value. 157 JWS Payload The bytes to be secured - a.k.a., the message. The 158 payload can contain an arbitrary sequence of bytes. 160 JWS Signature A byte array containing the cryptographic material 161 that secures the contents of the JWS Header and the JWS Payload. 163 Base64url Encoding The URL- and filename-safe Base64 encoding 164 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 165 safe) '=' padding characters omitted, as permitted by Section 3.2. 166 (See Appendix C of [JWS] for notes on implementing base64url 167 encoding without padding.) 169 Encoded JWS Header Base64url encoding of the bytes of the UTF-8 170 [RFC3629] representation of the JWS Header. 172 Encoded JWS Payload Base64url encoding of the JWS Payload. 174 Encoded JWS Signature Base64url encoding of the JWS Signature. 176 JWS Secured Input The concatenation of the Encoded JWS Header, a 177 period ('.') character, and the Encoded JWS Payload. 179 Collision Resistant Namespace A namespace that allows names to be 180 allocated in a manner such that they are highly unlikely to 181 collide with other names. For instance, collision resistance can 182 be achieved through administrative delegation of portions of the 183 namespace or through use of collision-resistant name allocation 184 functions. Examples of Collision Resistant Namespaces include: 185 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 186 X.660 and X.670 Recommendation series, and Universally Unique 187 IDentifiers (UUIDs) [RFC4122]. When using an administratively 188 delegated namespace, the definer of a name needs to take 189 reasonable precautions to ensure they are in control of the 190 portion of the namespace they use to define the name. 192 2.2. Terms Incorporated from the JWE Specification 194 These terms defined by the JSON Web Encryption (JWE) [JWE] 195 specification are incorporated into this specification: 197 JSON Web Encryption (JWE) A data structure representing an encrypted 198 version of a Plaintext. The structure consists of four parts: the 199 JWE Header, the JWE Encrypted Key, the JWE Ciphertext, and the JWE 200 Integrity Value. 202 Plaintext The bytes to be encrypted - a.k.a., the message. The 203 plaintext can contain an arbitrary sequence of bytes. 205 Ciphertext The encrypted version of the Plaintext. 207 Content Encryption Key (CEK) A symmetric key used to encrypt the 208 Plaintext for the recipient to produce the Ciphertext. 210 Content Integrity Key (CIK) A key used with a MAC function to ensure 211 the integrity of the Ciphertext and the parameters used to create 212 it. 214 Content Master Key (CMK) A key from which the CEK and CIK are 215 derived. When key wrapping or key encryption are employed, the 216 CMK is randomly generated and encrypted to the recipient as the 217 JWE Encrypted Key. When key agreement is employed, the CMK is the 218 result of the key agreement algorithm. 220 JWE Header A string representing a JSON object that describes the 221 encryption operations applied to create the JWE Encrypted Key, the 222 JWE Ciphertext, and the JWE Integrity Value. 224 JWE Encrypted Key When key wrapping or key encryption are employed, 225 the Content Master Key (CMK) is encrypted with the intended 226 recipient's key and the resulting encrypted content is recorded as 227 a byte array, which is referred to as the JWE Encrypted Key. 228 Otherwise, when key agreement is employed, the JWE Encrypted Key 229 is the empty byte array. 231 JWE Ciphertext A byte array containing the Ciphertext. 233 JWE Integrity Value A byte array containing a MAC value that ensures 234 the integrity of the Ciphertext and the parameters used to create 235 it. 237 Encoded JWE Header Base64url encoding of the bytes of the UTF-8 238 [RFC3629] representation of the JWE Header. 240 Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted 241 Key. 243 Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. 245 Encoded JWE Integrity Value Base64url encoding of the JWE Integrity 246 Value. 248 AEAD Algorithm An Authenticated Encryption with Associated Data 249 (AEAD) [RFC5116] encryption algorithm is one that provides an 250 integrated content integrity check. AES Galois/Counter Mode (GCM) 251 is one such algorithm. 253 2.3. Terms Incorporated from the JWK Specification 255 These terms defined by the JSON Web Key (JWK) [JWK] specification are 256 incorporated into this specification: 258 JSON Web Key (JWK) A JSON data structure that represents a public 259 key. 261 JSON Web Key Set (JWK Set) A JSON object that contains an array of 262 JWKs as a member. 264 2.4. Defined Terms 266 These terms are defined for use by this specification: 268 Header Parameter Name The name of a member of the JSON object 269 representing a JWS Header or JWE Header. 271 Header Parameter Value The value of a member of the JSON object 272 representing a JWS Header or JWE Header. 274 3. Cryptographic Algorithms for JWS 276 JWS uses cryptographic algorithms to digitally sign or create a 277 Message Authentication Codes (MAC) of the contents of the JWS Header 278 and the JWS Payload. The use of the following algorithms for 279 producing JWSs is defined in this section. 281 3.1. "alg" (Algorithm) Header Parameter Values for JWS 283 The table below is the set of "alg" (algorithm) header parameter 284 values defined by this specification for use with JWS, each of which 285 is explained in more detail in the following sections: 287 +--------------+--------------------------------+-------------------+ 288 | alg | Digital Signature or MAC | Implementation | 289 | Parameter | Algorithm | Requirements | 290 | Value | | | 291 +--------------+--------------------------------+-------------------+ 292 | HS256 | HMAC using SHA-256 hash | REQUIRED | 293 | | algorithm | | 294 | HS384 | HMAC using SHA-384 hash | OPTIONAL | 295 | | algorithm | | 296 | HS512 | HMAC using SHA-512 hash | OPTIONAL | 297 | | algorithm | | 298 | RS256 | RSASSA using SHA-256 hash | RECOMMENDED | 299 | | algorithm | | 300 | RS384 | RSASSA using SHA-384 hash | OPTIONAL | 301 | | algorithm | | 302 | RS512 | RSASSA using SHA-512 hash | OPTIONAL | 303 | | algorithm | | 304 | ES256 | ECDSA using P-256 curve and | RECOMMENDED+ | 305 | | SHA-256 hash algorithm | | 306 | ES384 | ECDSA using P-384 curve and | OPTIONAL | 307 | | SHA-384 hash algorithm | | 308 | ES512 | ECDSA using P-521 curve and | OPTIONAL | 309 | | SHA-512 hash algorithm | | 310 | none | No digital signature or MAC | REQUIRED | 311 | | value included | | 312 +--------------+--------------------------------+-------------------+ 314 All the names are short because a core goal of JWS is for the 315 representations to be compact. However, there is no a priori length 316 restriction on "alg" values. 318 The use of "+" in the Implementation Requirements indicates that the 319 requirement strength is likely to be increased in a future version of 320 the specification. 322 See Appendix A for a table cross-referencing the digital signature 323 and MAC "alg" (algorithm) values used in this specification with the 324 equivalent identifiers used by other standards and software packages. 326 3.2. MAC with HMAC SHA-256, HMAC SHA-384, or HMAC SHA-512 328 Hash-based Message Authentication Codes (HMACs) enable one to use a 329 secret plus a cryptographic hash function to generate a Message 330 Authentication Code (MAC). This can be used to demonstrate that the 331 MAC matches the hashed content, in this case the JWS Secured Input, 332 which therefore demonstrates that whoever generated the MAC was in 333 possession of the secret. The means of exchanging the shared key is 334 outside the scope of this specification. 336 The algorithm for implementing and validating HMACs is provided in 337 RFC 2104 [RFC2104]. This section defines the use of the HMAC SHA- 338 256, HMAC SHA-384, and HMAC SHA-512 functions [SHS]. The "alg" 339 (algorithm) header parameter values "HS256", "HS384", and "HS512" are 340 used in the JWS Header to indicate that the Encoded JWS Signature 341 contains a base64url encoded HMAC value using the respective hash 342 function. 344 A key of the same size as the hash output (for instance, 256 bits for 345 "HS256") or larger MUST be used with this algorithm. 347 The HMAC SHA-256 MAC is generated per RFC 2104, using SHA-256 as the 348 hash algorithm "H", using the bytes of the ASCII [USASCII] 349 representation of the JWS Secured Input as the "text" value, and 350 using the shared key. The HMAC output value is the JWS Signature. 351 The JWS signature is base64url encoded to produce the Encoded JWS 352 Signature. 354 The HMAC SHA-256 MAC for a JWS is validated by computing an HMAC 355 value per RFC 2104, using SHA-256 as the hash algorithm "H", using 356 the bytes of the ASCII representation of the received JWS Secured 357 input as the "text" value, and using the shared key. This computed 358 HMAC value is then compared to the result of base64url decoding the 359 received Encoded JWS signature. Alternatively, the computed HMAC 360 value can be base64url encoded and compared to the received Encoded 361 JWS Signature, as this comparison produces the same result as 362 comparing the unencoded values. In either case, if the values match, 363 the HMAC has been validated. If the validation fails, the JWS MUST 364 be rejected. 366 Securing content with the HMAC SHA-384 and HMAC SHA-512 algorithms is 367 performed identically to the procedure for HMAC SHA-256 - just using 368 the corresponding hash algorithm with correspondingly larger minimum 369 key sizes and result values: 384 bits each for HMAC SHA-384 and 512 370 bits each for HMAC SHA-512. 372 3.3. Digital Signature with RSA SHA-256, RSA SHA-384, or RSA SHA-512 374 This section defines the use of the RSASSA-PKCS1-V1_5 digital 375 signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447], 376 (commonly known as PKCS #1), using SHA-256, SHA-384, or SHA-512 [SHS] 377 as the hash functions. The "alg" (algorithm) header parameter values 378 "RS256", "RS384", and "RS512" are used in the JWS Header to indicate 379 that the Encoded JWS Signature contains a base64url encoded RSA 380 digital signature using the respective hash function. 382 A key of size 2048 bits or larger MUST be used with these algorithms. 384 The RSA SHA-256 digital signature is generated as follows: 386 1. Generate a digital signature of the bytes of the ASCII 387 representation of the JWS Secured Input using RSASSA-PKCS1-V1_5- 388 SIGN and the SHA-256 hash function with the desired private key. 389 The output will be a byte array. 391 2. Base64url encode the resulting byte array. 393 The output is the Encoded JWS Signature for that JWS. 395 The RSA SHA-256 digital signature for a JWS is validated as follows: 397 1. Take the Encoded JWS Signature and base64url decode it into a 398 byte array. If decoding fails, the JWS MUST be rejected. 400 2. Submit the bytes of the ASCII representation of the JWS Secured 401 Input and the public key corresponding to the private key used by 402 the signer to the RSASSA-PKCS1-V1_5-VERIFY algorithm using SHA- 403 256 as the hash function. 405 3. If the validation fails, the JWS MUST be rejected. 407 Signing with the RSA SHA-384 and RSA SHA-512 algorithms is performed 408 identically to the procedure for RSA SHA-256 - just using the 409 corresponding hash algorithm with correspondingly larger result 410 values: 384 bits for RSA SHA-384 and 512 bits for RSA SHA-512. 412 3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA P-384 SHA-384, 413 or ECDSA P-521 SHA-512 415 The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides 416 for the use of Elliptic Curve cryptography, which is able to provide 417 equivalent security to RSA cryptography but using shorter key sizes 418 and with greater processing speed. This means that ECDSA digital 419 signatures will be substantially smaller in terms of length than 420 equivalently strong RSA digital signatures. 422 This specification defines the use of ECDSA with the P-256 curve and 423 the SHA-256 cryptographic hash function, ECDSA with the P-384 curve 424 and the SHA-384 hash function, and ECDSA with the P-521 curve and the 425 SHA-512 hash function. The P-256, P-384, and P-521 curves are 426 defined in [DSS]. The "alg" (algorithm) header parameter values 427 "ES256", "ES384", and "ES512" are used in the JWS Header to indicate 428 that the Encoded JWS Signature contains a base64url encoded ECDSA 429 P-256 SHA-256, ECDSA P-384 SHA-384, or ECDSA P-521 SHA-512 digital 430 signature, respectively. 432 The ECDSA P-256 SHA-256 digital signature is generated as follows: 434 1. Generate a digital signature of the bytes of the ASCII 435 representation of the JWS Secured Input using ECDSA P-256 SHA-256 436 with the desired private key. The output will be the pair (R, 437 S), where R and S are 256 bit unsigned integers. 439 2. Turn R and S into byte arrays in big endian order, with each 440 array being be 32 bytes long. The array representations MUST not 441 be shortened to omit any leading zero bytes contained in the 442 values. 444 3. Concatenate the two byte arrays in the order R and then S. (Note 445 that many ECDSA implementations will directly produce this 446 concatenation as their output.) 448 4. Base64url encode the resulting 64 byte array. 450 The output is the Encoded JWS Signature for the JWS. 452 The ECDSA P-256 SHA-256 digital signature for a JWS is validated as 453 follows: 455 1. Take the Encoded JWS Signature and base64url decode it into a 456 byte array. If decoding fails, the JWS MUST be rejected. 458 2. The output of the base64url decoding MUST be a 64 byte array. If 459 decoding does not result in a 64 byte array, the JWS MUST be 460 rejected. 462 3. Split the 64 byte array into two 32 byte arrays. The first array 463 will be R and the second S (with both being in big endian byte 464 order). 466 4. Submit the bytes of the ASCII representation of the JWS Secured 467 Input R, S and the public key (x, y) to the ECDSA P-256 SHA-256 468 validator. 470 5. If the validation fails, the JWS MUST be rejected. 472 Note that ECDSA digital signature contains a value referred to as K, 473 which is a random number generated for each digital signature 474 instance. This means that two ECDSA digital signatures using exactly 475 the same input parameters will output different signature values 476 because their K values will be different. A consequence of this is 477 that one cannot validate an ECDSA signature by recomputing the 478 signature and comparing the results. 480 Signing with the ECDSA P-384 SHA-384 and ECDSA P-521 SHA-512 481 algorithms is performed identically to the procedure for ECDSA P-256 482 SHA-256 - just using the corresponding hash algorithm with 483 correspondingly larger result values. For ECDSA P-384 SHA-384, R and 484 S will be 384 bits each, resulting in a 96 byte array. For ECDSA 485 P-521 SHA-512, R and S will be 521 bits each, resulting in a 132 byte 486 array. 488 3.5. Using the Algorithm "none" 490 JWSs MAY also be created that do not provide integrity protection. 491 Such a JWS is called a "Plaintext JWS". Plaintext JWSs MUST use the 492 "alg" value "none", and are formatted identically to other JWSs, but 493 with an empty JWS Signature value. 495 3.6. Additional Digital Signature/MAC Algorithms and Parameters 497 Additional algorithms MAY be used to protect JWSs with corresponding 498 "alg" (algorithm) header parameter values being defined to refer to 499 them. New "alg" header parameter values SHOULD either be registered 500 in the IANA JSON Web Signature and Encryption Algorithms registry 501 Section 6.1 or be a URI that contains a Collision Resistant 502 Namespace. In particular, it is permissible to use the algorithm 503 identifiers defined in XML DSIG [RFC3275], XML DSIG 2.0 504 [W3C.CR-xmldsig-core2-20120124], and related specifications as "alg" 505 values. 507 As indicated by the common registry, JWSs and JWEs share a common 508 "alg" value space. The values used by the two specifications MUST be 509 distinct, as the "alg" value MAY be used to determine whether the 510 object is a JWS or JWE. 512 Likewise, additional reserved header parameter names MAY be defined 513 via the IANA JSON Web Signature and Encryption Header Parameters 514 registry [JWS]. As indicated by the common registry, JWSs and JWEs 515 share a common header parameter space; when a parameter is used by 516 both specifications, its usage must be compatible between the 517 specifications. 519 4. Cryptographic Algorithms for JWE 521 JWE uses cryptographic algorithms to encrypt the Content Master Key 522 (CMK) and the Plaintext. This section specifies a set of specific 523 algorithms for these purposes. 525 4.1. "alg" (Algorithm) Header Parameter Values for JWE 527 The table below is the set of "alg" (algorithm) header parameter 528 values that are defined by this specification for use with JWE. 529 These algorithms are used to encrypt the CMK, producing the JWE 530 Encrypted Key, or to use key agreement to agree upon the CMK. 532 +-----------+--------------------------------------+----------------+ 533 | alg | Key Encryption or Agreement | Implementation | 534 | Parameter | Algorithm | Requirements | 535 | Value | | | 536 +-----------+--------------------------------------+----------------+ 537 | RSA1_5 | RSAES-PKCS1-V1_5 [RFC3447] | REQUIRED | 538 | RSA-OAEP | RSAES using Optimal Asymmetric | OPTIONAL | 539 | | Encryption Padding (OAEP) [RFC3447], | | 540 | | with the default parameters | | 541 | | specified by RFC 3447 in Section | | 542 | | A.2.1 | | 543 | ECDH-ES | Elliptic Curve Diffie-Hellman | RECOMMENDED+ | 544 | | Ephemeral Static [RFC6090], and | | 545 | | using the Concat KDF, as defined in | | 546 | | Section 5.8.1 of [NIST.800-56A], | | 547 | | where the Digest Method is SHA-256 | | 548 | | and all OtherInfo parameters are the | | 549 | | empty bit string | | 550 | A128KW | Advanced Encryption Standard (AES) | RECOMMENDED | 551 | | Key Wrap Algorithm [RFC3394] using | | 552 | | 128 bit keys | | 553 | A256KW | AES Key Wrap Algorithm using 256 bit | RECOMMENDED | 554 | | keys | | 555 +-----------+--------------------------------------+----------------+ 557 The use of "+" in the Implementation Requirements indicates that the 558 requirement strength is likely to be increased in a future version of 559 the specification. 561 4.2. "enc" (Encryption Method) Header Parameter Values for JWE 563 The table below is the set of "enc" (encryption method) header 564 parameter values that are defined by this specification for use with 565 JWE. These algorithms are used to encrypt the Plaintext, which 566 produces the Ciphertext. 568 +-----------+--------------------------------------+----------------+ 569 | enc | Block Encryption Algorithm | Implementation | 570 | Parameter | | Requirements | 571 | Value | | | 572 +-----------+--------------------------------------+----------------+ 573 | A128CBC | Advanced Encryption Standard (AES) | REQUIRED | 574 | | in Cipher Block Chaining (CBC) mode | | 575 | | with PKCS #5 padding [AES] | | 576 | | [NIST.800-38A] using 128 bit keys | | 577 | A256CBC | AES in CBC mode with PKCS #5 padding | REQUIRED | 578 | | using 256 bit keys | | 579 | A128GCM | AES in Galois/Counter Mode (GCM) | RECOMMENDED | 580 | | [AES] [NIST.800-38D] using 128 bit | | 581 | | keys | | 582 | A256GCM | AES GCM using 256 bit keys | RECOMMENDED | 583 +-----------+--------------------------------------+----------------+ 585 All the names are short because a core goal of JWE is for the 586 representations to be compact. However, there is no a priori length 587 restriction on "alg" values. 589 See Appendix B for a table cross-referencing the encryption "alg" 590 (algorithm) and "enc" (encryption method) values used in this 591 specification with the equivalent identifiers used by other standards 592 and software packages. 594 4.3. "int" (Integrity Algorithm) Header Parameter Values for JWE 596 The table below is the set of "int" (integrity algorithm) header 597 parameter values defined by this specification for use with JWE. 598 Note that these are the HMAC SHA subset of the "alg" (algorithm) 599 header parameter values defined for use with JWS Section 3.1. 601 +-----------------+-------------------------+-----------------------+ 602 | int Parameter | Algorithm | Implementation | 603 | Value | | Requirements | 604 +-----------------+-------------------------+-----------------------+ 605 | HS256 | HMAC using SHA-256 hash | REQUIRED | 606 | | algorithm | | 607 | HS384 | HMAC using SHA-384 hash | OPTIONAL | 608 | | algorithm | | 609 | HS512 | HMAC using SHA-512 hash | OPTIONAL | 610 | | algorithm | | 611 +-----------------+-------------------------+-----------------------+ 613 4.4. "kdf" (Key Derivation Function) Header Parameter Values for JWE 615 The table below is the set of "kdf" (key derivation function) header 616 parameter values defined by this specification for use with JWE. 618 +-----------+--------------------------------------+----------------+ 619 | kdf | Algorithm | Implementation | 620 | Parameter | | Requirements | 621 | Value | | | 622 +-----------+--------------------------------------+----------------+ 623 | CS256 | Concat KDF, as defined in Section | REQUIRED | 624 | | 5.8.1 of [NIST.800-56A], with | | 625 | | parameters per Section 4.12, using | | 626 | | SHA-256 as the digest method | | 627 | CS384 | Concat KDF with parameters per | OPTIONAL | 628 | | Section 4.12, using SHA-384 as the | | 629 | | digest method | | 630 | CS512 | Concat KDF with parameters per | OPTIONAL | 631 | | Section 4.12, using SHA-512 as the | | 632 | | digest method | | 633 +-----------+--------------------------------------+----------------+ 635 4.5. Key Encryption with RSAES-PKCS1-V1_5 637 This section defines the specifics of encrypting a JWE CMK with 638 RSAES-PKCS1-V1_5 [RFC3447]. The "alg" header parameter value 639 "RSA1_5" is used in this case. 641 A key of size 2048 bits or larger MUST be used with this algorithm. 643 4.6. Key Encryption with RSAES OAEP 645 This section defines the specifics of encrypting a JWE CMK with RSAES 646 using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447], with 647 the default parameters specified by RFC 3447 in Section A.2.1. The 648 "alg" header parameter value "RSA-OAEP" is used in this case. 650 A key of size 2048 bits or larger MUST be used with this algorithm. 652 4.7. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static 653 (ECDH-ES) 655 This section defines the specifics of agreeing upon a JWE CMK with 656 Elliptic Curve Diffie-Hellman Ephemeral Static [RFC6090], and using 657 the Concat KDF, as defined in Section 5.8.1 of [NIST.800-56A], where 658 the Digest Method is SHA-256 and all OtherInfo parameters are the 659 empty bit string. The "alg" header parameter value "ECDH-ES" is used 660 in this case. 662 The output of the Concat KDF MUST be a key of the same length as that 663 used by the "enc" algorithm. 665 A new "epk" (ephemeral public key) value MUST be generated for each 666 key agreement transaction. 668 4.8. Key Encryption with AES Key Wrap 670 This section defines the specifics of encrypting a JWE CMK with the 671 Advanced Encryption Standard (AES) Key Wrap Algorithm [RFC3394] using 672 128 or 256 bit keys. The "alg" header parameter values "A128KW" or 673 "A256KW" are used in this case. 675 4.9. Plaintext Encryption with AES CBC Mode 677 This section defines the specifics of encrypting the JWE Plaintext 678 with Advanced Encryption Standard (AES) in Cipher Block Chaining 679 (CBC) mode with PKCS #5 padding [AES] [NIST.800-38A] using 128 or 256 680 bit keys. The "enc" header parameter values "A128CBC" or "A256CBC" 681 are used in this case. 683 Use of an initialization vector of size 128 bits is REQUIRED with 684 this algorithm. 686 4.10. Plaintext Encryption with AES GCM 688 This section defines the specifics of encrypting the JWE Plaintext 689 with Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) 690 [AES] [NIST.800-38D] using 128 or 256 bit keys. The "enc" header 691 parameter values "A128GCM" or "A256GCM" are used in this case. 693 Use of an initialization vector of size 96 bits is REQUIRED with this 694 algorithm. 696 The "additional authenticated data" parameter is used to secure the 697 header and key values, as specified for AEAD algorithms in Section 5 698 of [JWE]. 700 The requested size of the "authentication tag" output MUST be 128 701 bits, regardless of the key size. 703 As GCM is an AEAD algorithm, the JWE Integrity Value is set to be the 704 "authentication tag" value produced by the encryption. 706 4.11. Integrity Calculation with HMAC SHA-256, HMAC SHA-384, or HMAC 707 SHA-512 709 This section defines the specifics of computing a JWE Integrity Value 710 with HMAC SHA-256, HMAC SHA-384, or HMAC SHA-512 [SHS]. Other than 711 as stated below, these computations are performed identically to 712 those specified in Section 3.2. 714 A key of the same size as the hash output (for instance, 256 bits for 715 "HS256") MUST be used with this algorithm. 717 Per Section 9 of [JWE], the JWS Secured Input value used contains the 718 header, encrypted key, and ciphertext. 720 4.12. Key Derivation with Concat KDF and SHA-256, SHA-384, or SHA-512 722 The key derivation process derives CEK and CIK values from the CMK. 723 It uses as a primitive a Key Derivation Function (KDF) which 724 notionally takes three arguments: 726 MasterKey: The master key used to compute the individual use keys 727 Label: The use key label, used to differentiate individual use keys 729 Length: The desired length of the use key 731 This section defines the specifics of using the Concat KDF, as 732 defined in Section 5.8.1 of [NIST.800-56A], where the Digest Method 733 is one of SHA-256, SHA-384, or SHA-512, the SuppPubInfo parameter is 734 the Label, and the remaining OtherInfo parameters are the empty bit 735 string. 737 The "kdf" (key derivation function) header parameter values "CS256", 738 "CS384", and "CS512" are respectively used in the JWE Header to 739 indicate the use of the Concat KDF as above with the respective 740 digest methods. If the "kdf" header parameter is omitted when an 741 AEAD "enc" algorithm is not used, this is equivalent to specifying 742 use of the "CS256" key derivation function. 744 To compute the CEK from the CMK, the ASCII label "Encryption" ([69, 745 110, 99, 114, 121, 112, 116, 105, 111, 110]) is used. Use the key 746 size for the "enc" algorithm as the CEK desired key length. 748 To compute the CIK from the CMK, the ASCII label "Integrity" ([73, 749 110, 116, 101, 103, 114, 105, 116, 121]) is used. Use the minimum 750 key size for the "int" algorithm (for instance, 256 bits for "HS256") 751 as the CIK desired key length. 753 4.13. Additional Encryption Algorithms and Parameters 755 Additional algorithms MAY be used to protect JWEs with corresponding 756 "alg" (algorithm), "enc" (encryption method), and "int" (integrity 757 algorithm) header parameter values being defined to refer to them. 758 New "alg", "enc", and "int" header parameter values SHOULD either be 759 registered in the IANA JSON Web Signature and Encryption Algorithms 760 registry Section 6.1 or be a URI that contains a Collision Resistant 761 Namespace. In particular, it is permissible to use the algorithm 762 identifiers defined in XML Encryption [W3C.REC-xmlenc-core-20021210], 763 XML Encryption 1.1 [W3C.CR-xmlenc-core1-20120313], and related 764 specifications as "alg", "enc", and "int" values. 766 As indicated by the common registry, JWSs and JWEs share a common 767 "alg" value space. The values used by the two specifications MUST be 768 distinct, as the "alg" value MAY be used to determine whether the 769 object is a JWS or JWE. 771 Likewise, additional reserved header parameter names MAY be defined 772 via the IANA JSON Web Signature and Encryption Header Parameters 773 registry [JWS]. As indicated by the common registry, JWSs and JWEs 774 share a common header parameter space; when a parameter is used by 775 both specifications, its usage must be compatible between the 776 specifications. 778 5. Cryptographic Algorithms for JWK 780 A JSON Web Key (JWK) [JWK] is a JavaScript Object Notation (JSON) 781 [RFC4627] data structure that represents a public key. A JSON Web 782 Key Set (JWK Set) is a JSON data structure for representing a set of 783 JWKs. This section specifies a set of algorithm families to be used 784 for those public keys and the algorithm family specific parameters 785 for representing those keys. 787 5.1. "alg" (Algorithm Family) Parameter Values for JWK 789 The table below is the set of "alg" (algorithm family) parameter 790 values that are defined by this specification for use in JWKs. 792 +-----------------+-------------------------+-----------------------+ 793 | alg Parameter | Algorithm Family | Implementation | 794 | Value | | Requirements | 795 +-----------------+-------------------------+-----------------------+ 796 | EC | Elliptic Curve [DSS] | RECOMMENDED+ | 797 | | key family | | 798 | RSA | RSA [RFC3447] key | REQUIRED | 799 | | family | | 800 +-----------------+-------------------------+-----------------------+ 802 All the names are short because a core goal of JWK is for the 803 representations to be compact. However, there is no a priori length 804 restriction on "alg" values. 806 The use of "+" in the Implementation Requirements indicates that the 807 requirement strength is likely to be increased in a future version of 808 the specification. 810 5.2. JWK Parameters for Elliptic Curve Keys 812 JWKs can represent Elliptic Curve [DSS] keys. In this case, the 813 "alg" member value MUST be "EC". Furthermore, these additional 814 members MUST be present: 816 5.2.1. "crv" (Curve) Parameter 818 The "crv" (curve) member identifies the cryptographic curve used with 819 the key. Curve values from [DSS] used by this specification are: 821 o "P-256" 823 o "P-384" 825 o "P-521" 827 Additional "crv" values MAY be used, provided they are understood by 828 implementations using that Elliptic Curve key. The "crv" value is a 829 case sensitive string. 831 5.2.2. "x" (X Coordinate) Parameter 833 The "x" (x coordinate) member contains the x coordinate for the 834 elliptic curve point. It is represented as the base64url encoding of 835 the coordinate's big endian representation as a byte array. The 836 array representation MUST not be shortened to omit any leading zero 837 bytes contained in the value. For instance, when representing 521 838 bit integers, the byte array to be base64url encoded MUST contain 66 839 bytes, including any leading zero bytes. 841 5.2.3. "y" (Y Coordinate) Parameter 843 The "y" (y coordinate) member contains the y coordinate for the 844 elliptic curve point. It is represented as the base64url encoding of 845 the coordinate's big endian representation as a byte array. The 846 array representation MUST not be shortened to omit any leading zero 847 bytes contained in the value. For instance, when representing 521 848 bit integers, the byte array to be base64url encoded MUST contain 66 849 bytes, including any leading zero bytes. 851 5.3. JWK Parameters for RSA Keys 853 JWKs can represent RSA [RFC3447] keys. In this case, the "alg" 854 member value MUST be "RSA". Furthermore, these additional members 855 MUST be present: 857 5.3.1. "mod" (Modulus) Parameter 859 The "mod" (modulus) member contains the modulus value for the RSA 860 public key. It is represented as the base64url encoding of the 861 value's unsigned big endian representation as a byte array. The 862 array representation MUST not be shortened to omit any leading zero 863 bytes. For instance, when representing 2048 bit integers, the byte 864 array to be base64url encoded MUST contain 256 bytes, including any 865 leading zero bytes. 867 5.3.2. "exp" (Exponent) Parameter 869 The "exp" (exponent) member contains the exponent value for the RSA 870 public key. It is represented as the base64url encoding of the 871 value's unsigned big endian representation as a byte array. The 872 array representation MUST utilize the minimum number of bytes to 873 represent the value. For instance, when representing the value 874 65537, the byte array to be base64url encoded MUST consist of the 875 three bytes [1, 0, 1]. 877 5.4. Additional Key Algorithm Families and Parameters 879 Public keys using additional algorithm families MAY be represented 880 using JWK data structures with corresponding "alg" (algorithm family) 881 parameter values being defined to refer to them. New "alg" parameter 882 values SHOULD either be registered in the IANA JSON Web Key Algorithm 883 Families registry Section 6.2 or be a URI that contains a Collision 884 Resistant Namespace. 886 Likewise, parameters for representing keys for additional algorithm 887 families or additional key properties SHOULD either be registered in 888 the IANA JSON Web Key Parameters registry [JWK] or be a URI that 889 contains a Collision Resistant Namespace. 891 6. IANA Considerations 893 The following registration procedure is used for all the registries 894 established by this specification. 896 Values are registered with a Specification Required [RFC5226] after a 897 two week review period on the [TBD]@ietf.org mailing list, on the 898 advice of one or more Designated Experts. However, to allow for the 899 allocation of values prior to publication, the Designated Expert(s) 900 may approve registration once they are satisfied that such a 901 specification will be published. 903 Registration requests must be sent to the [TBD]@ietf.org mailing list 904 for review and comment, with an appropriate subject (e.g., "Request 905 for access token type: example"). [[ Note to RFC-EDITOR: The name of 906 the mailing list should be determined in consultation with the IESG 907 and IANA. Suggested name: jose-reg-review. ]] 909 Within the review period, the Designated Expert(s) will either 910 approve or deny the registration request, communicating this decision 911 to the review list and IANA. Denials should include an explanation 912 and, if applicable, suggestions as to how to make the request 913 successful. 915 IANA must only accept registry updates from the Designated Expert(s), 916 and should direct all requests for registration to the review mailing 917 list. 919 6.1. JSON Web Signature and Encryption Algorithms Registry 921 This specification establishes the IANA JSON Web Signature and 922 Encryption Algorithms registry for values of the JWS and JWE "alg" 923 (algorithm), "enc" (encryption method), and "int" (integrity 924 algorithm) header parameters. The registry records the algorithm 925 name, the algorithm usage locations from the set "alg", "enc", and 926 "int", implementation requirements, and a reference to the 927 specification that defines it. The same algorithm name may be 928 registered multiple times, provided that the sets of usage locations 929 are disjoint. The implementation requirements of an algorithm may be 930 changed over time by the Designated Experts(s) as the cryptographic 931 landscape evolves, for instance, to change the status of an algorithm 932 to DEPRECATED, or to change the status of an algorithm from OPTIONAL 933 to RECOMMENDED or REQUIRED. 935 6.1.1. Registration Template 937 Algorithm Name: 938 The name requested (e.g., "example"). This name is case 939 sensitive. Names that match other registered names in a case 940 insensitive manner SHOULD NOT be accepted. 942 Algorithm Usage Location(s): 943 The algorithm usage, which must be one or more of the values 944 "alg", "enc", "int", or "kdf". 946 Implementation Requirements: 947 The algorithm implementation requirements, which must be one the 948 words REQUIRED, RECOMMENDED, OPTIONAL, or DEPRECATED. Optionally, 949 the word may be followed by a "+" or "-". The use of "+" 950 indicates that the requirement strength is likely to be increased 951 in a future version of the specification. The use of "-" 952 indicates that the requirement strength is likely to be decreased 953 in a future version of the specification. 955 Change Controller: 956 For standards-track RFCs, state "IETF". For others, give the name 957 of the responsible party. Other details (e.g., postal address, 958 e-mail address, home page URI) may also be included. 960 Specification Document(s): 961 Reference to the document that specifies the parameter, preferably 962 including a URI that can be used to retrieve a copy of the 963 document. An indication of the relevant sections may also be 964 included, but is not required. 966 6.1.2. Initial Registry Contents 968 o Algorithm Name: "HS256" 970 o Algorithm Usage Location(s): "alg", "int" 972 o Implementation Requirements: REQUIRED 974 o Change Controller: IETF 976 o Specification Document(s): Section 3.1 and Section 4.3 of [[ this 977 document ]] 979 o Algorithm Name: "HS384" 981 o Algorithm Usage Location(s): "alg", "int" 983 o Implementation Requirements: OPTIONAL 985 o Change Controller: IETF 987 o Specification Document(s): Section 3.1 and Section 4.3 of [[ this 988 document ]] 990 o Algorithm Name: "HS512" 992 o Algorithm Usage Location(s): "alg", "int" 994 o Implementation Requirements: OPTIONAL 996 o Change Controller: IETF 998 o Specification Document(s): Section 3.1 and Section 4.3 of [[ this 999 document ]] 1001 o Algorithm Name: "RS256" 1003 o Algorithm Usage Location(s): "alg" 1005 o Implementation Requirements: RECOMMENDED 1006 o Change Controller: IETF 1008 o Specification Document(s): Section 3.1 of [[ this document ]] 1010 o Algorithm Name: "RS384" 1012 o Algorithm Usage Location(s): "alg" 1014 o Implementation Requirements: OPTIONAL 1016 o Change Controller: IETF 1018 o Specification Document(s): Section 3.1 of [[ this document ]] 1020 o Algorithm Name: "RS512" 1022 o Algorithm Usage Location(s): "alg" 1024 o Implementation Requirements: OPTIONAL 1026 o Change Controller: IETF 1028 o Specification Document(s): Section 3.1 of [[ this document ]] 1030 o Algorithm Name: "ES256" 1032 o Algorithm Usage Location(s): "alg" 1034 o Implementation Requirements: RECOMMENDED+ 1036 o Change Controller: IETF 1038 o Specification Document(s): Section 3.1 of [[ this document ]] 1040 o Algorithm Name: "ES384" 1042 o Algorithm Usage Location(s): "alg" 1044 o Implementation Requirements: OPTIONAL 1046 o Change Controller: IETF 1048 o Specification Document(s): Section 3.1 of [[ this document ]] 1050 o Algorithm Name: "ES512" 1052 o Algorithm Usage Location(s): "alg" 1053 o Implementation Requirements: OPTIONAL 1055 o Change Controller: IETF 1057 o Specification Document(s): Section 3.1 of [[ this document ]] 1059 o Algorithm Name: "none" 1061 o Algorithm Usage Location(s): "alg" 1063 o Implementation Requirements: REQUIRED 1065 o Change Controller: IETF 1067 o Specification Document(s): Section 3.1 of [[ this document ]] 1069 o Algorithm Name: "RSA1_5" 1071 o Algorithm Usage Location(s): "alg" 1073 o Implementation Requirements: REQUIRED 1075 o Change Controller: IETF 1077 o Specification Document(s): Section 4.1 of [[ this document ]] 1079 o Algorithm Name: "RSA-OAEP" 1081 o Algorithm Usage Location(s): "alg" 1083 o Implementation Requirements: OPTIONAL 1085 o Change Controller: IETF 1087 o Specification Document(s): Section 4.1 of [[ this document ]] 1089 o Algorithm Name: "ECDH-ES" 1091 o Algorithm Usage Location(s): "alg" 1093 o Implementation Requirements: RECOMMENDED+ 1095 o Change Controller: IETF 1097 o Specification Document(s): Section 4.1 of [[ this document ]] 1098 o Algorithm Name: "A128KW" 1100 o Algorithm Usage Location(s): "alg" 1102 o Implementation Requirements: RECOMMENDED 1104 o Change Controller: IETF 1106 o Specification Document(s): Section 4.1 of [[ this document ]] 1108 o Algorithm Name: "A256KW" 1110 o Algorithm Usage Location(s): "alg" 1112 o Implementation Requirements: RECOMMENDED 1114 o Change Controller: IETF 1116 o Specification Document(s): Section 4.1 of [[ this document ]] 1118 o Algorithm Name: "A128CBC" 1120 o Algorithm Usage Location(s): "enc" 1122 o Implementation Requirements: REQUIRED 1124 o Change Controller: IETF 1126 o Specification Document(s): Section 4.2 of [[ this document ]] 1128 o Algorithm Name: "A256CBC" 1130 o Algorithm Usage Location(s): "enc" 1132 o Implementation Requirements: REQUIRED 1134 o Change Controller: IETF 1136 o Specification Document(s): Section 4.2 of [[ this document ]] 1138 o Algorithm Name: "A128GCM" 1140 o Algorithm Usage Location(s): "enc" 1142 o Implementation Requirements: RECOMMENDED 1144 o Change Controller: IETF 1145 o Specification Document(s): Section 4.2 of [[ this document ]] 1147 o Algorithm Name: "A256GCM" 1149 o Algorithm Usage Location(s): "enc" 1151 o Implementation Requirements: RECOMMENDED 1153 o Change Controller: IETF 1155 o Specification Document(s): Section 4.2 of [[ this document ]] 1157 o Algorithm Name: "CS256" 1159 o Algorithm Usage Location(s): "kdf" 1161 o Implementation Requirements: REQUIRED 1163 o Change Controller: IETF 1165 o Specification Document(s): Section 4.4 of [[ this document ]] 1167 o Algorithm Name: "CS384" 1169 o Algorithm Usage Location(s): "kdf" 1171 o Implementation Requirements: OPTIONAL 1173 o Change Controller: IETF 1175 o Specification Document(s): Section 4.4 of [[ this document ]] 1177 o Algorithm Name: "CS512" 1179 o Algorithm Usage Location(s): "kdf" 1181 o Implementation Requirements: OPTIONAL 1183 o Change Controller: IETF 1185 o Specification Document(s): Section 4.4 of [[ this document ]] 1187 6.2. JSON Web Key Algorithm Families Registry 1189 This specification establishes the IANA JSON Web Key Algorithm 1190 Families registry for values of the JWK "alg" (algorithm family) 1191 parameter. The registry records the "alg" value and a reference to 1192 the specification that defines it. This specification registers the 1193 values defined in Section 5.1. 1195 6.2.1. Registration Template 1197 "alg" Parameter Value: 1198 The name requested (e.g., "example"). This name is case 1199 sensitive. Names that match other registered names in a case 1200 insensitive manner SHOULD NOT be accepted. 1202 Change Controller: 1203 For standards-track RFCs, state "IETF". For others, give the name 1204 of the responsible party. Other details (e.g., postal address, 1205 e-mail address, home page URI) may also be included. 1207 Implementation Requirements: 1208 The algorithm implementation requirements, which must be one the 1209 words REQUIRED, RECOMMENDED, OPTIONAL, or DEPRECATED. Optionally, 1210 the word may be followed by a "+" or "-". The use of "+" 1211 indicates that the requirement strength is likely to be increased 1212 in a future version of the specification. The use of "-" 1213 indicates that the requirement strength is likely to be decreased 1214 in a future version of the specification. 1216 Specification Document(s): 1217 Reference to the document that specifies the parameter, preferably 1218 including a URI that can be used to retrieve a copy of the 1219 document. An indication of the relevant sections may also be 1220 included, but is not required. 1222 6.2.2. Initial Registry Contents 1224 o "alg" Parameter Value: "EC" 1226 o Implementation Requirements: RECOMMENDED+ 1228 o Change Controller: IETF 1230 o Specification Document(s): Section 5.1 of [[ this document ]] 1232 o "alg" Parameter Value: "RSA" 1234 o Implementation Requirements: REQUIRED 1236 o Change Controller: IETF 1238 o Specification Document(s): Section 5.1 of [[ this document ]] 1240 6.3. JSON Web Key Parameters Registration 1242 This specification registers the parameter names defined in 1243 Section 5.2 and Section 5.3 in the IANA JSON Web Key Parameters 1244 registry [JWK]. 1246 6.3.1. Registry Contents 1248 o Parameter Name: "crv" 1250 o Change Controller: IETF 1252 o Specification Document(s): Section 5.2.1 of [[ this document ]] 1254 o Parameter Name: "x" 1256 o Change Controller: IETF 1258 o Specification Document(s): Section 5.2.2 of [[ this document ]] 1260 o Parameter Name: "y" 1262 o Change Controller: IETF 1264 o Specification Document(s): Section 5.2.3 of [[ this document ]] 1266 o Parameter Name: "mod" 1268 o Change Controller: IETF 1270 o Specification Document(s): Section 5.3.1 of [[ this document ]] 1272 o Parameter Name: "exp" 1274 o Change Controller: IETF 1276 o Specification Document(s): Section 5.3.2 of [[ this document ]] 1278 7. Security Considerations 1280 All of the security issues faced by any cryptographic application 1281 must be faced by a JWS/JWE/JWK agent. Among these issues are 1282 protecting the user's private key, preventing various attacks, and 1283 helping the user avoid mistakes such as inadvertently encrypting a 1284 message for the wrong recipient. The entire list of security 1285 considerations is beyond the scope of this document, but some 1286 significant concerns are listed here. 1288 The security considerations in [AES], [DSS], [JWE], [JWK], [JWS], 1289 [NIST.800-38A], [NIST.800-38D], [NIST.800-56A], [RFC2104], [RFC3394], 1290 [RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this 1291 specification. 1293 Eventually the algorithms and/or key sizes currently described in 1294 this specification will no longer be considered sufficiently secure 1295 and will be removed. Therefore, implementers and deployments must be 1296 prepared for this eventuality. 1298 Algorithms of matching strength should be used together whenever 1299 possible. For instance, when AES Key Wrap is used with a given key 1300 size, using the same key size for AES CBC or GCM is recommended. 1301 Likewise, when AES CBC is used with a 128 bit key, using HMAC SHA-256 1302 as the integrity algorithm is recommended, whereas when AES CBC is 1303 used with a 256 bit key, using HMAC SHA-512 as the integrity 1304 algorithm is recommended. 1306 While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not 1307 to adopt RSASSA-PKCS1 for new applications and instead requests that 1308 people transition to RSASSA-PSS, this specification does include 1309 RSASSA-PKCS1, for interoperability reasons, because it commonly 1310 implemented. 1312 Keys used with RSAES-PKCS1-v1_5 must follow the constraints in 1313 Section 7.2 of RFC 3447 [RFC3447]. In particular, keys with a low 1314 public key exponent value must not be used. 1316 Plaintext JWSs (JWSs that use the "alg" value "none") provide no 1317 integrity protection. Thus, they must only be used in contexts where 1318 the payload is secured by means other than a digital signature or MAC 1319 value, or need not be secured. 1321 Receiving agents that validate signatures and sending agents that 1322 encrypt messages need to be cautious of cryptographic processing 1323 usage when validating signatures and encrypting messages using keys 1324 larger than those mandated in this specification. An attacker could 1325 send certificates with keys that would result in excessive 1326 cryptographic processing, for example, keys larger than those 1327 mandated in this specification, which could swamp the processing 1328 element. Agents that use such keys without first validating the 1329 certificate to a trust anchor are advised to have some sort of 1330 cryptographic resource management system to prevent such attacks. 1332 8. Open Issues 1334 [[ to be removed by the RFC editor before publication as an RFC ]] 1335 The following items remain to be considered or done in this draft: 1337 o Should we use the "alg" value as the AlgorithmID input to the 1338 Concat KDF when doing key agreement? Or is an AlgorithmID value 1339 unnecessary in the way that we are using Concat for key agreement? 1341 o Similarly, should we use a combination of the "enc" and "int" 1342 values as the AlgorithmID input to the Concat KDF when doing key 1343 derivation? Or is an AlgorithmID value unnecessary in the way 1344 that we are using Concat for key derivation? 1346 o Do we need non-empty PartyUInfo and PartyVInfo values when using 1347 the Concat KDF for key agreement? Or given that we already 1348 require the use of a random unique Ephemeral Public Key (EPK), is 1349 this superfluous, as duplicate keys will not be generated unless a 1350 duplicate EPK is used? If we do decide we need PartyUInfo and 1351 PartyVInfo values, how can we dynamically generate them from 1352 information already carried in the header, rather than requiring 1353 that they be explicitly passed as header parameters? 1355 o Similarly, do we need non-empty PartyUInfo and PartyVInfo values 1356 when using the Concat KDF for key derivation? Or given that we 1357 already require the use of a random unique Content Master Key 1358 (CMK), is this superfluous, as duplicate keys will not be 1359 generated unless a duplicate CMK is used? If we do decide we need 1360 PartyUInfo and PartyVInfo values, how can we dynamically generate 1361 them from information already carried in the header, rather than 1362 requiring that they be explicitly passed as header parameters? 1364 o Do we want to add AES ECB as a (non-authenticated) key wrap 1365 algorithm? Is there any problem with doing key wrap without an 1366 integrity check, given that a separate integrity check already 1367 covers the wrapped key? 1369 o Do we want to add the ability to perform symmetric encryption 1370 directly with a shared key, without using a CMK? This would save 1371 space and time in the single recipient case. It would also be 1372 parallel to the current treatment of key agreement, which doesn't 1373 use a CMK. 1375 9. References 1377 9.1. Normative References 1379 [AES] National Institute of Standards and Technology (NIST), 1380 "Advanced Encryption Standard (AES)", FIPS PUB 197, 1381 November 2001. 1383 [DSS] National Institute of Standards and Technology, "Digital 1384 Signature Standard (DSS)", FIPS PUB 186-3, June 2009. 1386 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 1387 Encryption (JWE)", July 2012. 1389 [JWK] Jones, M., "JSON Web Key (JWK)", July 2012. 1391 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1392 Signature (JWS)", July 2012. 1394 [NIST.800-38A] 1395 National Institute of Standards and Technology (NIST), 1396 "Recommendation for Block Cipher Modes of Operation", 1397 NIST PUB 800-38A, December 2001. 1399 [NIST.800-38D] 1400 National Institute of Standards and Technology (NIST), 1401 "Recommendation for Block Cipher Modes of Operation: 1402 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 1403 December 2001. 1405 [NIST.800-56A] 1406 National Institute of Standards and Technology (NIST), 1407 "Recommendation for Pair-Wise Key Establishment Schemes 1408 Using Discrete Logarithm Cryptography (Revised)", NIST PUB 1409 800-56A, March 2007. 1411 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1412 Hashing for Message Authentication", RFC 2104, 1413 February 1997. 1415 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1416 Requirement Levels", BCP 14, RFC 2119, March 1997. 1418 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 1419 (AES) Key Wrap Algorithm", RFC 3394, September 2002. 1421 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1422 Standards (PKCS) #1: RSA Cryptography Specifications 1423 Version 2.1", RFC 3447, February 2003. 1425 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1426 10646", STD 63, RFC 3629, November 2003. 1428 [RFC4627] Crockford, D., "The application/json Media Type for 1429 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1431 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1432 Encodings", RFC 4648, October 2006. 1434 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 1435 Encryption", RFC 5116, January 2008. 1437 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1438 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1439 May 2008. 1441 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 1442 Curve Cryptography Algorithms", RFC 6090, February 2011. 1444 [SHS] National Institute of Standards and Technology, "Secure 1445 Hash Standard (SHS)", FIPS PUB 180-3, October 2008. 1447 [USASCII] American National Standards Institute, "Coded Character 1448 Set -- 7-bit American Standard Code for Information 1449 Interchange", ANSI X3.4, 1986. 1451 9.2. Informative References 1453 [CanvasApp] 1454 Facebook, "Canvas Applications", 2010. 1456 [I-D.rescorla-jsms] 1457 Rescorla, E. and J. Hildebrand, "JavaScript Message 1458 Security Format", draft-rescorla-jsms-00 (work in 1459 progress), March 2011. 1461 [JCA] Oracle, "Java Cryptography Architecture", 2011. 1463 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1464 Encryption", September 2010. 1466 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 1467 September 2010. 1469 [MagicSignatures] 1470 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 1471 Signatures", January 2011. 1473 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 1474 Language) XML-Signature Syntax and Processing", RFC 3275, 1475 March 2002. 1477 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1478 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1479 July 2005. 1481 [W3C.CR-xmldsig-core2-20120124] 1482 Reagle, J., Hirsch, F., Cantor, S., Roessler, T., 1483 Eastlake, D., Yiu, K., Solo, D., and P. Datta, "XML 1484 Signature Syntax and Processing Version 2.0", World Wide 1485 Web Consortium CR CR-xmldsig-core2-20120124, January 2012, 1486 . 1488 [W3C.CR-xmlenc-core1-20120313] 1489 Eastlake, D., Reagle, J., Hirsch, F., and T. Roessler, 1490 "XML Encryption Syntax and Processing Version 1.1", World 1491 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1492 March 2012, 1493 . 1495 [W3C.REC-xmlenc-core-20021210] 1496 Eastlake, D. and J. Reagle, "XML Encryption Syntax and 1497 Processing", World Wide Web Consortium Recommendation REC- 1498 xmlenc-core-20021210, December 2002, 1499 . 1501 Appendix A. Digital Signature/MAC Algorithm Identifier Cross-Reference 1503 This appendix contains a table cross-referencing the digital 1504 signature and MAC "alg" (algorithm) values used in this specification 1505 with the equivalent identifiers used by other standards and software 1506 packages. See XML DSIG [RFC3275], XML DSIG 2.0 1507 [W3C.CR-xmldsig-core2-20120124], and Java Cryptography Architecture 1508 [JCA] for more information about the names defined by those 1509 documents. 1511 +-------+-----+----------------------------+----------+-------------+ 1512 | Algor | JWS | XML DSIG | JCA | OID | 1513 | ithm | | | | | 1514 +-------+-----+----------------------------+----------+-------------+ 1515 | HMAC | HS2 | http://www.w3.org/2001/04/ | HmacSHA2 | 1.2.840.113 | 1516 | using | 56 | xmldsig-more#hmac-sha256 | 56 | 549.2.9 | 1517 | SHA-2 | | | | | 1518 | 56 | | | | | 1519 | hash | | | | | 1520 | algo | | | | | 1521 | rithm | | | | | 1522 | HMAC | HS3 | http://www.w3.org/2001/04/ | HmacSHA3 | 1.2.840.113 | 1523 | using | 84 | xmldsig-more#hmac-sha384 | 84 | 549.2.10 | 1524 | SHA-3 | | | | | 1525 | 84 | | | | | 1526 | hash | | | | | 1527 | algo | | | | | 1528 | rithm | | | | | 1529 | HMAC | HS5 | http://www.w3.org/2001/04/ | HmacSHA5 | 1.2.840.113 | 1530 | using | 12 | xmldsig-more#hmac-sha512 | 12 | 549.2.11 | 1531 | SHA-5 | | | | | 1532 | 12 | | | | | 1533 | hash | | | | | 1534 | algo | | | | | 1535 | rithm | | | | | 1536 | RSASS | RS2 | http://www.w3.org/2001/04/ | SHA256wi | 1.2.840.113 | 1537 | A | 56 | xmldsig-more#rsa-sha256 | thRSA | 549.1.1.11 | 1538 | usin | | | | | 1539 | gSHA- | | | | | 1540 | 256 | | | | | 1541 | has | | | | | 1542 | h alg | | | | | 1543 | orith | | | | | 1544 | m | | | | | 1545 | RSASS | RS3 | http://www.w3.org/2001/04/ | SHA384wi | 1.2.840.113 | 1546 | A | 84 | xmldsig-more#rsa-sha384 | thRSA | 549.1.1.12 | 1547 | usin | | | | | 1548 | gSHA- | | | | | 1549 | 384 | | | | | 1550 | has | | | | | 1551 | h alg | | | | | 1552 | orith | | | | | 1553 | m | | | | | 1554 | RSASS | RS5 | http://www.w3.org/2001/04/ | SHA512wi | 1.2.840.113 | 1555 | A | 12 | xmldsig-more#rsa-sha512 | thRSA | 549.1.1.13 | 1556 | usin | | | | | 1557 | gSHA- | | | | | 1558 | 512 | | | | | 1559 | has | | | | | 1560 | h alg | | | | | 1561 | orith | | | | | 1562 | m | | | | | 1563 | ECDSA | ES2 | http://www.w3.org/2001/04/ | SHA256wi | 1.2.840.100 | 1564 | using | 56 | xmldsig-more#ecdsa-sha256 | thECDSA | 45.4.3.2 | 1565 | P-256 | | | | | 1566 | curve | | | | | 1567 | and | | | | | 1568 | SHA-2 | | | | | 1569 | 56 | | | | | 1570 | hash | | | | | 1571 | algo | | | | | 1572 | rithm | | | | | 1573 | ECDSA | ES3 | http://www.w3.org/2001/04/ | SHA384wi | 1.2.840.100 | 1574 | using | 84 | xmldsig-more#ecdsa-sha384 | thECDSA | 45.4.3.3 | 1575 | P-384 | | | | | 1576 | curve | | | | | 1577 | and | | | | | 1578 | SHA-3 | | | | | 1579 | 84 | | | | | 1580 | hash | | | | | 1581 | algo | | | | | 1582 | rithm | | | | | 1583 | ECDSA | ES5 | http://www.w3.org/2001/04/ | SHA512wi | 1.2.840.100 | 1584 | using | 12 | xmldsig-more#ecdsa-sha512 | thECDSA | 45.4.3.4 | 1585 | P-521 | | | | | 1586 | curve | | | | | 1587 | and | | | | | 1588 | SHA-5 | | | | | 1589 | 12 | | | | | 1590 | hash | | | | | 1591 | algo | | | | | 1592 | rithm | | | | | 1593 +-------+-----+----------------------------+----------+-------------+ 1595 Appendix B. Encryption Algorithm Identifier Cross-Reference 1597 This appendix contains a table cross-referencing the "alg" 1598 (algorithm) and "enc" (encryption method) values used in this 1599 specification with the equivalent identifiers used by other standards 1600 and software packages. See XML Encryption 1601 [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 1602 [W3C.CR-xmlenc-core1-20120313], and Java Cryptography Architecture 1603 [JCA] for more information about the names defined by those 1604 documents. 1606 +----------+------+---------------------------+---------------------+ 1607 | Algorith | JWE | XML ENC | JCA | 1608 | m | | | | 1609 +----------+------+---------------------------+---------------------+ 1610 | RSAES-PK | RSA1 | http://www.w3.org/2001/04 | RSA/None/PKCS1Paddi | 1611 | CS1-V1_5 | _5 | /xmlenc#rsa-1_5 | ng | 1612 | RSAES | RSA- | http://www.w3.org/2001/04 | RSA/None/OAEPWithSH | 1613 | using | OAEP | /xmlenc#rsa-oaep-mgf1p | A-1AndMGF1Padding | 1614 | Optimal | | | | 1615 | Asymmetr | | | | 1616 | ic | | | | 1617 | Encrypt | | | | 1618 | ion | | | | 1619 | Paddin | | | | 1620 | g (OAEP) | | | | 1621 | Elliptic | ECDH | http://www.w3.org/2009/xm | | 1622 | Curve | -ES | lenc11#ECDH-ES | | 1623 | Diffie-H | | | | 1624 | ellman | | | | 1625 | Ephemer | | | | 1626 | alStatic | | | | 1627 | Advanced | A128 | http://www.w3.org/2001/04 | | 1628 | Encrypti | KW | /xmlenc#kw-aes128 | | 1629 | on | | | | 1630 | Standar | | | | 1631 | d(AES) | | | | 1632 | Key Wra | | | | 1633 | pAlgorit | | | | 1634 | hmusing | | | | 1635 | 128 bi | | | | 1636 | t keys | | | | 1637 | AES Key | A256 | http://www.w3.org/2001/04 | | 1638 | Wrap | KW | /xmlenc#kw-aes256 | | 1639 | Algorith | | | | 1640 | musing | | | | 1641 | 256 bit | | | | 1642 | keys | | | | 1643 | AES in | A128 | http://www.w3.org/2001/04 | AES/CBC/PKCS5Paddin | 1644 | Cipher | CBC | /xmlenc#aes128-cbc | g | 1645 | Block | | | | 1646 | Chaining | | | | 1647 | (CBC) | | | | 1648 | mode | | | | 1649 | with | | | | 1650 | PKCS #5 | | | | 1651 | padding | | | | 1652 | using | | | | 1653 | 128 bit | | | | 1654 | keys | | | | 1655 | AES in | A256 | http://www.w3.org/2001/04 | AES/CBC/PKCS5Paddin | 1656 | CBC mode | CBC | /xmlenc#aes256-cbc | g | 1657 | with | | | | 1658 | PKCS #5 | | | | 1659 | padding | | | | 1660 | using | | | | 1661 | 256 bit | | | | 1662 | keys | | | | 1663 | AES in | A128 | http://www.w3.org/2009/xm | AES/GCM/NoPadding | 1664 | Galois/C | GCM | lenc11#aes128-gcm | | 1665 | ounter | | | | 1666 | Mode | | | | 1667 | (GCM) | | | | 1668 | using | | | | 1669 | 128 bit | | | | 1670 | keys | | | | 1671 | AES GCM | A256 | http://www.w3.org/2009/xm | AES/GCM/NoPadding | 1672 | using | GCM | lenc11#aes256-gcm | | 1673 | 256 bit | | | | 1674 | keys | | | | 1675 +----------+------+---------------------------+---------------------+ 1677 Appendix C. Acknowledgements 1679 Solutions for signing and encrypting JSON content were previously 1680 explored by Magic Signatures [MagicSignatures], JSON Simple Sign 1681 [JSS], Canvas Applications [CanvasApp], JSON Simple Encryption [JSE], 1682 and JavaScript Message Security Format [I-D.rescorla-jsms], all of 1683 which influenced this draft. Dirk Balfanz, John Bradley, Yaron Y. 1684 Goland, John Panzer, Nat Sakimura, and Paul Tarjan all made 1685 significant contributions to the design of this specification and its 1686 related specifications. 1688 Appendix D. Document History 1690 [[ to be removed by the RFC editor before publication as an RFC ]] 1692 -04 1694 o Added text requiring that any leading zero bytes be retained in 1695 base64url encoded key value representations for fixed-length 1696 values. 1698 o Added this language to Registration Templates: "This name is case 1699 sensitive. Names that match other registered names in a case 1700 insensitive manner SHOULD NOT be accepted." 1702 o Described additional open issues. 1704 o Applied editorial suggestions. 1706 -03 1708 o Always use a 128 bit "authentication tag" size for AES GCM, 1709 regardless of the key size. 1711 o Specified that use of a 128 bit IV is REQUIRED with AES CBC. It 1712 was previously RECOMMENDED. 1714 o Removed key size language for ECDSA algorithms, since the key size 1715 is implied by the algorithm being used. 1717 o Stated that the "int" key size must be the same as the hash output 1718 size (and not larger, as was previously allowed) so that its size 1719 is defined for key generation purposes. 1721 o Added the "kdf" (key derivation function) header parameter to 1722 provide crypto agility for key derivation. The default KDF 1723 remains the Concat KDF with the SHA-256 digest function. 1725 o Clarified that the "mod" and "exp" values are unsigned. 1727 o Added Implementation Requirements columns to algorithm tables and 1728 Implementation Requirements entries to algorithm registries. 1730 o Changed AES Key Wrap to RECOMMENDED. 1732 o Moved registries JSON Web Signature and Encryption Header 1733 Parameters and JSON Web Signature and Encryption Type Values to 1734 the JWS specification. 1736 o Moved JSON Web Key Parameters registry to the JWK specification. 1738 o Changed registration requirements from RFC Required to 1739 Specification Required with Expert Review. 1741 o Added Registration Template sections for defined registries. 1743 o Added Registry Contents sections to populate registry values. 1745 o No longer say "the UTF-8 representation of the JWS Secured Input 1746 (which is the same as the ASCII representation)". Just call it 1747 "the ASCII representation of the JWS Secured Input". 1749 o Added "Collision Resistant Namespace" to the terminology section. 1751 o Numerous editorial improvements. 1753 -02 1755 o For AES GCM, use the "additional authenticated data" parameter to 1756 provide integrity for the header, encrypted key, and ciphertext 1757 and use the resulting "authentication tag" value as the JWE 1758 Integrity Value. 1760 o Defined minimum required key sizes for algorithms without 1761 specified key sizes. 1763 o Defined KDF output key sizes. 1765 o Specified the use of PKCS #5 padding with AES-CBC. 1767 o Generalized text to allow key agreement to be employed as an 1768 alternative to key wrapping or key encryption. 1770 o Clarified that ECDH-ES is a key agreement algorithm. 1772 o Required implementation of AES-128-KW and AES-256-KW. 1774 o Removed the use of "A128GCM" and "A256GCM" for key wrapping. 1776 o Removed "A512KW" since it turns out that it's not a standard 1777 algorithm. 1779 o Clarified the relationship between "typ" header parameter values 1780 and MIME types. 1782 o Generalized language to refer to Message Authentication Codes 1783 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 1784 unless in a context specific to HMAC algorithms. 1786 o Established registries: JSON Web Signature and Encryption Header 1787 Parameters, JSON Web Signature and Encryption Algorithms, JSON Web 1788 Signature and Encryption "typ" Values, JSON Web Key Parameters, 1789 and JSON Web Key Algorithm Families. 1791 o Moved algorithm-specific definitions from JWK to JWA. 1793 o Reformatted to give each member definition its own section 1794 heading. 1796 -01 1798 o Moved definition of "alg":"none" for JWSs here from the JWT 1799 specification since this functionality is likely to be useful in 1800 more contexts that just for JWTs. 1802 o Added Advanced Encryption Standard (AES) Key Wrap Algorithm using 1803 512 bit keys ("A512KW"). 1805 o Added text "Alternatively, the Encoded JWS Signature MAY be 1806 base64url decoded to produce the JWS Signature and this value can 1807 be compared with the computed HMAC value, as this comparison 1808 produces the same result as comparing the encoded values". 1810 o Corrected the Magic Signatures reference. 1812 o Made other editorial improvements suggested by JOSE working group 1813 participants. 1815 -00 1817 o Created the initial IETF draft based upon 1818 draft-jones-json-web-signature-04 and 1819 draft-jones-json-web-encryption-02 with no normative changes. 1821 o Changed terminology to no longer call both digital signatures and 1822 HMACs "signatures". 1824 Author's Address 1826 Michael B. Jones 1827 Microsoft 1829 Email: mbj@microsoft.com 1830 URI: http://self-issued.info/