idnits 2.17.1 draft-ietf-jose-json-web-encryption-10.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 25, 2013) is 4013 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 1745 -- Looks like a reference, but probably isn't: '0' on line 2144 -- Looks like a reference, but probably isn't: '227' on line 1557 -- Looks like a reference, but probably isn't: '197' on line 1557 -- Looks like a reference, but probably isn't: '117' on line 1557 -- Looks like a reference, but probably isn't: '252' on line 1557 -- Looks like a reference, but probably isn't: '2' on line 1557 -- Looks like a reference, but probably isn't: '219' on line 1557 -- Looks like a reference, but probably isn't: '233' on line 1557 -- Looks like a reference, but probably isn't: '68' on line 1557 -- Looks like a reference, but probably isn't: '180' on line 1557 -- Looks like a reference, but probably isn't: '225' on line 1557 -- Looks like a reference, but probably isn't: '77' on line 1557 -- Looks like a reference, but probably isn't: '3' on line 2144 -- Looks like a reference, but probably isn't: '80' on line 2144 -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X690.1994' ** Downref: Normative reference to an Historic RFC: RFC 1421 ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 4288 (Obsoleted by RFC 6838) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) == Outdated reference: A later version (-05) exists of draft-mcgrew-aead-aes-cbc-hmac-sha2-01 Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 17 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 E. Rescorla 5 Expires: October 27, 2013 RTFM 6 J. Hildebrand 7 Cisco 8 April 25, 2013 10 JSON Web Encryption (JWE) 11 draft-ietf-jose-json-web-encryption-10 13 Abstract 15 JSON Web Encryption (JWE) is a means of representing encrypted 16 content using JavaScript Object Notation (JSON) data structures. 17 Cryptographic algorithms and identifiers for use with this 18 specification are described in the separate JSON Web Algorithms (JWA) 19 specification. Related digital signature and MAC capabilities are 20 described in the separate JSON Web Signature (JWS) specification. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on October 27, 2013. 39 Copyright Notice 41 Copyright (c) 2013 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 58 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 8 60 3.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 8 61 3.2. Example JWE using RSAES-PKCS1-V1_5 and 62 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 10 63 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11 64 4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 12 65 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 12 66 4.1.2. "enc" (Encryption Method) Header Parameter . . . . . . 12 67 4.1.3. "epk" (Ephemeral Public Key) Header Parameter . . . . 13 68 4.1.4. "zip" (Compression Algorithm) Header Parameter . . . . 13 69 4.1.5. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 13 70 4.1.6. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 13 71 4.1.7. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 13 72 4.1.8. "x5t" (X.509 Certificate Thumbprint) Header 73 Parameter . . . . . . . . . . . . . . . . . . . . . . 14 74 4.1.9. "x5c" (X.509 Certificate Chain) Header Parameter . . . 14 75 4.1.10. "kid" (Key ID) Header Parameter . . . . . . . . . . . 15 76 4.1.11. "typ" (Type) Header Parameter . . . . . . . . . . . . 15 77 4.1.12. "cty" (Content Type) Header Parameter . . . . . . . . 15 78 4.1.13. "apu" (Agreement PartyUInfo) Header Parameter . . . . 15 79 4.1.14. "apv" (Agreement PartyVInfo) Header Parameter . . . . 16 80 4.1.15. "crit" (Critical) Header Parameter . . . . . . . . . . 16 81 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 16 82 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 16 83 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 17 84 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 17 85 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 19 86 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 21 87 6. Encrypting JWEs with Cryptographic Algorithms . . . . . . . . 21 88 6.1. CEK Encryption . . . . . . . . . . . . . . . . . . . . . . 22 89 7. JSON Serialization . . . . . . . . . . . . . . . . . . . . . . 22 90 7.1. Example JWE-JS . . . . . . . . . . . . . . . . . . . . . . 23 91 8. Implementation Considerations . . . . . . . . . . . . . . . . 25 92 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 93 9.1. Registration of JWE Header Parameter Names . . . . . . . . 25 94 9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25 95 9.2. JSON Web Signature and Encryption Type Values 96 Registration . . . . . . . . . . . . . . . . . . . . . . . 27 97 9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 27 98 9.3. Media Type Registration . . . . . . . . . . . . . . . . . 27 99 9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 27 100 10. Security Considerations . . . . . . . . . . . . . . . . . . . 29 101 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 102 11.1. Normative References . . . . . . . . . . . . . . . . . . . 29 103 11.2. Informative References . . . . . . . . . . . . . . . . . . 31 104 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 31 105 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 31 106 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 32 107 A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 32 108 A.1.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 32 109 A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 32 110 A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 35 111 A.1.6. Initialization Vector . . . . . . . . . . . . . . . . 35 112 A.1.7. Additional Authenticated Data Parameter . . . . . . . 35 113 A.1.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 36 114 A.1.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 36 115 A.1.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 37 116 A.1.11. Complete Representation . . . . . . . . . . . . . . . 37 117 A.1.12. Validation . . . . . . . . . . . . . . . . . . . . . . 37 118 A.2. Example JWE using RSAES-PKCS1-V1_5 and 119 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 37 120 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 38 121 A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 38 122 A.2.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 38 123 A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 38 124 A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 41 125 A.2.6. Initialization Vector . . . . . . . . . . . . . . . . 41 126 A.2.7. Additional Authenticated Data Parameter . . . . . . . 41 127 A.2.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 42 128 A.2.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 42 129 A.2.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 43 130 A.2.11. Complete Representation . . . . . . . . . . . . . . . 43 131 A.2.12. Validation . . . . . . . . . . . . . . . . . . . . . . 43 132 A.3. Example JWE using AES Key Wrap and AES GCM . . . . . . . . 43 133 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 44 134 A.3.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 44 135 A.3.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 44 136 A.3.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 44 137 A.3.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 45 138 A.3.6. Initialization Vector . . . . . . . . . . . . . . . . 45 139 A.3.7. Additional Authenticated Data Parameter . . . . . . . 45 140 A.3.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 45 141 A.3.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 46 142 A.3.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 46 143 A.3.11. Complete Representation . . . . . . . . . . . . . . . 46 144 A.3.12. Validation . . . . . . . . . . . . . . . . . . . . . . 46 145 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 47 146 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 47 147 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 47 148 B.3. Create 64 Bit Big Endian Representation of AAD Length . . 48 149 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 48 150 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 48 151 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 49 152 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 49 153 Appendix C. Possible Compact Serialization for Multiple 154 Recipients . . . . . . . . . . . . . . . . . . . . . 49 155 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 50 156 Appendix E. Document History . . . . . . . . . . . . . . . . . . 51 157 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 56 159 1. Introduction 161 JSON Web Encryption (JWE) is a compact encryption format intended for 162 space constrained environments such as HTTP Authorization headers and 163 URI query parameters. It represents this content using JavaScript 164 Object Notation (JSON) [RFC4627] based data structures. The JWE 165 cryptographic mechanisms encrypt and provide integrity protection for 166 arbitrary sequences of octets. 168 Cryptographic algorithms and identifiers for use with this 169 specification are described in the separate JSON Web Algorithms (JWA) 170 [JWA] specification. Related digital signature and MAC capabilities 171 are described in the separate JSON Web Signature (JWS) [JWS] 172 specification. 174 1.1. Notational Conventions 176 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 177 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 178 document are to be interpreted as described in Key words for use in 179 RFCs to Indicate Requirement Levels [RFC2119]. 181 2. Terminology 183 JSON Web Encryption (JWE) A data structure representing an encrypted 184 message. The structure represents five values: the JWE Header, 185 the JWE Encrypted Key, the JWE Initialization Vector, the JWE 186 Ciphertext, and the JWE Authentication Tag. 188 Authenticated Encryption An Authenticated Encryption algorithm is 189 one that provides an integrated content integrity check. 190 Authenticated Encryption algorithms accept two inputs, the 191 Plaintext and the Additional Authenticated Data value, and produce 192 two outputs, the Ciphertext and the Authentication Tag value. AES 193 Galois/Counter Mode (GCM) is one such algorithm. 195 Plaintext The sequence of octets to be encrypted -- a.k.a., the 196 message. The plaintext can contain an arbitrary sequence of 197 octets. 199 Ciphertext An encrypted representation of the Plaintext. 201 Additional Associated Data (AAD) An input to an Authenticated 202 Encryption operation that is integrity protected but not 203 encrypted. 205 Authentication Tag An output of an Authenticated Encryption 206 operation that ensures the integrity of the Ciphertext and the 207 Additional Associated Data. 209 Content Encryption Key (CEK) A symmetric key for the Authenticated 210 Encryption algorithm used to encrypt the Plaintext for the 211 recipient to produce the Ciphertext and the Authentication Tag. 213 JSON Text Object A UTF-8 [RFC3629] encoded text string representing 214 a JSON object; the syntax of JSON objects is defined in Section 215 2.2 of [RFC4627]. 217 JWE Header A JSON Text Object that describes the encryption 218 operations applied to create the JWE Encrypted Key, the JWE 219 Ciphertext, and the JWE Authentication Tag. 221 JWE Encrypted Key The result of encrypting the Content Encryption 222 Key (CEK) with the intended recipient's key using the specified 223 algorithm. Note that for some algorithms, the JWE Encrypted Key 224 value is specified as being the empty octet sequence. 226 JWE Initialization Vector A sequence of octets containing the 227 Initialization Vector used when encrypting the Plaintext. Note 228 that some algorithms may not use an Initialization Vector, in 229 which case this value is the empty octet sequence. 231 JWE Ciphertext A sequence of octets containing the Ciphertext for a 232 JWE. 234 JWE Authentication Tag A sequence of octets containing the 235 Authentication Tag for a JWE. 237 Base64url Encoding The URL- and filename-safe Base64 encoding 238 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 239 safe) '=' padding characters omitted, as permitted by Section 3.2. 240 (See Appendix C of [JWS] for notes on implementing base64url 241 encoding without padding.) 243 Encoded JWE Header Base64url encoding of the JWE Header. 245 Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted 246 Key. 248 Encoded JWE Initialization Vector Base64url encoding of the JWE 249 Initialization Vector. 251 Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. 253 Encoded JWE Authentication Tag Base64url encoding of the JWE 254 Authentication Tag. 256 Header Parameter Name The name of a member of the JWE Header. 258 Header Parameter Value The value of a member of the JWE Header. 260 JWE Compact Serialization A representation of the JWE as the 261 concatenation of the Encoded JWE Header, the Encoded JWE Encrypted 262 Key, the Encoded JWE Initialization Vector, the Encoded JWE 263 Ciphertext, and the Encoded JWE Authentication Tag in that order, 264 with the five strings being separated by four period ('.') 265 characters. This results in a compact, URL-safe representation. 267 JWE JSON Serialization A representation of the JWE as a JSON 268 structure containing Encoded JWE Header, Encoded JWE Encrypted 269 Key, Encoded JWE Initialization Vector, Encoded JWE Ciphertext, 270 and Encoded JWE Authentication Tag values. Unlike the JWE Compact 271 Serialization, the JWE JSON Serialization enables the same content 272 to be encrypted to multiple parties. This representation is 273 neither compact nor URL-safe. 275 Collision Resistant Namespace A namespace that allows names to be 276 allocated in a manner such that they are highly unlikely to 277 collide with other names. For instance, collision resistance can 278 be achieved through administrative delegation of portions of the 279 namespace or through use of collision-resistant name allocation 280 functions. Examples of Collision Resistant Namespaces include: 281 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 282 X.660 and X.670 Recommendation series, and Universally Unique 283 IDentifiers (UUIDs) [RFC4122]. When using an administratively 284 delegated namespace, the definer of a name needs to take 285 reasonable precautions to ensure they are in control of the 286 portion of the namespace they use to define the name. 288 StringOrURI A JSON string value, with the additional requirement 289 that while arbitrary string values MAY be used, any value 290 containing a ":" character MUST be a URI [RFC3986]. StringOrURI 291 values are compared as case-sensitive strings with no 292 transformations or canonicalizations applied. 294 Key Management Mode A method of determining the Content Encryption 295 Key (CEK) value to use. Each algorithm used for determining the 296 CEK value uses a specific Key Management Mode. Key Management 297 Modes employed by this specification are Key Encryption, Key 298 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 299 and Direct Encryption. 301 Key Encryption A Key Management Mode in which the Content Encryption 302 Key (CEK) value is encrypted to the intended recipient using an 303 asymmetric encryption algorithm. 305 Key Wrapping A Key Management Mode in which the Content Encryption 306 Key (CEK) value is encrypted to the intended recipient using a 307 symmetric key wrapping algorithm. 309 Direct Key Agreement A Key Management Mode in which a key agreement 310 algorithm is used to agree upon the Content Encryption Key (CEK) 311 value. 313 Key Agreement with Key Wrapping A Key Management Mode in which a key 314 agreement algorithm is used to agree upon a symmetric key used to 315 encrypt the Content Encryption Key (CEK) value to the intended 316 recipient using a symmetric key wrapping algorithm. 318 Direct Encryption A Key Management Mode in which the Content 319 Encryption Key (CEK) value used is the secret symmetric key value 320 shared between the parties. 322 3. JSON Web Encryption (JWE) Overview 324 JWE represents encrypted content using JSON data structures and 325 base64url encoding. Five values are represented in a JWE: the JWE 326 Header, the JWE Encrypted Key, the JWE Initialization Vector, the JWE 327 Ciphertext, and the JWE Authentication Tag. In the Compact 328 Serialization, the five values are base64url-encoded for 329 transmission, and represented as the concatenation of the encoded 330 strings in that order, with the five strings being separated by four 331 period ('.') characters. A JSON Serialization for this information 332 is also defined in Section 7. 334 JWE utilizes authenticated encryption to ensure the confidentiality 335 and integrity of the Plaintext. 337 3.1. Example JWE using RSAES OAEP and AES GCM 339 This example encrypts the plaintext "The true sign of intelligence is 340 not knowledge but imagination." to the recipient using RSAES OAEP and 341 AES GCM. 343 The following example JWE Header declares that: 345 o the Content Encryption Key is encrypted to the recipient using the 346 RSAES OAEP algorithm to produce the JWE Encrypted Key and 348 o the Plaintext is encrypted using the AES GCM algorithm with a 256 349 bit key to produce the Ciphertext. 351 {"alg":"RSA-OAEP","enc":"A256GCM"} 353 Base64url encoding the octets of the UTF-8 representation of the JWE 354 Header yields this Encoded JWE Header value: 356 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 358 The remaining steps to finish creating this JWE are: 360 o Generate a random Content Encryption Key (CEK) 362 o Encrypt the CEK with the recipient's public key using the RSAES 363 OAEP algorithm to produce the JWE Encrypted Key 365 o Base64url encode the JWE Encrypted Key to produce the Encoded JWE 366 Encrypted Key 368 o Generate a random JWE Initialization Vector 370 o Base64url encode the JWE Initialization Vector to produce the 371 Encoded JWE Initialization Vector 373 o Concatenate the Encoded JWE Header value, a period ('.') 374 character, and the Encoded JWE Encrypted Key to create the 375 Additional Authenticated Data parameter 377 o Encrypt the Plaintext with AES GCM using the CEK as the encryption 378 key, the JWE Initialization Vector, and the Additional 379 Authenticated Data value, requesting a 128 bit Authentication Tag 380 output 382 o Base64url encode the Ciphertext to create the Encoded JWE 383 Ciphertext 385 o Base64url encode the Authentication Tag to create the Encoded JWE 386 Authentication Tag 388 o Assemble the final representation: The Compact Serialization of 389 this result is the concatenation of the Encoded JWE Header, the 390 Encoded JWE Encrypted Key, the Encoded JWE Initialization Vector, 391 the Encoded JWE Ciphertext, and the Encoded JWE Authentication Tag 392 in that order, with the five strings being separated by four 393 period ('.') characters. 395 The final result in this example (with line breaks for display 396 purposes only) is: 398 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 399 ApfOLCaDbqs_JXPYy2I937v_xmrzj-Iss1mG6NAHmeJViM6j2l0MHvfseIdHVyU2 400 BIoGVu9ohvkkWiRq5DL2jYZTPA9TAdwq3FUIVyoH-Pedf6elHIVFi2KGDEspYMtQ 401 ARMMSBcS7pslx6flh1Cfh3GBKysztVMEhZ_maFkm4PYVCsJsvq6Ct3fg2CJPOs0X 402 1DHuxZKoIGIqcbeK4XEO5a0h5TAuJObKdfO0dKwfNSSbpu5sFrpRFwV2FTTYoqF4 403 zI46N9-_hMIznlEpftRXhScEJuZ9HG8C8CHB1WRZ_J48PleqdhF4o7fB5J1wFqUX 404 BtbtuGJ_A2Xe6AEhrlzCOw. 405 48V1_ALb6US04U3b. 406 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 407 SdiwkIr3ajwQzaBtQD_A. 408 ghEgxninkHEAMp4xZtB2mA 410 See Appendix A.1 for the complete details of computing this JWE. 412 3.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 414 This example encrypts the plaintext "Live long and prosper." to the 415 recipient using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256. 417 The following example JWE Header (with line breaks for display 418 purposes only) declares that: 420 o the Content Encryption Key is encrypted to the recipient using the 421 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 423 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 424 algorithm to produce the Ciphertext. 426 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 428 Base64url encoding the octets of the UTF-8 representation of the JWE 429 Header yields this Encoded JWE Header value: 431 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDK0hTMjU2In0 433 The remaining steps to finish creating this JWE are the same as for 434 the previous example, but using RSAES-PKCS1-v1_5 instead of RSAES 435 OAEP and using the AES_128_CBC_HMAC_SHA_256 algorithm (which is 436 specified in Sections 4.8 and 4.8.3 of JWA) instead of AES GCM. 438 The final result in this example (with line breaks for display 439 purposes only) is: 441 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 442 nJa_uE2D0wlKz-OcwSbKFzj302xYSI-RLBM6hbVGmP4axtJQPA9S0po3s3NMkmOm 443 kkawnfwPNjpc0mc3z79cuQWkQPFQo-mDxmogz8dxBcheaTUg3ZvpbGCXxZjDYENR 444 WiZ5M9BiLy09BIF5mHp85QL6XED1JEZMOh-1uT1lqPDcDD79qWtrCfEJmNmfsx5f 445 cB2PfAcVtQ0t_YmOXx5_Gu0it1nILKXLR2Ynf9mfLhEcC5LebpWyEHW6WzQ4iH9S 446 IcIupPV1iKCzmJcPrDBJ5Fc_KMBcXBinaS__wftNywaGgfi_NSsx24LxtK6fIkej 447 RlMBmCfxv0Tg8CtxpURigg. 448 AxY8DCtDaGlsbGljb3RoZQ. 449 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 450 fY2U_Hx5VcfXmipEldHhMA 452 See Appendix A.2 for the complete details of computing this JWE. 454 4. JWE Header 456 The members of the JSON object represented by the JWE Header describe 457 the encryption applied to the Plaintext and optionally additional 458 properties of the JWE. The Header Parameter Names within this object 459 MUST be unique; JWEs with duplicate Header Parameter Names MUST be 460 rejected. 462 Implementations are required to understand the specific header 463 parameters defined by this specification that are designated as "MUST 464 be understood" and process them in the manner defined in this 465 specification. All other header parameters defined by this 466 specification that are not so designated MUST be ignored when not 467 understood. Unless listed as a critical header parameter, per 468 Section 4.1.15, all other header parameters MUST be ignored when not 469 understood. 471 There are two ways of distinguishing whether a header is a JWS Header 472 or a JWE Header. The first is by examining the "alg" (algorithm) 473 header parameter value. If the value represents a digital signature 474 or MAC algorithm, or is the value "none", it is for a JWS; if it 475 represents a Key Encryption, Key Wrapping, Direct Key Agreement, Key 476 Agreement with Key Wrapping, or Direct Encryption algorithm, it is 477 for a JWE. A second method is determining whether an "enc" 478 (encryption method) member exists. If the "enc" member exists, it is 479 a JWE; otherwise, it is a JWS. Both methods will yield the same 480 result for all legal input values. 482 There are three classes of Header Parameter Names: Reserved Header 483 Parameter Names, Public Header Parameter Names, and Private Header 484 Parameter Names. 486 4.1. Reserved Header Parameter Names 488 The following Header Parameter Names are reserved with meanings as 489 defined below. All the names are short because a core goal of this 490 specification is for the resulting representations using the JWE 491 Compact Serialization to be compact. 493 Additional reserved Header Parameter Names MAY be defined via the 494 IANA JSON Web Signature and Encryption Header Parameters registry 495 [JWS]. As indicated by the common registry, JWSs and JWEs share a 496 common header parameter space; when a parameter is used by both 497 specifications, its usage must be compatible between the 498 specifications. 500 4.1.1. "alg" (Algorithm) Header Parameter 502 The "alg" (algorithm) header parameter identifies the cryptographic 503 algorithm used to encrypt or determine the value of the Content 504 Encryption Key (CEK). The algorithm specified by the "alg" value 505 MUST be supported by the implementation and there MUST be a key for 506 use with that algorithm associated with the intended recipient or the 507 JWE MUST be rejected. "alg" values SHOULD either be registered in the 508 IANA JSON Web Signature and Encryption Algorithms registry [JWA] or 509 be a value that contains a Collision Resistant Namespace. The "alg" 510 value is a case sensitive string containing a StringOrURI value. Use 511 of this header parameter is REQUIRED. This header parameter MUST be 512 understood by implementations. 514 A list of defined "alg" values can be found in the IANA JSON Web 515 Signature and Encryption Algorithms registry [JWA]; the initial 516 contents of this registry are the values defined in Section 4.1 of 517 the JSON Web Algorithms (JWA) [JWA] specification. 519 4.1.2. "enc" (Encryption Method) Header Parameter 521 The "enc" (encryption method) header parameter identifies the block 522 encryption algorithm used to encrypt the Plaintext to produce the 523 Ciphertext. This algorithm MUST be an Authenticated Encryption 524 algorithm with a specified key length. The algorithm specified by 525 the "enc" value MUST be supported by the implementation or the JWE 526 MUST be rejected. "enc" values SHOULD either be registered in the 527 IANA JSON Web Signature and Encryption Algorithms registry [JWA] or 528 be a value that contains a Collision Resistant Namespace. The "enc" 529 value is a case sensitive string containing a StringOrURI value. Use 530 of this header parameter is REQUIRED. This header parameter MUST be 531 understood by implementations. 533 A list of defined "enc" values can be found in the IANA JSON Web 534 Signature and Encryption Algorithms registry [JWA]; the initial 535 contents of this registry are the values defined in Section 4.2 of 536 the JSON Web Algorithms (JWA) [JWA] specification. 538 4.1.3. "epk" (Ephemeral Public Key) Header Parameter 540 The "epk" (ephemeral public key) value created by the originator for 541 the use in key agreement algorithms. This key is represented as a 542 JSON Web Key [JWK] value. Use of this header parameter is OPTIONAL, 543 although its use is REQUIRED with some "alg" algorithms. When its 544 use is REQUIRED, this header parameter MUST be understood by 545 implementations. 547 4.1.4. "zip" (Compression Algorithm) Header Parameter 549 The "zip" (compression algorithm) applied to the Plaintext before 550 encryption, if any. If present, the value of the "zip" header 551 parameter MUST be the case sensitive string "DEF". Compression is 552 performed with the DEFLATE [RFC1951] algorithm. If no "zip" 553 parameter is present, no compression is applied to the Plaintext 554 before encryption. Use of this header parameter is OPTIONAL. This 555 header parameter MUST be understood by implementations. 557 4.1.5. "jku" (JWK Set URL) Header Parameter 559 The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that 560 refers to a resource for a set of JSON-encoded public keys, one of 561 which is the key to which the JWE was encrypted; this can be used to 562 determine the private key needed to decrypt the JWE. The keys MUST 563 be encoded as a JSON Web Key Set (JWK Set) [JWK]. The protocol used 564 to acquire the resource MUST provide integrity protection; an HTTP 565 GET request to retrieve the certificate MUST use TLS [RFC2818] 566 [RFC5246]; the identity of the server MUST be validated, as per 567 Section 3.1 of HTTP Over TLS [RFC2818]. Use of this header parameter 568 is OPTIONAL. 570 4.1.6. "jwk" (JSON Web Key) Header Parameter 572 The "jwk" (JSON Web Key) header parameter is the public key to which 573 the JWE was encrypted; this can be used to determine the private key 574 needed to decrypt the JWE. This key is represented as a JSON Web Key 575 [JWK]. Use of this header parameter is OPTIONAL. 577 4.1.7. "x5u" (X.509 URL) Header Parameter 579 The "x5u" (X.509 URL) header parameter is a URI [RFC3986] that refers 580 to a resource for the X.509 public key certificate or certificate 581 chain [RFC5280] containing the key to which the JWE was encrypted; 582 this can be used to determine the private key needed to decrypt the 583 JWE. The identified resource MUST provide a representation of the 584 certificate or certificate chain that conforms to RFC 5280 [RFC5280] 585 in PEM encoded form [RFC1421]. The certificate containing the public 586 key to which the JWE was encrypted MUST be the first certificate. 587 This MAY be followed by additional certificates, with each subsequent 588 certificate being the one used to certify the previous one. The 589 protocol used to acquire the resource MUST provide integrity 590 protection; an HTTP GET request to retrieve the certificate MUST use 591 TLS [RFC2818] [RFC5246]; the identity of the server MUST be 592 validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. Use of 593 this header parameter is OPTIONAL. 595 4.1.8. "x5t" (X.509 Certificate Thumbprint) Header Parameter 597 The "x5t" (X.509 Certificate Thumbprint) header parameter provides a 598 base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER 599 encoding of the X.509 certificate [RFC5280] containing the key to 600 which the JWE was encrypted; this can be used to determine the 601 private key needed to decrypt the JWE. Use of this header parameter 602 is OPTIONAL. 604 If, in the future, certificate thumbprints need to be computed using 605 hash functions other than SHA-1, it is suggested that additional 606 related header parameters be defined for that purpose. For example, 607 it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint 608 using SHA-256) header parameter could be defined by registering it in 609 the IANA JSON Web Signature and Encryption Header Parameters registry 610 [JWS]. 612 4.1.9. "x5c" (X.509 Certificate Chain) Header Parameter 614 The "x5c" (X.509 Certificate Chain) header parameter contains the 615 X.509 public key certificate or certificate chain [RFC5280] 616 containing the key to which the JWE was encrypted; this can be used 617 to determine the private key needed to decrypt the JWE. The 618 certificate or certificate chain is represented as an array of 619 certificate value strings. Each string is a base64 encoded 620 ([RFC4648] Section 4 -- not base64url encoded) DER [ITU.X690.1994] 621 PKIX certificate value. The certificate containing the public key to 622 which the JWE was encrypted MUST be the first certificate. This MAY 623 be followed by additional certificates, with each subsequent 624 certificate being the one used to certify the previous one. Use of 625 this header parameter is OPTIONAL. 627 See Appendix B of [JWS] for an example "x5c" value. 629 4.1.10. "kid" (Key ID) Header Parameter 631 The "kid" (key ID) header parameter is a hint indicating which key to 632 which the JWE was encrypted; this can be used to determine the 633 private key needed to decrypt the JWE. This parameter allows 634 originators to explicitly signal a change of key to recipients. 635 Should the recipient be unable to locate a key corresponding to the 636 "kid" value, they SHOULD treat that condition as an error. The 637 interpretation of the "kid" value is unspecified. Its value MUST be 638 a string. Use of this header parameter is OPTIONAL. 640 When used with a JWK, the "kid" value can be used to match a JWK 641 "kid" parameter value. 643 4.1.11. "typ" (Type) Header Parameter 645 The "typ" (type) header parameter is used to declare the type of this 646 object. The type value "JWE" is used to indicate that this object is 647 a JWE using the JWE Compact Serialization. The type value "JWE-JS" 648 is used to indicate that this object is a JWE using the JWE JSON 649 Serialization. The "typ" value is a case sensitive string. Use of 650 this header parameter is OPTIONAL. 652 MIME Media Type [RFC2046] values MAY be used as "typ" values. 654 "typ" values SHOULD either be registered in the IANA JSON Web 655 Signature and Encryption Type Values registry [JWS] or be a value 656 that contains a Collision Resistant Namespace. 658 4.1.12. "cty" (Content Type) Header Parameter 660 The "cty" (content type) header parameter is used to declare the type 661 of the encrypted content (the Plaintext). For example, the JSON Web 662 Token (JWT) [JWT] specification uses the "cty" value "JWT" to 663 indicate that the Plaintext is a JSON Web Token (JWT). The "cty" 664 value is a case sensitive string. Use of this header parameter is 665 OPTIONAL. 667 The values used for the "cty" header parameter come from the same 668 value space as the "typ" header parameter, with the same rules 669 applying. 671 4.1.13. "apu" (Agreement PartyUInfo) Header Parameter 673 The "apu" (agreement PartyUInfo) value for key agreement algorithms 674 using it (such as "ECDH-ES"), represented as a base64url encoded 675 string. Use of this header parameter is OPTIONAL. When the "alg" 676 value used identifies an algorithm for which "apu" is a parameter, 677 this header parameter MUST be understood by implementations. 679 4.1.14. "apv" (Agreement PartyVInfo) Header Parameter 681 The "apv" (agreement PartyVInfo) value for key agreement algorithms 682 using it (such as "ECDH-ES"), represented as a base64url encoded 683 string. Use of this header parameter is OPTIONAL. When the "alg" 684 value used identifies an algorithm for which "apv" is a parameter, 685 this header parameter MUST be understood by implementations. 687 4.1.15. "crit" (Critical) Header Parameter 689 The "crit" (critical) header parameter is array listing the names of 690 header parameters that are present in the JWE Header that MUST be 691 understood and processed by the implementation or if not understood, 692 MUST cause the JWE to be rejected. This list MUST NOT include header 693 parameters defined by this specification, duplicate names, or names 694 that do not occur as header parameters within the JWE. Use of this 695 header parameter is OPTIONAL. This header parameter MUST be 696 understood by implementations. 698 An example use, along with a hypothetical "exp" (expiration-time) 699 field is: 701 {"alg":"RSA-OAEP", 702 "enc":"A256GCM", 703 "crit":["exp"], 704 "exp":1363284000 705 } 707 4.2. Public Header Parameter Names 709 Additional Header Parameter Names can be defined by those using JWEs. 710 However, in order to prevent collisions, any new Header Parameter 711 Name SHOULD either be registered in the IANA JSON Web Signature and 712 Encryption Header Parameters registry [JWS] or be a Public Name: a 713 value that contains a Collision Resistant Namespace. In each case, 714 the definer of the name or value needs to take reasonable precautions 715 to make sure they are in control of the part of the namespace they 716 use to define the Header Parameter Name. 718 New header parameters should be introduced sparingly, as they can 719 result in non-interoperable JWEs. 721 4.3. Private Header Parameter Names 723 A producer and consumer of a JWE may agree to use Header Parameter 724 Names that are Private Names: names that are not Reserved Names 725 Section 4.1 or Public Names Section 4.2. Unlike Public Names, 726 Private Names are subject to collision and should be used with 727 caution. 729 5. Producing and Consuming JWEs 731 5.1. Message Encryption 733 The message encryption process is as follows. The order of the steps 734 is not significant in cases where there are no dependencies between 735 the inputs and outputs of the steps. 737 1. Determine the Key Management Mode employed by the algorithm used 738 to determine the Content Encryption Key (CEK) value. (This is 739 the algorithm recorded in the "alg" (algorithm) header parameter 740 of the resulting JWE.) 742 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 743 Wrapping are employed, generate a random Content Encryption Key 744 (CEK) value. See RFC 4086 [RFC4086] for considerations on 745 generating random values. The CEK MUST have a length equal to 746 that required for the block encryption algorithm. 748 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 749 employed, use the key agreement algorithm to compute the value 750 of the agreed upon key. When Direct Key Agreement is employed, 751 let the Content Encryption Key (CEK) be the agreed upon key. 752 When Key Agreement with Key Wrapping is employed, the agreed 753 upon key will be used to wrap the CEK. 755 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 756 Wrapping are employed, encrypt the CEK to the recipient (see 757 Section 6.1) and let the result be the JWE Encrypted Key. 759 5. Otherwise, when Direct Key Agreement or Direct Encryption are 760 employed, let the JWE Encrypted Key be the empty octet sequence. 762 6. When Direct Encryption is employed, let the Content Encryption 763 Key (CEK) be the shared symmetric key. 765 7. Base64url encode the JWE Encrypted Key to create the Encoded JWE 766 Encrypted Key. 768 8. Generate a random JWE Initialization Vector of the correct size 769 for the block encryption algorithm (if required for the 770 algorithm); otherwise, let the JWE Initialization Vector be the 771 empty octet sequence. 773 9. Base64url encode the JWE Initialization Vector to create the 774 Encoded JWE Initialization Vector. 776 10. Compress the Plaintext if a "zip" parameter was included. 778 11. Serialize the (compressed) Plaintext into an octet sequence M. 780 12. Create a JWE Header containing the encryption parameters used. 781 Note that white space is explicitly allowed in the 782 representation and no canonicalization need be performed before 783 encoding. 785 13. Base64url encode the octets of the UTF-8 representation of the 786 JWE Header to create the Encoded JWE Header. 788 14. If the JWE JSON Serialization is being used, repeat this process 789 for each recipient. 791 15. Let the value X be the concatenation of the Encoded JWE Header 792 values computed above, with a tilde ('~') character between each 793 Encoded JWE Header value. (In the single recipient case, X is 794 simply the single Encoded JWE Header value.) 796 16. Let the value Y be the concatenation of the Encoded JWE 797 Encrypted Key values computed above, with a tilde ('~') 798 character between each Encoded JWE Encrypted Key value. The 799 order of the Encoded JWE Encrypted Key values MUST be the same 800 as the order of the corresponding Encoded JWE Header values in 801 the previous step. (In the single recipient case, Y is simply 802 the single Encoded JWE Encrypted Key value.) 804 17. Let the Additional Authenticated Data value be the octets of the 805 ASCII representation of the concatenation of X, a period ('.') 806 character, and Y. 808 18. Encrypt M using the CEK, the JWE Initialization Vector, and the 809 Additional Authenticated Data value using the specified block 810 encryption algorithm to create the JWE Ciphertext value and the 811 JWE Authentication Tag (which is the Authentication Tag output 812 from the encryption operation). 814 19. Base64url encode the JWE Ciphertext to create the Encoded JWE 815 Ciphertext. 817 20. Base64url encode the JWE Authentication Tag to create the 818 Encoded JWE Authentication Tag. 820 21. The five encoded parts are the result values used in both the 821 JWE Compact Serialization and the JWE JSON Serialization 822 representations. 824 22. Create the desired serialized output. The JWE Compact 825 Serialization of this result is the concatenation of the Encoded 826 JWE Header, the Encoded JWE Encrypted Key, the Encoded JWE 827 Initialization Vector, the Encoded JWE Ciphertext, and the 828 Encoded JWE Authentication Tag in that order, with the five 829 strings being separated by four period ('.') characters. The 830 JWE JSON Serialization is described in Section 7. 832 5.2. Message Decryption 834 The message decryption process is the reverse of the encryption 835 process. The order of the steps is not significant in cases where 836 there are no dependencies between the inputs and outputs of the 837 steps. If any of these steps fails, the JWE MUST be rejected. 839 1. Parse the serialized input to determine the values of the 840 Encoded JWE Header, the Encoded JWE Encrypted Key, the Encoded 841 JWE Initialization Vector, the Encoded JWE Ciphertext, and the 842 Encoded JWE Authentication Tag. When using the JWE Compact 843 Serialization, these five values are represented as text strings 844 in that order, separated by four period ('.') characters. The 845 JWE JSON Serialization is described in Section 7. 847 2. The Encoded JWE Header, the Encoded JWE Encrypted Key, the 848 Encoded JWE Initialization Vector, the Encoded JWE Ciphertext, 849 and the Encoded JWE Authentication Tag MUST be successfully 850 base64url decoded following the restriction that no padding 851 characters have been used. 853 3. The resulting JWE Header MUST be completely valid JSON syntax 854 conforming to RFC 4627 [RFC4627]. 856 4. The resulting JWE Header MUST be validated to only include 857 parameters and values whose syntax and semantics are both 858 understood and supported or that are specified as being ignored 859 when not understood. 861 5. Determine the Key Management Mode employed by the algorithm 862 specified by the "alg" (algorithm) header parameter. 864 6. Verify that the JWE uses a key known to the recipient. 866 7. When Direct Key Agreement or Key Agreement with Key Wrapping are 867 employed, use the key agreement algorithm to compute the value 868 of the agreed upon key. When Direct Key Agreement is employed, 869 let the Content Encryption Key (CEK) be the agreed upon key. 870 When Key Agreement with Key Wrapping is employed, the agreed 871 upon key will be used to decrypt the JWE Encrypted Key. 873 8. When Key Wrapping, Key Encryption, or Key Agreement with Key 874 Wrapping are employed, decrypt the JWE Encrypted Key to produce 875 the Content Encryption Key (CEK). The CEK MUST have a length 876 equal to that required for the block encryption algorithm. Note 877 that when there are multiple recipients, each recipient will 878 only be able decrypt any JWE Encrypted Key values that were 879 encrypted to a key in that recipient's possession. It is 880 therefore normal to only be able to decrypt one of the per- 881 recipient JWE Encrypted Key values to obtain the CEK value. To 882 mitigate against attacks described in RFC 3218 [RFC3218], the 883 recipient MUST NOT distinguish between format, padding, and 884 length errors of encrypted keys. It is strongly recommended, in 885 the event of receiving an improperly formatted key, that the 886 receiver substitute a randomly generated CEK and proceed to the 887 next step, to mitigate timing attacks. 889 9. Otherwise, when Direct Key Agreement or Direct Encryption are 890 employed, verify that the JWE Encrypted Key value is empty octet 891 sequence. 893 10. When Direct Encryption is employed, let the Content Encryption 894 Key (CEK) be the shared symmetric key. 896 11. If the JWE JSON Serialization is being used, repeat this process 897 for each recipient contained in the representation. 899 12. Let the value X be the concatenation of the Encoded JWE Header 900 values identified above, with a tilde ('~') character between 901 each Encoded JWE Header value. (In the single recipient case, X 902 is simply the single Encoded JWE Header value.) 904 13. Let the value Y be the concatenation of the Encoded JWE 905 Encrypted Key values identified above, with a tilde ('~') 906 character between each Encoded JWE Encrypted Key value. The 907 order of the Encoded JWE Encrypted Key values MUST be the same 908 as the order of the corresponding Encoded JWE Header values in 909 the previous step. (In the single recipient case, Y is simply 910 the single Encoded JWE Encrypted Key value.) 912 14. Let the Additional Authenticated Data value be the octets of the 913 ASCII representation of the concatenation of X, a period ('.') 914 character, and Y. 916 15. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 917 Vector, the Additional Authenticated Data value, and the JWE 918 Authentication Tag (which is the Authentication Tag input to the 919 calculation) using the specified block encryption algorithm, 920 returning the decrypted plaintext and verifying the JWE 921 Authentication Tag in the manner specified for the algorithm, 922 rejecting the input without emitting any decrypted output if the 923 JWE Authentication Tag is incorrect. 925 16. Uncompress the decrypted plaintext if a "zip" parameter was 926 included. 928 17. Output the resulting Plaintext. 930 5.3. String Comparison Rules 932 Processing a JWE inevitably requires comparing known strings to 933 values in JSON objects. For example, in checking what the encryption 934 method is, the Unicode string encoding "enc" will be checked against 935 the member names in the JWE Header to see if there is a matching 936 Header Parameter Name. 938 Comparisons between JSON strings and other Unicode strings MUST be 939 performed by comparing Unicode code points without normalization as 940 specified in the String Comparison Rules in Section 5.3 of [JWS]. 942 6. Encrypting JWEs with Cryptographic Algorithms 944 JWE uses cryptographic algorithms to encrypt the Plaintext and the 945 Content Encryption Key (CEK) and to provide integrity protection for 946 the JWE Header, JWE Encrypted Key, and JWE Ciphertext. The JSON Web 947 Algorithms (JWA) [JWA] specification specifies a set of cryptographic 948 algorithms and identifiers to be used with this specification and 949 defines registries for additional such algorithms. Specifically, 950 Section 4.1 specifies a set of "alg" (algorithm) header parameter 951 values and Section 4.2 specifies a set of "enc" (encryption method) 952 header parameter values intended for use this specification. It also 953 describes the semantics and operations that are specific to these 954 algorithms. 956 Public keys employed for encryption can be identified using the 957 Header Parameter methods described in Section 4.1 or can be 958 distributed using methods that are outside the scope of this 959 specification. 961 6.1. CEK Encryption 963 JWE supports three forms of Content Encryption Key (CEK) encryption: 965 o Asymmetric encryption under the recipient's public key. 967 o Symmetric encryption under a key shared between the sender and 968 receiver. 970 o Symmetric encryption under a key agreed upon between the sender 971 and receiver. 973 See the algorithms registered for "enc" usage in the IANA JSON Web 974 Signature and Encryption Algorithms registry [JWA] and Section 4.1 of 975 the JSON Web Algorithms (JWA) [JWA] specification for lists of 976 encryption algorithms that can be used for CEK encryption. 978 7. JSON Serialization 980 The JWE JSON Serialization represents encrypted content as a JSON 981 object with a "recipients" member containing an array of per- 982 recipient information, an "initialization_vector" member containing a 983 shared Encoded JWE Initialization Vector value, a "ciphertext" member 984 containing a shared Encoded JWE Ciphertext value, and an 985 "authentication_tag" member containing a shared Encoded JWE 986 Authentication Tag value. Each member of the "recipients" array is a 987 JSON object with a "header" member containing an Encoded JWE Header 988 value and an "encrypted_key" member containing an Encoded JWE 989 Encrypted Key value. 991 Unlike the JWE Compact Serialization, content using the JWE JSON 992 Serialization MAY be encrypted to more than one recipient. Each 993 recipient requires: 995 o a JWE Header value specifying the cryptographic parameters used to 996 encrypt the JWE Encrypted Key to that recipient and the parameters 997 used to encrypt the plaintext to produce the JWE Ciphertext; this 998 is represented as an Encoded JWE Header value in the "header" 999 member of an object in the "recipients" array. 1001 o a JWE Encrypted Key value used to encrypt the ciphertext; this is 1002 represented as an Encoded JWE Encrypted Key value in the 1003 "encrypted_key" member of the same object in the "recipients" 1004 array. 1006 Therefore, the syntax is: 1008 {"recipients":[ 1009 {"header":"
", 1010 "encrypted_key":""}, 1011 ... 1012 {"header":"
", 1013 "encrypted_key":""}], 1014 "initialization_vector":"", 1015 "ciphertext":"", 1016 "authentication_tag":"" 1017 } 1019 The contents of the Encoded JWE Header, Encoded JWE Encrypted Key, 1020 Encoded JWE Initialization Vector, Encoded JWE Ciphertext, and 1021 Encoded JWE Authentication Tag values are exactly as specified in the 1022 rest of this specification. They are interpreted and validated in 1023 the same manner, with each corresponding "header" and "encrypted_key" 1024 value being created and validated together. 1026 All recipients use the same JWE Ciphertext, JWE Initialization 1027 Vector, and JWE Authentication Tag values, resulting in potentially 1028 significant space savings if the message is large. Therefore, all 1029 header parameters that specify the treatment of the JWE Ciphertext 1030 value MUST be the same for all recipients. This primarily means that 1031 the "enc" (encryption method) header parameter value in the JWE 1032 Header for each recipient MUST be the same. 1034 7.1. Example JWE-JS 1036 This section contains an example using the JWE JSON Serialization. 1037 This example demonstrates the capability for encrypting the same 1038 plaintext to multiple recipients. 1040 Two recipients are present in this example: the first using the 1041 RSAES-PKCS1-V1_5 algorithm to encrypt the Content Encryption Key 1042 (CEK) and the second using RSAES OAEP to encrypt the CEK. The 1043 Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 algorithm 1044 and the same block encryption parameters to produce the common JWE 1045 Ciphertext value. The two Decoded JWE Header Segments used are: 1047 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1049 and: 1051 {"alg":"RSA-OAEP","enc":"A128CBC-HS256"} 1053 The keys used for the first recipient are the same as those in 1054 Appendix A.2, as is the Plaintext used. The encryption key used for 1055 the second recipient is the same as that used in Appendix A.3; the 1056 block encryption keys and parameters for the second recipient are the 1057 same as those for the first recipient (which must be the case, since 1058 the Initialization Vector and Ciphertext are shared). Thus, the same 1059 two Encoded JWE Header and JWE Encoded Encrypted Key values are used 1060 in this example as are used in those examples. 1062 The value X used as part of the AAD value is the concatenation of the 1063 Encoded JWE Header values, separated by a tilde ('~') character. In 1064 this example, the value of X (with line breaks for display purposes 1065 only) is: 1067 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1068 ~ 1069 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1071 The value Y used as part of the AAD value is the concatenation of the 1072 Encoded JWE Encrypted Key values, separated by a tilde ('~') 1073 character. In this example, the value of Y (with line breaks for 1074 display purposes only) is: 1076 nJa_uE2D0wlKz-OcwSbKFzj302xYSI-RLBM6hbVGmP4axtJQPA9S0po3s3NMk 1077 mOmkkawnfwPNjpc0mc3z79cuQWkQPFQo-mDxmogz8dxBcheaTUg3ZvpbGCXxZ 1078 jDYENRWiZ5M9BiLy09BIF5mHp85QL6XED1JEZMOh-1uT1lqPDcDD79qWtrCfE 1079 JmNmfsx5fcB2PfAcVtQ0t_YmOXx5_Gu0it1nILKXLR2Ynf9mfLhEcC5LebpWy 1080 EHW6WzQ4iH9SIcIupPV1iKCzmJcPrDBJ5Fc_KMBcXBinaS__wftNywaGgfi_N 1081 Ssx24LxtK6fIkejRlMBmCfxv0Tg8CtxpURigg 1082 ~ 1083 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1085 The AAD value used for the block encryption is the octets of the 1086 ASCII representation of the concatenation of X, a period ('.') 1087 character, and Y. This concatenation (with line breaks for display 1088 purposes only) is: 1090 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1091 ~ 1092 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1093 . 1094 nJa_uE2D0wlKz-OcwSbKFzj302xYSI-RLBM6hbVGmP4axtJQPA9S0po3s3NMk 1095 mOmkkawnfwPNjpc0mc3z79cuQWkQPFQo-mDxmogz8dxBcheaTUg3ZvpbGCXxZ 1096 jDYENRWiZ5M9BiLy09BIF5mHp85QL6XED1JEZMOh-1uT1lqPDcDD79qWtrCfE 1097 JmNmfsx5fcB2PfAcVtQ0t_YmOXx5_Gu0it1nILKXLR2Ynf9mfLhEcC5LebpWy 1098 EHW6WzQ4iH9SIcIupPV1iKCzmJcPrDBJ5Fc_KMBcXBinaS__wftNywaGgfi_N 1099 Ssx24LxtK6fIkejRlMBmCfxv0Tg8CtxpURigg 1100 ~ 1101 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1103 The complete JSON Web Encryption JSON Serialization (JWE-JS) for 1104 these values is as follows (with line breaks for display purposes 1105 only): 1107 {"recipients":[ 1108 {"header": 1109 "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1110 "encrypted_key": 1111 "nJa_uE2D0wlKz-OcwSbKFzj302xYSI-RLBM6hbVGmP4axtJQPA9S0po3s3NMk 1112 mOmkkawnfwPNjpc0mc3z79cuQWkQPFQo-mDxmogz8dxBcheaTUg3ZvpbGCXxZ 1113 jDYENRWiZ5M9BiLy09BIF5mHp85QL6XED1JEZMOh-1uT1lqPDcDD79qWtrCfE 1114 JmNmfsx5fcB2PfAcVtQ0t_YmOXx5_Gu0it1nILKXLR2Ynf9mfLhEcC5LebpWy 1115 EHW6WzQ4iH9SIcIupPV1iKCzmJcPrDBJ5Fc_KMBcXBinaS__wftNywaGgfi_N 1116 Ssx24LxtK6fIkejRlMBmCfxv0Tg8CtxpURigg"}, 1117 {"header": 1118 "eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1119 "encrypted_key": 1120 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1121 "initialization_vector": 1122 "AxY8DCtDaGlsbGljb3RoZQ", 1123 "ciphertext": 1124 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1125 "authentication_tag": 1126 "LlhRZFfphc2f5X3nTTJP6g" 1127 } 1129 8. Implementation Considerations 1131 The JWE Compact Serialization is mandatory to implement. 1132 Implementation of the JWE JSON Serialization is OPTIONAL. 1134 9. IANA Considerations 1136 9.1. Registration of JWE Header Parameter Names 1138 This specification registers the Header Parameter Names defined in 1139 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1140 Parameters registry [JWS]. 1142 9.1.1. Registry Contents 1144 o Header Parameter Name: "alg" 1145 o Header Parameter Usage Location(s): JWE 1146 o Change Controller: IETF 1147 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1148 o Header Parameter Name: "enc" 1149 o Header Parameter Usage Location(s): JWE 1150 o Change Controller: IETF 1151 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1153 o Header Parameter Name: "epk" 1154 o Header Parameter Usage Location(s): JWE 1155 o Change Controller: IETF 1156 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1158 o Header Parameter Name: "zip" 1159 o Header Parameter Usage Location(s): JWE 1160 o Change Controller: IETF 1161 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1163 o Header Parameter Name: "jku" 1164 o Header Parameter Usage Location(s): JWE 1165 o Change Controller: IETF 1166 o Specification Document(s): Section 4.1.5 of [[ this document ]] 1168 o Header Parameter Name: "jwk" 1169 o Header Parameter Usage Location(s): JWE 1170 o Change Controller: IETF 1171 o Specification document(s): Section 4.1.6 of [[ this document ]] 1173 o Header Parameter Name: "x5u" 1174 o Header Parameter Usage Location(s): JWE 1175 o Change Controller: IETF 1176 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1178 o Header Parameter Name: "x5t" 1179 o Header Parameter Usage Location(s): JWE 1180 o Change Controller: IETF 1181 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1183 o Header Parameter Name: "x5c" 1184 o Header Parameter Usage Location(s): JWE 1185 o Change Controller: IETF 1186 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1188 o Header Parameter Name: "kid" 1189 o Header Parameter Usage Location(s): JWE 1190 o Change Controller: IETF 1191 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1193 o Header Parameter Name: "typ" 1194 o Header Parameter Usage Location(s): JWE 1195 o Change Controller: IETF 1196 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1198 o Header Parameter Name: "cty" 1199 o Header Parameter Usage Location(s): JWE 1200 o Change Controller: IETF 1201 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1203 o Header Parameter Name: "apu" 1204 o Header Parameter Usage Location(s): JWE 1205 o Change Controller: IETF 1206 o Specification Document(s): Section 4.1.13 of [[ this document ]] 1208 o Header Parameter Name: "apv" 1209 o Header Parameter Usage Location(s): JWE 1210 o Change Controller: IETF 1211 o Specification Document(s): Section 4.1.14 of [[ this document ]] 1213 o Header Parameter Name: "crit" 1214 o Header Parameter Usage Location(s): JWS 1215 o Change Controller: IETF 1216 o Specification Document(s): Section 4.1.15 of [[ this document ]] 1218 9.2. JSON Web Signature and Encryption Type Values Registration 1220 9.2.1. Registry Contents 1222 This specification registers the "JWE" and "JWE-JS" type values in 1223 the IANA JSON Web Signature and Encryption Type Values registry 1224 [JWS]: 1226 o "typ" Header Parameter Value: "JWE" 1227 o Abbreviation for MIME Type: application/jwe 1228 o Change Controller: IETF 1229 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1231 o "typ" Header Parameter Value: "JWE-JS" 1232 o Abbreviation for MIME Type: application/jwe-js 1233 o Change Controller: IETF 1234 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1236 9.3. Media Type Registration 1238 9.3.1. Registry Contents 1240 This specification registers the "application/jwe" and 1241 "application/jwe-js" Media Types [RFC2046] in the MIME Media Type 1242 registry [RFC4288] to indicate, respectively, that the content is a 1243 JWE using the JWE Compact Serialization or a JWE using the JWE JSON 1244 Serialization. 1246 o Type Name: application 1247 o Subtype Name: jwe 1248 o Required Parameters: n/a 1249 o Optional Parameters: n/a 1250 o Encoding considerations: JWE values are encoded as a series of 1251 base64url encoded values (some of which may be the empty string) 1252 separated by period ('.') characters 1253 o Security Considerations: See the Security Considerations section 1254 of [[ this document ]] 1255 o Interoperability Considerations: n/a 1256 o Published Specification: [[ this document ]] 1257 o Applications that use this media type: OpenID Connect and other 1258 applications using encrypted JWTs 1259 o Additional Information: Magic number(s): n/a, File extension(s): 1260 n/a, Macintosh file type code(s): n/a 1261 o Person & email address to contact for further information: Michael 1262 B. Jones, mbj@microsoft.com 1263 o Intended Usage: COMMON 1264 o Restrictions on Usage: none 1265 o Author: Michael B. Jones, mbj@microsoft.com 1266 o Change Controller: IETF 1268 o Type Name: application 1269 o Subtype Name: jwe-js 1270 o Required Parameters: n/a 1271 o Optional Parameters: n/a 1272 o Encoding considerations: JWE-JS values are represented as a JSON 1273 Object; UTF-8 encoding SHOULD be employed for the JSON object. 1274 o Security Considerations: See the Security Considerations section 1275 of [[ this document ]] 1276 o Interoperability Considerations: n/a 1277 o Published Specification: [[ this document ]] 1278 o Applications that use this media type: TBD 1279 o Additional Information: Magic number(s): n/a, File extension(s): 1280 n/a, Macintosh file type code(s): n/a 1281 o Person & email address to contact for further information: Michael 1282 B. Jones, mbj@microsoft.com 1283 o Intended Usage: COMMON 1284 o Restrictions on Usage: none 1285 o Author: Michael B. Jones, mbj@microsoft.com 1286 o Change Controller: IETF 1288 10. Security Considerations 1290 All of the security issues faced by any cryptographic application 1291 must be faced by a JWS/JWE/JWK agent. Among these issues are 1292 protecting the user's private and symmetric keys, preventing various 1293 attacks, and helping the user avoid mistakes such as inadvertently 1294 encrypting a message for the wrong recipient. The entire list of 1295 security considerations is beyond the scope of this document. 1297 All the security considerations in the JWS specification also apply 1298 to this specification. Likewise, all the security considerations in 1299 XML Encryption 1.1 [W3C.CR-xmlenc-core1-20120313] also apply, other 1300 than those that are XML specific. 1302 When decrypting, particular care must be taken not to allow the JWE 1303 recipient to be used as an oracle for decrypting messages. RFC 3218 1304 [RFC3218] should be consulted for specific countermeasures to attacks 1305 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1306 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1307 formatting error that can be detected and used to recover the CEK 1308 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1309 particularly important to report all formatting errors to the CEK, 1310 Additional Authenticated Data, or ciphertext as a single error when 1311 the JWE is rejected. 1313 11. References 1315 11.1. Normative References 1317 [ITU.X690.1994] 1318 International Telecommunications Union, "Information 1319 Technology - ASN.1 encoding rules: Specification of Basic 1320 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1321 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1322 X.690, 1994. 1324 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1325 draft-ietf-jose-json-web-algorithms (work in progress), 1326 April 2013. 1328 [JWK] Jones, M., "JSON Web Key (JWK)", 1329 draft-ietf-jose-json-web-key (work in progress), 1330 April 2013. 1332 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1333 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1334 in progress), April 2013. 1336 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 1337 Mail: Part I: Message Encryption and Authentication 1338 Procedures", RFC 1421, February 1993. 1340 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1341 version 1.3", RFC 1951, May 1996. 1343 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1344 Extensions (MIME) Part Two: Media Types", RFC 2046, 1345 November 1996. 1347 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1348 Requirement Levels", BCP 14, RFC 2119, March 1997. 1350 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1352 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1353 10646", STD 63, RFC 3629, November 2003. 1355 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1356 Resource Identifier (URI): Generic Syntax", STD 66, 1357 RFC 3986, January 2005. 1359 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1360 Requirements for Security", BCP 106, RFC 4086, June 2005. 1362 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 1363 Registration Procedures", RFC 4288, December 2005. 1365 [RFC4627] Crockford, D., "The application/json Media Type for 1366 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1368 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1369 Encodings", RFC 4648, October 2006. 1371 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1372 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1374 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1375 Housley, R., and W. Polk, "Internet X.509 Public Key 1376 Infrastructure Certificate and Certificate Revocation List 1377 (CRL) Profile", RFC 5280, May 2008. 1379 [W3C.CR-xmlenc-core1-20120313] 1380 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 1381 "XML Encryption Syntax and Processing Version 1.1", World 1382 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1383 March 2012, 1384 . 1386 11.2. Informative References 1388 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1389 McGrew, D. and K. Paterson, "Authenticated Encryption with 1390 AES-CBC and HMAC-SHA", 1391 draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), 1392 October 2012. 1394 [I-D.rescorla-jsms] 1395 Rescorla, E. and J. Hildebrand, "JavaScript Message 1396 Security Format", draft-rescorla-jsms-00 (work in 1397 progress), March 2011. 1399 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1400 Encryption", September 2010. 1402 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1403 (JWT)", draft-ietf-oauth-json-web-token (work in 1404 progress), April 2013. 1406 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1407 Cryptographic Message Syntax", RFC 3218, January 2002. 1409 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1410 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1411 July 2005. 1413 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1414 RFC 5652, September 2009. 1416 Appendix A. JWE Examples 1418 This section provides examples of JWE computations. 1420 A.1. Example JWE using RSAES OAEP and AES GCM 1422 This example encrypts the plaintext "The true sign of intelligence is 1423 not knowledge but imagination." to the recipient using RSAES OAEP and 1424 AES GCM. The representation of this plaintext is: 1426 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1427 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1428 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1429 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1430 110, 97, 116, 105, 111, 110, 46] 1432 A.1.1. JWE Header 1434 The following example JWE Header declares that: 1436 o the Content Encryption Key is encrypted to the recipient using the 1437 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1439 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1440 bit key to produce the Ciphertext. 1442 {"alg":"RSA-OAEP","enc":"A256GCM"} 1444 A.1.2. Encoded JWE Header 1446 Base64url encoding the octets of the UTF-8 representation of the JWE 1447 Header yields this Encoded JWE Header value: 1449 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1451 A.1.3. Content Encryption Key (CEK) 1453 Generate a 256 bit random Content Encryption Key (CEK). In this 1454 example, the value is: 1456 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1457 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1458 234, 64, 252] 1460 A.1.4. Key Encryption 1462 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1463 algorithm to produce the JWE Encrypted Key. In this example, the RSA 1464 key parameters are: 1466 +-----------+-------------------------------------------------------+ 1467 | Parameter | Value | 1468 | Name | | 1469 +-----------+-------------------------------------------------------+ 1470 | Modulus | [161, 168, 84, 34, 133, 176, 208, 173, 46, 176, 163, | 1471 | | 110, 57, 30, 135, 227, 9, 31, 226, 128, 84, 92, 116, | 1472 | | 241, 70, 248, 27, 227, 193, 62, 5, 91, 241, 145, 224, | 1473 | | 205, 141, 176, 184, 133, 239, 43, 81, 103, 9, 161, | 1474 | | 153, 157, 179, 104, 123, 51, 189, 34, 152, 69, 97, | 1475 | | 69, 78, 93, 140, 131, 87, 182, 169, 101, 92, 142, 3, | 1476 | | 22, 167, 8, 212, 56, 35, 79, 210, 222, 192, 208, 252, | 1477 | | 49, 109, 138, 173, 253, 210, 166, 201, 63, 102, 74, | 1478 | | 5, 158, 41, 90, 144, 108, 160, 79, 10, 89, 222, 231, | 1479 | | 172, 31, 227, 197, 0, 19, 72, 81, 138, 78, 136, 221, | 1480 | | 121, 118, 196, 17, 146, 10, 244, 188, 72, 113, 55, | 1481 | | 221, 162, 217, 171, 27, 57, 233, 210, 101, 236, 154, | 1482 | | 199, 56, 138, 239, 101, 48, 198, 186, 202, 160, 76, | 1483 | | 111, 234, 71, 57, 183, 5, 211, 171, 136, 126, 64, 40, | 1484 | | 75, 58, 89, 244, 254, 107, 84, 103, 7, 236, 69, 163, | 1485 | | 18, 180, 251, 58, 153, 46, 151, 174, 12, 103, 197, | 1486 | | 181, 161, 162, 55, 250, 235, 123, 110, 17, 11, 158, | 1487 | | 24, 47, 133, 8, 199, 235, 107, 126, 130, 246, 73, | 1488 | | 195, 20, 108, 202, 176, 214, 187, 45, 146, 182, 118, | 1489 | | 54, 32, 200, 61, 201, 71, 243, 1, 255, 131, 84, 37, | 1490 | | 111, 211, 168, 228, 45, 192, 118, 27, 197, 235, 232, | 1491 | | 36, 10, 230, 248, 190, 82, 182, 140, 35, 204, 108, | 1492 | | 190, 253, 186, 186, 27] | 1493 | Exponent | [1, 0, 1] | 1494 | Private | [144, 183, 109, 34, 62, 134, 108, 57, 44, 252, 10, | 1495 | Exponent | 66, 73, 54, 16, 181, 233, 92, 54, 219, 101, 42, 35, | 1496 | | 178, 63, 51, 43, 92, 119, 136, 251, 41, 53, 23, 191, | 1497 | | 164, 164, 60, 88, 227, 229, 152, 228, 213, 149, 228, | 1498 | | 169, 237, 104, 71, 151, 75, 88, 252, 216, 77, 251, | 1499 | | 231, 28, 97, 88, 193, 215, 202, 248, 216, 121, 195, | 1500 | | 211, 245, 250, 112, 71, 243, 61, 129, 95, 39, 244, | 1501 | | 122, 225, 217, 169, 211, 165, 48, 253, 220, 59, 122, | 1502 | | 219, 42, 86, 223, 32, 236, 39, 48, 103, 78, 122, 216, | 1503 | | 187, 88, 176, 89, 24, 1, 42, 177, 24, 99, 142, 170, | 1504 | | 1, 146, 43, 3, 108, 64, 194, 121, 182, 95, 187, 134, | 1505 | | 71, 88, 96, 134, 74, 131, 167, 69, 106, 143, 121, 27, | 1506 | | 72, 44, 245, 95, 39, 194, 179, 175, 203, 122, 16, | 1507 | | 112, 183, 17, 200, 202, 31, 17, 138, 156, 184, 210, | 1508 | | 157, 184, 154, 131, 128, 110, 12, 85, 195, 122, 241, | 1509 | | 79, 251, 229, 183, 117, 21, 123, 133, 142, 220, 153, | 1510 | | 9, 59, 57, 105, 81, 255, 138, 77, 82, 54, 62, 216, | 1511 | | 38, 249, 208, 17, 197, 49, 45, 19, 232, 157, 251, | 1512 | | 131, 137, 175, 72, 126, 43, 229, 69, 179, 117, 82, | 1513 | | 157, 213, 83, 35, 57, 210, 197, 252, 171, 143, 194, | 1514 | | 11, 47, 163, 6, 253, 75, 252, 96, 11, 187, 84, 130, | 1515 | | 210, 7, 121, 78, 91, 79, 57, 251, 138, 132, 220, 60, | 1516 | | 224, 173, 56, 224, 201] | 1517 +-----------+-------------------------------------------------------+ 1519 The resulting JWE Encrypted Key value is: 1521 [2, 151, 206, 44, 38, 131, 110, 171, 63, 37, 115, 216, 203, 98, 61, 1522 223, 187, 255, 198, 106, 243, 143, 226, 44, 179, 89, 134, 232, 208, 1523 7, 153, 226, 85, 136, 206, 163, 218, 93, 12, 30, 247, 236, 120, 135, 1524 71, 87, 37, 54, 4, 138, 6, 86, 239, 104, 134, 249, 36, 90, 36, 106, 1525 228, 50, 246, 141, 134, 83, 60, 15, 83, 1, 220, 42, 220, 85, 8, 87, 1526 42, 7, 248, 247, 157, 127, 167, 165, 28, 133, 69, 139, 98, 134, 12, 1527 75, 41, 96, 203, 80, 1, 19, 12, 72, 23, 18, 238, 155, 37, 199, 167, 1528 229, 135, 80, 159, 135, 113, 129, 43, 43, 51, 181, 83, 4, 133, 159, 1529 230, 104, 89, 38, 224, 246, 21, 10, 194, 108, 190, 174, 130, 183, 1530 119, 224, 216, 34, 79, 58, 205, 23, 212, 49, 238, 197, 146, 168, 32, 1531 98, 42, 113, 183, 138, 225, 113, 14, 229, 173, 33, 229, 48, 46, 36, 1532 230, 202, 117, 243, 180, 116, 172, 31, 53, 36, 155, 166, 238, 108, 1533 22, 186, 81, 23, 5, 118, 21, 52, 216, 162, 161, 120, 204, 142, 58, 1534 55, 223, 191, 132, 194, 51, 158, 81, 41, 126, 212, 87, 133, 39, 4, 1535 38, 230, 125, 28, 111, 2, 240, 33, 193, 213, 100, 89, 252, 158, 60, 1536 62, 87, 170, 118, 17, 120, 163, 183, 193, 228, 157, 112, 22, 165, 23, 1537 6, 214, 237, 184, 98, 127, 3, 101, 222, 232, 1, 33, 174, 92, 194, 59] 1539 A.1.5. Encoded JWE Encrypted Key 1541 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1542 Encrypted Key. This result (with line breaks for display purposes 1543 only) is: 1545 ApfOLCaDbqs_JXPYy2I937v_xmrzj-Iss1mG6NAHmeJViM6j2l0MHvfseIdHVyU2 1546 BIoGVu9ohvkkWiRq5DL2jYZTPA9TAdwq3FUIVyoH-Pedf6elHIVFi2KGDEspYMtQ 1547 ARMMSBcS7pslx6flh1Cfh3GBKysztVMEhZ_maFkm4PYVCsJsvq6Ct3fg2CJPOs0X 1548 1DHuxZKoIGIqcbeK4XEO5a0h5TAuJObKdfO0dKwfNSSbpu5sFrpRFwV2FTTYoqF4 1549 zI46N9-_hMIznlEpftRXhScEJuZ9HG8C8CHB1WRZ_J48PleqdhF4o7fB5J1wFqUX 1550 BtbtuGJ_A2Xe6AEhrlzCOw 1552 A.1.6. Initialization Vector 1554 Generate a random 96 bit JWE Initialization Vector. In this example, 1555 the value is: 1557 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1559 Base64url encoding this value yields the Encoded JWE Initialization 1560 Vector value: 1562 48V1_ALb6US04U3b 1564 A.1.7. Additional Authenticated Data Parameter 1566 Concatenate the Encoded JWE Header value, a period ('.') character, 1567 and the Encoded JWE Encrypted Key to create the Additional 1568 Authenticated Data parameter. This result (with line breaks for 1569 display purposes only) is: 1571 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1572 ApfOLCaDbqs_JXPYy2I937v_xmrzj-Iss1mG6NAHmeJViM6j2l0MHvfseIdHVyU2 1573 BIoGVu9ohvkkWiRq5DL2jYZTPA9TAdwq3FUIVyoH-Pedf6elHIVFi2KGDEspYMtQ 1574 ARMMSBcS7pslx6flh1Cfh3GBKysztVMEhZ_maFkm4PYVCsJsvq6Ct3fg2CJPOs0X 1575 1DHuxZKoIGIqcbeK4XEO5a0h5TAuJObKdfO0dKwfNSSbpu5sFrpRFwV2FTTYoqF4 1576 zI46N9-_hMIznlEpftRXhScEJuZ9HG8C8CHB1WRZ_J48PleqdhF4o7fB5J1wFqUX 1577 BtbtuGJ_A2Xe6AEhrlzCOw 1579 The representation of this value is: 1581 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1582 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1583 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81, 46, 1584 65, 112, 102, 79, 76, 67, 97, 68, 98, 113, 115, 95, 74, 88, 80, 89, 1585 121, 50, 73, 57, 51, 55, 118, 95, 120, 109, 114, 122, 106, 45, 73, 1586 115, 115, 49, 109, 71, 54, 78, 65, 72, 109, 101, 74, 86, 105, 77, 54, 1587 106, 50, 108, 48, 77, 72, 118, 102, 115, 101, 73, 100, 72, 86, 121, 1588 85, 50, 66, 73, 111, 71, 86, 117, 57, 111, 104, 118, 107, 107, 87, 1589 105, 82, 113, 53, 68, 76, 50, 106, 89, 90, 84, 80, 65, 57, 84, 65, 1590 100, 119, 113, 51, 70, 85, 73, 86, 121, 111, 72, 45, 80, 101, 100, 1591 102, 54, 101, 108, 72, 73, 86, 70, 105, 50, 75, 71, 68, 69, 115, 112, 1592 89, 77, 116, 81, 65, 82, 77, 77, 83, 66, 99, 83, 55, 112, 115, 108, 1593 120, 54, 102, 108, 104, 49, 67, 102, 104, 51, 71, 66, 75, 121, 115, 1594 122, 116, 86, 77, 69, 104, 90, 95, 109, 97, 70, 107, 109, 52, 80, 89, 1595 86, 67, 115, 74, 115, 118, 113, 54, 67, 116, 51, 102, 103, 50, 67, 1596 74, 80, 79, 115, 48, 88, 49, 68, 72, 117, 120, 90, 75, 111, 73, 71, 1597 73, 113, 99, 98, 101, 75, 52, 88, 69, 79, 53, 97, 48, 104, 53, 84, 1598 65, 117, 74, 79, 98, 75, 100, 102, 79, 48, 100, 75, 119, 102, 78, 83, 1599 83, 98, 112, 117, 53, 115, 70, 114, 112, 82, 70, 119, 86, 50, 70, 84, 1600 84, 89, 111, 113, 70, 52, 122, 73, 52, 54, 78, 57, 45, 95, 104, 77, 1601 73, 122, 110, 108, 69, 112, 102, 116, 82, 88, 104, 83, 99, 69, 74, 1602 117, 90, 57, 72, 71, 56, 67, 56, 67, 72, 66, 49, 87, 82, 90, 95, 74, 1603 52, 56, 80, 108, 101, 113, 100, 104, 70, 52, 111, 55, 102, 66, 53, 1604 74, 49, 119, 70, 113, 85, 88, 66, 116, 98, 116, 117, 71, 74, 95, 65, 1605 50, 88, 101, 54, 65, 69, 104, 114, 108, 122, 67, 79, 119] 1607 A.1.8. Plaintext Encryption 1609 Encrypt the Plaintext with AES GCM using the CEK as the encryption 1610 key, the JWE Initialization Vector, and the Additional Authenticated 1611 Data value above, requesting a 128 bit Authentication Tag output. 1612 The resulting Ciphertext is: 1614 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1615 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1616 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1617 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1618 160, 109, 64, 63, 192] 1620 The resulting Authentication Tag value is: 1622 [130, 17, 32, 198, 120, 167, 144, 113, 0, 50, 158, 49, 102, 208, 118, 1623 152] 1625 A.1.9. Encoded JWE Ciphertext 1627 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1628 This result (with line breaks for display purposes only) is: 1630 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1631 SdiwkIr3ajwQzaBtQD_A 1633 A.1.10. Encoded JWE Authentication Tag 1635 Base64url encode the Authentication Tag to create the Encoded JWE 1636 Authentication Tag. This result is: 1638 ghEgxninkHEAMp4xZtB2mA 1640 A.1.11. Complete Representation 1642 Assemble the final representation: The Compact Serialization of this 1643 result is the concatenation of the Encoded JWE Header, the Encoded 1644 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1645 JWE Ciphertext, and the Encoded JWE Authentication Tag in that order, 1646 with the five strings being separated by four period ('.') 1647 characters. 1649 The final result in this example (with line breaks for display 1650 purposes only) is: 1652 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1653 ApfOLCaDbqs_JXPYy2I937v_xmrzj-Iss1mG6NAHmeJViM6j2l0MHvfseIdHVyU2 1654 BIoGVu9ohvkkWiRq5DL2jYZTPA9TAdwq3FUIVyoH-Pedf6elHIVFi2KGDEspYMtQ 1655 ARMMSBcS7pslx6flh1Cfh3GBKysztVMEhZ_maFkm4PYVCsJsvq6Ct3fg2CJPOs0X 1656 1DHuxZKoIGIqcbeK4XEO5a0h5TAuJObKdfO0dKwfNSSbpu5sFrpRFwV2FTTYoqF4 1657 zI46N9-_hMIznlEpftRXhScEJuZ9HG8C8CHB1WRZ_J48PleqdhF4o7fB5J1wFqUX 1658 BtbtuGJ_A2Xe6AEhrlzCOw. 1659 48V1_ALb6US04U3b. 1660 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1661 SdiwkIr3ajwQzaBtQD_A. 1662 ghEgxninkHEAMp4xZtB2mA 1664 A.1.12. Validation 1666 This example illustrates the process of creating a JWE with RSA OAEP 1667 and AES GCM. These results can be used to validate JWE decryption 1668 implementations for these algorithms. Note that since the RSAES OAEP 1669 computation includes random values, the encryption results above will 1670 not be completely reproducible. However, since the AES GCM 1671 computation is deterministic, the JWE Encrypted Ciphertext values 1672 will be the same for all encryptions performed using these inputs. 1674 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1676 This example encrypts the plaintext "Live long and prosper." to the 1677 recipient using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256. The 1678 representation of this plaintext is: 1680 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1681 112, 114, 111, 115, 112, 101, 114, 46] 1683 A.2.1. JWE Header 1685 The following example JWE Header (with line breaks for display 1686 purposes only) declares that: 1688 o the Content Encryption Key is encrypted to the recipient using the 1689 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1691 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1692 algorithm to produce the Ciphertext. 1694 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1696 A.2.2. Encoded JWE Header 1698 Base64url encoding the octets of the UTF-8 representation of the JWE 1699 Header yields this Encoded JWE Header value: 1701 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1703 A.2.3. Content Encryption Key (CEK) 1705 Generate a 256 bit random Content Encryption Key (CEK). In this 1706 example, the key value is: 1708 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1709 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1710 44, 207] 1712 A.2.4. Key Encryption 1714 Encrypt the CEK with the recipient's public key using the RSAES- 1715 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. In this 1716 example, the RSA key parameters are: 1718 +-----------+-------------------------------------------------------+ 1719 | Parameter | Value | 1720 | Name | | 1721 +-----------+-------------------------------------------------------+ 1722 | Modulus | [177, 119, 33, 13, 164, 30, 108, 121, 207, 136, 107, | 1723 | | 242, 12, 224, 19, 226, 198, 134, 17, 71, 173, 75, 42, | 1724 | | 61, 48, 162, 206, 161, 97, 108, 185, 234, 226, 219, | 1725 | | 118, 206, 118, 5, 169, 224, 60, 181, 90, 85, 51, 123, | 1726 | | 6, 224, 4, 122, 29, 230, 151, 12, 244, 127, 121, 25, | 1727 | | 4, 85, 220, 144, 215, 110, 130, 17, 68, 228, 129, | 1728 | | 138, 7, 130, 231, 40, 212, 214, 17, 179, 28, 124, | 1729 | | 151, 178, 207, 20, 14, 154, 222, 113, 176, 24, 198, | 1730 | | 73, 211, 113, 9, 33, 178, 80, 13, 25, 21, 25, 153, | 1731 | | 212, 206, 67, 154, 147, 70, 194, 192, 183, 160, 83, | 1732 | | 98, 236, 175, 85, 23, 97, 75, 199, 177, 73, 145, 50, | 1733 | | 253, 206, 32, 179, 254, 236, 190, 82, 73, 67, 129, | 1734 | | 253, 252, 220, 108, 136, 138, 11, 192, 1, 36, 239, | 1735 | | 228, 55, 81, 113, 17, 25, 140, 63, 239, 146, 3, 172, | 1736 | | 96, 60, 227, 233, 64, 255, 224, 173, 225, 228, 229, | 1737 | | 92, 112, 72, 99, 97, 26, 87, 187, 123, 46, 50, 90, | 1738 | | 202, 117, 73, 10, 153, 47, 224, 178, 163, 77, 48, 46, | 1739 | | 154, 33, 148, 34, 228, 33, 172, 216, 89, 46, 225, | 1740 | | 127, 68, 146, 234, 30, 147, 54, 146, 5, 133, 45, 78, | 1741 | | 254, 85, 55, 75, 213, 86, 194, 218, 215, 163, 189, | 1742 | | 194, 54, 6, 83, 36, 18, 153, 53, 7, 48, 89, 35, 66, | 1743 | | 144, 7, 65, 154, 13, 97, 75, 55, 230, 132, 3, 13, | 1744 | | 239, 71] | 1745 | Exponent | [1, 0, 1] | 1746 | Private | [84, 80, 150, 58, 165, 235, 242, 123, 217, 55, 38, | 1747 | Exponent | 154, 36, 181, 221, 156, 211, 215, 100, 164, 90, 88, | 1748 | | 40, 228, 83, 148, 54, 122, 4, 16, 165, 48, 76, 194, | 1749 | | 26, 107, 51, 53, 179, 165, 31, 18, 198, 173, 78, 61, | 1750 | | 56, 97, 252, 158, 140, 80, 63, 25, 223, 156, 36, 203, | 1751 | | 214, 252, 120, 67, 180, 167, 3, 82, 243, 25, 97, 214, | 1752 | | 83, 133, 69, 16, 104, 54, 160, 200, 41, 83, 164, 187, | 1753 | | 70, 153, 111, 234, 242, 158, 175, 28, 198, 48, 211, | 1754 | | 45, 148, 58, 23, 62, 227, 74, 52, 117, 42, 90, 41, | 1755 | | 249, 130, 154, 80, 119, 61, 26, 193, 40, 125, 10, | 1756 | | 152, 174, 227, 225, 205, 32, 62, 66, 6, 163, 100, 99, | 1757 | | 219, 19, 253, 25, 105, 80, 201, 29, 252, 157, 237, | 1758 | | 69, 1, 80, 171, 167, 20, 196, 156, 109, 249, 88, 0, | 1759 | | 3, 152, 38, 165, 72, 87, 6, 152, 71, 156, 214, 16, | 1760 | | 71, 30, 82, 51, 103, 76, 218, 63, 9, 84, 163, 249, | 1761 | | 91, 215, 44, 238, 85, 101, 240, 148, 1, 82, 224, 91, | 1762 | | 135, 105, 127, 84, 171, 181, 152, 210, 183, 126, 24, | 1763 | | 46, 196, 90, 173, 38, 245, 219, 186, 222, 27, 240, | 1764 | | 212, 194, 15, 66, 135, 226, 178, 190, 52, 245, 74, | 1765 | | 65, 224, 81, 100, 85, 25, 204, 165, 203, 187, 175, | 1766 | | 84, 100, 82, 15, 11, 23, 202, 151, 107, 54, 41, 207, | 1767 | | 3, 136, 229, 134, 131, 93, 139, 50, 182, 204, 93, | 1768 | | 130, 89] | 1769 +-----------+-------------------------------------------------------+ 1771 The resulting JWE Encrypted Key value is: 1773 [156, 150, 191, 184, 77, 131, 211, 9, 74, 207, 227, 156, 193, 38, 1774 202, 23, 56, 247, 211, 108, 88, 72, 143, 145, 44, 19, 58, 133, 181, 1775 70, 152, 254, 26, 198, 210, 80, 60, 15, 82, 210, 154, 55, 179, 115, 1776 76, 146, 99, 166, 146, 70, 176, 157, 252, 15, 54, 58, 92, 210, 103, 1777 55, 207, 191, 92, 185, 5, 164, 64, 241, 80, 163, 233, 131, 198, 106, 1778 32, 207, 199, 113, 5, 200, 94, 105, 53, 32, 221, 155, 233, 108, 96, 1779 151, 197, 152, 195, 96, 67, 81, 90, 38, 121, 51, 208, 98, 47, 45, 61, 1780 4, 129, 121, 152, 122, 124, 229, 2, 250, 92, 64, 245, 36, 70, 76, 58, 1781 31, 181, 185, 61, 101, 168, 240, 220, 12, 62, 253, 169, 107, 107, 9, 1782 241, 9, 152, 217, 159, 179, 30, 95, 112, 29, 143, 124, 7, 21, 181, 1783 13, 45, 253, 137, 142, 95, 30, 127, 26, 237, 34, 183, 89, 200, 44, 1784 165, 203, 71, 102, 39, 127, 217, 159, 46, 17, 28, 11, 146, 222, 110, 1785 149, 178, 16, 117, 186, 91, 52, 56, 136, 127, 82, 33, 194, 46, 164, 1786 245, 117, 136, 160, 179, 152, 151, 15, 172, 48, 73, 228, 87, 63, 40, 1787 192, 92, 92, 24, 167, 105, 47, 255, 193, 251, 77, 203, 6, 134, 129, 1788 248, 191, 53, 43, 49, 219, 130, 241, 180, 174, 159, 34, 71, 163, 70, 1789 83, 1, 152, 39, 241, 191, 68, 224, 240, 43, 113, 165, 68, 98, 130] 1791 A.2.5. Encoded JWE Encrypted Key 1793 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1794 Encrypted Key. This result (with line breaks for display purposes 1795 only) is: 1797 nJa_uE2D0wlKz-OcwSbKFzj302xYSI-RLBM6hbVGmP4axtJQPA9S0po3s3NMkmOm 1798 kkawnfwPNjpc0mc3z79cuQWkQPFQo-mDxmogz8dxBcheaTUg3ZvpbGCXxZjDYENR 1799 WiZ5M9BiLy09BIF5mHp85QL6XED1JEZMOh-1uT1lqPDcDD79qWtrCfEJmNmfsx5f 1800 cB2PfAcVtQ0t_YmOXx5_Gu0it1nILKXLR2Ynf9mfLhEcC5LebpWyEHW6WzQ4iH9S 1801 IcIupPV1iKCzmJcPrDBJ5Fc_KMBcXBinaS__wftNywaGgfi_NSsx24LxtK6fIkej 1802 RlMBmCfxv0Tg8CtxpURigg 1804 A.2.6. Initialization Vector 1806 Generate a random 128 bit JWE Initialization Vector. In this 1807 example, the value is: 1809 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1810 101] 1812 Base64url encoding this value yields the Encoded JWE Initialization 1813 Vector value: 1815 AxY8DCtDaGlsbGljb3RoZQ 1817 A.2.7. Additional Authenticated Data Parameter 1819 Concatenate the Encoded JWE Header value, a period ('.') character, 1820 and the Encoded JWE Encrypted Key to create the Additional 1821 Authenticated Data parameter. This result (with line breaks for 1822 display purposes only) is: 1824 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1825 nJa_uE2D0wlKz-OcwSbKFzj302xYSI-RLBM6hbVGmP4axtJQPA9S0po3s3NMkmOm 1826 kkawnfwPNjpc0mc3z79cuQWkQPFQo-mDxmogz8dxBcheaTUg3ZvpbGCXxZjDYENR 1827 WiZ5M9BiLy09BIF5mHp85QL6XED1JEZMOh-1uT1lqPDcDD79qWtrCfEJmNmfsx5f 1828 cB2PfAcVtQ0t_YmOXx5_Gu0it1nILKXLR2Ynf9mfLhEcC5LebpWyEHW6WzQ4iH9S 1829 IcIupPV1iKCzmJcPrDBJ5Fc_KMBcXBinaS__wftNywaGgfi_NSsx24LxtK6fIkej 1830 RlMBmCfxv0Tg8CtxpURigg 1832 The representation of this value is: 1834 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1835 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1836 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1837 50, 73, 110, 48, 46, 110, 74, 97, 95, 117, 69, 50, 68, 48, 119, 108, 1838 75, 122, 45, 79, 99, 119, 83, 98, 75, 70, 122, 106, 51, 48, 50, 120, 1839 89, 83, 73, 45, 82, 76, 66, 77, 54, 104, 98, 86, 71, 109, 80, 52, 97, 1840 120, 116, 74, 81, 80, 65, 57, 83, 48, 112, 111, 51, 115, 51, 78, 77, 1841 107, 109, 79, 109, 107, 107, 97, 119, 110, 102, 119, 80, 78, 106, 1842 112, 99, 48, 109, 99, 51, 122, 55, 57, 99, 117, 81, 87, 107, 81, 80, 1843 70, 81, 111, 45, 109, 68, 120, 109, 111, 103, 122, 56, 100, 120, 66, 1844 99, 104, 101, 97, 84, 85, 103, 51, 90, 118, 112, 98, 71, 67, 88, 120, 1845 90, 106, 68, 89, 69, 78, 82, 87, 105, 90, 53, 77, 57, 66, 105, 76, 1846 121, 48, 57, 66, 73, 70, 53, 109, 72, 112, 56, 53, 81, 76, 54, 88, 1847 69, 68, 49, 74, 69, 90, 77, 79, 104, 45, 49, 117, 84, 49, 108, 113, 1848 80, 68, 99, 68, 68, 55, 57, 113, 87, 116, 114, 67, 102, 69, 74, 109, 1849 78, 109, 102, 115, 120, 53, 102, 99, 66, 50, 80, 102, 65, 99, 86, 1850 116, 81, 48, 116, 95, 89, 109, 79, 88, 120, 53, 95, 71, 117, 48, 105, 1851 116, 49, 110, 73, 76, 75, 88, 76, 82, 50, 89, 110, 102, 57, 109, 102, 1852 76, 104, 69, 99, 67, 53, 76, 101, 98, 112, 87, 121, 69, 72, 87, 54, 1853 87, 122, 81, 52, 105, 72, 57, 83, 73, 99, 73, 117, 112, 80, 86, 49, 1854 105, 75, 67, 122, 109, 74, 99, 80, 114, 68, 66, 74, 53, 70, 99, 95, 1855 75, 77, 66, 99, 88, 66, 105, 110, 97, 83, 95, 95, 119, 102, 116, 78, 1856 121, 119, 97, 71, 103, 102, 105, 95, 78, 83, 115, 120, 50, 52, 76, 1857 120, 116, 75, 54, 102, 73, 107, 101, 106, 82, 108, 77, 66, 109, 67, 1858 102, 120, 118, 48, 84, 103, 56, 67, 116, 120, 112, 85, 82, 105, 103, 1859 103] 1861 A.2.8. Plaintext Encryption 1863 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1864 the encryption key, the JWE Initialization Vector, and the Additional 1865 Authenticated Data value above. The steps for doing this using the 1866 values from Appendix A.3 are detailed in Appendix B. The resulting 1867 Ciphertext is: 1869 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1870 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1871 112, 56, 102] 1873 The resulting Authentication Tag value is: 1875 [125, 141, 148, 252, 124, 121, 85, 199, 215, 154, 42, 68, 149, 209, 1876 225, 48] 1878 A.2.9. Encoded JWE Ciphertext 1880 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1881 This result is: 1883 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1885 A.2.10. Encoded JWE Authentication Tag 1887 Base64url encode the Authentication Tag to create the Encoded JWE 1888 Authentication Tag. This result is: 1890 fY2U_Hx5VcfXmipEldHhMA 1892 A.2.11. Complete Representation 1894 Assemble the final representation: The Compact Serialization of this 1895 result is the concatenation of the Encoded JWE Header, the Encoded 1896 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1897 JWE Ciphertext, and the Encoded JWE Authentication Tag in that order, 1898 with the five strings being separated by four period ('.') 1899 characters. 1901 The final result in this example (with line breaks for display 1902 purposes only) is: 1904 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1905 nJa_uE2D0wlKz-OcwSbKFzj302xYSI-RLBM6hbVGmP4axtJQPA9S0po3s3NMkmOm 1906 kkawnfwPNjpc0mc3z79cuQWkQPFQo-mDxmogz8dxBcheaTUg3ZvpbGCXxZjDYENR 1907 WiZ5M9BiLy09BIF5mHp85QL6XED1JEZMOh-1uT1lqPDcDD79qWtrCfEJmNmfsx5f 1908 cB2PfAcVtQ0t_YmOXx5_Gu0it1nILKXLR2Ynf9mfLhEcC5LebpWyEHW6WzQ4iH9S 1909 IcIupPV1iKCzmJcPrDBJ5Fc_KMBcXBinaS__wftNywaGgfi_NSsx24LxtK6fIkej 1910 RlMBmCfxv0Tg8CtxpURigg. 1911 AxY8DCtDaGlsbGljb3RoZQ. 1912 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1913 fY2U_Hx5VcfXmipEldHhMA 1915 A.2.12. Validation 1917 This example illustrates the process of creating a JWE with RSAES- 1918 PKCS1-V1_5 and AES_CBC_HMAC_SHA2. These results can be used to 1919 validate JWE decryption implementations for these algorithms. Note 1920 that since the RSAES-PKCS1-V1_5 computation includes random values, 1921 the encryption results above will not be completely reproducible. 1922 However, since the AES CBC computation is deterministic, the JWE 1923 Encrypted Ciphertext values will be the same for all encryptions 1924 performed using these inputs. 1926 A.3. Example JWE using AES Key Wrap and AES GCM 1928 This example encrypts the plaintext "Live long and prosper." to the 1929 recipient using AES Key Wrap and AES GCM. The representation of this 1930 plaintext is: 1932 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1933 112, 114, 111, 115, 112, 101, 114, 46] 1935 A.3.1. JWE Header 1937 The following example JWE Header declares that: 1939 o the Content Encryption Key is encrypted to the recipient using the 1940 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1941 Encrypted Key and 1943 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1944 algorithm to produce the Ciphertext. 1946 {"alg":"A128KW","enc":"A128CBC-HS256"} 1948 A.3.2. Encoded JWE Header 1950 Base64url encoding the octets of the UTF-8 representation of the JWE 1951 Header yields this Encoded JWE Header value: 1953 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1955 A.3.3. Content Encryption Key (CEK) 1957 Generate a 256 bit random Content Encryption Key (CEK). In this 1958 example, the value is: 1960 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1961 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1962 44, 207] 1964 A.3.4. Key Encryption 1966 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1967 algorithm to produce the JWE Encrypted Key. In this example, the 1968 shared symmetric key value is: 1970 [25, 172, 32, 130, 225, 114, 26, 181, 138, 106, 254, 192, 95, 133, 1971 74, 82] 1973 The resulting JWE Encrypted Key value is: 1975 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1976 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1977 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1979 A.3.5. Encoded JWE Encrypted Key 1981 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1982 Encrypted Key. This result is: 1984 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1986 A.3.6. Initialization Vector 1988 Generate a random 128 bit JWE Initialization Vector. In this 1989 example, the value is: 1991 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1992 101] 1994 Base64url encoding this value yields the Encoded JWE Initialization 1995 Vector value: 1997 AxY8DCtDaGlsbGljb3RoZQ 1999 A.3.7. Additional Authenticated Data Parameter 2001 Concatenate the Encoded JWE Header value, a period ('.') character, 2002 and the Encoded JWE Encrypted Key to create the Additional 2003 Authenticated Data parameter. This result (with line breaks for 2004 display purposes only) is: 2006 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 2007 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 2009 The representation of this value is: 2011 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2012 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2013 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2014 110, 48, 46, 54, 75, 66, 55, 48, 55, 100, 77, 57, 89, 84, 73, 103, 2015 72, 116, 76, 118, 116, 103, 87, 81, 56, 109, 75, 119, 98, 111, 74, 2016 87, 51, 111, 102, 57, 108, 111, 99, 105, 122, 107, 68, 84, 72, 122, 2017 66, 67, 50, 73, 108, 114, 84, 49, 111, 79, 81] 2019 A.3.8. Plaintext Encryption 2021 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 2022 the encryption key, the JWE Initialization Vector, and the Additional 2023 Authenticated Data value above. The steps for doing this using the 2024 values from this example are detailed in Appendix B. The resulting 2025 Ciphertext is: 2027 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 2028 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 2029 112, 56, 102] 2031 The resulting Authentication Tag value is: 2033 [8, 65, 248, 101, 45, 185, 28, 218, 232, 112, 83, 79, 84, 221, 18, 2034 172] 2036 A.3.9. Encoded JWE Ciphertext 2038 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 2039 This result is: 2041 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 2043 A.3.10. Encoded JWE Authentication Tag 2045 Base64url encode the Authentication Tag to create the Encoded JWE 2046 Authentication Tag. This result is: 2048 CEH4ZS25HNrocFNPVN0SrA 2050 A.3.11. Complete Representation 2052 Assemble the final representation: The Compact Serialization of this 2053 result is the concatenation of the Encoded JWE Header, the Encoded 2054 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 2055 JWE Ciphertext, and the Encoded JWE Authentication Tag in that order, 2056 with the five strings being separated by four period ('.') 2057 characters. 2059 The final result in this example (with line breaks for display 2060 purposes only) is: 2062 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 2063 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 2064 AxY8DCtDaGlsbGljb3RoZQ. 2065 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 2066 CEH4ZS25HNrocFNPVN0SrA 2068 A.3.12. Validation 2070 This example illustrates the process of creating a JWE with symmetric 2071 key wrap and AES_CBC_HMAC_SHA2. These results can be used to 2072 validate JWE decryption implementations for these algorithms. Also, 2073 since both the AES Key Wrap and AES GCM computations are 2074 deterministic, the resulting JWE value will be the same for all 2075 encryptions performed using these inputs. Since the computation is 2076 reproducible, these results can also be used to validate JWE 2077 encryption implementations for these algorithms. 2079 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 2081 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 2082 authenticated encryption computation using the values from the 2083 example in Appendix A.3. As described where this algorithm is 2084 defined in Sections 4.8 and 4.8.3 of JWA, the AES_CBC_HMAC_SHA2 2085 family of algorithms are implemented using Advanced Encryption 2086 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #5 2087 padding to perform the encryption and an HMAC SHA-2 function to 2088 perform the integrity calculation - in this case, HMAC SHA-256. 2090 B.1. Extract MAC_KEY and ENC_KEY from Key 2092 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example is: 2094 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 2095 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 2096 44, 207] 2098 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 2099 which is: 2101 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 2102 206] 2104 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 2105 is: 2107 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 2108 207] 2110 Note that the MAC key comes before the encryption key in the input 2111 key K; this is in the opposite order of the algorithm names in the 2112 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 2114 B.2. Encrypt Plaintext to Create Ciphertext 2116 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 2117 using PKCS #5 padding using the ENC_KEY above. The Plaintext in this 2118 example is: 2120 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 2121 112, 114, 111, 115, 112, 101, 114, 46] 2122 The encryption result is as follows, which is the Ciphertext output: 2124 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 2125 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 2126 112, 56, 102] 2128 B.3. Create 64 Bit Big Endian Representation of AAD Length 2130 The Additional Authenticated Data (AAD) in this example is: 2132 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2133 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2134 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2135 110, 48, 46, 54, 75, 66, 55, 48, 55, 100, 77, 57, 89, 84, 73, 103, 2136 72, 116, 76, 118, 116, 103, 87, 81, 56, 109, 75, 119, 98, 111, 74, 2137 87, 51, 111, 102, 57, 108, 111, 99, 105, 122, 107, 68, 84, 72, 122, 2138 66, 67, 50, 73, 108, 114, 84, 49, 111, 79, 81] 2140 This AAD is 106 bytes long, which is 848 bits long. The octet string 2141 AL, which is the number of bits in AAD expressed as a big endian 64 2142 bit unsigned integer is: 2144 [0, 0, 0, 0, 0, 0, 3, 80] 2146 B.4. Initialization Vector Value 2148 The Initialization Vector value used in this example is: 2150 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 2151 101] 2153 B.5. Create Input to HMAC Computation 2155 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 2156 the AL value. The result of this concatenation is: 2158 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2159 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2160 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2161 110, 48, 46, 54, 75, 66, 55, 48, 55, 100, 77, 57, 89, 84, 73, 103, 2162 72, 116, 76, 118, 116, 103, 87, 81, 56, 109, 75, 119, 98, 111, 74, 2163 87, 51, 111, 102, 57, 108, 111, 99, 105, 122, 107, 68, 84, 72, 122, 2164 66, 67, 50, 73, 108, 114, 84, 49, 111, 79, 81, 3, 22, 60, 12, 43, 67, 2165 104, 105, 108, 108, 105, 99, 111, 116, 104, 101, 40, 57, 83, 181, 2166 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 75, 129, 223, 127, 2167 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 112, 56, 102, 0, 0, 0, 2168 0, 0, 0, 3, 80] 2170 B.6. Compute HMAC Value 2172 Compute the HMAC SHA-256 of the concatenated value above. This 2173 result M is: 2175 [8, 65, 248, 101, 45, 185, 28, 218, 232, 112, 83, 79, 84, 221, 18, 2176 172, 50, 145, 207, 8, 14, 74, 44, 220, 100, 117, 32, 57, 239, 149, 2177 173, 226] 2179 B.7. Truncate HMAC Value to Create Authentication Tag 2181 Use the first half (128 bits) of the HMAC output M as the 2182 Authentication Tag output T. This truncated value is: 2184 [8, 65, 248, 101, 45, 185, 28, 218, 232, 112, 83, 79, 84, 221, 18, 2185 172] 2187 Appendix C. Possible Compact Serialization for Multiple Recipients 2189 The JWE encryption process in Section 5.1, and in particular in steps 2190 15 and 16, hint at a possible compact serialization when there are 2191 multiple recipients. This possible compact serialization 2192 concatenates instances of the per-recipient fields, separating them 2193 with tilde ('~') characters, which are URL-safe. 2195 The concatenation of the Encoded JWE Header values goes before the 2196 first period ('.') character in the compact serialization. The 2197 concatenation of the corresponding Encoded JWE Encoded Key values 2198 goes between the first and second period ('.') characters in the 2199 compact serialization. 2201 A complete compact serialization of the multi-recipient JWE in 2202 Section 7.1 (with line breaks for display purposes only) would be: 2204 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 2205 ~ 2206 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 2207 . 2208 nJa_uE2D0wlKz-OcwSbKFzj302xYSI-RLBM6hbVGmP4axtJQPA9S0po3s3NMk 2209 mOmkkawnfwPNjpc0mc3z79cuQWkQPFQo-mDxmogz8dxBcheaTUg3ZvpbGCXxZ 2210 jDYENRWiZ5M9BiLy09BIF5mHp85QL6XED1JEZMOh-1uT1lqPDcDD79qWtrCfE 2211 JmNmfsx5fcB2PfAcVtQ0t_YmOXx5_Gu0it1nILKXLR2Ynf9mfLhEcC5LebpWy 2212 EHW6WzQ4iH9SIcIupPV1iKCzmJcPrDBJ5Fc_KMBcXBinaS__wftNywaGgfi_N 2213 Ssx24LxtK6fIkejRlMBmCfxv0Tg8CtxpURigg 2214 ~ 2215 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 2216 . 2217 AxY8DCtDaGlsbGljb3RoZQ 2218 . 2219 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 2220 . 2221 LlhRZFfphc2f5X3nTTJP6g 2223 Note that the octets of the UTF-8 representation of the first two 2224 parts of this serialization, including the period ('.') character 2225 separating them, are used as the AAD value in step 17 of the JWE 2226 encryption process in Section 5.1. 2228 This representation is suggested for those who may desire or require 2229 a compact, URL-safe serialization of JWEs with multiple recipients. 2230 It is a suggestion to implementers for whom this functionality would 2231 be valuable, and not a normative part of this specification. 2233 Appendix D. Acknowledgements 2235 Solutions for encrypting JSON content were also explored by JSON 2236 Simple Encryption [JSE] and JavaScript Message Security Format 2237 [I-D.rescorla-jsms], both of which significantly influenced this 2238 draft. This draft attempts to explicitly reuse as many of the 2239 relevant concepts from XML Encryption 1.1 2240 [W3C.CR-xmlenc-core1-20120313] and RFC 5652 [RFC5652] as possible, 2241 while utilizing simple compact JSON-based data structures. 2243 Special thanks are due to John Bradley and Nat Sakimura for the 2244 discussions that helped inform the content of this specification and 2245 to Eric Rescorla and Joe Hildebrand for allowing the reuse of text 2246 from [I-D.rescorla-jsms] in this document. 2248 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2249 Jay for validating the examples in this specification. 2251 This specification is the work of the JOSE Working Group, which 2252 includes dozens of active and dedicated participants. In particular, 2253 the following individuals contributed ideas, feedback, and wording 2254 that influenced this specification: 2256 Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick 2257 Hardt, Jeff Hodges, Edmund Jay, James Manger, Tony Nadalin, Axel 2258 Nennker, Emmanuel Raviart, Nat Sakimura, Jim Schaad, Hannes 2259 Tschofenig, and Sean Turner. 2261 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2262 Sean Turner and Stephen Farrell served as Security area directors 2263 during the creation of this specification. 2265 Appendix E. Document History 2267 [[ to be removed by the RFC editor before publication as an RFC ]] 2269 -10 2271 o Changed the JWE processing rules for multiple recipients so that a 2272 single AAD value contains the header parameters and encrypted key 2273 values for all the recipients, enabling AES GCM to be safely used 2274 for multiple recipients. 2276 o Added an appendix suggesting a possible compact serialization for 2277 JWEs with multiple recipients. 2279 -09 2281 o Added JWE JSON Serialization, as specified by 2282 draft-jones-jose-jwe-json-serialization-04. 2284 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2285 parameter value. 2287 o Defined that the default action for header parameters that are not 2288 understood is to ignore them unless specifically designated as 2289 "MUST be understood" or included in the new "crit" (critical) 2290 header parameter list. This addressed issue #6. 2292 o Corrected "x5c" description. This addressed issue #12. 2294 o Changed from using the term "byte" to "octet" when referring to 8 2295 bit values. 2297 o Added Key Management Mode definitions to terminology section and 2298 used the defined terms to provide clearer key management 2299 instructions. This addressed issue #5. 2301 o Added text about preventing the recipient from behaving as an 2302 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2304 o Changed from using the term "Integrity Value" to "Authentication 2305 Tag". 2307 o Changed member name from "integrity_value" to "authentication_tag" 2308 in the JWE JSON Serialization. 2310 o Removed Initialization Vector from the AAD value since it is 2311 already integrity protected by all of the authenticated encryption 2312 algorithms specified in the JWA specification. 2314 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2315 and "A256CBC-HS512". The new algorithms perform the same 2316 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2317 but with the Initialization Vector and Authentication Tag values 2318 remaining separate from the Ciphertext value in the output 2319 representation. Also deleted the header parameters "epu" 2320 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2321 they are no longer used. 2323 -08 2325 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2326 since the term AEAD in the RFC 5116 sense implied the use of a 2327 particular data representation, rather than just referring to the 2328 class of algorithms that perform authenticated encryption with 2329 associated data. 2331 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2332 Tschofenig. Many of these simplified the terminology used. 2334 o Clarified statements of the form "This header parameter is 2335 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2337 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2338 Web Signature and Encryption Header Parameters registry. 2340 o Added seriesInfo information to Internet Draft references. 2342 -07 2343 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2345 o Updated values for example AES CBC calculations. 2347 o Made several local editorial changes to clean up loose ends left 2348 over from to the decision to only support block encryption methods 2349 providing integrity. One of these changes was to explicitly state 2350 that the "enc" (encryption method) algorithm must be an 2351 Authenticated Encryption algorithm with a specified key length. 2353 -06 2355 o Removed the "int" and "kdf" parameters and defined the new 2356 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2357 "A256CBC+HS512" to replace the former uses of AES CBC, which 2358 required the use of separate integrity and key derivation 2359 functions. 2361 o Included additional values in the Concat KDF calculation -- the 2362 desired output size and the algorithm value, and optionally 2363 PartyUInfo and PartyVInfo values. Added the optional header 2364 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2365 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2366 PartyVInfo). Updated the KDF examples accordingly. 2368 o Promoted Initialization Vector from being a header parameter to 2369 being a top-level JWE element. This saves approximately 16 bytes 2370 in the compact serialization, which is a significant savings for 2371 some use cases. Promoting the Initialization Vector out of the 2372 header also avoids repeating this shared value in the JSON 2373 serialization. 2375 o Changed "x5c" (X.509 Certificate Chain) representation from being 2376 a single string to being an array of strings, each containing a 2377 single base64 encoded DER certificate value, representing elements 2378 of the certificate chain. 2380 o Added an AES Key Wrap example. 2382 o Reordered the encryption steps so CMK creation is first, when 2383 required. 2385 o Correct statements in examples about which algorithms produce 2386 reproducible results. 2388 -05 2389 o Support both direct encryption using a shared or agreed upon 2390 symmetric key, and the use of a shared or agreed upon symmetric 2391 key to key wrap the CMK. 2393 o Added statement that "StringOrURI values are compared as case- 2394 sensitive strings with no transformations or canonicalizations 2395 applied". 2397 o Updated open issues. 2399 o Indented artwork elements to better distinguish them from the body 2400 text. 2402 -04 2404 o Refer to the registries as the primary sources of defined values 2405 and then secondarily reference the sections defining the initial 2406 contents of the registries. 2408 o Normatively reference XML Encryption 1.1 2409 [W3C.CR-xmlenc-core1-20120313] for its security considerations. 2411 o Reference draft-jones-jose-jwe-json-serialization instead of 2412 draft-jones-json-web-encryption-json-serialization. 2414 o Described additional open issues. 2416 o Applied editorial suggestions. 2418 -03 2420 o Added the "kdf" (key derivation function) header parameter to 2421 provide crypto agility for key derivation. The default KDF 2422 remains the Concat KDF with the SHA-256 digest function. 2424 o Reordered encryption steps so that the Encoded JWE Header is 2425 always created before it is needed as an input to the 2426 Authenticated Encryption "additional authenticated data" 2427 parameter. 2429 o Added the "cty" (content type) header parameter for declaring type 2430 information about the secured content, as opposed to the "typ" 2431 (type) header parameter, which declares type information about 2432 this object. 2434 o Moved description of how to determine whether a header is for a 2435 JWS or a JWE from the JWT spec to the JWE spec. 2437 o Added complete encryption examples for both Authenticated 2438 Encryption and non-Authenticated Encryption algorithms. 2440 o Added complete key derivation examples. 2442 o Added "Collision Resistant Namespace" to the terminology section. 2444 o Reference ITU.X690.1994 for DER encoding. 2446 o Added Registry Contents sections to populate registry values. 2448 o Numerous editorial improvements. 2450 -02 2452 o When using Authenticated Encryption algorithms (such as AES GCM), 2453 use the "additional authenticated data" parameter to provide 2454 integrity for the header, encrypted key, and ciphertext and use 2455 the resulting "authentication tag" value as the JWE Authentication 2456 Tag. 2458 o Defined KDF output key sizes. 2460 o Generalized text to allow key agreement to be employed as an 2461 alternative to key wrapping or key encryption. 2463 o Changed compression algorithm from gzip to DEFLATE. 2465 o Clarified that it is an error when a "kid" value is included and 2466 no matching key is found. 2468 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2469 rejected. 2471 o Clarified the relationship between "typ" header parameter values 2472 and MIME types. 2474 o Registered application/jwe MIME type and "JWE" typ header 2475 parameter value. 2477 o Simplified JWK terminology to get replace the "JWK Key Object" and 2478 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2479 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2480 between single keys and sets of keys. As part of this change, the 2481 Header Parameter Name for a public key value was changed from 2482 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2484 o Added suggestion on defining additional header parameters such as 2485 "x5t#S256" in the future for certificate thumbprints using hash 2486 algorithms other than SHA-1. 2488 o Specify RFC 2818 server identity validation, rather than RFC 6125 2489 (paralleling the same decision in the OAuth specs). 2491 o Generalized language to refer to Message Authentication Codes 2492 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2493 unless in a context specific to HMAC algorithms. 2495 o Reformatted to give each header parameter its own section heading. 2497 -01 2499 o Added an integrity check for non-Authenticated Encryption 2500 algorithms. 2502 o Added "jpk" and "x5c" header parameters for including JWK public 2503 keys and X.509 certificate chains directly in the header. 2505 o Clarified that this specification is defining the JWE Compact 2506 Serialization. Referenced the new JWE-JS spec, which defines the 2507 JWE JSON Serialization. 2509 o Added text "New header parameters should be introduced sparingly 2510 since an implementation that does not understand a parameter MUST 2511 reject the JWE". 2513 o Clarified that the order of the encryption and decryption steps is 2514 not significant in cases where there are no dependencies between 2515 the inputs and outputs of the steps. 2517 o Made other editorial improvements suggested by JOSE working group 2518 participants. 2520 -00 2522 o Created the initial IETF draft based upon 2523 draft-jones-json-web-encryption-02 with no normative changes. 2525 o Changed terminology to no longer call both digital signatures and 2526 HMACs "signatures". 2528 Authors' Addresses 2530 Michael B. Jones 2531 Microsoft 2533 Email: mbj@microsoft.com 2534 URI: http://self-issued.info/ 2536 Eric Rescorla 2537 RTFM, Inc. 2539 Email: ekr@rtfm.com 2541 Joe Hildebrand 2542 Cisco Systems, Inc. 2544 Email: jhildebr@cisco.com