idnits 2.17.1 draft-ietf-jose-json-web-encryption-27.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 (June 10, 2014) is 3608 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '227' on line 1417 -- Looks like a reference, but probably isn't: '197' on line 1417 -- Looks like a reference, but probably isn't: '117' on line 1417 -- Looks like a reference, but probably isn't: '252' on line 1417 -- Looks like a reference, but probably isn't: '2' on line 1417 -- Looks like a reference, but probably isn't: '219' on line 1417 -- Looks like a reference, but probably isn't: '233' on line 1417 -- Looks like a reference, but probably isn't: '68' on line 1417 -- Looks like a reference, but probably isn't: '180' on line 1417 -- Looks like a reference, but probably isn't: '225' on line 1417 -- Looks like a reference, but probably isn't: '77' on line 1417 -- Looks like a reference, but probably isn't: '0' on line 2006 -- Looks like a reference, but probably isn't: '1' on line 2006 -- Looks like a reference, but probably isn't: '152' on line 2006 -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMAScript' ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' == Outdated reference: A later version (-05) exists of draft-mcgrew-aead-aes-cbc-hmac-sha2-04 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 18 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 J. Hildebrand 5 Expires: December 12, 2014 Cisco 6 June 10, 2014 8 JSON Web Encryption (JWE) 9 draft-ietf-jose-json-web-encryption-27 11 Abstract 13 JSON Web Encryption (JWE) represents encrypted content using 14 JavaScript Object Notation (JSON) based data structures. 15 Cryptographic algorithms and identifiers for use with this 16 specification are described in the separate JSON Web Algorithms (JWA) 17 specification and IANA registries defined by that specification. 18 Related digital signature and MAC capabilities are described in the 19 separate JSON Web Signature (JWS) specification. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on December 12, 2014. 38 Copyright Notice 40 Copyright (c) 2014 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 58 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 9 59 3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 11 60 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 12 61 4.1. Registered Header Parameter Names . . . . . . . . . . . . 13 62 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 13 63 4.1.2. "enc" (Encryption Algorithm) Header Parameter . . . . 13 64 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 13 65 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 14 66 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 14 67 4.1.6. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14 68 4.1.7. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 14 69 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 15 70 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 71 Parameter . . . . . . . . . . . . . . . . . . . . . . 15 72 4.1.10. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) 73 Header Parameter . . . . . . . . . . . . . . . . . . . 15 74 4.1.11. "typ" (Type) Header Parameter . . . . . . . . . . . . 15 75 4.1.12. "cty" (Content Type) Header Parameter . . . . . . . . 15 76 4.1.13. "crit" (Critical) Header Parameter . . . . . . . . . . 15 77 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 16 78 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 16 79 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 16 80 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 16 81 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 18 82 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 21 83 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 21 84 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 21 85 7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 21 86 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21 87 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 24 88 9. Distinguishing between JWS and JWE Objects . . . . . . . . . . 24 89 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 90 10.1. JSON Web Signature and Encryption Header Parameters 91 Registration . . . . . . . . . . . . . . . . . . . . . . . 25 92 10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25 93 11. Security Considerations . . . . . . . . . . . . . . . . . . . 27 94 11.1. Adaptive Chosen-Ciphertext Attacks . . . . . . . . . . . . 27 95 11.2. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 28 97 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 98 12.1. Normative References . . . . . . . . . . . . . . . . . . . 28 99 12.2. Informative References . . . . . . . . . . . . . . . . . . 29 100 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 29 101 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 29 102 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 30 103 A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 30 104 A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 30 105 A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 32 106 A.1.5. Additional Authenticated Data . . . . . . . . . . . . 32 107 A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 32 108 A.1.7. Complete Representation . . . . . . . . . . . . . . . 33 109 A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 33 110 A.2. Example JWE using RSAES-PKCS1-V1_5 and 111 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 33 112 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 34 113 A.2.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 34 114 A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 34 115 A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 35 116 A.2.5. Additional Authenticated Data . . . . . . . . . . . . 36 117 A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 36 118 A.2.7. Complete Representation . . . . . . . . . . . . . . . 36 119 A.2.8. Validation . . . . . . . . . . . . . . . . . . . . . . 37 120 A.3. Example JWE using AES Key Wrap and 121 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 37 122 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 37 123 A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 38 124 A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 38 125 A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 38 126 A.3.5. Additional Authenticated Data . . . . . . . . . . . . 39 127 A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 39 128 A.3.7. Complete Representation . . . . . . . . . . . . . . . 39 129 A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 40 130 A.4. Example JWE using JWE JSON Serialization . . . . . . . . . 40 131 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 40 132 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 41 133 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 41 134 A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 41 135 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 41 136 A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 42 137 A.4.7. Complete JWE JSON Serialization Representation . . . . 42 138 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 43 139 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 43 140 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 44 141 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 44 142 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 45 143 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 45 144 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 45 145 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 45 146 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 45 147 Appendix D. Document History . . . . . . . . . . . . . . . . . . 46 148 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 56 150 1. Introduction 152 JSON Web Encryption (JWE) represents encrypted content using 153 JavaScript Object Notation (JSON) [RFC7159] based data structures. 154 The JWE cryptographic mechanisms encrypt and provide integrity 155 protection for an arbitrary sequence of octets. 157 Two closely related serializations for JWE objects are defined. The 158 JWE Compact Serialization is a compact, URL-safe representation 159 intended for space constrained environments such as HTTP 160 Authorization headers and URI query parameters. The JWE JSON 161 Serialization represents JWE objects as JSON objects and enables the 162 same content to be encrypted to multiple parties. Both share the 163 same cryptographic underpinnings. 165 Cryptographic algorithms and identifiers for use with this 166 specification are described in the separate JSON Web Algorithms (JWA) 167 [JWA] specification and IANA registries defined by that 168 specification. Related digital signature and MAC capabilities are 169 described in the separate JSON Web Signature (JWS) [JWS] 170 specification. 172 Names defined by this specification are short because a core goal is 173 for the resulting representations to be compact. 175 1.1. Notational Conventions 177 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 178 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 179 "OPTIONAL" in this document are to be interpreted as described in Key 180 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 181 these words are used without being spelled in uppercase then they are 182 to be interpreted with their normal natural language meanings. 184 BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per 185 Section 2. 187 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 188 of STRING. 190 ASCII(STRING) denotes the octets of the ASCII [USASCII] 191 representation of STRING. 193 The concatenation of two values A and B is denoted as A || B. 195 2. Terminology 197 These terms defined by the JSON Web Signature (JWS) [JWS] 198 specification are incorporated into this specification: "JSON Web 199 Signature (JWS)", "Base64url Encoding", "Collision-Resistant Name", 200 and "StringOrURI". 202 These terms are defined for use by this specification: 204 JSON Web Encryption (JWE) 205 A data structure representing an encrypted and integrity protected 206 message. 208 Authenticated Encryption with Associated Data (AEAD) 209 An AEAD algorithm is one that encrypts the Plaintext, allows 210 Additional Authenticated Data to be specified, and provides an 211 integrated content integrity check over the Ciphertext and 212 Additional Authenticated Data. AEAD algorithms accept two inputs, 213 the Plaintext and the Additional Authenticated Data value, and 214 produce two outputs, the Ciphertext and the Authentication Tag 215 value. AES Galois/Counter Mode (GCM) is one such algorithm. 217 Plaintext 218 The sequence of octets to be encrypted -- a.k.a., the message. 219 The plaintext can contain an arbitrary sequence of octets. 221 Ciphertext 222 An encrypted representation of the Plaintext. 224 Additional Authenticated Data (AAD) 225 An input to an AEAD operation that is integrity protected but not 226 encrypted. 228 Authentication Tag 229 An output of an AEAD operation that ensures the integrity of the 230 Ciphertext and the Additional Authenticated Data. Note that some 231 algorithms may not use an Authentication Tag, in which case this 232 value is the empty octet sequence. 234 Content Encryption Key (CEK) 235 A symmetric key for the AEAD algorithm used to encrypt the 236 Plaintext for the recipient to produce the Ciphertext and the 237 Authentication Tag. 239 JWE Header 240 JSON object containing the parameters describing the cryptographic 241 operations and parameters employed. The JWE Header members are 242 the union of the members of the JWE Protected Header, the JWE 243 Shared Unprotected Header, and the JWE Per-Recipient Unprotected 244 Header. The members of the JWE Header are Header Parameters. 246 JWE Encrypted Key 247 Encrypted Content Encryption Key (CEK) value. Note that for some 248 algorithms, the JWE Encrypted Key value is specified as being the 249 empty octet sequence. 251 JWE Initialization Vector 252 Initialization Vector value used when encrypting the plaintext. 253 Note that some algorithms may not use an Initialization Vector, in 254 which case this value is the empty octet sequence. 256 JWE AAD 257 Additional value to be integrity protected by the authenticated 258 encryption operation. This can only be present when using the JWE 259 JSON Serialization. (Note that this can also be achieved when 260 using either serialization by including the AAD value as an 261 integrity protected Header Parameter value, but at the cost of the 262 value being double base64url encoded.) 264 JWE Ciphertext 265 Ciphertext value resulting from authenticated encryption of the 266 plaintext with additional authenticated data. 268 JWE Authentication Tag 269 Authentication Tag value resulting from authenticated encryption 270 of the plaintext with additional authenticated data. 272 Header Parameter 273 A name/value pair that is member of the JWE Header. 275 JWE Protected Header 276 JSON object that contains the JWE Header Parameters that are 277 integrity protected by the authenticated encryption operation. 278 These parameters apply to all recipients of the JWE. For the JWE 279 Compact Serialization, this comprises the entire JWE Header. For 280 the JWE JSON Serialization, this is one component of the JWE 281 Header. 283 JWE Shared Unprotected Header 284 JSON object that contains the JWE Header Parameters that apply to 285 all recipients of the JWE that are not integrity protected. This 286 can only be present when using the JWE JSON Serialization. 288 JWE Per-Recipient Unprotected Header 289 JSON object that contains JWE Header Parameters that apply to a 290 single recipient of the JWE. These Header Parameter values are 291 not integrity protected. This can only be present when using the 292 JWE JSON Serialization. 294 JWE Compact Serialization 295 A representation of the JWE as a compact, URL-safe string. 297 JWE JSON Serialization 298 A representation of the JWE as a JSON object. The JWE JSON 299 Serialization enables the same content to be encrypted to multiple 300 parties. This representation is neither optimized for compactness 301 nor URL-safe. 303 Key Management Mode 304 A method of determining the Content Encryption Key (CEK) value to 305 use. Each algorithm used for determining the CEK value uses a 306 specific Key Management Mode. Key Management Modes employed by 307 this specification are Key Encryption, Key Wrapping, Direct Key 308 Agreement, Key Agreement with Key Wrapping, and Direct Encryption. 310 Key Encryption 311 A Key Management Mode in which the Content Encryption Key (CEK) 312 value is encrypted to the intended recipient using an asymmetric 313 encryption algorithm. 315 Key Wrapping 316 A Key Management Mode in which the Content Encryption Key (CEK) 317 value is encrypted to the intended recipient using a symmetric key 318 wrapping algorithm. 320 Direct Key Agreement 321 A Key Management Mode in which a key agreement algorithm is used 322 to agree upon the Content Encryption Key (CEK) value. 324 Key Agreement with Key Wrapping 325 A Key Management Mode in which a key agreement algorithm is used 326 to agree upon a symmetric key used to encrypt the Content 327 Encryption Key (CEK) value to the intended recipient using a 328 symmetric key wrapping algorithm. 330 Direct Encryption 331 A Key Management Mode in which the Content Encryption Key (CEK) 332 value used is the secret symmetric key value shared between the 333 parties. 335 3. JSON Web Encryption (JWE) Overview 337 JWE represents encrypted content using JSON data structures and 338 base64url encoding. A JWE represents these logical values: 340 JWE Header 341 JSON object containing the parameters describing the cryptographic 342 operations and parameters employed. The JWE Header members are 343 the union of the members of the JWE Protected Header, the JWE 344 Shared Unprotected Header, and the JWE Per-Recipient Unprotected 345 Header, as described below. 347 JWE Encrypted Key 348 Encrypted Content Encryption Key (CEK) value. 350 JWE Initialization Vector 351 Initialization Vector value used when encrypting the plaintext. 353 JWE AAD 354 Additional value to be integrity protected by the authenticated 355 encryption operation. 357 JWE Ciphertext 358 Ciphertext value resulting from authenticated encryption of the 359 plaintext with additional authenticated data. 361 JWE Authentication Tag 362 Authentication Tag value resulting from authenticated encryption 363 of the plaintext with additional authenticated data. 365 The JWE Header represents the combination of these logical values: 367 JWE Protected Header 368 JSON object that contains the JWE Header Parameters that are 369 integrity protected by the authenticated encryption operation. 370 These parameters apply to all recipients of the JWE. 372 JWE Shared Unprotected Header 373 JSON object that contains the JWE Header Parameters that apply to 374 all recipients of the JWE that are not integrity protected. 376 JWE Per-Recipient Unprotected Header 377 JSON object that contains JWE Header Parameters that apply to a 378 single recipient of the JWE. These Header Parameter values are 379 not integrity protected. 381 This document defines two serializations for JWE objects: a compact, 382 URL-safe serialization called the JWE Compact Serialization and a 383 JSON serialization called the JWE JSON Serialization. In both 384 serializations, the JWE Protected Header, JWE Encrypted Key, JWE 385 Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are 386 base64url encoded for transmission, since JSON lacks a way to 387 directly represent octet sequences. When present, the JWE AAD is 388 also base64url encoded for transmission. 390 In the JWE Compact Serialization, no JWE Shared Unprotected Header or 391 JWE Per-Recipient Unprotected Header are used. In this case, the JWE 392 Header and the JWE Protected Header are the same. 394 In the JWE Compact Serialization, a JWE object is represented as the 395 combination of these five string values, 396 BASE64URL(UTF8(JWE Protected Header)), 397 BASE64URL(JWE Encrypted Key), 398 BASE64URL(JWE Initialization Vector), 399 BASE64URL(JWE Ciphertext), and 400 BASE64URL(JWE Authentication Tag), 401 concatenated in that order, with the five strings being separated by 402 four period ('.') characters. 404 In the JWE JSON Serialization, one or more of the JWE Protected 405 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 406 Unprotected Header MUST be present. In this case, the members of the 407 JWE Header are the combination of the members of the JWE Protected 408 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 409 Unprotected Header values that are present. 411 In the JWE JSON Serialization, a JWE object is represented as the 412 combination of these eight values, 413 BASE64URL(UTF8(JWE Protected Header)), 414 JWE Shared Unprotected Header, 415 JWE Per-Recipient Unprotected Header, 416 BASE64URL(JWE Encrypted Key), 417 BASE64URL(JWE Initialization Vector), 418 BASE64URL(JWE Ciphertext), 419 BASE64URL(JWE Authentication Tag), and 420 BASE64URL(JWE AAD), 421 with the six base64url encoding result strings and the two 422 unprotected JSON object values being represented as members within a 423 JSON object. The inclusion of some of these values is OPTIONAL. The 424 JWE JSON Serialization can also encrypt the plaintext to multiple 425 recipients. See Section 7.2 for more information about the JWE JSON 426 Serialization. 428 JWE utilizes authenticated encryption to ensure the confidentiality 429 and integrity of the Plaintext and the integrity of the JWE Protected 430 Header and the JWE AAD. 432 3.1. Example JWE 434 This example encrypts the plaintext "The true sign of intelligence is 435 not knowledge but imagination." to the recipient using RSAES OAEP for 436 key encryption and AES GCM for content encryption. 438 The following example JWE Protected Header declares that: 440 o the Content Encryption Key is encrypted to the recipient using the 441 RSAES OAEP algorithm to produce the JWE Encrypted Key and 443 o the Plaintext is encrypted using the AES GCM algorithm with a 256 444 bit key to produce the Ciphertext. 446 {"alg":"RSA-OAEP","enc":"A256GCM"} 448 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 449 Header)) gives this value: 451 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 453 The remaining steps to finish creating this JWE are: 455 o Generate a random Content Encryption Key (CEK). 457 o Encrypt the CEK with the recipient's public key using the RSAES 458 OAEP algorithm to produce the JWE Encrypted Key. 460 o Base64url encode the JWE Encrypted Key. 462 o Generate a random JWE Initialization Vector. 464 o Base64url encode the JWE Initialization Vector. 466 o Let the Additional Authenticated Data encryption parameter be 467 ASCII(BASE64URL(UTF8(JWE Protected Header))). 469 o Encrypt the Plaintext with AES GCM using the CEK as the encryption 470 key, the JWE Initialization Vector, and the Additional 471 Authenticated Data value, requesting a 128 bit Authentication Tag 472 output. 474 o Base64url encode the Ciphertext. 476 o Base64url encode the Authentication Tag. 478 o Assemble the final representation: The Compact Serialization of 479 this result is the string BASE64URL(UTF8(JWE Protected Header)) || 480 '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE 481 Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' 482 || BASE64URL(JWE Authentication Tag). 484 The final result in this example (with line breaks for display 485 purposes only) is: 487 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 488 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 489 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 490 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 491 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 492 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 493 6UklfCpIMfIjf7iGdXKHzg. 494 48V1_ALb6US04U3b. 495 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 496 SdiwkIr3ajwQzaBtQD_A. 497 XFBoMYUZodetZdvTiFvSkQ 499 See Appendix A.1 for the complete details of computing this JWE. See 500 other parts of Appendix A for additional examples. 502 4. JWE Header 504 The members of the JSON object(s) representing the JWE Header 505 describe the encryption applied to the Plaintext and optionally 506 additional properties of the JWE. The Header Parameter names within 507 the JWE Header MUST be unique; recipients MUST either reject JWEs 508 with duplicate Header Parameter names or use a JSON parser that 509 returns only the lexically last duplicate member name, as specified 510 in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. 512 Implementations are required to understand the specific Header 513 Parameters defined by this specification that are designated as "MUST 514 be understood" and process them in the manner defined in this 515 specification. All other Header Parameters defined by this 516 specification that are not so designated MUST be ignored when not 517 understood. Unless listed as a critical Header Parameter, per 518 Section 4.1.13, all Header Parameters not defined by this 519 specification MUST be ignored when not understood. 521 There are three classes of Header Parameter names: Registered Header 522 Parameter names, Public Header Parameter names, and Private Header 523 Parameter names. 525 4.1. Registered Header Parameter Names 527 The following Header Parameter names are registered in the IANA JSON 528 Web Signature and Encryption Header Parameters registry defined in 529 [JWS], with meanings as defined below. 531 As indicated by the common registry, JWSs and JWEs share a common 532 Header Parameter space; when a parameter is used by both 533 specifications, its usage must be compatible between the 534 specifications. 536 4.1.1. "alg" (Algorithm) Header Parameter 538 This parameter has the same meaning, syntax, and processing rules as 539 the "alg" Header Parameter defined in Section 4.1.1 of [JWS], except 540 that the Header Parameter identifies the cryptographic algorithm used 541 to encrypt or determine the value of the Content Encryption Key 542 (CEK). The encrypted content is not usable if the "alg" value does 543 not represent a supported algorithm, or if the recipient does not 544 have a key that can be used with that algorithm. 546 A list of defined "alg" values for this use can be found in the IANA 547 JSON Web Signature and Encryption Algorithms registry defined in 548 [JWA]; the initial contents of this registry are the values defined 549 in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. 551 4.1.2. "enc" (Encryption Algorithm) Header Parameter 553 The "enc" (encryption algorithm) Header Parameter identifies the 554 content encryption algorithm used to encrypt the Plaintext to produce 555 the Ciphertext. This algorithm MUST be an AEAD algorithm with a 556 specified key length. The recipient MUST reject the JWE if the "enc" 557 value does not represent a supported algorithm. "enc" values should 558 either be registered in the IANA JSON Web Signature and Encryption 559 Algorithms registry defined in [JWA] or be a value that contains a 560 Collision-Resistant Name. The "enc" value is a case-sensitive string 561 containing a StringOrURI value. This Header Parameter MUST be 562 present and MUST be understood and processed by implementations. 564 A list of defined "enc" values for this use can be found in the IANA 565 JSON Web Signature and Encryption Algorithms registry defined in 566 [JWA]; the initial contents of this registry are the values defined 567 in Section 5.1 of the JSON Web Algorithms (JWA) [JWA] specification. 569 4.1.3. "zip" (Compression Algorithm) Header Parameter 571 The "zip" (compression algorithm) applied to the Plaintext before 572 encryption, if any. The "zip" value defined by this specification 573 is: 575 o "DEF" - Compression with the DEFLATE [RFC1951] algorithm 577 Other values MAY be used. Compression algorithm values can be 578 registered in the IANA JSON Web Encryption Compression Algorithm 579 registry defined in [JWA]. The "zip" value is a case-sensitive 580 string. If no "zip" parameter is present, no compression is applied 581 to the Plaintext before encryption. This Header Parameter MUST be 582 integrity protected, and therefore MUST occur only within the JWE 583 Protected Header, when used. Use of this Header Parameter is 584 OPTIONAL. This Header Parameter MUST be understood and processed by 585 implementations. 587 4.1.4. "jku" (JWK Set URL) Header Parameter 589 This parameter has the same meaning, syntax, and processing rules as 590 the "jku" Header Parameter defined in Section 4.1.2 of [JWS], except 591 that the JWK Set resource contains the public key to which the JWE 592 was encrypted; this can be used to determine the private key needed 593 to decrypt the JWE. 595 4.1.5. "jwk" (JSON Web Key) Header Parameter 597 This parameter has the same meaning, syntax, and processing rules as 598 the "jwk" Header Parameter defined in Section 4.1.3 of [JWS], except 599 that the key is the public key to which the JWE was encrypted; this 600 can be used to determine the private key needed to decrypt the JWE. 602 4.1.6. "kid" (Key ID) Header Parameter 604 This parameter has the same meaning, syntax, and processing rules as 605 the "kid" Header Parameter defined in Section 4.1.4 of [JWS], except 606 that the key hint references the public key to which the JWE was 607 encrypted; this can be used to determine the private key needed to 608 decrypt the JWE. This parameter allows originators to explicitly 609 signal a change of key to JWE recipients. 611 4.1.7. "x5u" (X.509 URL) Header Parameter 613 This parameter has the same meaning, syntax, and processing rules as 614 the "x5u" Header Parameter defined in Section 4.1.5 of [JWS], except 615 that the X.509 public key certificate or certificate chain [RFC5280] 616 contains the public key to which the JWE was encrypted; this can be 617 used to determine the private key needed to decrypt the JWE. 619 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 621 This parameter has the same meaning, syntax, and processing rules as 622 the "x5c" Header Parameter defined in Section 4.1.6 of [JWS], except 623 that the X.509 public key certificate or certificate chain [RFC5280] 624 contains the public key to which the JWE was encrypted; this can be 625 used to determine the private key needed to decrypt the JWE. 627 See Appendix B of [JWS] for an example "x5c" value. 629 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 631 This parameter has the same meaning, syntax, and processing rules as 632 the "x5t" Header Parameter defined in Section 4.1.7 of [JWS], except 633 that the certificate referenced by the thumbprint contains the public 634 key to which the JWE was encrypted; this can be used to determine the 635 private key needed to decrypt the JWE. 637 4.1.10. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header 638 Parameter 640 This parameter has the same meaning, syntax, and processing rules as 641 the "x5t#S256" Header Parameter defined in Section 4.1.8 of [JWS], 642 except that the certificate referenced by the thumbprint contains the 643 public key to which the JWE was encrypted; this can be used to 644 determine the private key needed to decrypt the JWE. 646 4.1.11. "typ" (Type) Header Parameter 648 This parameter has the same meaning, syntax, and processing rules as 649 the "typ" Header Parameter defined in Section 4.1.9 of [JWS], except 650 that the type is of this complete JWE object. 652 4.1.12. "cty" (Content Type) Header Parameter 654 This parameter has the same meaning, syntax, and processing rules as 655 the "cty" Header Parameter defined in Section 4.1.10 of [JWS], except 656 that the type is of the secured content (the plaintext). 658 4.1.13. "crit" (Critical) Header Parameter 660 This parameter has the same meaning, syntax, and processing rules as 661 the "crit" Header Parameter defined in Section 4.1.11 of [JWS], 662 except that JWE Header Parameters are being referred to, rather than 663 JWS Header Parameters. 665 4.2. Public Header Parameter Names 667 Additional Header Parameter names can be defined by those using JWEs. 668 However, in order to prevent collisions, any new Header Parameter 669 name should either be registered in the IANA JSON Web Signature and 670 Encryption Header Parameters registry defined in [JWS] or be a Public 671 Name: a value that contains a Collision-Resistant Name. In each 672 case, the definer of the name or value needs to take reasonable 673 precautions to make sure they are in control of the part of the 674 namespace they use to define the Header Parameter name. 676 New Header Parameters should be introduced sparingly, as they can 677 result in non-interoperable JWEs. 679 4.3. Private Header Parameter Names 681 A producer and consumer of a JWE may agree to use Header Parameter 682 names that are Private Names: names that are not Registered Header 683 Parameter names Section 4.1 or Public Header Parameter names 684 Section 4.2. Unlike Public Header Parameter names, Private Header 685 Parameter names are subject to collision and should be used with 686 caution. 688 5. Producing and Consuming JWEs 690 5.1. Message Encryption 692 The message encryption process is as follows. The order of the steps 693 is not significant in cases where there are no dependencies between 694 the inputs and outputs of the steps. 696 1. Determine the Key Management Mode employed by the algorithm used 697 to determine the Content Encryption Key (CEK) value. (This is 698 the algorithm recorded in the "alg" (algorithm) Header Parameter 699 of the resulting JWE.) 701 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 702 Wrapping are employed, generate a random Content Encryption Key 703 (CEK) value. See RFC 4086 [RFC4086] for considerations on 704 generating random values. The CEK MUST have a length equal to 705 that required for the content encryption algorithm. 707 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 708 employed, use the key agreement algorithm to compute the value 709 of the agreed upon key. When Direct Key Agreement is employed, 710 let the Content Encryption Key (CEK) be the agreed upon key. 711 When Key Agreement with Key Wrapping is employed, the agreed 712 upon key will be used to wrap the CEK. 714 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 715 Wrapping are employed, encrypt the CEK to the recipient and let 716 the result be the JWE Encrypted Key. 718 5. When Direct Key Agreement or Direct Encryption are employed, let 719 the JWE Encrypted Key be the empty octet sequence. 721 6. When Direct Encryption is employed, let the Content Encryption 722 Key (CEK) be the shared symmetric key. 724 7. Compute the encoded key value BASE64URL(JWE Encrypted Key). 726 8. If the JWE JSON Serialization is being used, repeat this process 727 (steps 1-7) for each recipient. 729 9. Generate a random JWE Initialization Vector of the correct size 730 for the content encryption algorithm (if required for the 731 algorithm); otherwise, let the JWE Initialization Vector be the 732 empty octet sequence. 734 10. Compute the encoded initialization vector value BASE64URL(JWE 735 Initialization Vector). 737 11. If a "zip" parameter was included, compress the Plaintext using 738 the specified compression algorithm. 740 12. Serialize the (compressed) Plaintext into an octet sequence M. 742 13. Create the JSON object(s) containing the desired set of Header 743 Parameters, which together comprise the JWE Header: the JWE 744 Protected Header, and if the JWE JSON Serialization is being 745 used, the JWE Shared Unprotected Header and the JWE Per- 746 Recipient Unprotected Header. 748 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 749 Protected Header)). If the JWE Protected Header is not present 750 (which can only happen when using the JWE JSON Serialization and 751 no "protected" member is present), let this value be the empty 752 string. 754 15. Let the Additional Authenticated Data encryption parameter be 755 ASCII(Encoded Protected Header). However if a JWE AAD value is 756 present (which can only be the case when using the JWE JSON 757 Serialization), instead let the Additional Authenticated Data 758 encryption parameter be ASCII(Encoded Protected Header || '.' || 759 BASE64URL(JWE AAD)). 761 16. Encrypt M using the CEK, the JWE Initialization Vector, and the 762 Additional Authenticated Data value using the specified content 763 encryption algorithm to create the JWE Ciphertext value and the 764 JWE Authentication Tag (which is the Authentication Tag output 765 from the encryption operation). 767 17. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext). 769 18. Compute the encoded authentication tag value BASE64URL(JWE 770 Authentication Tag). 772 19. The five encoded values are used in both the JWE Compact 773 Serialization and the JWE JSON Serialization representations. 775 20. If a JWE AAD value is present, compute the encoded AAD value 776 BASE64URL(JWE AAD). 778 21. Create the desired serialized output. The Compact Serialization 779 of this result is the string BASE64URL(UTF8(JWE Protected 780 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 781 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 782 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). The 783 JWE JSON Serialization is described in Section 7.2. 785 5.2. Message Decryption 787 The message decryption process is the reverse of the encryption 788 process. The order of the steps is not significant in cases where 789 there are no dependencies between the inputs and outputs of the 790 steps. If any of these steps fails, the encrypted content cannot be 791 validated. 793 It is an application decision which recipients' encrypted content 794 must successfully validate for the JWE to be accepted. In some 795 cases, encrypted content for all recipients must successfully 796 validate or the JWE will be rejected. In other cases, only the 797 encrypted content for a single recipient needs to be successfully 798 validated. However, in all cases, the encrypted content for at least 799 one recipient MUST successfully validate or the JWE MUST be rejected. 801 1. Parse the JWE representation to extract the serialized values 802 for the components of the JWE -- when using the JWE Compact 803 Serialization, the base64url encoded representations of the JWE 804 Protected Header, the JWE Encrypted Key, the JWE Initialization 805 Vector, the JWE Ciphertext, and the JWE Authentication Tag, and 806 when using the JWE JSON Serialization, also the base64url 807 encoded representation of the JWE AAD and the unencoded JWE 808 Shared Unprotected Header and JWE Per-Recipient Unprotected 809 Header values. When using the JWE Compact Serialization, the 810 JWE Protected Header, the JWE Encrypted Key, the JWE 811 Initialization Vector, the JWE Ciphertext, and the JWE 812 Authentication Tag are represented as base64url encoded values 813 in that order, separated by four period ('.') characters. The 814 JWE JSON Serialization is described in Section 7.2. 816 2. The encoded representations of the JWE Protected Header, the JWE 817 Encrypted Key, the JWE Initialization Vector, the JWE 818 Ciphertext, the JWE Authentication Tag, and the JWE AAD MUST be 819 successfully base64url decoded following the restriction that no 820 padding characters have been used. 822 3. The octet sequence resulting from decoding the encoded JWE 823 Protected Header MUST be a UTF-8 encoded representation of a 824 completely valid JSON object conforming to [RFC7159], which is 825 the JWE Protected Header. 827 4. If using the JWE Compact Serialization, let the JWE Header be 828 the JWE Protected Header; otherwise, when using the JWE JSON 829 Serialization, let the JWE Header be the union of the members of 830 the JWE Protected Header, the JWE Shared Unprotected Header and 831 the corresponding JWE Per-Recipient Unprotected Header, all of 832 which must be completely valid JSON objects. 834 5. The resulting JWE Header MUST NOT contain duplicate Header 835 Parameter names. When using the JWE JSON Serialization, this 836 restriction includes that the same Header Parameter name also 837 MUST NOT occur in distinct JSON object values that together 838 comprise the JWE Header. 840 6. Verify that the implementation understands and can process all 841 fields that it is required to support, whether required by this 842 specification, by the algorithms being used, or by the "crit" 843 Header Parameter value, and that the values of those parameters 844 are also understood and supported. 846 7. Determine the Key Management Mode employed by the algorithm 847 specified by the "alg" (algorithm) Header Parameter. 849 8. Verify that the JWE uses a key known to the recipient. 851 9. When Direct Key Agreement or Key Agreement with Key Wrapping are 852 employed, use the key agreement algorithm to compute the value 853 of the agreed upon key. When Direct Key Agreement is employed, 854 let the Content Encryption Key (CEK) be the agreed upon key. 855 When Key Agreement with Key Wrapping is employed, the agreed 856 upon key will be used to decrypt the JWE Encrypted Key. 858 10. When Key Wrapping, Key Encryption, or Key Agreement with Key 859 Wrapping are employed, decrypt the JWE Encrypted Key to produce 860 the Content Encryption Key (CEK). The CEK MUST have a length 861 equal to that required for the content encryption algorithm. 862 Note that when there are multiple recipients, each recipient 863 will only be able decrypt any JWE Encrypted Key values that were 864 encrypted to a key in that recipient's possession. It is 865 therefore normal to only be able to decrypt one of the per- 866 recipient JWE Encrypted Key values to obtain the CEK value. 867 Also, see Section 11.2 for security considerations on mitigating 868 timing attacks. 870 11. When Direct Key Agreement or Direct Encryption are employed, 871 verify that the JWE Encrypted Key value is empty octet sequence. 873 12. When Direct Encryption is employed, let the Content Encryption 874 Key (CEK) be the shared symmetric key. 876 13. If the JWE JSON Serialization is being used, repeat this process 877 (steps 4-12) for each recipient contained in the representation 878 until the CEK value has been determined. 880 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 881 Protected Header)). If the JWE Protected Header is not present 882 (which can only happen when using the JWE JSON Serialization and 883 no "protected" member is present), let this value be the empty 884 string. 886 15. Let the Additional Authenticated Data encryption parameter be 887 ASCII(Encoded Protected Header). However if a JWE AAD value is 888 present (which can only be the case when using the JWE JSON 889 Serialization), instead let the Additional Authenticated Data 890 encryption parameter be ASCII(Encoded Protected Header || '.' || 891 BASE64URL(JWE AAD)). 893 16. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 894 Vector, the Additional Authenticated Data value, and the JWE 895 Authentication Tag (which is the Authentication Tag input to the 896 calculation) using the specified content encryption algorithm, 897 returning the decrypted plaintext and validating the JWE 898 Authentication Tag in the manner specified for the algorithm, 899 rejecting the input without emitting any decrypted output if the 900 JWE Authentication Tag is incorrect. 902 17. If a "zip" parameter was included, uncompress the decrypted 903 plaintext using the specified compression algorithm. 905 18. If all the previous steps succeeded, output the resulting 906 Plaintext. 908 5.3. String Comparison Rules 910 The string comparison rules for this specification are the same as 911 those defined in Section 5.3 of [JWS]. 913 6. Key Identification 915 The key identification methods for this specification are the same as 916 those defined in Section 6 of [JWS], except that the key being 917 identified is the public key to which the JWE was encrypted. 919 7. Serializations 921 JWE objects use one of two serializations, the JWE Compact 922 Serialization or the JWE JSON Serialization. Applications using this 923 specification need to specify what serialization and serialization 924 features are used for that application. For instance, applications 925 might specify that only the JWE JSON Serialization is used, that only 926 JWE JSON Serialization support for a single recipient is used, or 927 that support for multiple recipients is used. JWE implementations 928 only need to implement the features needed for the applications they 929 are designed to support. 931 7.1. JWE Compact Serialization 933 The JWE Compact Serialization represents encrypted content as a 934 compact URL-safe string. This string is BASE64URL(UTF8(JWE Protected 935 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 936 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 937 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). Only one 938 recipient is supported by the JWE Compact Serialization and it 939 provides no syntax to represent JWE Shared Unprotected Header, JWE 940 Per-Recipient Unprotected Header, or JWE AAD values. 942 7.2. JWE JSON Serialization 944 The JWE JSON Serialization represents encrypted content as a JSON 945 object. Content using the JWE JSON Serialization can be encrypted to 946 more than one recipient. This representation is neither optimized 947 for compactness nor URL-safe. 949 The following members are defined for use in top-level JSON objects 950 used for the JWE JSON Serialization: 952 protected 953 The "protected" member MUST be present and contain the value 954 BASE64URL(UTF8(JWE Protected Header)) when the JWE Protected 955 Header value is non-empty; otherwise, it MUST be absent. These 956 Header Parameter values are integrity protected. 958 unprotected 959 The "unprotected" member MUST be present and contain the value JWE 960 Shared Unprotected Header when the JWE Shared Unprotected Header 961 value is non-empty; otherwise, it MUST be absent. This value is 962 represented as an unencoded JSON object, rather than as a string. 963 These Header Parameter values are not integrity protected. 965 iv 966 The "iv" member MUST be present and contain the value 967 BASE64URL(JWE Initialization Vector) when the JWE Initialization 968 Vector value is non-empty; otherwise, it MUST be absent. 970 aad 971 The "aad" member MUST be present and contain the value 972 BASE64URL(JWE AAD)) when the JWE AAD value is non-empty; 973 otherwise, it MUST be absent. A JWE AAD value can be included to 974 supply a base64url encoded value to be integrity protected but not 975 encrypted. 977 ciphertext 978 The "ciphertext" member MUST be present and contain the value 979 BASE64URL(JWE Ciphertext). 981 tag 982 The "tag" member MUST be present and contain the value 983 BASE64URL(JWE Authentication Tag) when the JWE Authentication Tag 984 value is non-empty; otherwise, it MUST be absent. 986 recipients 987 The "recipients" member value MUST be an array of JSON objects. 988 Each object contains information specific to a single recipient. 989 This member MUST be present, even if the array elements contain 990 only the empty JSON object "{}" (which can happen when all Header 991 Parameter values are shared between all recipients and when no 992 encrypted key is used, such as when doing Direct Encryption). 994 The following members are defined for use in the JSON objects that 995 are elements of the "recipients" array: 997 header 998 The "header" member MUST be present and contain the value JWE Per- 999 Recipient Unprotected Header when the JWE Per-Recipient 1000 Unprotected Header value is non-empty; otherwise, it MUST be 1001 absent. This value is represented as an unencoded JSON object, 1002 rather than as a string. These Header Parameter values are not 1003 integrity protected. 1005 encrypted_key 1006 The "encrypted_key" member MUST be present and contain the value 1007 BASE64URL(JWE Encrypted Key) when the JWE Encrypted Key value is 1008 non-empty; otherwise, it MUST be absent. 1010 At least one of the "header", "protected", and "unprotected" members 1011 MUST be present so that "alg" and "enc" Header Parameter values are 1012 conveyed for each recipient computation. 1014 Additional members can be present in both the JSON objects defined 1015 above; if not understood by implementations encountering them, they 1016 MUST be ignored. 1018 Some Header Parameters, including the "alg" parameter, can be shared 1019 among all recipient computations. Header Parameters in the JWE 1020 Protected Header and JWE Shared Unprotected Header values are shared 1021 among all recipients. 1023 The Header Parameter values used when creating or validating per- 1024 recipient Ciphertext and Authentication Tag values are the union of 1025 the three sets of Header Parameter values that may be present: (1) 1026 the JWE Protected Header represented in the "protected" member, (2) 1027 the JWE Shared Unprotected Header represented in the "unprotected" 1028 member, and (3) the JWE Per-Recipient Unprotected Header represented 1029 in the "header" member of the recipient's array element. The union 1030 of these sets of Header Parameters comprises the JWE Header. The 1031 Header Parameter names in the three locations MUST be disjoint. 1033 Each JWE Encrypted Key value is computed using the parameters of the 1034 corresponding JWE Header value in the same manner as for the JWE 1035 Compact Serialization. This has the desirable property that each JWE 1036 Encrypted Key value in the "recipients" array is identical to the 1037 value that would have been computed for the same parameter in the JWE 1038 Compact Serialization. Likewise, the JWE Ciphertext and JWE 1039 Authentication Tag values match those produced for the JWE Compact 1040 Serialization, provided that the JWE Protected Header value (which 1041 represents the integrity-protected Header Parameter values) matches 1042 that used in the JWE Compact Serialization. 1044 All recipients use the same JWE Protected Header, JWE Initialization 1045 Vector, JWE Ciphertext, and JWE Authentication Tag values, when 1046 present, resulting in potentially significant space savings if the 1047 message is large. Therefore, all Header Parameters that specify the 1048 treatment of the Plaintext value MUST be the same for all recipients. 1049 This primarily means that the "enc" (encryption algorithm) Header 1050 Parameter value in the JWE Header for each recipient and any 1051 parameters of that algorithm MUST be the same. 1053 In summary, the syntax of a JWE using the JWE JSON Serialization is 1054 as follows: 1056 {"protected":"", 1057 "unprotected":, 1058 "recipients":[ 1059 {"header":, 1060 "encrypted_key":""}, 1061 ... 1062 {"header":, 1063 "encrypted_key":""}], 1064 "aad":"", 1065 "iv":"", 1066 "ciphertext":"", 1067 "tag":"" 1068 } 1070 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1071 Serialization. 1073 8. TLS Requirements 1075 The TLS requirements for this specification are the same as those 1076 defined in Section 8 of [JWS]. 1078 9. Distinguishing between JWS and JWE Objects 1080 There are several ways of distinguishing whether an object is a JWS 1081 or JWE object. All these methods will yield the same result for all 1082 legal input values; they may yield different results for malformed 1083 inputs. 1085 o If the object is using the JWS Compact Serialization or the JWE 1086 Compact Serialization, the number of base64url encoded segments 1087 separated by period ('.') characters differs for JWSs and JWEs. 1088 JWSs have three segments separated by two period ('.') characters. 1089 JWEs have five segments separated by four period ('.') characters. 1091 o If the object is using the JWS JSON Serialization or the JWE JSON 1092 Serialization, the members used will be different. JWSs have a 1093 "signatures" member and JWEs do not. JWEs have a "recipients" 1094 member and JWSs do not. 1096 o A JWS Header can be distinguished from a JWE header by examining 1097 the "alg" (algorithm) Header Parameter value. If the value 1098 represents a digital signature or MAC algorithm, or is the value 1099 "none", it is for a JWS; if it represents a Key Encryption, Key 1100 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 1101 or Direct Encryption algorithm, it is for a JWE. (Extracting the 1102 "alg" value to examine is straightforward when using the JWS 1103 Compact Serialization or the JWE Compact Serialization and may be 1104 more difficult when using the JWS JSON Serialization or the JWE 1105 JSON Serialization.) 1107 o A JWS Header can also be distinguished from a JWE header by 1108 determining whether an "enc" (encryption algorithm) member exists. 1109 If the "enc" member exists, it is a JWE; otherwise, it is a JWS. 1111 10. IANA Considerations 1113 10.1. JSON Web Signature and Encryption Header Parameters Registration 1115 This specification registers the Header Parameter names defined in 1116 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1117 Parameters registry defined in [JWS]. 1119 10.1.1. Registry Contents 1121 o Header Parameter Name: "alg" 1122 o Header Parameter Description: Algorithm 1123 o Header Parameter Usage Location(s): JWE 1124 o Change Controller: IESG 1125 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1127 o Header Parameter Name: "enc" 1128 o Header Parameter Description: Encryption Algorithm 1129 o Header Parameter Usage Location(s): JWE 1130 o Change Controller: IESG 1131 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1133 o Header Parameter Name: "zip" 1134 o Header Parameter Description: Compression Algorithm 1135 o Header Parameter Usage Location(s): JWE 1136 o Change Controller: IESG 1137 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1139 o Header Parameter Name: "jku" 1140 o Header Parameter Description: JWK Set URL 1141 o Header Parameter Usage Location(s): JWE 1142 o Change Controller: IESG 1143 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1145 o Header Parameter Name: "jwk" 1146 o Header Parameter Description: JSON Web Key 1147 o Header Parameter Usage Location(s): JWE 1148 o Change Controller: IESG 1149 o Specification document(s): Section 4.1.5 of [[ this document ]] 1151 o Header Parameter Name: "kid" 1152 o Header Parameter Description: Key ID 1153 o Header Parameter Usage Location(s): JWE 1154 o Change Controller: IESG 1155 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1157 o Header Parameter Name: "x5u" 1158 o Header Parameter Description: X.509 URL 1159 o Header Parameter Usage Location(s): JWE 1160 o Change Controller: IESG 1161 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1163 o Header Parameter Name: "x5c" 1164 o Header Parameter Description: X.509 Certificate Chain 1165 o Header Parameter Usage Location(s): JWE 1166 o Change Controller: IESG 1167 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1169 o Header Parameter Name: "x5t" 1170 o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint 1171 o Header Parameter Usage Location(s): JWE 1172 o Change Controller: IESG 1173 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1175 o Header Parameter Name: "x5t#S256" 1176 o Header Parameter Description: X.509 Certificate SHA-256 Thumbprint 1177 o Header Parameter Usage Location(s): JWE 1178 o Change Controller: IESG 1179 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1181 o Header Parameter Name: "typ" 1182 o Header Parameter Description: Type 1183 o Header Parameter Usage Location(s): JWE 1184 o Change Controller: IESG 1185 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1187 o Header Parameter Name: "cty" 1188 o Header Parameter Description: Content Type 1189 o Header Parameter Usage Location(s): JWE 1190 o Change Controller: IESG 1191 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1193 o Header Parameter Name: "crit" 1194 o Header Parameter Description: Critical 1195 o Header Parameter Usage Location(s): JWE 1196 o Change Controller: IESG 1197 o Specification Document(s): Section 4.1.13 of [[ this document ]] 1199 11. Security Considerations 1201 All of the security issues faced by any cryptographic application 1202 must be faced by a JWS/JWE/JWK agent. Among these issues are 1203 protecting the user's private and symmetric keys, preventing various 1204 attacks, and helping the user avoid mistakes such as inadvertently 1205 encrypting a message for the wrong recipient. The entire list of 1206 security considerations is beyond the scope of this document. 1208 All the security considerations in the JWS specification also apply 1209 to this specification. Likewise, all the security considerations in 1210 XML Encryption 1.1 [W3C.REC-xmlenc-core1-20130411] also apply, other 1211 than those that are XML specific. 1213 11.1. Adaptive Chosen-Ciphertext Attacks 1215 When decrypting, particular care must be taken not to allow the JWE 1216 recipient to be used as an oracle for decrypting messages. RFC 3218 1217 [RFC3218] should be consulted for specific countermeasures to attacks 1218 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1219 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1220 formatting error that can be detected and used to recover the CEK 1221 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1222 particularly important to report all formatting errors to the CEK, 1223 Additional Authenticated Data, or ciphertext as a single error when 1224 the encrypted content is rejected. 1226 Additionally, this type of attack can be prevented by the use of "key 1227 tainting". This method restricts the use of a key to a limited set 1228 of algorithms -- usually one. This means, for instance, that if the 1229 key is marked as being for "RSA-OAEP" only, any attempt to decrypt a 1230 message using the "RSA1_5" algorithm with that key would fail 1231 immediately due to invalid use of the key. 1233 11.2. Timing Attacks 1235 To mitigate the attacks described in RFC 3218 [RFC3218], the 1236 recipient MUST NOT distinguish between format, padding, and length 1237 errors of encrypted keys. It is strongly recommended, in the event 1238 of receiving an improperly formatted key, that the receiver 1239 substitute a randomly generated CEK and proceed to the next step, to 1240 mitigate timing attacks. 1242 12. References 1244 12.1. Normative References 1246 [ECMAScript] 1247 Ecma International, "ECMAScript Language Specification, 1248 5.1 Edition", ECMA 262, June 2011. 1250 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1251 draft-ietf-jose-json-web-algorithms (work in progress), 1252 June 2014. 1254 [JWK] Jones, M., "JSON Web Key (JWK)", 1255 draft-ietf-jose-json-web-key (work in progress), 1256 June 2014. 1258 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1259 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1260 in progress), June 2014. 1262 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1263 version 1.3", RFC 1951, May 1996. 1265 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1266 Requirement Levels", BCP 14, RFC 2119, March 1997. 1268 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1269 10646", STD 63, RFC 3629, November 2003. 1271 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1272 Housley, R., and W. Polk, "Internet X.509 Public Key 1273 Infrastructure Certificate and Certificate Revocation List 1274 (CRL) Profile", RFC 5280, May 2008. 1276 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1277 Interchange Format", RFC 7159, March 2014. 1279 [USASCII] American National Standards Institute, "Coded Character 1280 Set -- 7-bit American Standard Code for Information 1281 Interchange", ANSI X3.4, 1986. 1283 12.2. Informative References 1285 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1286 McGrew, D., Foley, J., and K. Paterson, "Authenticated 1287 Encryption with AES-CBC and HMAC-SHA", 1288 draft-mcgrew-aead-aes-cbc-hmac-sha2-04 (work in progress), 1289 February 2014. 1291 [I-D.rescorla-jsms] 1292 Rescorla, E. and J. Hildebrand, "JavaScript Message 1293 Security Format", draft-rescorla-jsms-00 (work in 1294 progress), March 2011. 1296 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1297 Encryption", September 2010. 1299 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1300 Cryptographic Message Syntax", RFC 3218, January 2002. 1302 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1303 Requirements for Security", BCP 106, RFC 4086, June 2005. 1305 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1306 RFC 5652, September 2009. 1308 [W3C.REC-xmlenc-core1-20130411] 1309 Eastlake, D., Reagle, J., Hirsch, F., and T. Roessler, 1310 "XML Encryption Syntax and Processing Version 1.1", World 1311 Wide Web Consortium Recommendation REC-xmlenc-core1- 1312 20130411, April 2013, 1313 . 1315 Appendix A. JWE Examples 1317 This section provides examples of JWE computations. 1319 A.1. Example JWE using RSAES OAEP and AES GCM 1321 This example encrypts the plaintext "The true sign of intelligence is 1322 not knowledge but imagination." to the recipient using RSAES OAEP for 1323 key encryption and AES GCM for content encryption. The 1324 representation of this plaintext (using JSON array notation) is: 1326 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1327 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1328 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1329 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1330 110, 97, 116, 105, 111, 110, 46] 1332 A.1.1. JWE Header 1334 The following example JWE Protected Header declares that: 1336 o the Content Encryption Key is encrypted to the recipient using the 1337 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1339 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1340 bit key to produce the Ciphertext. 1342 {"alg":"RSA-OAEP","enc":"A256GCM"} 1344 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1345 Header)) gives this value: 1347 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1349 A.1.2. Content Encryption Key (CEK) 1351 Generate a 256 bit random Content Encryption Key (CEK). In this 1352 example, the value (using JSON array notation) is: 1354 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1355 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1356 234, 64, 252] 1358 A.1.3. Key Encryption 1360 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1361 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1362 key represented in JSON Web Key [JWK] format below (with line breaks 1363 for display purposes only): 1365 {"kty":"RSA", 1366 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1367 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1368 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1369 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1370 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1371 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1372 "e":"AQAB", 1373 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1374 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1375 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1376 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1377 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1378 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ" 1379 } 1381 The resulting JWE Encrypted Key value is: 1383 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1384 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1385 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1386 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1387 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1388 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1389 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1390 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1391 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1392 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1393 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1394 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1395 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1396 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1397 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1398 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1399 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1400 117, 114, 135, 206] 1402 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1403 this value (with line breaks for display purposes only): 1405 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1406 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1407 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1408 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1409 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1410 6UklfCpIMfIjf7iGdXKHzg 1412 A.1.4. Initialization Vector 1414 Generate a random 96 bit JWE Initialization Vector. In this example, 1415 the value is: 1417 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1419 Encoding this JWE Initialization Vector as BASE64URL(JWE 1420 Initialization Vector) gives this value: 1422 48V1_ALb6US04U3b 1424 A.1.5. Additional Authenticated Data 1426 Let the Additional Authenticated Data encryption parameter be 1427 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1429 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1430 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1431 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1433 A.1.6. Content Encryption 1435 Encrypt the Plaintext with AES GCM using the CEK as the encryption 1436 key, the JWE Initialization Vector, and the Additional Authenticated 1437 Data value above, requesting a 128 bit Authentication Tag output. 1438 The resulting Ciphertext is: 1440 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1441 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1442 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1443 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1444 160, 109, 64, 63, 192] 1446 The resulting Authentication Tag value is: 1448 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1449 210, 145] 1451 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1452 value (with line breaks for display purposes only): 1454 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1455 SdiwkIr3ajwQzaBtQD_A 1457 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1458 Tag) gives this value: 1460 XFBoMYUZodetZdvTiFvSkQ 1462 A.1.7. Complete Representation 1464 Assemble the final representation: The Compact Serialization of this 1465 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1466 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1467 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1468 Authentication Tag). 1470 The final result in this example (with line breaks for display 1471 purposes only) is: 1473 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1474 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1475 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1476 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1477 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1478 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1479 6UklfCpIMfIjf7iGdXKHzg. 1480 48V1_ALb6US04U3b. 1481 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1482 SdiwkIr3ajwQzaBtQD_A. 1483 XFBoMYUZodetZdvTiFvSkQ 1485 A.1.8. Validation 1487 This example illustrates the process of creating a JWE with RSAES 1488 OAEP for key encryption and AES GCM for content encryption. These 1489 results can be used to validate JWE decryption implementations for 1490 these algorithms. Note that since the RSAES OAEP computation 1491 includes random values, the encryption results above will not be 1492 completely reproducible. However, since the AES GCM computation is 1493 deterministic, the JWE Encrypted Ciphertext values will be the same 1494 for all encryptions performed using these inputs. 1496 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1498 This example encrypts the plaintext "Live long and prosper." to the 1499 recipient using RSAES-PKCS1-V1_5 for key encryption and 1500 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1501 of this plaintext (using JSON array notation) is: 1503 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1504 112, 114, 111, 115, 112, 101, 114, 46] 1506 A.2.1. JWE Header 1508 The following example JWE Protected Header declares that: 1510 o the Content Encryption Key is encrypted to the recipient using the 1511 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1513 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1514 algorithm to produce the Ciphertext. 1516 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1518 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1519 Header)) gives this value: 1521 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1523 A.2.2. Content Encryption Key (CEK) 1525 Generate a 256 bit random Content Encryption Key (CEK). In this 1526 example, the key value is: 1528 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1529 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1530 44, 207] 1532 A.2.3. Key Encryption 1534 Encrypt the CEK with the recipient's public key using the RSAES- 1535 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1536 uses the RSA key represented in JSON Web Key [JWK] format below (with 1537 line breaks for display purposes only): 1539 {"kty":"RSA", 1540 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1541 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1542 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1543 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1544 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1545 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1546 "e":"AQAB", 1547 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1548 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1549 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1550 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1551 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1552 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1554 } 1556 The resulting JWE Encrypted Key value is: 1558 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1559 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1560 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1561 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1562 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1563 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1564 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1565 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1566 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1567 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1568 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1569 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1570 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1571 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1572 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1573 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1574 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1575 146, 114, 165, 204, 71, 136, 41, 252] 1577 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1578 this value (with line breaks for display purposes only): 1580 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1581 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1582 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1583 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1584 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1585 -B3oWh2TbqmScqXMR4gp_A 1587 A.2.4. Initialization Vector 1589 Generate a random 128 bit JWE Initialization Vector. In this 1590 example, the value is: 1592 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1593 101] 1595 Encoding this JWE Initialization Vector as BASE64URL(JWE 1596 Initialization Vector) gives this value: 1598 AxY8DCtDaGlsbGljb3RoZQ 1600 A.2.5. Additional Authenticated Data 1602 Let the Additional Authenticated Data encryption parameter be 1603 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1605 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1606 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1607 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1608 50, 73, 110, 48] 1610 A.2.6. Content Encryption 1612 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1613 the encryption key, the JWE Initialization Vector, and the Additional 1614 Authenticated Data value above. The steps for doing this using the 1615 values from Appendix A.3 are detailed in Appendix B. The resulting 1616 Ciphertext is: 1618 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1619 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1620 112, 56, 102] 1622 The resulting Authentication Tag value is: 1624 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1625 191] 1627 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1628 value: 1630 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1632 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1633 Tag) gives this value: 1635 9hH0vgRfYgPnAHOd8stkvw 1637 A.2.7. Complete Representation 1639 Assemble the final representation: The Compact Serialization of this 1640 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1641 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1642 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1643 Authentication Tag). 1645 The final result in this example (with line breaks for display 1646 purposes only) is: 1648 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1649 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1650 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1651 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1652 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1653 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1654 -B3oWh2TbqmScqXMR4gp_A. 1655 AxY8DCtDaGlsbGljb3RoZQ. 1656 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1657 9hH0vgRfYgPnAHOd8stkvw 1659 A.2.8. Validation 1661 This example illustrates the process of creating a JWE with RSAES- 1662 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1663 encryption. These results can be used to validate JWE decryption 1664 implementations for these algorithms. Note that since the RSAES- 1665 PKCS1-V1_5 computation includes random values, the encryption results 1666 above will not be completely reproducible. However, since the AES 1667 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1668 will be the same for all encryptions performed using these inputs. 1670 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1672 This example encrypts the plaintext "Live long and prosper." to the 1673 recipient using AES Key Wrap for key encryption and 1674 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1675 of this plaintext (using JSON array notation) is: 1677 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1678 112, 114, 111, 115, 112, 101, 114, 46] 1680 A.3.1. JWE Header 1682 The following example JWE Protected Header declares that: 1684 o the Content Encryption Key is encrypted to the recipient using the 1685 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1686 Encrypted Key and 1688 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1689 algorithm to produce the Ciphertext. 1691 {"alg":"A128KW","enc":"A128CBC-HS256"} 1693 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1694 Header)) gives this value: 1696 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1698 A.3.2. Content Encryption Key (CEK) 1700 Generate a 256 bit random Content Encryption Key (CEK). In this 1701 example, the value is: 1703 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1704 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1705 44, 207] 1707 A.3.3. Key Encryption 1709 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1710 algorithm to produce the JWE Encrypted Key. This example uses the 1711 symmetric key represented in JSON Web Key [JWK] format below: 1713 {"kty":"oct", 1714 "k":"GawgguFyGrWKav7AX4VKUg" 1715 } 1717 The resulting JWE Encrypted Key value is: 1719 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1720 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1721 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1723 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1724 this value: 1726 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1728 A.3.4. Initialization Vector 1730 Generate a random 128 bit JWE Initialization Vector. In this 1731 example, the value is: 1733 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1734 101] 1736 Encoding this JWE Initialization Vector as BASE64URL(JWE 1737 Initialization Vector) gives this value: 1739 AxY8DCtDaGlsbGljb3RoZQ 1741 A.3.5. Additional Authenticated Data 1743 Let the Additional Authenticated Data encryption parameter be 1744 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1746 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1747 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1748 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1749 110, 48] 1751 A.3.6. Content Encryption 1753 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1754 the encryption key, the JWE Initialization Vector, and the Additional 1755 Authenticated Data value above. The steps for doing this using the 1756 values from this example are detailed in Appendix B. The resulting 1757 Ciphertext is: 1759 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1760 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1761 112, 56, 102] 1763 The resulting Authentication Tag value is: 1765 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1766 194, 85] 1768 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1769 value: 1771 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1773 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1774 Tag) gives this value: 1776 U0m_YmjN04DJvceFICbCVQ 1778 A.3.7. Complete Representation 1780 Assemble the final representation: The Compact Serialization of this 1781 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1782 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1783 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1784 Authentication Tag). 1786 The final result in this example (with line breaks for display 1787 purposes only) is: 1789 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1790 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1791 AxY8DCtDaGlsbGljb3RoZQ. 1792 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1793 U0m_YmjN04DJvceFICbCVQ 1795 A.3.8. Validation 1797 This example illustrates the process of creating a JWE with AES Key 1798 Wrap for key encryption and AES GCM for content encryption. These 1799 results can be used to validate JWE decryption implementations for 1800 these algorithms. Also, since both the AES Key Wrap and AES GCM 1801 computations are deterministic, the resulting JWE value will be the 1802 same for all encryptions performed using these inputs. Since the 1803 computation is reproducible, these results can also be used to 1804 validate JWE encryption implementations for these algorithms. 1806 A.4. Example JWE using JWE JSON Serialization 1808 This section contains an example using the JWE JSON Serialization. 1809 This example demonstrates the capability for encrypting the same 1810 plaintext to multiple recipients. 1812 Two recipients are present in this example. The algorithm and key 1813 used for the first recipient are the same as that used in 1814 Appendix A.2. The algorithm and key used for the second recipient 1815 are the same as that used in Appendix A.3. The resulting JWE 1816 Encrypted Key values are therefore the same; those computations are 1817 not repeated here. 1819 The Plaintext, the Content Encryption Key (CEK), Initialization 1820 Vector, and JWE Protected Header are shared by all recipients (which 1821 must be the case, since the Ciphertext and Authentication Tag are 1822 also shared). 1824 A.4.1. JWE Per-Recipient Unprotected Headers 1826 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1827 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1828 encrypt the CEK. Key ID values are supplied for both keys. The two 1829 per-recipient header values used to represent these algorithms and 1830 Key IDs are: 1832 {"alg":"RSA1_5","kid":"2011-04-29"} 1834 and 1836 {"alg":"A128KW","kid":"7"} 1838 A.4.2. JWE Protected Header 1840 The Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1841 algorithm to produce the common JWE Ciphertext and JWE Authentication 1842 Tag values. The JWE Protected Header value representing this is: 1844 {"enc":"A128CBC-HS256"} 1846 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1847 Header)) gives this value: 1849 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1851 A.4.3. JWE Unprotected Header 1853 This JWE uses the "jku" Header Parameter to reference a JWK Set. This 1854 is represented in the following JWE Unprotected Header value as: 1856 {"jku":"https://server.example.com/keys.jwks"} 1858 A.4.4. Complete JWE Header Values 1860 Combining the per-recipient, protected, and unprotected header values 1861 supplied, the JWE Header values used for the first and second 1862 recipient respectively are: 1864 {"alg":"RSA1_5", 1865 "kid":"2011-04-29", 1866 "enc":"A128CBC-HS256", 1867 "jku":"https://server.example.com/keys.jwks"} 1869 and 1871 {"alg":"A128KW", 1872 "kid":"7", 1873 "enc":"A128CBC-HS256", 1874 "jku":"https://server.example.com/keys.jwks"} 1876 A.4.5. Additional Authenticated Data 1878 Let the Additional Authenticated Data encryption parameter be 1879 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1881 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1882 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1884 A.4.6. Content Encryption 1886 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1887 the encryption key, the JWE Initialization Vector, and the Additional 1888 Authenticated Data value above. The steps for doing this using the 1889 values from Appendix A.3 are detailed in Appendix B. The resulting 1890 Ciphertext is: 1892 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1893 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1894 112, 56, 102] 1896 The resulting Authentication Tag value is: 1898 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1899 207] 1901 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1902 value: 1904 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1906 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1907 Tag) gives this value: 1909 Mz-VPPyU4RlcuYv1IwIvzw 1911 A.4.7. Complete JWE JSON Serialization Representation 1913 The complete JSON Web Encryption JSON Serialization for these values 1914 is as follows (with line breaks for display purposes only): 1916 {"protected": 1917 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1918 "unprotected": 1919 {"jku":"https://server.example.com/keys.jwks"}, 1920 "recipients":[ 1921 {"header": 1922 {"alg":"RSA1_5","kid":"2011-04-29"}, 1923 "encrypted_key": 1924 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1925 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1926 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 1927 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 1928 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 1929 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 1930 {"header": 1931 {"alg":"A128KW","kid":"7"}, 1932 "encrypted_key": 1933 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1934 "iv": 1935 "AxY8DCtDaGlsbGljb3RoZQ", 1936 "ciphertext": 1937 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1938 "tag": 1939 "Mz-VPPyU4RlcuYv1IwIvzw" 1940 } 1942 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 1944 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 1945 authenticated encryption computation using the values from the 1946 example in Appendix A.3. As described where this algorithm is 1947 defined in Sections 5.2 and 5.2.3 of JWA, the AES_CBC_HMAC_SHA2 1948 family of algorithms are implemented using Advanced Encryption 1949 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #5 1950 padding to perform the encryption and an HMAC SHA-2 function to 1951 perform the integrity calculation - in this case, HMAC SHA-256. 1953 B.1. Extract MAC_KEY and ENC_KEY from Key 1955 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example 1956 (using JSON array notation) is: 1958 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1959 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1960 44, 207] 1962 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 1963 which is: 1965 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1966 206] 1968 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 1969 is: 1971 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 1972 207] 1974 Note that the MAC key comes before the encryption key in the input 1975 key K; this is in the opposite order of the algorithm names in the 1976 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 1978 B.2. Encrypt Plaintext to Create Ciphertext 1980 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 1981 using PKCS #5 padding using the ENC_KEY above. The Plaintext in this 1982 example is: 1984 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1985 112, 114, 111, 115, 112, 101, 114, 46] 1987 The encryption result is as follows, which is the Ciphertext output: 1989 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1990 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1991 112, 56, 102] 1993 B.3. 64 Bit Big Endian Representation of AAD Length 1995 The Additional Authenticated Data (AAD) in this example is: 1997 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1998 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1999 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2000 110, 48] 2002 This AAD is 51 bytes long, which is 408 bits long. The octet string 2003 AL, which is the number of bits in AAD expressed as a big endian 64 2004 bit unsigned integer is: 2006 [0, 0, 0, 0, 0, 0, 1, 152] 2008 B.4. Initialization Vector Value 2010 The Initialization Vector value used in this example is: 2012 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 2013 101] 2015 B.5. Create Input to HMAC Computation 2017 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 2018 the AL value. The result of this concatenation is: 2020 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2021 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2022 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2023 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 2024 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 2025 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 2026 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 2028 B.6. Compute HMAC Value 2030 Compute the HMAC SHA-256 of the concatenated value above. This 2031 result M is: 2033 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2034 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 2035 86, 229, 116] 2037 B.7. Truncate HMAC Value to Create Authentication Tag 2039 Use the first half (128 bits) of the HMAC output M as the 2040 Authentication Tag output T. This truncated value is: 2042 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2043 194, 85] 2045 Appendix C. Acknowledgements 2047 Solutions for encrypting JSON content were also explored by JSON 2048 Simple Encryption [JSE] and JavaScript Message Security Format 2049 [I-D.rescorla-jsms], both of which significantly influenced this 2050 draft. This draft attempts to explicitly reuse as many of the 2051 relevant concepts from XML Encryption 1.1 2052 [W3C.REC-xmlenc-core1-20130411] and RFC 5652 [RFC5652] as possible, 2053 while utilizing simple, compact JSON-based data structures. 2055 Special thanks are due to John Bradley, Eric Rescorla, and Nat 2056 Sakimura for the discussions that helped inform the content of this 2057 specification, to Eric Rescorla and Joe Hildebrand for allowing the 2058 reuse of text from [I-D.rescorla-jsms] in this document, and to Eric 2059 Rescorla for co-authoring many drafts of this specification. 2061 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2062 Jay for validating the examples in this specification. 2064 This specification is the work of the JOSE Working Group, which 2065 includes dozens of active and dedicated participants. In particular, 2066 the following individuals contributed ideas, feedback, and wording 2067 that influenced this specification: 2069 Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick 2070 Hardt, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Tony 2071 Nadalin, Hideki Nara, Axel Nennker, Emmanuel Raviart, Eric Rescorla, 2072 Nat Sakimura, Jim Schaad, Hannes Tschofenig, and Sean Turner. 2074 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2075 Sean Turner, Stephen Farrell, and Kathleen Moriarty served as 2076 Security area directors during the creation of this specification. 2078 Appendix D. Document History 2080 [[ to be removed by the RFC Editor before publication as an RFC ]] 2082 -27 2084 o Described additional security considerations. 2086 o Added the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) header 2087 parameter. 2089 -26 2091 o Noted that octet sequences are depicted using JSON array notation. 2093 o Updated references, including to W3C specifications. 2095 -25 2097 o Corrected two external section number references that had changed. 2099 o Corrected a typo in an algorithm name in the prose of an example. 2101 -24 2102 o Corrected complete JSON Serialization example. 2104 o Replaced uses of the term "associated data" wherever it was used 2105 to refer to a data value with "additional authenticated data", 2106 since both terms were being used as synonyms, causing confusion. 2108 o Updated the JSON reference to RFC 7159. 2110 o Thanked Eric Rescorla for helping to author of most of the drafts 2111 of this specification and removed him from the current author 2112 list. 2114 -23 2116 o Corrected a use of the word "payload" to "plaintext". 2118 -22 2120 o Corrected RFC 2119 terminology usage. 2122 o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. 2124 -21 2126 o Changed some references from being normative to informative, 2127 addressing issue #90. 2129 o Applied review comments to the JSON Serialization section, 2130 addressing issue #178. 2132 -20 2134 o Made terminology definitions more consistent, addressing issue 2135 #165. 2137 o Restructured the JSON Serialization section to call out the 2138 parameters used in hanging lists, addressing issue #178. 2140 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 2141 addressing issue #90. 2143 -19 2145 o Reordered the key selection parameters. 2147 -18 2148 o Updated the mandatory-to-implement (MTI) language to say that 2149 applications using this specification need to specify what 2150 serialization and serialization features are used for that 2151 application, addressing issue #176. 2153 o Changes to address editorial and minor issues #89, #135, #165, 2154 #174, #175, #177, #179, and #180. 2156 o Used Header Parameter Description registry field. 2158 -17 2160 o Refined the "typ" and "cty" definitions to always be MIME Media 2161 Types, with the omission of "application/" prefixes recommended 2162 for brevity, addressing issue #50. 2164 o Updated the mandatory-to-implement (MTI) language to say that 2165 general-purpose implementations must implement the single 2166 recipient case for both serializations whereas special-purpose 2167 implementations can implement just one serialization if that meets 2168 the needs of the use cases the implementation is designed for, 2169 addressing issue #176. 2171 o Explicitly named all the logical components of a JWE and defined 2172 the processing rules and serializations in terms of those 2173 components, addressing issues #60, #61, and #62. 2175 o Replaced verbose repetitive phases such as "base64url encode the 2176 octets of the UTF-8 representation of X" with mathematical 2177 notation such as "BASE64URL(UTF8(X))". 2179 o Header Parameters and processing rules occurring in both JWS and 2180 JWE are now referenced in JWS by JWE, rather than duplicated, 2181 addressing issue #57. 2183 o Terms used in multiple documents are now defined in one place and 2184 incorporated by reference. Some lightly used or obvious terms 2185 were also removed. This addresses issue #58. 2187 -16 2189 o Changes to address editorial and minor issues #163, #168, #169, 2190 #170, #172, and #173. 2192 -15 2194 o Clarified that it is an application decision which recipients' 2195 encrypted content must successfully validate for the JWE to be 2196 accepted, addressing issue #35. 2198 o Changes to address editorial issues #34, #164, and #169. 2200 -14 2202 o Clarified that the "protected", "unprotected", "header", "iv", 2203 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2204 JSON Serialization when their values would be empty. Stated that 2205 the "recipients" array must always be present. 2207 -13 2209 o Added an "aad" (Additional Authenticated Data) member for the JWE 2210 JSON Serialization, enabling Additional Authenticated Data to be 2211 supplied that is not double base64url encoded, addressing issue 2212 #29. 2214 -12 2216 o Clarified that the "typ" and "cty" header parameters are used in 2217 an application-specific manner and have no effect upon the JWE 2218 processing. 2220 o Replaced the MIME types "application/jwe+json" and 2221 "application/jwe" with "application/jose+json" and 2222 "application/jose". 2224 o Stated that recipients MUST either reject JWEs with duplicate 2225 Header Parameter Names or use a JSON parser that returns only the 2226 lexically last duplicate member name. 2228 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2229 be with the algorithm descriptions that use them. 2231 o Added a Serializations section with parallel treatment of the JWE 2232 Compact Serialization and the JWE JSON Serialization and also 2233 moved the former Implementation Considerations content there. 2235 o Restored use of the term "AEAD". 2237 o Changed terminology from "block encryption" to "content 2238 encryption". 2240 -11 2242 o Added Key Identification section. 2244 o Removed the Encrypted Key value from the AAD computation since it 2245 is already effectively integrity protected by the encryption 2246 process. The AAD value now only contains the representation of 2247 the JWE Encrypted Header. 2249 o For the JWE JSON Serialization, enable Header Parameter values to 2250 be specified in any of three parameters: the "protected" member 2251 that is integrity protected and shared among all recipients, the 2252 "unprotected" member that is not integrity protected and shared 2253 among all recipients, and the "header" member that is not 2254 integrity protected and specific to a particular recipient. (This 2255 does not affect the JWE Compact Serialization, in which all Header 2256 Parameter values are in a single integrity protected JWE Header 2257 value.) 2259 o Shortened the names "authentication_tag" to "tag" and 2260 "initialization_vector" to "iv" in the JWE JSON Serialization, 2261 addressing issue #20. 2263 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2265 o Removed suggested compact serialization for multiple recipients. 2267 o Changed the MIME type name "application/jwe-js" to 2268 "application/jwe+json", addressing issue #22. 2270 o Tightened the description of the "crit" (critical) header 2271 parameter. 2273 -10 2275 o Changed the JWE processing rules for multiple recipients so that a 2276 single AAD value contains the header parameters and encrypted key 2277 values for all the recipients, enabling AES GCM to be safely used 2278 for multiple recipients. 2280 o Added an appendix suggesting a possible compact serialization for 2281 JWEs with multiple recipients. 2283 -09 2285 o Added JWE JSON Serialization, as specified by 2286 draft-jones-jose-jwe-json-serialization-04. 2288 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2289 parameter value. 2291 o Defined that the default action for header parameters that are not 2292 understood is to ignore them unless specifically designated as 2293 "MUST be understood" or included in the new "crit" (critical) 2294 header parameter list. This addressed issue #6. 2296 o Corrected "x5c" description. This addressed issue #12. 2298 o Changed from using the term "byte" to "octet" when referring to 8 2299 bit values. 2301 o Added Key Management Mode definitions to terminology section and 2302 used the defined terms to provide clearer key management 2303 instructions. This addressed issue #5. 2305 o Added text about preventing the recipient from behaving as an 2306 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2308 o Changed from using the term "Integrity Value" to "Authentication 2309 Tag". 2311 o Changed member name from "integrity_value" to "authentication_tag" 2312 in the JWE JSON Serialization. 2314 o Removed Initialization Vector from the AAD value since it is 2315 already integrity protected by all of the authenticated encryption 2316 algorithms specified in the JWA specification. 2318 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2319 and "A256CBC-HS512". The new algorithms perform the same 2320 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2321 but with the Initialization Vector and Authentication Tag values 2322 remaining separate from the Ciphertext value in the output 2323 representation. Also deleted the header parameters "epu" 2324 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2325 they are no longer used. 2327 -08 2329 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2330 since the term AEAD in the RFC 5116 sense implied the use of a 2331 particular data representation, rather than just referring to the 2332 class of algorithms that perform authenticated encryption with 2333 associated data. 2335 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2336 Tschofenig. Many of these simplified the terminology used. 2338 o Clarified statements of the form "This header parameter is 2339 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2341 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2342 Web Signature and Encryption Header Parameters registry. 2344 o Added seriesInfo information to Internet Draft references. 2346 -07 2348 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2350 o Updated values for example AES CBC calculations. 2352 o Made several local editorial changes to clean up loose ends left 2353 over from to the decision to only support block encryption methods 2354 providing integrity. One of these changes was to explicitly state 2355 that the "enc" (encryption method) algorithm must be an 2356 Authenticated Encryption algorithm with a specified key length. 2358 -06 2360 o Removed the "int" and "kdf" parameters and defined the new 2361 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2362 "A256CBC+HS512" to replace the former uses of AES CBC, which 2363 required the use of separate integrity and key derivation 2364 functions. 2366 o Included additional values in the Concat KDF calculation -- the 2367 desired output size and the algorithm value, and optionally 2368 PartyUInfo and PartyVInfo values. Added the optional header 2369 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2370 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2371 PartyVInfo). Updated the KDF examples accordingly. 2373 o Promoted Initialization Vector from being a header parameter to 2374 being a top-level JWE element. This saves approximately 16 bytes 2375 in the compact serialization, which is a significant savings for 2376 some use cases. Promoting the Initialization Vector out of the 2377 header also avoids repeating this shared value in the JSON 2378 serialization. 2380 o Changed "x5c" (X.509 Certificate Chain) representation from being 2381 a single string to being an array of strings, each containing a 2382 single base64 encoded DER certificate value, representing elements 2383 of the certificate chain. 2385 o Added an AES Key Wrap example. 2387 o Reordered the encryption steps so CMK creation is first, when 2388 required. 2390 o Correct statements in examples about which algorithms produce 2391 reproducible results. 2393 -05 2395 o Support both direct encryption using a shared or agreed upon 2396 symmetric key, and the use of a shared or agreed upon symmetric 2397 key to key wrap the CMK. 2399 o Added statement that "StringOrURI values are compared as case- 2400 sensitive strings with no transformations or canonicalizations 2401 applied". 2403 o Updated open issues. 2405 o Indented artwork elements to better distinguish them from the body 2406 text. 2408 -04 2410 o Refer to the registries as the primary sources of defined values 2411 and then secondarily reference the sections defining the initial 2412 contents of the registries. 2414 o Normatively reference XML Encryption 1.1 for its security 2415 considerations. 2417 o Reference draft-jones-jose-jwe-json-serialization instead of 2418 draft-jones-json-web-encryption-json-serialization. 2420 o Described additional open issues. 2422 o Applied editorial suggestions. 2424 -03 2426 o Added the "kdf" (key derivation function) header parameter to 2427 provide crypto agility for key derivation. The default KDF 2428 remains the Concat KDF with the SHA-256 digest function. 2430 o Reordered encryption steps so that the Encoded JWE Header is 2431 always created before it is needed as an input to the 2432 Authenticated Encryption "additional authenticated data" 2433 parameter. 2435 o Added the "cty" (content type) header parameter for declaring type 2436 information about the secured content, as opposed to the "typ" 2437 (type) header parameter, which declares type information about 2438 this object. 2440 o Moved description of how to determine whether a header is for a 2441 JWS or a JWE from the JWT spec to the JWE spec. 2443 o Added complete encryption examples for both Authenticated 2444 Encryption and non-Authenticated Encryption algorithms. 2446 o Added complete key derivation examples. 2448 o Added "Collision Resistant Namespace" to the terminology section. 2450 o Reference ITU.X690.1994 for DER encoding. 2452 o Added Registry Contents sections to populate registry values. 2454 o Numerous editorial improvements. 2456 -02 2458 o When using Authenticated Encryption algorithms (such as AES GCM), 2459 use the "additional authenticated data" parameter to provide 2460 integrity for the header, encrypted key, and ciphertext and use 2461 the resulting "authentication tag" value as the JWE Authentication 2462 Tag. 2464 o Defined KDF output key sizes. 2466 o Generalized text to allow key agreement to be employed as an 2467 alternative to key wrapping or key encryption. 2469 o Changed compression algorithm from gzip to DEFLATE. 2471 o Clarified that it is an error when a "kid" value is included and 2472 no matching key is found. 2474 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2475 rejected. 2477 o Clarified the relationship between "typ" header parameter values 2478 and MIME types. 2480 o Registered application/jwe MIME type and "JWE" typ header 2481 parameter value. 2483 o Simplified JWK terminology to get replace the "JWK Key Object" and 2484 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2485 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2486 between single keys and sets of keys. As part of this change, the 2487 Header Parameter Name for a public key value was changed from 2488 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2490 o Added suggestion on defining additional header parameters such as 2491 "x5t#S256" in the future for certificate thumbprints using hash 2492 algorithms other than SHA-1. 2494 o Specify RFC 2818 server identity validation, rather than RFC 6125 2495 (paralleling the same decision in the OAuth specs). 2497 o Generalized language to refer to Message Authentication Codes 2498 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2499 unless in a context specific to HMAC algorithms. 2501 o Reformatted to give each header parameter its own section heading. 2503 -01 2505 o Added an integrity check for non-Authenticated Encryption 2506 algorithms. 2508 o Added "jpk" and "x5c" header parameters for including JWK public 2509 keys and X.509 certificate chains directly in the header. 2511 o Clarified that this specification is defining the JWE Compact 2512 Serialization. Referenced the new JWE-JS spec, which defines the 2513 JWE JSON Serialization. 2515 o Added text "New header parameters should be introduced sparingly 2516 since an implementation that does not understand a parameter MUST 2517 reject the JWE". 2519 o Clarified that the order of the encryption and decryption steps is 2520 not significant in cases where there are no dependencies between 2521 the inputs and outputs of the steps. 2523 o Made other editorial improvements suggested by JOSE working group 2524 participants. 2526 -00 2527 o Created the initial IETF draft based upon 2528 draft-jones-json-web-encryption-02 with no normative changes. 2530 o Changed terminology to no longer call both digital signatures and 2531 HMACs "signatures". 2533 Authors' Addresses 2535 Michael B. Jones 2536 Microsoft 2538 Email: mbj@microsoft.com 2539 URI: http://self-issued.info/ 2541 Joe Hildebrand 2542 Cisco Systems, Inc. 2544 Email: jhildebr@cisco.com