idnits 2.17.1 draft-ietf-jose-json-web-algorithms-06.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 "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 (October 15, 2012) is 4210 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 777 -- Looks like a reference, but probably isn't: '110' on line 778 -- Looks like a reference, but probably isn't: '99' on line 777 -- Looks like a reference, but probably isn't: '114' on line 778 -- Looks like a reference, but probably isn't: '121' on line 778 -- Looks like a reference, but probably isn't: '112' on line 777 -- Looks like a reference, but probably isn't: '116' on line 778 -- Looks like a reference, but probably isn't: '105' on line 778 -- Looks like a reference, but probably isn't: '111' on line 777 -- Looks like a reference, but probably isn't: '73' on line 778 -- Looks like a reference, but probably isn't: '101' on line 778 -- Looks like a reference, but probably isn't: '103' on line 778 -- Looks like a reference, but probably isn't: '1' on line 985 -- Looks like a reference, but probably isn't: '0' on line 985 -- 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 (==), 22 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track October 15, 2012 5 Expires: April 18, 2013 7 JSON Web Algorithms (JWA) 8 draft-ietf-jose-json-web-algorithms-06 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 April 18, 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" . . . . . . . . . . . . . . . . 12 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . 15 76 4.7. Key Agreement with Elliptic Curve Diffie-Hellman 77 Ephemeral Static (ECDH-ES) . . . . . . . . . . . . . . . . 15 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" . . . . . . . . . . . . . . . . . . . 17 83 4.8.2. Encryption Calculation for "A128CBC+HS256" and 84 "A256CBC+HS512" . . . . . . . . . . . . . . . . . . . 18 85 4.8.3. Integrity Calculation for "A128CBC+HS256" and 86 "A256CBC+HS512" . . . . . . . . . . . . . . . . . . . 18 87 4.9. Plaintext Encryption with AES GCM . . . . . . . . . . . . 19 88 4.10. Additional Encryption Algorithms and Parameters . . . . . 19 89 5. Cryptographic Algorithms for JWK . . . . . . . . . . . . . . . 20 90 5.1. "alg" (Algorithm Family) Parameter Values for JWK . . . . 20 91 5.2. JWK Parameters for Elliptic Curve Keys . . . . . . . . . . 21 92 5.2.1. "crv" (Curve) Parameter . . . . . . . . . . . . . . . 21 93 5.2.2. "x" (X Coordinate) Parameter . . . . . . . . . . . . . 21 94 5.2.3. "y" (Y Coordinate) Parameter . . . . . . . . . . . . . 21 95 5.3. JWK Parameters for RSA Keys . . . . . . . . . . . . . . . 22 96 5.3.1. "mod" (Modulus) Parameter . . . . . . . . . . . . . . 22 97 5.3.2. "xpo" (Exponent) Parameter . . . . . . . . . . . . . . 22 98 5.4. Additional Key Algorithm Families and Parameters . . . . . 22 99 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 100 6.1. JSON Web Signature and Encryption Algorithms Registry . . 23 101 6.1.1. Registration Template . . . . . . . . . . . . . . . . 23 102 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 24 103 6.2. JSON Web Key Algorithm Families Registry . . . . . . . . . 27 104 6.2.1. Registration Template . . . . . . . . . . . . . . . . 27 105 6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 28 106 6.3. JSON Web Key Parameters Registration . . . . . . . . . . . 28 107 6.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 28 108 7. Security Considerations . . . . . . . . . . . . . . . . . . . 29 109 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 110 8.1. Normative References . . . . . . . . . . . . . . . . . . . 30 111 8.2. Informative References . . . . . . . . . . . . . . . . . . 31 112 Appendix A. Digital Signature/MAC Algorithm Identifier 113 Cross-Reference . . . . . . . . . . . . . . . . . . . 32 114 Appendix B. Encryption Algorithm Identifier Cross-Reference . . . 34 115 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 36 116 Appendix D. Open Issues . . . . . . . . . . . . . . . . . . . . . 37 117 Appendix E. Document History . . . . . . . . . . . . . . . . . . 37 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 An example using this algorithm is shown in Appendix A.1 of [JWS]. 374 3.3. Digital Signature with RSA SHA-256, RSA SHA-384, or RSA SHA-512 376 This section defines the use of the RSASSA-PKCS1-V1_5 digital 377 signature algorithm as defined in Section 8.2 of RFC 3447 [RFC3447], 378 (commonly known as PKCS #1), using SHA-256, SHA-384, or SHA-512 [SHS] 379 as the hash functions. The "alg" (algorithm) header parameter values 380 "RS256", "RS384", and "RS512" are used in the JWS Header to indicate 381 that the Encoded JWS Signature contains a base64url encoded RSA 382 digital signature using the respective hash function. 384 A key of size 2048 bits or larger MUST be used with these algorithms. 386 The RSA SHA-256 digital signature is generated as follows: 388 1. Generate a digital signature of the bytes of the ASCII 389 representation of the JWS Secured Input using RSASSA-PKCS1-V1_5- 390 SIGN and the SHA-256 hash function with the desired private key. 391 The output will be a byte array. 393 2. Base64url encode the resulting byte array. 395 The output is the Encoded JWS Signature for that JWS. 397 The RSA SHA-256 digital signature for a JWS is validated as follows: 399 1. Take the Encoded JWS Signature and base64url decode it into a 400 byte array. If decoding fails, the JWS MUST be rejected. 402 2. Submit the bytes of the ASCII representation of the JWS Secured 403 Input and the public key corresponding to the private key used by 404 the signer to the RSASSA-PKCS1-V1_5-VERIFY algorithm using SHA- 405 256 as the hash function. 407 3. If the validation fails, the JWS MUST be rejected. 409 Signing with the RSA SHA-384 and RSA SHA-512 algorithms is performed 410 identically to the procedure for RSA SHA-256 - just using the 411 corresponding hash algorithm with correspondingly larger result 412 values: 384 bits for RSA SHA-384 and 512 bits for RSA SHA-512. 414 An example using this algorithm is shown in Appendix A.2 of [JWS]. 416 3.4. Digital Signature with ECDSA P-256 SHA-256, ECDSA P-384 SHA-384, 417 or ECDSA P-521 SHA-512 419 The Elliptic Curve Digital Signature Algorithm (ECDSA) [DSS] provides 420 for the use of Elliptic Curve cryptography, which is able to provide 421 equivalent security to RSA cryptography but using shorter key sizes 422 and with greater processing speed. This means that ECDSA digital 423 signatures will be substantially smaller in terms of length than 424 equivalently strong RSA digital signatures. 426 This specification defines the use of ECDSA with the P-256 curve and 427 the SHA-256 cryptographic hash function, ECDSA with the P-384 curve 428 and the SHA-384 hash function, and ECDSA with the P-521 curve and the 429 SHA-512 hash function. The P-256, P-384, and P-521 curves are 430 defined in [DSS]. The "alg" (algorithm) header parameter values 431 "ES256", "ES384", and "ES512" are used in the JWS Header to indicate 432 that the Encoded JWS Signature contains a base64url encoded ECDSA 433 P-256 SHA-256, ECDSA P-384 SHA-384, or ECDSA P-521 SHA-512 digital 434 signature, respectively. 436 The ECDSA P-256 SHA-256 digital signature is generated as follows: 438 1. Generate a digital signature of the bytes of the ASCII 439 representation of the JWS Secured Input using ECDSA P-256 SHA-256 440 with the desired private key. The output will be the pair (R, 441 S), where R and S are 256 bit unsigned integers. 443 2. Turn R and S into byte arrays in big endian order, with each 444 array being be 32 bytes long. The array representations MUST not 445 be shortened to omit any leading zero bytes contained in the 446 values. 448 3. Concatenate the two byte arrays in the order R and then S. (Note 449 that many ECDSA implementations will directly produce this 450 concatenation as their output.) 452 4. Base64url encode the resulting 64 byte array. 454 The output is the Encoded JWS Signature for the JWS. 456 The ECDSA P-256 SHA-256 digital signature for a JWS is validated as 457 follows: 459 1. Take the Encoded JWS Signature and base64url decode it into a 460 byte array. If decoding fails, the JWS MUST be rejected. 462 2. The output of the base64url decoding MUST be a 64 byte array. If 463 decoding does not result in a 64 byte array, the JWS MUST be 464 rejected. 466 3. Split the 64 byte array into two 32 byte arrays. The first array 467 will be R and the second S (with both being in big endian byte 468 order). 470 4. Submit the bytes of the ASCII representation of the JWS Secured 471 Input R, S and the public key (x, y) to the ECDSA P-256 SHA-256 472 validator. 474 5. If the validation fails, the JWS MUST be rejected. 476 Note that ECDSA digital signature contains a value referred to as K, 477 which is a random number generated for each digital signature 478 instance. This means that two ECDSA digital signatures using exactly 479 the same input parameters will output different signature values 480 because their K values will be different. A consequence of this is 481 that one cannot validate an ECDSA signature by recomputing the 482 signature and comparing the results. 484 Signing with the ECDSA P-384 SHA-384 and ECDSA P-521 SHA-512 485 algorithms is performed identically to the procedure for ECDSA P-256 486 SHA-256 - just using the corresponding hash algorithm with 487 correspondingly larger result values. For ECDSA P-384 SHA-384, R and 488 S will be 384 bits each, resulting in a 96 byte array. For ECDSA 489 P-521 SHA-512, R and S will be 521 bits each, resulting in a 132 byte 490 array. 492 Examples using these algorithms are shown in Appendices A.3 and A.4 493 of [JWS]. 495 3.5. Using the Algorithm "none" 497 JWSs MAY also be created that do not provide integrity protection. 498 Such a JWS is called a "Plaintext JWS". Plaintext JWSs MUST use the 499 "alg" value "none", and are formatted identically to other JWSs, but 500 with an empty JWS Signature value. 502 3.6. Additional Digital Signature/MAC Algorithms and Parameters 504 Additional algorithms MAY be used to protect JWSs with corresponding 505 "alg" (algorithm) header parameter values being defined to refer to 506 them. New "alg" header parameter values SHOULD either be registered 507 in the IANA JSON Web Signature and Encryption Algorithms registry 508 Section 6.1 or be a URI that contains a Collision Resistant 509 Namespace. In particular, it is permissible to use the algorithm 510 identifiers defined in XML DSIG [RFC3275], XML DSIG 2.0 511 [W3C.CR-xmldsig-core2-20120124], and related specifications as "alg" 512 values. 514 As indicated by the common registry, JWSs and JWEs share a common 515 "alg" value space. The values used by the two specifications MUST be 516 distinct, as the "alg" value MAY be used to determine whether the 517 object is a JWS or JWE. 519 Likewise, additional reserved header parameter names MAY be defined 520 via the IANA JSON Web Signature and Encryption Header Parameters 521 registry [JWS]. As indicated by the common registry, JWSs and JWEs 522 share a common header parameter space; when a parameter is used by 523 both specifications, its usage must be compatible between the 524 specifications. 526 4. Cryptographic Algorithms for JWE 528 JWE uses cryptographic algorithms to encrypt the Content Master Key 529 (CMK) and the Plaintext. This section specifies a set of specific 530 algorithms for these purposes. 532 4.1. "alg" (Algorithm) Header Parameter Values for JWE 534 The table below is the set of "alg" (algorithm) header parameter 535 values that are defined by this specification for use with JWE. 536 These algorithms are used to encrypt the CMK, producing the JWE 537 Encrypted Key, or to use key agreement to agree upon the CMK. 539 +----------------+---------------------------------+----------------+ 540 | alg Parameter | Key Encryption or Agreement | Implementation | 541 | Value | Algorithm | Requirements | 542 +----------------+---------------------------------+----------------+ 543 | RSA1_5 | RSAES-PKCS1-V1_5 [RFC3447] | REQUIRED | 544 | RSA-OAEP | RSAES using Optimal Asymmetric | OPTIONAL | 545 | | Encryption Padding (OAEP) | | 546 | | [RFC3447], with the default | | 547 | | parameters specified by RFC | | 548 | | 3447 in Section A.2.1 | | 549 | A128KW | Advanced Encryption Standard | RECOMMENDED | 550 | | (AES) Key Wrap Algorithm | | 551 | | [RFC3394] using 128 bit keys | | 552 | A256KW | AES Key Wrap Algorithm using | RECOMMENDED | 553 | | 256 bit keys | | 554 | dir | Direct use of a shared | RECOMMENDED | 555 | | symmetric key as the Content | | 556 | | Master Key (CMK) for the block | | 557 | | encryption step (rather than | | 558 | | using the symmetric key to wrap | | 559 | | the CMK) | | 560 | ECDH-ES | Elliptic Curve Diffie-Hellman | RECOMMENDED+ | 561 | | Ephemeral Static [RFC6090] key | | 562 | | agreement using the Concat KDF, | | 563 | | as defined in Section 5.8.1 of | | 564 | | [NIST.800-56A], with the | | 565 | | agreed-upon key being used | | 566 | | directly as the Content Master | | 567 | | Key (CMK) (rather than being | | 568 | | used to wrap the CMK), as | | 569 | | specified in Section 4.7 | | 570 | ECDH-ES+A128KW | Elliptic Curve Diffie-Hellman | RECOMMENDED | 571 | | Ephemeral Static key agreement | | 572 | | per "ECDH-ES" and Section 4.7, | | 573 | | but where the agreed-upon key | | 574 | | is used to wrap the Content | | 575 | | Master Key (CMK) with the | | 576 | | "A128KW" function (rather than | | 577 | | being used directly as the CMK) | | 578 | ECDH-ES+A256KW | Elliptic Curve Diffie-Hellman | RECOMMENDED | 579 | | Ephemeral Static key agreement | | 580 | | per "ECDH-ES" and Section 4.7, | | 581 | | but where the agreed-upon key | | 582 | | is used to wrap the Content | | 583 | | Master Key (CMK) with the | | 584 | | "A256KW" function (rather than | | 585 | | being used directly as the CMK) | | 586 +----------------+---------------------------------+----------------+ 587 The use of "+" in the Implementation Requirements indicates that the 588 requirement strength is likely to be increased in a future version of 589 the specification. 591 4.2. "enc" (Encryption Method) Header Parameter Values for JWE 593 The table below is the set of "enc" (encryption method) header 594 parameter values that are defined by this specification for use with 595 JWE. These algorithms are used to encrypt the Plaintext, which 596 produces the Ciphertext. 598 +---------------+----------------------------------+----------------+ 599 | enc Parameter | Block Encryption Algorithm | Implementation | 600 | Value | | Requirements | 601 +---------------+----------------------------------+----------------+ 602 | A128CBC+HS256 | Composite AEAD algorithm using | REQUIRED | 603 | | Advanced Encryption Standard | | 604 | | (AES) in Cipher Block Chaining | | 605 | | (CBC) mode with PKCS #5 padding | | 606 | | [AES] [NIST.800-38A] with an | | 607 | | integrity calculation using HMAC | | 608 | | SHA-256, using a 256 bit CMK | | 609 | | (and 128 bit CEK) as specified | | 610 | | in Section 4.8 | | 611 | A256CBC+HS512 | Composite AEAD algorithm using | REQUIRED | 612 | | AES in CBC mode with PKCS #5 | | 613 | | padding with an integrity | | 614 | | calculation using HMAC SHA-512, | | 615 | | using a 512 bit CMK (and 256 bit | | 616 | | CEK) as specified in Section 4.8 | | 617 | A128GCM | AES in Galois/Counter Mode (GCM) | RECOMMENDED | 618 | | [AES] [NIST.800-38D] using 128 | | 619 | | bit keys | | 620 | A256GCM | AES GCM using 256 bit keys | RECOMMENDED | 621 +---------------+----------------------------------+----------------+ 623 All the names are short because a core goal of JWE is for the 624 representations to be compact. However, there is no a priori length 625 restriction on "alg" values. 627 See Appendix B for a table cross-referencing the encryption "alg" 628 (algorithm) and "enc" (encryption method) values used in this 629 specification with the equivalent identifiers used by other standards 630 and software packages. 632 4.3. Key Encryption with RSAES-PKCS1-V1_5 634 This section defines the specifics of encrypting a JWE CMK with 635 RSAES-PKCS1-V1_5 [RFC3447]. The "alg" header parameter value 636 "RSA1_5" is used in this case. 638 A key of size 2048 bits or larger MUST be used with this algorithm. 640 An example using this algorithm is shown in Appendix A.2 of [JWE]. 642 4.4. Key Encryption with RSAES OAEP 644 This section defines the specifics of encrypting a JWE CMK with RSAES 645 using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447], with 646 the default parameters specified by RFC 3447 in Section A.2.1. The 647 "alg" header parameter value "RSA-OAEP" is used in this case. 649 A key of size 2048 bits or larger MUST be used with this algorithm. 651 An example using this algorithm is shown in Appendix A.1 of [JWE]. 653 4.5. Key Encryption with AES Key Wrap 655 This section defines the specifics of encrypting a JWE CMK with the 656 Advanced Encryption Standard (AES) Key Wrap Algorithm [RFC3394] using 657 128 or 256 bit keys. The "alg" header parameter values "A128KW" or 658 "A256KW" are used in this case. 660 An example using this algorithm is shown in Appendix A.3 of [JWE]. 662 4.6. Direct Encryption with a Shared Symmetric Key 664 This section defines the specifics of directly performing symmetric 665 key encryption without performing a key wrapping step. In this case, 666 the shared symmetric key is used directly as the Content Master Key 667 (CMK) value for the "enc" algorithm. An empty byte array is used as 668 the JWE Encrypted Key value. The "alg" header parameter value "dir" 669 is used in this case. 671 4.7. Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static 672 (ECDH-ES) 674 This section defines the specifics of key agreement with Elliptic 675 Curve Diffie-Hellman Ephemeral Static [RFC6090], and using the Concat 676 KDF, as defined in Section 5.8.1 of [NIST.800-56A]. The key 677 agreement result can be used in one of two ways: (1) directly as the 678 Content Master Key (CMK) for the "enc" algorithm, or (2) as a 679 symmetric key used to wrap the CMK with either the "A128KW" or 680 "A256KW" algorithms. The "alg" header parameter values "ECDH-ES", 681 "ECDH-ES+A128KW", and "ECDH-ES+A256KW" are respectively used in this 682 case. 684 In the direct case, the output of the Concat KDF MUST be a key of the 685 same length as that used by the "enc" algorithm; in this case, the 686 empty byte array is used as the JWE Encrypted Key value. In the key 687 wrap case, the output of the Concat KDF MUST be a key of the length 688 needed for the specified key wrap algorithm, either 128 or 256 bits 689 respectively. 691 A new "epk" (ephemeral public key) value MUST be generated for each 692 key agreement transaction. 694 4.7.1. Key Derivation for "ECDH-ES" 696 The key derivation process derives the agreed upon key from the 697 shared secret Z established through the ECDH algorithm, per Section 698 6.2.2.2 of [NIST.800-56A]. 700 Key derivation is performed using the Concat KDF, as defined in 701 Section 5.8.1 of [NIST.800-56A], where the Digest Method is SHA-256. 702 The Concat KDF parameters are set as follows: 704 Z This is set to the representation of the shared secret Z as a byte 705 array. 707 keydatalen This is set to the number of bits in the desired output 708 key. For "ECDH-ES", this is length of the key used by the "enc" 709 algorithm. For "ECDH-ES+A128KW", and "ECDH-ES+A256KW", this is 710 128 and 256, respectively. 712 AlgorithmID This is set to the concatenation of keydatalen 713 represented as a 32 bit big endian integer and the bytes of the 714 UTF-8 representation of the "alg" header parameter value. 716 PartyUInfo If an "apu" (agreement PartyUInfo) header parameter is 717 present, this is set to the result of base64url decoding the "apu" 718 value; otherwise, it is set to the empty byte string. 720 PartyVInfo If an "apv" (agreement PartyVInfo) header parameter is 721 present, this is set to the result of base64url decoding the "apv" 722 value; otherwise, it is set to the empty byte string. 724 SuppPubInfo This is set to the empty byte string. 726 SuppPrivInfo This is set to the empty byte string. 728 For all three "alg" values, the digest function used is SHA-256. 730 4.8. Composite Plaintext Encryption Algorithms "A128CBC+HS256" and 731 "A256CBC+HS512" 733 This section defines two composite "enc" algorithms that perform 734 plaintext encryption using non-AEAD algorithms and add an integrity 735 check calculation, so that the resulting composite algorithms are 736 AEAD. These composite algorithms derive a Content Encryption Key 737 (CEK) and a Content Integrity Key (CIK) from a Content Master Key, 738 per Section 4.8.1. They perform block encryption with AES CBC, per 739 Section 4.8.2. Finally, they add an integrity check using HMAC SHA-2 740 algorithms of matching strength, per Section 4.8.3. 742 A 256 bit Content Master Key (CMK) value is used with the 743 "A128CBC+HS256" algorithm. A 512 bit Content Master Key (CMK) value 744 is used with the "A256CBC+HS512" algorithm. 746 An example using this algorithm is shown in Appendix A.2 of [JWE]. 748 4.8.1. Key Derivation for "A128CBC+HS256" and "A256CBC+HS512" 750 The key derivation process derives CEK and CIK values from the CMK. 751 This section defines the specifics of deriving keys for the "enc" 752 algorithms "A128CBC+HS256" and "A256CBC+HS512". 754 Key derivation is performed using the Concat KDF, as defined in 755 Section 5.8.1 of [NIST.800-56A], where the Digest Method is SHA-256 756 or SHA-512, respectively. The Concat KDF parameters are set as 757 follows: 759 Z This is set to the Content Master Key (CMK). 761 keydatalen This is set to the number of bits in the desired output 762 key. 764 AlgorithmID This is set to the concatenation of keydatalen 765 represented as a 32 bit big endian integer and the bytes of the 766 UTF-8 representation of the "enc" header parameter value. 768 PartyUInfo If an "epu" (encryption PartyUInfo) header parameter is 769 present, this is set to the result of base64url decoding the "epu" 770 value; otherwise, it is set to the empty byte string. 772 PartyVInfo If an "epv" (encryption PartyVInfo) header parameter is 773 present, this is set to the result of base64url decoding the "epv" 774 value; otherwise, it is set to the empty byte string. 776 SuppPubInfo This is set to the bytes of one of the ASCII strings 777 "Encryption" ([69, 110, 99, 114, 121, 112, 116, 105, 111, 110]) or 778 "Integrity" ([73, 110, 116, 101, 103, 114, 105, 116, 121]) 779 respectively, depending upon whether the CEK or CIK is being 780 generated. 782 SuppPrivInfo This is set to the empty byte string. 784 To compute the CEK from the CMK, the ASCII label "Encryption" is used 785 for the SuppPubInfo value. For "A128CBC+HS256", the keydatalen is 786 128 and the digest function used is SHA-256. For "A256CBC+HS512", 787 the keydatalen is 256 and the digest function used is SHA-512. 789 To compute the CIK from the CMK, the ASCII label "Integrity" is used 790 for the SuppPubInfo value. For "A128CBC+HS256", the keydatalen is 791 256 and the digest function used is SHA-256. For "A256CBC+HS512", 792 the keydatalen is 512 and the digest function used is SHA-512. 794 Example derivation computations are shown in Appendices A.4 and A.5 795 of [JWE]. 797 4.8.2. Encryption Calculation for "A128CBC+HS256" and "A256CBC+HS512" 799 This section defines the specifics of encrypting the JWE Plaintext 800 with Advanced Encryption Standard (AES) in Cipher Block Chaining 801 (CBC) mode with PKCS #5 padding [AES] [NIST.800-38A] using 128 or 256 802 bit keys. The "enc" header parameter values "A128CBC+HS256" or 803 "A256CBC+HS512" are respectively used in this case. 805 The CEK is used as the encryption key. 807 Use of an initialization vector of size 128 bits is REQUIRED with 808 these algorithms. 810 4.8.3. Integrity Calculation for "A128CBC+HS256" and "A256CBC+HS512" 812 This section defines the specifics of computing the JWE Integrity 813 Value for the "enc" algorithms "A128CBC+HS256" and "A256CBC+HS512". 814 This value is computed as a MAC of the JWE parameters to be secured. 816 The MAC input value is the bytes of the ASCII representation of the 817 concatenation of the Encoded JWE Header, a period ('.') character, 818 the Encoded JWE Encrypted Key, a second period character ('.'), the 819 Encoded JWE Initialization Vector, a third period ('.') character, 820 and the Encoded JWE Ciphertext. 822 The CIK is used as the MAC key. 824 For "A128CBC+HS256", HMAC SHA-256 is used as the MAC algorithm. For 825 "A256CBC+HS512", HMAC SHA-512 is used as the MAC algorithm. 827 The resulting MAC value is used as the JWE Integrity Value. The same 828 integrity calculation is performed during decryption. During 829 decryption, the computed integrity value must match the received JWE 830 Integrity Value. 832 4.9. Plaintext Encryption with AES GCM 834 This section defines the specifics of encrypting the JWE Plaintext 835 with Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) 836 [AES] [NIST.800-38D] using 128 or 256 bit keys. The "enc" header 837 parameter values "A128GCM" or "A256GCM" are used in this case. 839 The CMK is used as the encryption key. 841 Use of an initialization vector of size 96 bits is REQUIRED with this 842 algorithm. 844 The "additional authenticated data" parameter is used to secure the 845 header and key values. The "additional authenticated data" value 846 used is the bytes of the ASCII representation of the concatenation of 847 the Encoded JWE Header, a period ('.') character, the Encoded JWE 848 Encrypted Key, a second period character ('.'), and the Encoded JWE 849 Initialization Vector. This same "additional authenticated data" 850 value is used when decrypting as well. 852 The requested size of the "authentication tag" output MUST be 128 853 bits, regardless of the key size. 855 As GCM is an AEAD algorithm, the JWE Integrity Value is set to be the 856 "authentication tag" value produced by the encryption. During 857 decryption, the received JWE Integrity Value is used as the 858 "authentication tag" value. 860 Examples using this algorithm are shown in Appendices A.1 and A.3 of 861 [JWE]. 863 4.10. Additional Encryption Algorithms and Parameters 865 Additional algorithms MAY be used to protect JWEs with corresponding 866 "alg" (algorithm) and "enc" (encryption method) header parameter 867 values being defined to refer to them. New "alg" and "enc" header 868 parameter values SHOULD either be registered in the IANA JSON Web 869 Signature and Encryption Algorithms registry Section 6.1 or be a URI 870 that contains a Collision Resistant Namespace. In particular, it is 871 permissible to use the algorithm identifiers defined in XML 872 Encryption [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 873 [W3C.CR-xmlenc-core1-20120313], and related specifications as "alg" 874 and "enc" values. 876 As indicated by the common registry, JWSs and JWEs share a common 877 "alg" value space. The values used by the two specifications MUST be 878 distinct, as the "alg" value MAY be used to determine whether the 879 object is a JWS or JWE. 881 Likewise, additional reserved header parameter names MAY be defined 882 via the IANA JSON Web Signature and Encryption Header Parameters 883 registry [JWS]. As indicated by the common registry, JWSs and JWEs 884 share a common header parameter space; when a parameter is used by 885 both specifications, its usage must be compatible between the 886 specifications. 888 5. Cryptographic Algorithms for JWK 890 A JSON Web Key (JWK) [JWK] is a JavaScript Object Notation (JSON) 891 [RFC4627] data structure that represents a public key. A JSON Web 892 Key Set (JWK Set) is a JSON data structure for representing a set of 893 JWKs. This section specifies a set of algorithm families to be used 894 for those public keys and the algorithm family specific parameters 895 for representing those keys. 897 5.1. "alg" (Algorithm Family) Parameter Values for JWK 899 The table below is the set of "alg" (algorithm family) parameter 900 values that are defined by this specification for use in JWKs. 902 +-----------------+-------------------------+-----------------------+ 903 | alg Parameter | Algorithm Family | Implementation | 904 | Value | | Requirements | 905 +-----------------+-------------------------+-----------------------+ 906 | EC | Elliptic Curve [DSS] | RECOMMENDED+ | 907 | | key family | | 908 | RSA | RSA [RFC3447] key | REQUIRED | 909 | | family | | 910 +-----------------+-------------------------+-----------------------+ 912 All the names are short because a core goal of JWK is for the 913 representations to be compact. However, there is no a priori length 914 restriction on "alg" values. 916 The use of "+" in the Implementation Requirements indicates that the 917 requirement strength is likely to be increased in a future version of 918 the specification. 920 5.2. JWK Parameters for Elliptic Curve Keys 922 JWKs can represent Elliptic Curve [DSS] keys. In this case, the 923 "alg" member value MUST be "EC". Furthermore, these additional 924 members MUST be present: 926 5.2.1. "crv" (Curve) Parameter 928 The "crv" (curve) member identifies the cryptographic curve used with 929 the key. Curve values from [DSS] used by this specification are: 931 o "P-256" 933 o "P-384" 935 o "P-521" 937 Additional "crv" values MAY be used, provided they are understood by 938 implementations using that Elliptic Curve key. The "crv" value is a 939 case sensitive string. 941 5.2.2. "x" (X Coordinate) Parameter 943 The "x" (x coordinate) member contains the x coordinate for the 944 elliptic curve point. It is represented as the base64url encoding of 945 the coordinate's big endian representation as a byte array. The 946 array representation MUST not be shortened to omit any leading zero 947 bytes contained in the value. For instance, when representing 521 948 bit integers, the byte array to be base64url encoded MUST contain 66 949 bytes, including any leading zero bytes. 951 5.2.3. "y" (Y Coordinate) Parameter 953 The "y" (y coordinate) member contains the y coordinate for the 954 elliptic curve point. It is represented as the base64url encoding of 955 the coordinate's big endian representation as a byte array. The 956 array representation MUST not be shortened to omit any leading zero 957 bytes contained in the value. For instance, when representing 521 958 bit integers, the byte array to be base64url encoded MUST contain 66 959 bytes, including any leading zero bytes. 961 5.3. JWK Parameters for RSA Keys 963 JWKs can represent RSA [RFC3447] keys. In this case, the "alg" 964 member value MUST be "RSA". Furthermore, these additional members 965 MUST be present: 967 5.3.1. "mod" (Modulus) Parameter 969 The "mod" (modulus) member contains the modulus value for the RSA 970 public key. It is represented as the base64url encoding of the 971 value's unsigned big endian representation as a byte array. The 972 array representation MUST not be shortened to omit any leading zero 973 bytes. For instance, when representing 2048 bit integers, the byte 974 array to be base64url encoded MUST contain 256 bytes, including any 975 leading zero bytes. 977 5.3.2. "xpo" (Exponent) Parameter 979 The "xpo" (exponent) member contains the exponent value for the RSA 980 public key. It is represented as the base64url encoding of the 981 value's unsigned big endian representation as a byte array. The 982 array representation MUST utilize the minimum number of bytes to 983 represent the value. For instance, when representing the value 984 65537, the byte array to be base64url encoded MUST consist of the 985 three bytes [1, 0, 1]. 987 5.4. Additional Key Algorithm Families and Parameters 989 Public keys using additional algorithm families MAY be represented 990 using JWK data structures with corresponding "alg" (algorithm family) 991 parameter values being defined to refer to them. New "alg" parameter 992 values SHOULD either be registered in the IANA JSON Web Key Algorithm 993 Families registry Section 6.2 or be a URI that contains a Collision 994 Resistant Namespace. 996 Likewise, parameters for representing keys for additional algorithm 997 families or additional key properties SHOULD either be registered in 998 the IANA JSON Web Key Parameters registry [JWK] or be a URI that 999 contains a Collision Resistant Namespace. 1001 6. IANA Considerations 1003 The following registration procedure is used for all the registries 1004 established by this specification. 1006 Values are registered with a Specification Required [RFC5226] after a 1007 two-week review period on the [TBD]@ietf.org mailing list, on the 1008 advice of one or more Designated Experts. However, to allow for the 1009 allocation of values prior to publication, the Designated Expert(s) 1010 may approve registration once they are satisfied that such a 1011 specification will be published. 1013 Registration requests must be sent to the [TBD]@ietf.org mailing list 1014 for review and comment, with an appropriate subject (e.g., "Request 1015 for access token type: example"). [[ Note to RFC-EDITOR: The name of 1016 the mailing list should be determined in consultation with the IESG 1017 and IANA. Suggested name: jose-reg-review. ]] 1019 Within the review period, the Designated Expert(s) will either 1020 approve or deny the registration request, communicating this decision 1021 to the review list and IANA. Denials should include an explanation 1022 and, if applicable, suggestions as to how to make the request 1023 successful. 1025 IANA must only accept registry updates from the Designated Expert(s) 1026 and should direct all requests for registration to the review mailing 1027 list. 1029 6.1. JSON Web Signature and Encryption Algorithms Registry 1031 This specification establishes the IANA JSON Web Signature and 1032 Encryption Algorithms registry for values of the JWS and JWE "alg" 1033 (algorithm) and "enc" (encryption method) header parameters. The 1034 registry records the algorithm name, the algorithm usage locations 1035 from the set "alg" and "enc", implementation requirements, and a 1036 reference to the specification that defines it. The same algorithm 1037 name may be registered multiple times, provided that the sets of 1038 usage locations are disjoint. The implementation requirements of an 1039 algorithm may be changed over time by the Designated Experts(s) as 1040 the cryptographic landscape evolves, for instance, to change the 1041 status of an algorithm to DEPRECATED, or to change the status of an 1042 algorithm from OPTIONAL to RECOMMENDED or REQUIRED. 1044 6.1.1. Registration Template 1046 Algorithm Name: 1047 The name requested (e.g., "example"). This name is case 1048 sensitive. Names that match other registered names in a case 1049 insensitive manner SHOULD NOT be accepted. 1051 Algorithm Usage Location(s): 1052 The algorithm usage, which must be one or more of the values "alg" 1053 or "enc". 1055 Implementation Requirements: 1056 The algorithm implementation requirements, which must be one the 1057 words REQUIRED, RECOMMENDED, OPTIONAL, or DEPRECATED. Optionally, 1058 the word may be followed by a "+" or "-". The use of "+" 1059 indicates that the requirement strength is likely to be increased 1060 in a future version of the specification. The use of "-" 1061 indicates that the requirement strength is likely to be decreased 1062 in a future version of the specification. 1064 Change Controller: 1065 For Standards Track RFCs, state "IETF". For others, give the name 1066 of the responsible party. Other details (e.g., postal address, 1067 email address, home page URI) may also be included. 1069 Specification Document(s): 1070 Reference to the document(s) that specify the parameter, 1071 preferably including URI(s) that can be used to retrieve copies of 1072 the document(s). An indication of the relevant sections may also 1073 be included but is not required. 1075 6.1.2. Initial Registry Contents 1077 o Algorithm Name: "HS256" 1078 o Algorithm Usage Location(s): "alg" 1079 o Implementation Requirements: REQUIRED 1080 o Change Controller: IETF 1081 o Specification Document(s): Section 3.1 of [[ this document ]] 1083 o Algorithm Name: "HS384" 1084 o Algorithm Usage Location(s): "alg" 1085 o Implementation Requirements: OPTIONAL 1086 o Change Controller: IETF 1087 o Specification Document(s): Section 3.1 of [[ this document ]] 1089 o Algorithm Name: "HS512" 1090 o Algorithm Usage Location(s): "alg" 1091 o Implementation Requirements: OPTIONAL 1092 o Change Controller: IETF 1093 o Specification Document(s): Section 3.1 of [[ this document ]] 1095 o Algorithm Name: "RS256" 1096 o Algorithm Usage Location(s): "alg" 1097 o Implementation Requirements: RECOMMENDED 1098 o Change Controller: IETF 1099 o Specification Document(s): Section 3.1 of [[ this document ]] 1100 o Algorithm Name: "RS384" 1101 o Algorithm Usage Location(s): "alg" 1102 o Implementation Requirements: OPTIONAL 1103 o Change Controller: IETF 1104 o Specification Document(s): Section 3.1 of [[ this document ]] 1106 o Algorithm Name: "RS512" 1107 o Algorithm Usage Location(s): "alg" 1108 o Implementation Requirements: OPTIONAL 1109 o Change Controller: IETF 1110 o Specification Document(s): Section 3.1 of [[ this document ]] 1112 o Algorithm Name: "ES256" 1113 o Algorithm Usage Location(s): "alg" 1114 o Implementation Requirements: RECOMMENDED+ 1115 o Change Controller: IETF 1116 o Specification Document(s): Section 3.1 of [[ this document ]] 1118 o Algorithm Name: "ES384" 1119 o Algorithm Usage Location(s): "alg" 1120 o Implementation Requirements: OPTIONAL 1121 o Change Controller: IETF 1122 o Specification Document(s): Section 3.1 of [[ this document ]] 1124 o Algorithm Name: "ES512" 1125 o Algorithm Usage Location(s): "alg" 1126 o Implementation Requirements: OPTIONAL 1127 o Change Controller: IETF 1128 o Specification Document(s): Section 3.1 of [[ this document ]] 1130 o Algorithm Name: "none" 1131 o Algorithm Usage Location(s): "alg" 1132 o Implementation Requirements: REQUIRED 1133 o Change Controller: IETF 1134 o Specification Document(s): Section 3.1 of [[ this document ]] 1136 o Algorithm Name: "RSA1_5" 1137 o Algorithm Usage Location(s): "alg" 1138 o Implementation Requirements: REQUIRED 1139 o Change Controller: IETF 1140 o Specification Document(s): Section 4.1 of [[ this document ]] 1142 o Algorithm Name: "RSA-OAEP" 1143 o Algorithm Usage Location(s): "alg" 1144 o Implementation Requirements: OPTIONAL 1145 o Change Controller: IETF 1146 o Specification Document(s): Section 4.1 of [[ this document ]] 1148 o Algorithm Name: "A128KW" 1149 o Algorithm Usage Location(s): "alg" 1150 o Implementation Requirements: RECOMMENDED 1151 o Change Controller: IETF 1152 o Specification Document(s): Section 4.1 of [[ this document ]] 1154 o Algorithm Name: "A256KW" 1155 o Algorithm Usage Location(s): "alg" 1156 o Implementation Requirements: RECOMMENDED 1157 o Change Controller: IETF 1158 o Specification Document(s): Section 4.1 of [[ this document ]] 1160 o Algorithm Name: "dir" 1161 o Algorithm Usage Location(s): "alg" 1162 o Implementation Requirements: RECOMMENDED 1163 o Change Controller: IETF 1164 o Specification Document(s): Section 4.1 of [[ this document ]] 1166 o Algorithm Name: "ECDH-ES" 1167 o Algorithm Usage Location(s): "alg" 1168 o Implementation Requirements: RECOMMENDED+ 1169 o Change Controller: IETF 1170 o Specification Document(s): Section 4.1 of [[ this document ]] 1172 o Algorithm Name: "ECDH-ES+A128KW" 1173 o Algorithm Usage Location(s): "alg" 1174 o Implementation Requirements: RECOMMENDED 1175 o Change Controller: IETF 1176 o Specification Document(s): Section 4.1 of [[ this document ]] 1178 o Algorithm Name: "ECDH-ES+A256KW" 1179 o Algorithm Usage Location(s): "alg" 1180 o Implementation Requirements: RECOMMENDED 1181 o Change Controller: IETF 1182 o Specification Document(s): Section 4.1 of [[ this document ]] 1184 o Algorithm Name: "A128CBC+HS256" 1185 o Algorithm Usage Location(s): "enc" 1186 o Implementation Requirements: REQUIRED 1187 o Change Controller: IETF 1188 o Specification Document(s): Section 4.2 of [[ this document ]] 1190 o Algorithm Name: "A256CBC+HS512" 1191 o Algorithm Usage Location(s): "enc" 1192 o Implementation Requirements: REQUIRED 1193 o Change Controller: IETF 1194 o Specification Document(s): Section 4.2 of [[ this document ]] 1196 o Algorithm Name: "A128GCM" 1197 o Algorithm Usage Location(s): "enc" 1198 o Implementation Requirements: RECOMMENDED 1199 o Change Controller: IETF 1200 o Specification Document(s): Section 4.2 of [[ this document ]] 1202 o Algorithm Name: "A256GCM" 1203 o Algorithm Usage Location(s): "enc" 1204 o Implementation Requirements: RECOMMENDED 1205 o Change Controller: IETF 1206 o Specification Document(s): Section 4.2 of [[ this document ]] 1208 6.2. JSON Web Key Algorithm Families Registry 1210 This specification establishes the IANA JSON Web Key Algorithm 1211 Families registry for values of the JWK "alg" (algorithm family) 1212 parameter. The registry records the "alg" value and a reference to 1213 the specification that defines it. This specification registers the 1214 values defined in Section 5.1. 1216 6.2.1. Registration Template 1218 "alg" Parameter Value: 1219 The name requested (e.g., "example"). This name is case 1220 sensitive. Names that match other registered names in a case 1221 insensitive manner SHOULD NOT be accepted. 1223 Change Controller: 1224 For Standards Track RFCs, state "IETF". For others, give the name 1225 of the responsible party. Other details (e.g., postal address, 1226 email address, home page URI) may also be included. 1228 Implementation Requirements: 1229 The algorithm implementation requirements, which must be one the 1230 words REQUIRED, RECOMMENDED, OPTIONAL, or DEPRECATED. Optionally, 1231 the word may be followed by a "+" or "-". The use of "+" 1232 indicates that the requirement strength is likely to be increased 1233 in a future version of the specification. The use of "-" 1234 indicates that the requirement strength is likely to be decreased 1235 in a future version of the specification. 1237 Specification Document(s): 1238 Reference to the document(s) that specify the parameter, 1239 preferably including URI(s) that can be used to retrieve copies of 1240 the document(s). An indication of the relevant sections may also 1241 be included but is not required. 1243 6.2.2. Initial Registry Contents 1245 o "alg" Parameter Value: "EC" 1246 o Implementation Requirements: RECOMMENDED+ 1247 o Change Controller: IETF 1248 o Specification Document(s): Section 5.1 of [[ this document ]] 1250 o "alg" Parameter Value: "RSA" 1251 o Implementation Requirements: REQUIRED 1252 o Change Controller: IETF 1253 o Specification Document(s): Section 5.1 of [[ this document ]] 1255 6.3. JSON Web Key Parameters Registration 1257 This specification registers the parameter names defined in Sections 1258 5.2 and 5.3 in the IANA JSON Web Key Parameters registry [JWK]. 1260 6.3.1. Registry Contents 1262 o Parameter Name: "crv" 1263 o Change Controller: IETF 1264 o Specification Document(s): Section 5.2.1 of [[ this document ]] 1266 o Parameter Name: "x" 1267 o Change Controller: IETF 1268 o Specification Document(s): Section 5.2.2 of [[ this document ]] 1270 o Parameter Name: "y" 1271 o Change Controller: IETF 1272 o Specification Document(s): Section 5.2.3 of [[ this document ]] 1274 o Parameter Name: "mod" 1275 o Change Controller: IETF 1276 o Specification Document(s): Section 5.3.1 of [[ this document ]] 1278 o Parameter Name: "xpo" 1279 o Change Controller: IETF 1280 o Specification Document(s): Section 5.3.2 of [[ this document ]] 1282 7. Security Considerations 1284 All of the security issues faced by any cryptographic application 1285 must be faced by a JWS/JWE/JWK agent. Among these issues are 1286 protecting the user's private key, preventing various attacks, and 1287 helping the user avoid mistakes such as inadvertently encrypting a 1288 message for the wrong recipient. The entire list of security 1289 considerations is beyond the scope of this document, but some 1290 significant concerns are listed here. 1292 The security considerations in [AES], [DSS], [JWE], [JWK], [JWS], 1293 [NIST.800-38A], [NIST.800-38D], [NIST.800-56A], [RFC2104], [RFC3394], 1294 [RFC3447], [RFC5116], [RFC6090], and [SHS] apply to this 1295 specification. 1297 Eventually the algorithms and/or key sizes currently described in 1298 this specification will no longer be considered sufficiently secure 1299 and will be removed. Therefore, implementers and deployments must be 1300 prepared for this eventuality. 1302 Algorithms of matching strength should be used together whenever 1303 possible. For instance, when AES Key Wrap is used with a given key 1304 size, using the same key size is recommended when AES GCM is also 1305 used. 1307 While Section 8 of RFC 3447 [RFC3447] explicitly calls for people not 1308 to adopt RSASSA-PKCS1 for new applications and instead requests that 1309 people transition to RSASSA-PSS, this specification does include 1310 RSASSA-PKCS1, for interoperability reasons, because it commonly 1311 implemented. 1313 Keys used with RSAES-PKCS1-v1_5 must follow the constraints in 1314 Section 7.2 of RFC 3447 [RFC3447]. In particular, keys with a low 1315 public key exponent value must not be used. 1317 Plaintext JWSs (JWSs that use the "alg" value "none") provide no 1318 integrity protection. Thus, they must only be used in contexts where 1319 the payload is secured by means other than a digital signature or MAC 1320 value, or need not be secured. 1322 Receiving agents that validate signatures and sending agents that 1323 encrypt messages need to be cautious of cryptographic processing 1324 usage when validating signatures and encrypting messages using keys 1325 larger than those mandated in this specification. An attacker could 1326 send certificates with keys that would result in excessive 1327 cryptographic processing, for example, keys larger than those 1328 mandated in this specification, which could swamp the processing 1329 element. Agents that use such keys without first validating the 1330 certificate to a trust anchor are advised to have some sort of 1331 cryptographic resource management system to prevent such attacks. 1333 8. References 1335 8.1. Normative References 1337 [AES] National Institute of Standards and Technology (NIST), 1338 "Advanced Encryption Standard (AES)", FIPS PUB 197, 1339 November 2001. 1341 [DSS] National Institute of Standards and Technology, "Digital 1342 Signature Standard (DSS)", FIPS PUB 186-3, June 2009. 1344 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 1345 Encryption (JWE)", October 2012. 1347 [JWK] Jones, M., "JSON Web Key (JWK)", October 2012. 1349 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1350 Signature (JWS)", October 2012. 1352 [NIST.800-38A] 1353 National Institute of Standards and Technology (NIST), 1354 "Recommendation for Block Cipher Modes of Operation", 1355 NIST PUB 800-38A, December 2001. 1357 [NIST.800-38D] 1358 National Institute of Standards and Technology (NIST), 1359 "Recommendation for Block Cipher Modes of Operation: 1360 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 1361 December 2001. 1363 [NIST.800-56A] 1364 National Institute of Standards and Technology (NIST), 1365 "Recommendation for Pair-Wise Key Establishment Schemes 1366 Using Discrete Logarithm Cryptography (Revised)", NIST PUB 1367 800-56A, March 2007. 1369 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 1370 Hashing for Message Authentication", RFC 2104, 1371 February 1997. 1373 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1374 Requirement Levels", BCP 14, RFC 2119, March 1997. 1376 [RFC3394] Schaad, J. and R. Housley, "Advanced Encryption Standard 1377 (AES) Key Wrap Algorithm", RFC 3394, September 2002. 1379 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1380 Standards (PKCS) #1: RSA Cryptography Specifications 1381 Version 2.1", RFC 3447, February 2003. 1383 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1384 10646", STD 63, RFC 3629, November 2003. 1386 [RFC4627] Crockford, D., "The application/json Media Type for 1387 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1389 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1390 Encodings", RFC 4648, October 2006. 1392 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 1393 Encryption", RFC 5116, January 2008. 1395 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1396 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1397 May 2008. 1399 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 1400 Curve Cryptography Algorithms", RFC 6090, February 2011. 1402 [SHS] National Institute of Standards and Technology, "Secure 1403 Hash Standard (SHS)", FIPS PUB 180-3, October 2008. 1405 [USASCII] American National Standards Institute, "Coded Character 1406 Set -- 7-bit American Standard Code for Information 1407 Interchange", ANSI X3.4, 1986. 1409 8.2. Informative References 1411 [CanvasApp] 1412 Facebook, "Canvas Applications", 2010. 1414 [I-D.rescorla-jsms] 1415 Rescorla, E. and J. Hildebrand, "JavaScript Message 1416 Security Format", draft-rescorla-jsms-00 (work in 1417 progress), March 2011. 1419 [JCA] Oracle, "Java Cryptography Architecture", 2011. 1421 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1422 Encryption", September 2010. 1424 [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", 1425 September 2010. 1427 [MagicSignatures] 1428 Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic 1429 Signatures", January 2011. 1431 [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup 1432 Language) XML-Signature Syntax and Processing", RFC 3275, 1433 March 2002. 1435 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1436 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1437 July 2005. 1439 [W3C.CR-xmldsig-core2-20120124] 1440 Roessler, T., Yiu, K., Solo, D., Reagle, J., Datta, P., 1441 Eastlake, D., Hirsch, F., and S. Cantor, "XML Signature 1442 Syntax and Processing Version 2.0", World Wide Web 1443 Consortium CR CR-xmldsig-core2-20120124, January 2012, 1444 . 1446 [W3C.CR-xmlenc-core1-20120313] 1447 Eastlake, D., Reagle, J., Hirsch, F., and T. Roessler, 1448 "XML Encryption Syntax and Processing Version 1.1", World 1449 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1450 March 2012, 1451 . 1453 [W3C.REC-xmlenc-core-20021210] 1454 Eastlake, D. and J. Reagle, "XML Encryption Syntax and 1455 Processing", World Wide Web Consortium Recommendation REC- 1456 xmlenc-core-20021210, December 2002, 1457 . 1459 Appendix A. Digital Signature/MAC Algorithm Identifier Cross-Reference 1461 This appendix contains a table cross-referencing the digital 1462 signature and MAC "alg" (algorithm) values used in this specification 1463 with the equivalent identifiers used by other standards and software 1464 packages. See XML DSIG [RFC3275], XML DSIG 2.0 1465 [W3C.CR-xmldsig-core2-20120124], and Java Cryptography Architecture 1466 [JCA] for more information about the names defined by those 1467 documents. 1469 +-------+-----+----------------------------+----------+-------------+ 1470 | Algor | JWS | XML DSIG | JCA | OID | 1471 | ithm | | | | | 1472 +-------+-----+----------------------------+----------+-------------+ 1473 | HMAC | HS2 | http://www.w3.org/2001/04/ | HmacSHA2 | 1.2.840.113 | 1474 | using | 56 | xmldsig-more#hmac-sha256 | 56 | 549.2.9 | 1475 | SHA-2 | | | | | 1476 | 56 | | | | | 1477 | hash | | | | | 1478 | algo | | | | | 1479 | rithm | | | | | 1480 | HMAC | HS3 | http://www.w3.org/2001/04/ | HmacSHA3 | 1.2.840.113 | 1481 | using | 84 | xmldsig-more#hmac-sha384 | 84 | 549.2.10 | 1482 | SHA-3 | | | | | 1483 | 84 | | | | | 1484 | hash | | | | | 1485 | algo | | | | | 1486 | rithm | | | | | 1487 | HMAC | HS5 | http://www.w3.org/2001/04/ | HmacSHA5 | 1.2.840.113 | 1488 | using | 12 | xmldsig-more#hmac-sha512 | 12 | 549.2.11 | 1489 | SHA-5 | | | | | 1490 | 12 | | | | | 1491 | hash | | | | | 1492 | algo | | | | | 1493 | rithm | | | | | 1494 | RSASS | RS2 | http://www.w3.org/2001/04/ | SHA256wi | 1.2.840.113 | 1495 | A | 56 | xmldsig-more#rsa-sha256 | thRSA | 549.1.1.11 | 1496 | usin | | | | | 1497 | gSHA- | | | | | 1498 | 256 | | | | | 1499 | has | | | | | 1500 | h alg | | | | | 1501 | orith | | | | | 1502 | m | | | | | 1503 | RSASS | RS3 | http://www.w3.org/2001/04/ | SHA384wi | 1.2.840.113 | 1504 | A | 84 | xmldsig-more#rsa-sha384 | thRSA | 549.1.1.12 | 1505 | usin | | | | | 1506 | gSHA- | | | | | 1507 | 384 | | | | | 1508 | has | | | | | 1509 | h alg | | | | | 1510 | orith | | | | | 1511 | m | | | | | 1512 | RSASS | RS5 | http://www.w3.org/2001/04/ | SHA512wi | 1.2.840.113 | 1513 | A | 12 | xmldsig-more#rsa-sha512 | thRSA | 549.1.1.13 | 1514 | usin | | | | | 1515 | gSHA- | | | | | 1516 | 512 | | | | | 1517 | has | | | | | 1518 | h alg | | | | | 1519 | orith | | | | | 1520 | m | | | | | 1521 | ECDSA | ES2 | http://www.w3.org/2001/04/ | SHA256wi | 1.2.840.100 | 1522 | using | 56 | xmldsig-more#ecdsa-sha256 | thECDSA | 45.4.3.2 | 1523 | P-256 | | | | | 1524 | curve | | | | | 1525 | and | | | | | 1526 | SHA-2 | | | | | 1527 | 56 | | | | | 1528 | hash | | | | | 1529 | algo | | | | | 1530 | rithm | | | | | 1531 | ECDSA | ES3 | http://www.w3.org/2001/04/ | SHA384wi | 1.2.840.100 | 1532 | using | 84 | xmldsig-more#ecdsa-sha384 | thECDSA | 45.4.3.3 | 1533 | P-384 | | | | | 1534 | curve | | | | | 1535 | and | | | | | 1536 | SHA-3 | | | | | 1537 | 84 | | | | | 1538 | hash | | | | | 1539 | algo | | | | | 1540 | rithm | | | | | 1541 | ECDSA | ES5 | http://www.w3.org/2001/04/ | SHA512wi | 1.2.840.100 | 1542 | using | 12 | xmldsig-more#ecdsa-sha512 | thECDSA | 45.4.3.4 | 1543 | P-521 | | | | | 1544 | curve | | | | | 1545 | and | | | | | 1546 | SHA-5 | | | | | 1547 | 12 | | | | | 1548 | hash | | | | | 1549 | algo | | | | | 1550 | rithm | | | | | 1551 +-------+-----+----------------------------+----------+-------------+ 1553 Appendix B. Encryption Algorithm Identifier Cross-Reference 1555 This appendix contains a table cross-referencing the "alg" 1556 (algorithm) and "enc" (encryption method) values used in this 1557 specification with the equivalent identifiers used by other standards 1558 and software packages. See XML Encryption 1560 [W3C.REC-xmlenc-core-20021210], XML Encryption 1.1 1561 [W3C.CR-xmlenc-core1-20120313], and Java Cryptography Architecture 1562 [JCA] for more information about the names defined by those 1563 documents. 1565 For the composite algorithms "A128CBC+HS256" and "A256CBC+HS512", the 1566 corresponding AES CBC algorithm identifiers are listed. 1568 +----------+--------+--------------------------+--------------------+ 1569 | Algorith | JWE | XML ENC | JCA | 1570 | m | | | | 1571 +----------+--------+--------------------------+--------------------+ 1572 | RSAES-PK | RSA1_5 | http://www.w3.org/2001/0 | RSA/ECB/PKCS1Paddi | 1573 | CS1-V1_5 | | 4/xmlenc#rsa-1_5 | ng | 1574 | RSAES | RSA-OA | http://www.w3.org/2001/0 | RSA/ECB/OAEPWithSH | 1575 | using | EP | 4/xmlenc#rsa-oaep-mgf1p | A-1AndMGF1Padding | 1576 | Optimal | | | | 1577 | Asymmetr | | | | 1578 | ic | | | | 1579 | Encrypt | | | | 1580 | ion | | | | 1581 | Paddin | | | | 1582 | g (OAEP) | | | | 1583 | Elliptic | ECDH-E | http://www.w3.org/2009/x | | 1584 | Curve | S | mlenc11#ECDH-ES | | 1585 | Diffie-H | | | | 1586 | ellman | | | | 1587 | Ephemer | | | | 1588 | alStatic | | | | 1589 | Advanced | A128KW | http://www.w3.org/2001/0 | | 1590 | Encrypti | | 4/xmlenc#kw-aes128 | | 1591 | on | | | | 1592 | Standar | | | | 1593 | d(AES) | | | | 1594 | Key Wra | | | | 1595 | pAlgorit | | | | 1596 | hmusing | | | | 1597 | 128 bi | | | | 1598 | t keys | | | | 1599 | AES Key | A256KW | http://www.w3.org/2001/0 | | 1600 | Wrap | | 4/xmlenc#kw-aes256 | | 1601 | Algorith | | | | 1602 | musing | | | | 1603 | 256 bit | | | | 1604 | keys | | | | 1605 | AES in | A128CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 1606 | Cipher | C+HS25 | 4/xmlenc#aes128-cbc | ng | 1607 | Block | 6 | | | 1608 | Chaining | | | | 1609 | (CBC) | | | | 1610 | mode | | | | 1611 | with | | | | 1612 | PKCS #5 | | | | 1613 | padding | | | | 1614 | using | | | | 1615 | 128 bit | | | | 1616 | keys | | | | 1617 | AES in | A256CB | http://www.w3.org/2001/0 | AES/CBC/PKCS5Paddi | 1618 | CBC mode | C+HS51 | 4/xmlenc#aes256-cbc | ng | 1619 | with | 2 | | | 1620 | PKCS #5 | | | | 1621 | padding | | | | 1622 | using | | | | 1623 | 256 bit | | | | 1624 | keys | | | | 1625 | AES in | A128GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 1626 | Galois/C | M | mlenc11#aes128-gcm | | 1627 | ounter | | | | 1628 | Mode | | | | 1629 | (GCM) | | | | 1630 | using | | | | 1631 | 128 bit | | | | 1632 | keys | | | | 1633 | AES GCM | A256GC | http://www.w3.org/2009/x | AES/GCM/NoPadding | 1634 | using | M | mlenc11#aes256-gcm | | 1635 | 256 bit | | | | 1636 | keys | | | | 1637 +----------+--------+--------------------------+--------------------+ 1639 Appendix C. Acknowledgements 1641 Solutions for signing and encrypting JSON content were previously 1642 explored by Magic Signatures [MagicSignatures], JSON Simple Sign 1643 [JSS], Canvas Applications [CanvasApp], JSON Simple Encryption [JSE], 1644 and JavaScript Message Security Format [I-D.rescorla-jsms], all of 1645 which influenced this draft. Dirk Balfanz, John Bradley, Yaron Y. 1646 Goland, John Panzer, Nat Sakimura, and Paul Tarjan all made 1647 significant contributions to the design of this specification and its 1648 related specifications. 1650 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 1651 Sean Turner and Stephen Farrell served as Security area directors 1652 during the creation of this specification. 1654 Appendix D. Open Issues 1656 [[ to be removed by the RFC editor before publication as an RFC ]] 1658 The following items remain to be considered or done in this draft: 1660 o No known open issues. 1662 Appendix E. Document History 1664 [[ to be removed by the RFC editor before publication as an RFC ]] 1666 -06 1668 o Removed the "int" and "kdf" parameters and defined the new 1669 composite AEAD algorithms "A128CBC+HS256" and "A256CBC+HS512" to 1670 replace the former uses of AES CBC, which required the use of 1671 separate integrity and key derivation functions. 1673 o Included additional values in the Concat KDF calculation -- the 1674 desired output size and the algorithm value, and optionally 1675 PartyUInfo and PartyVInfo values. Added the optional header 1676 parameters "apu" (agreement PartyUInfo), "apv" (agreement 1677 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 1678 PartyVInfo). 1680 o Changed the name of the JWK RSA exponent parameter from "exp" to 1681 "xpo" so as to allow the potential use of the name "exp" for a 1682 future extension that might define an expiration parameter for 1683 keys. (The "exp" name is already used for this purpose in the JWT 1684 specification.) 1686 o Applied changes made by the RFC Editor to RFC 6749's registry 1687 language to this specification. 1689 -05 1691 o Support both direct encryption using a shared or agreed upon 1692 symmetric key, and the use of a shared or agreed upon symmetric 1693 key to key wrap the CMK. Specifically, added the "alg" values 1694 "dir", "ECDH-ES+A128KW", and "ECDH-ES+A256KW" to finish filling in 1695 this set of capabilities. 1697 o Updated open issues. 1699 -04 1701 o Added text requiring that any leading zero bytes be retained in 1702 base64url encoded key value representations for fixed-length 1703 values. 1705 o Added this language to Registration Templates: "This name is case 1706 sensitive. Names that match other registered names in a case 1707 insensitive manner SHOULD NOT be accepted." 1709 o Described additional open issues. 1711 o Applied editorial suggestions. 1713 -03 1715 o Always use a 128 bit "authentication tag" size for AES GCM, 1716 regardless of the key size. 1718 o Specified that use of a 128 bit IV is REQUIRED with AES CBC. It 1719 was previously RECOMMENDED. 1721 o Removed key size language for ECDSA algorithms, since the key size 1722 is implied by the algorithm being used. 1724 o Stated that the "int" key size must be the same as the hash output 1725 size (and not larger, as was previously allowed) so that its size 1726 is defined for key generation purposes. 1728 o Added the "kdf" (key derivation function) header parameter to 1729 provide crypto agility for key derivation. The default KDF 1730 remains the Concat KDF with the SHA-256 digest function. 1732 o Clarified that the "mod" and "exp" values are unsigned. 1734 o Added Implementation Requirements columns to algorithm tables and 1735 Implementation Requirements entries to algorithm registries. 1737 o Changed AES Key Wrap to RECOMMENDED. 1739 o Moved registries JSON Web Signature and Encryption Header 1740 Parameters and JSON Web Signature and Encryption Type Values to 1741 the JWS specification. 1743 o Moved JSON Web Key Parameters registry to the JWK specification. 1745 o Changed registration requirements from RFC Required to 1746 Specification Required with Expert Review. 1748 o Added Registration Template sections for defined registries. 1750 o Added Registry Contents sections to populate registry values. 1752 o No longer say "the UTF-8 representation of the JWS Secured Input 1753 (which is the same as the ASCII representation)". Just call it 1754 "the ASCII representation of the JWS Secured Input". 1756 o Added "Collision Resistant Namespace" to the terminology section. 1758 o Numerous editorial improvements. 1760 -02 1762 o For AES GCM, use the "additional authenticated data" parameter to 1763 provide integrity for the header, encrypted key, and ciphertext 1764 and use the resulting "authentication tag" value as the JWE 1765 Integrity Value. 1767 o Defined minimum required key sizes for algorithms without 1768 specified key sizes. 1770 o Defined KDF output key sizes. 1772 o Specified the use of PKCS #5 padding with AES CBC. 1774 o Generalized text to allow key agreement to be employed as an 1775 alternative to key wrapping or key encryption. 1777 o Clarified that ECDH-ES is a key agreement algorithm. 1779 o Required implementation of AES-128-KW and AES-256-KW. 1781 o Removed the use of "A128GCM" and "A256GCM" for key wrapping. 1783 o Removed "A512KW" since it turns out that it's not a standard 1784 algorithm. 1786 o Clarified the relationship between "typ" header parameter values 1787 and MIME types. 1789 o Generalized language to refer to Message Authentication Codes 1790 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 1791 unless in a context specific to HMAC algorithms. 1793 o Established registries: JSON Web Signature and Encryption Header 1794 Parameters, JSON Web Signature and Encryption Algorithms, JSON Web 1795 Signature and Encryption "typ" Values, JSON Web Key Parameters, 1796 and JSON Web Key Algorithm Families. 1798 o Moved algorithm-specific definitions from JWK to JWA. 1800 o Reformatted to give each member definition its own section 1801 heading. 1803 -01 1805 o Moved definition of "alg":"none" for JWSs here from the JWT 1806 specification since this functionality is likely to be useful in 1807 more contexts that just for JWTs. 1809 o Added Advanced Encryption Standard (AES) Key Wrap Algorithm using 1810 512 bit keys ("A512KW"). 1812 o Added text "Alternatively, the Encoded JWS Signature MAY be 1813 base64url decoded to produce the JWS Signature and this value can 1814 be compared with the computed HMAC value, as this comparison 1815 produces the same result as comparing the encoded values". 1817 o Corrected the Magic Signatures reference. 1819 o Made other editorial improvements suggested by JOSE working group 1820 participants. 1822 -00 1824 o Created the initial IETF draft based upon 1825 draft-jones-json-web-signature-04 and 1826 draft-jones-json-web-encryption-02 with no normative changes. 1828 o Changed terminology to no longer call both digital signatures and 1829 HMACs "signatures". 1831 Author's Address 1833 Michael B. Jones 1834 Microsoft 1836 Email: mbj@microsoft.com 1837 URI: http://self-issued.info/