idnits 2.17.1 draft-ietf-jose-json-web-encryption-38.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 (December 9, 2014) is 3418 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 1497 -- Looks like a reference, but probably isn't: '197' on line 1497 -- Looks like a reference, but probably isn't: '117' on line 1497 -- Looks like a reference, but probably isn't: '252' on line 1497 -- Looks like a reference, but probably isn't: '2' on line 1497 -- Looks like a reference, but probably isn't: '219' on line 1497 -- Looks like a reference, but probably isn't: '233' on line 1497 -- Looks like a reference, but probably isn't: '68' on line 1497 -- Looks like a reference, but probably isn't: '180' on line 1497 -- Looks like a reference, but probably isn't: '225' on line 1497 -- Looks like a reference, but probably isn't: '77' on line 1497 -- Looks like a reference, but probably isn't: '0' on line 2136 -- Looks like a reference, but probably isn't: '1' on line 2136 -- Looks like a reference, but probably isn't: '152' on line 2136 == Unused Reference: 'AES' is defined on line 1331, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 17 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track J. Hildebrand 5 Expires: June 12, 2015 Cisco 6 December 9, 2014 8 JSON Web Encryption (JWE) 9 draft-ietf-jose-json-web-encryption-38 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 June 12, 2015. 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 . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 8 59 3.1. JWE Compact Serialization Overview . . . . . . . . . . . . 9 60 3.2. JWE JSON Serialization Overview . . . . . . . . . . . . . 9 61 3.3. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 10 62 4. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 11 63 4.1. Registered Header Parameter Names . . . . . . . . . . . . 11 64 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 12 65 4.1.2. "enc" (Encryption Algorithm) Header Parameter . . . . 12 66 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 12 67 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 13 68 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 13 69 4.1.6. "kid" (Key ID) Header Parameter . . . . . . . . . . . 13 70 4.1.7. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 13 71 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 13 72 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 73 Parameter . . . . . . . . . . . . . . . . . . . . . . 14 74 4.1.10. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) 75 Header Parameter . . . . . . . . . . . . . . . . . . . 14 76 4.1.11. "typ" (Type) Header Parameter . . . . . . . . . . . . 14 77 4.1.12. "cty" (Content Type) Header Parameter . . . . . . . . 14 78 4.1.13. "crit" (Critical) Header Parameter . . . . . . . . . . 14 79 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 14 80 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 15 81 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 15 82 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 15 83 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 17 84 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20 85 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20 86 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 20 87 7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 20 88 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21 89 7.2.1. General JWE JSON Serialization Syntax . . . . . . . . 21 90 7.2.2. Flattened JWE JSON Serialization Syntax . . . . . . . 24 91 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 24 92 9. Distinguishing between JWS and JWE Objects . . . . . . . . . . 24 93 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 94 10.1. JSON Web Signature and Encryption Header Parameters 95 Registration . . . . . . . . . . . . . . . . . . . . . . . 25 97 10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25 98 11. Security Considerations . . . . . . . . . . . . . . . . . . . 27 99 11.1. Key Entropy and Random Values . . . . . . . . . . . . . . 27 100 11.2. Key Protection . . . . . . . . . . . . . . . . . . . . . . 28 101 11.3. Using Matching Algorithm Strengths . . . . . . . . . . . . 28 102 11.4. Adaptive Chosen-Ciphertext Attacks . . . . . . . . . . . . 28 103 11.5. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 28 104 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 105 12.1. Normative References . . . . . . . . . . . . . . . . . . . 29 106 12.2. Informative References . . . . . . . . . . . . . . . . . . 29 107 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 30 108 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 31 109 A.1.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 31 110 A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 31 111 A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 31 112 A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 33 113 A.1.5. Additional Authenticated Data . . . . . . . . . . . . 33 114 A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 33 115 A.1.7. Complete Representation . . . . . . . . . . . . . . . 34 116 A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 34 117 A.2. Example JWE using RSAES-PKCS1-V1_5 and 118 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 35 119 A.2.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 35 120 A.2.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 35 121 A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 35 122 A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 37 123 A.2.5. Additional Authenticated Data . . . . . . . . . . . . 37 124 A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 37 125 A.2.7. Complete Representation . . . . . . . . . . . . . . . 38 126 A.2.8. Validation . . . . . . . . . . . . . . . . . . . . . . 38 127 A.3. Example JWE using AES Key Wrap and 128 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 39 129 A.3.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 39 130 A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 39 131 A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 39 132 A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 40 133 A.3.5. Additional Authenticated Data . . . . . . . . . . . . 40 134 A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 40 135 A.3.7. Complete Representation . . . . . . . . . . . . . . . 41 136 A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 41 137 A.4. Example JWE using General JWE JSON Serialization . . . . . 42 138 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 42 139 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 42 140 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 43 141 A.4.4. Complete JOSE Header Values . . . . . . . . . . . . . 43 142 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 43 143 A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 43 144 A.4.7. Complete JWE JSON Serialization Representation . . . . 44 146 A.5. Example JWE using Flattened JWE JSON Serialization . . . . 45 147 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 45 148 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 45 149 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 46 150 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 46 151 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 47 152 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 47 153 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 47 154 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 47 155 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 47 156 Appendix D. Document History . . . . . . . . . . . . . . . . . . 48 157 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 59 159 1. Introduction 161 JSON Web Encryption (JWE) represents encrypted content using 162 JavaScript Object Notation (JSON) [RFC7159] based data structures. 163 The JWE cryptographic mechanisms encrypt and provide integrity 164 protection for an arbitrary sequence of octets. 166 Two closely related serializations for JWEs are defined. The JWE 167 Compact Serialization is a compact, URL-safe representation intended 168 for space constrained environments such as HTTP Authorization headers 169 and URI query parameters. The JWE JSON Serialization represents JWEs 170 as JSON objects and enables the same content to be encrypted to 171 multiple parties. Both share the same cryptographic underpinnings. 173 Cryptographic algorithms and identifiers for use with this 174 specification are described in the separate JSON Web Algorithms (JWA) 175 [JWA] specification and IANA registries defined by that 176 specification. Related digital signature and MAC capabilities are 177 described in the separate JSON Web Signature (JWS) [JWS] 178 specification. 180 Names defined by this specification are short because a core goal is 181 for the resulting representations to be compact. 183 1.1. Notational Conventions 185 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 186 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 187 "OPTIONAL" in this document are to be interpreted as described in Key 188 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 189 these words are used without being spelled in uppercase then they are 190 to be interpreted with their normal natural language meanings. 192 BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per 193 Section 2 of [JWS]. 195 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 196 of STRING. 198 ASCII(STRING) denotes the octets of the ASCII [RFC20] representation 199 of STRING. 201 The concatenation of two values A and B is denoted as A || B. 203 2. Terminology 205 These terms defined by the JSON Web Signature (JWS) [JWS] 206 specification are incorporated into this specification: "JSON Web 207 Signature (JWS)", "Base64url Encoding", "Collision-Resistant Name", 208 "Header Parameter", "JOSE Header", and "StringOrURI". 210 These terms defined by the Internet Security Glossary, Version 2 211 [RFC4949] are incorporated into this specification: "Ciphertext", 212 "Digital Signature", "Message Authentication Code (MAC)", and 213 "Plaintext". 215 These terms are defined by this specification: 217 JSON Web Encryption (JWE) 218 A data structure representing an encrypted and integrity protected 219 message. 221 Authenticated Encryption with Associated Data (AEAD) 222 An AEAD algorithm is one that encrypts the Plaintext, allows 223 Additional Authenticated Data to be specified, and provides an 224 integrated content integrity check over the Ciphertext and 225 Additional Authenticated Data. AEAD algorithms accept two inputs, 226 the Plaintext and the Additional Authenticated Data value, and 227 produce two outputs, the Ciphertext and the Authentication Tag 228 value. AES Galois/Counter Mode (GCM) is one such algorithm. 230 Additional Authenticated Data (AAD) 231 An input to an AEAD operation that is integrity protected but not 232 encrypted. 234 Authentication Tag 235 An output of an AEAD operation that ensures the integrity of the 236 Ciphertext and the Additional Authenticated Data. Note that some 237 algorithms may not use an Authentication Tag, in which case this 238 value is the empty octet sequence. 240 Content Encryption Key (CEK) 241 A symmetric key for the AEAD algorithm used to encrypt the 242 Plaintext to produce the Ciphertext and the Authentication Tag. 244 JWE Encrypted Key 245 Encrypted Content Encryption Key (CEK) value. Note that for some 246 algorithms, the JWE Encrypted Key value is specified as being the 247 empty octet sequence. 249 JWE Initialization Vector 250 Initialization vector value used when encrypting the plaintext. 251 Note that some algorithms may not use an Initialization Vector, in 252 which case this value is the empty octet sequence. 254 JWE AAD 255 Additional value to be integrity protected by the authenticated 256 encryption operation. This can only be present when using the JWE 257 JSON Serialization. (Note that this can also be achieved when 258 using either serialization by including the AAD value as an 259 integrity protected Header Parameter value, but at the cost of the 260 value being double base64url encoded.) 262 JWE Ciphertext 263 Ciphertext value resulting from authenticated encryption of the 264 plaintext with additional authenticated data. 266 JWE Authentication Tag 267 Authentication Tag value resulting from authenticated encryption 268 of the plaintext with additional authenticated data. 270 JWE Protected Header 271 JSON object that contains the Header Parameters that are integrity 272 protected by the authenticated encryption operation. These 273 parameters apply to all recipients of the JWE. For the JWE 274 Compact Serialization, this comprises the entire JOSE Header. For 275 the JWE JSON Serialization, this is one component of the JOSE 276 Header. 278 JWE Shared Unprotected Header 279 JSON object that contains the Header Parameters that apply to all 280 recipients of the JWE that are not integrity protected. This can 281 only be present when using the JWE JSON Serialization. 283 JWE Per-Recipient Unprotected Header 284 JSON object that contains Header Parameters that apply to a single 285 recipient of the JWE. These Header Parameter values are not 286 integrity protected. This can only be present when using the JWE 287 JSON Serialization. 289 JWE Compact Serialization 290 A representation of the JWE as a compact, URL-safe string. 292 JWE JSON Serialization 293 A representation of the JWE as a JSON object. The JWE JSON 294 Serialization enables the same content to be encrypted to multiple 295 parties. This representation is neither optimized for compactness 296 nor URL-safe. 298 Key Management Mode 299 A method of determining the Content Encryption Key (CEK) value to 300 use. Each algorithm used for determining the CEK value uses a 301 specific Key Management Mode. Key Management Modes employed by 302 this specification are Key Encryption, Key Wrapping, Direct Key 303 Agreement, Key Agreement with Key Wrapping, and Direct Encryption. 305 Key Encryption 306 A Key Management Mode in which the Content Encryption Key (CEK) 307 value is encrypted to the intended recipient using an asymmetric 308 encryption algorithm. 310 Key Wrapping 311 A Key Management Mode in which the Content Encryption Key (CEK) 312 value is encrypted to the intended recipient using a symmetric key 313 wrapping algorithm. 315 Direct Key Agreement 316 A Key Management Mode in which a key agreement algorithm is used 317 to agree upon the Content Encryption Key (CEK) value. 319 Key Agreement with Key Wrapping 320 A Key Management Mode in which a key agreement algorithm is used 321 to agree upon a symmetric key used to encrypt the Content 322 Encryption Key (CEK) value to the intended recipient using a 323 symmetric key wrapping algorithm. 325 Direct Encryption 326 A Key Management Mode in which the Content Encryption Key (CEK) 327 value used is the secret symmetric key value shared between the 328 parties. 330 3. JSON Web Encryption (JWE) Overview 332 JWE represents encrypted content using JSON data structures and 333 base64url encoding. These JSON data structures MAY contain white 334 space and/or line breaks before or after any JSON values or 335 structural characters, in accordance with Section 2 of RFC 7159 336 [RFC7159]. A JWE represents these logical values (each of which is 337 defined in Section 2): 339 o JOSE Header 340 o JWE Encrypted Key 341 o JWE Initialization Vector 342 o JWE AAD 343 o JWE Ciphertext 344 o JWE Authentication Tag 346 For a JWE, the JOSE Header members are the union of the members of 347 these values (each of which is defined in Section 2): 349 o JWE Protected Header 350 o JWE Shared Unprotected Header 351 o JWE Per-Recipient Unprotected Header 353 JWE utilizes authenticated encryption to ensure the confidentiality 354 and integrity of the Plaintext and the integrity of the JWE Protected 355 Header and the JWE AAD. 357 This document defines two serializations for JWEs: a compact, URL- 358 safe serialization called the JWE Compact Serialization and a JSON 359 serialization called the JWE JSON Serialization. In both 360 serializations, the JWE Protected Header, JWE Encrypted Key, JWE 361 Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are 362 base64url encoded, since JSON lacks a way to directly represent 363 arbitrary octet sequences. When present, the JWE AAD is also 364 base64url encoded. 366 3.1. JWE Compact Serialization Overview 368 In the JWE Compact Serialization, no JWE Shared Unprotected Header or 369 JWE Per-Recipient Unprotected Header are used. In this case, the 370 JOSE Header and the JWE Protected Header are the same. 372 In the JWE Compact Serialization, a JWE is represented as the 373 concatenation: 375 BASE64URL(UTF8(JWE Protected Header)) || '.' || 376 BASE64URL(JWE Encrypted Key) || '.' || 377 BASE64URL(JWE Initialization Vector) || '.' || 378 BASE64URL(JWE Ciphertext) || '.' || 379 BASE64URL(JWE Authentication Tag) 381 See Section 7.1 for more information about the JWE Compact 382 Serialization. 384 3.2. JWE JSON Serialization Overview 386 In the JWE JSON Serialization, one or more of the JWE Protected 387 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 388 Unprotected Header MUST be present. In this case, the members of the 389 JOSE Header are the union of the members of the JWE Protected Header, 390 JWE Shared Unprotected Header, and JWE Per-Recipient Unprotected 391 Header values that are present. 393 In the JWE JSON Serialization, a JWE is represented as a JSON object 394 containing some or all of these eight members: 396 "protected", with the value BASE64URL(UTF8(JWE Protected Header)) 397 "unprotected", with the value JWE Shared Unprotected Header 398 "header", with the value JWE Per-Recipient Unprotected Header 399 "encrypted_key", with the value BASE64URL(JWE Encrypted Key) 400 "iv", with the value BASE64URL(JWE Initialization Vector) 401 "ciphertext", with the value BASE64URL(JWE Ciphertext) 402 "tag", with the value BASE64URL(JWE Authentication Tag) 403 "aad", with the value BASE64URL(JWE AAD) 405 The six base64url encoded result strings and the two unprotected JSON 406 object values are represented as members within a JSON object. The 407 inclusion of some of these values is OPTIONAL. The JWE JSON 408 Serialization can also encrypt the plaintext to multiple recipients. 409 See Section 7.2 for more information about the JWE JSON 410 Serialization. 412 3.3. Example JWE 414 This example encrypts the plaintext "The true sign of intelligence is 415 not knowledge but imagination." to the recipient. 417 The following example JWE Protected Header declares that: 419 o The Content Encryption Key is encrypted to the recipient using the 420 RSAES OAEP [RFC3447] algorithm to produce the JWE Encrypted Key. 422 o Authenticated encryption is performed on the Plaintext using the 423 AES GCM [AES, NIST.800-38D] algorithm with a 256 bit key to 424 produce the Ciphertext and the Authentication Tag. 426 {"alg":"RSA-OAEP","enc":"A256GCM"} 428 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 429 Header)) gives this value: 431 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 433 The remaining steps to finish creating this JWE are: 434 o Generate a random Content Encryption Key (CEK). 435 o Encrypt the CEK with the recipient's public key using the RSAES 436 OAEP algorithm to produce the JWE Encrypted Key. 437 o Base64url encode the JWE Encrypted Key. 438 o Generate a random JWE Initialization Vector. 439 o Base64url encode the JWE Initialization Vector. 440 o Let the Additional Authenticated Data encryption parameter be 441 ASCII(BASE64URL(UTF8(JWE Protected Header))). 443 o Perform authenticated encryption on the Plaintext with the AES GCM 444 algorithm using the CEK as the encryption key, the JWE 445 Initialization Vector, and the Additional Authenticated Data 446 value, requesting a 128 bit Authentication Tag output. 447 o Base64url encode the Ciphertext. 448 o Base64url encode the Authentication Tag. 449 o Assemble the final representation: The Compact Serialization of 450 this result is the string BASE64URL(UTF8(JWE Protected Header)) || 451 '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE 452 Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' 453 || BASE64URL(JWE Authentication Tag). 455 The final result in this example (with line breaks for display 456 purposes only) is: 458 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 459 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 460 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 461 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 462 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 463 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 464 6UklfCpIMfIjf7iGdXKHzg. 465 48V1_ALb6US04U3b. 466 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 467 SdiwkIr3ajwQzaBtQD_A. 468 XFBoMYUZodetZdvTiFvSkQ 470 See Appendix A.1 for the complete details of computing this JWE. See 471 Appendix A for additional examples, including examples using the JWE 472 JSON Serialization in Sections A.4 and A.5. 474 4. JOSE Header 476 For a JWE, the members of the JSON object(s) representing the JOSE 477 Header describe the encryption applied to the Plaintext and 478 optionally additional properties of the JWE. The Header Parameter 479 names within the JOSE Header MUST be unique, just as described in 480 Section 4 of [JWS]. The rules about handling Header Parameters that 481 are not understood by the implementation are also the same. The 482 classes of Header Parameter names are likewise the same. 484 4.1. Registered Header Parameter Names 486 The following Header Parameter names for use in JWEs are registered 487 in the IANA JSON Web Signature and Encryption Header Parameters 488 registry defined in [JWS], with meanings as defined below. 490 As indicated by the common registry, JWSs and JWEs share a common 491 Header Parameter space; when a parameter is used by both 492 specifications, its usage must be compatible between the 493 specifications. 495 4.1.1. "alg" (Algorithm) Header Parameter 497 This parameter has the same meaning, syntax, and processing rules as 498 the "alg" Header Parameter defined in Section 4.1.1 of [JWS], except 499 that the Header Parameter identifies the cryptographic algorithm used 500 to encrypt or determine the value of the Content Encryption Key 501 (CEK). The encrypted content is not usable if the "alg" value does 502 not represent a supported algorithm, or if the recipient does not 503 have a key that can be used with that algorithm. 505 A list of defined "alg" values for this use can be found in the IANA 506 JSON Web Signature and Encryption Algorithms registry defined in 507 [JWA]; the initial contents of this registry are the values defined 508 in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. 510 4.1.2. "enc" (Encryption Algorithm) Header Parameter 512 The "enc" (encryption algorithm) Header Parameter identifies the 513 content encryption algorithm used to perform authenticated encryption 514 on the Plaintext to produce the Ciphertext and the Authentication 515 Tag. This algorithm MUST be an AEAD algorithm with a specified key 516 length. The encrypted content is not usable if the "enc" value does 517 not represent a supported algorithm. "enc" values should either be 518 registered in the IANA JSON Web Signature and Encryption Algorithms 519 registry defined in [JWA] or be a value that contains a Collision- 520 Resistant Name. The "enc" value is a case-sensitive ASCII string 521 containing a StringOrURI value. This Header Parameter MUST be 522 present and MUST be understood and processed by implementations. 524 A list of defined "enc" values for this use can be found in the IANA 525 JSON Web Signature and Encryption Algorithms registry defined in 526 [JWA]; the initial contents of this registry are the values defined 527 in Section 5.1 of the JSON Web Algorithms (JWA) [JWA] specification. 529 4.1.3. "zip" (Compression Algorithm) Header Parameter 531 The "zip" (compression algorithm) applied to the Plaintext before 532 encryption, if any. The "zip" value defined by this specification 533 is: 535 o "DEF" - Compression with the DEFLATE [RFC1951] algorithm 537 Other values MAY be used. Compression algorithm values can be 538 registered in the IANA JSON Web Encryption Compression Algorithm 539 registry defined in [JWA]. The "zip" value is a case-sensitive 540 string. If no "zip" parameter is present, no compression is applied 541 to the Plaintext before encryption. When used, this Header Parameter 542 MUST be integrity protected; therefore, it MUST occur only within the 543 JWE Protected Header. Use of this Header Parameter is OPTIONAL. 544 This Header Parameter MUST be understood and processed by 545 implementations. 547 4.1.4. "jku" (JWK Set URL) Header Parameter 549 This parameter has the same meaning, syntax, and processing rules as 550 the "jku" Header Parameter defined in Section 4.1.2 of [JWS], except 551 that the JWK Set resource contains the public key to which the JWE 552 was encrypted; this can be used to determine the private key needed 553 to decrypt the JWE. 555 4.1.5. "jwk" (JSON Web Key) Header Parameter 557 This parameter has the same meaning, syntax, and processing rules as 558 the "jwk" Header Parameter defined in Section 4.1.3 of [JWS], except 559 that the key is the public key to which the JWE was encrypted; this 560 can be used to determine the private key needed to decrypt the JWE. 562 4.1.6. "kid" (Key ID) Header Parameter 564 This parameter has the same meaning, syntax, and processing rules as 565 the "kid" Header Parameter defined in Section 4.1.4 of [JWS], except 566 that the key hint references the public key to which the JWE was 567 encrypted; this can be used to determine the private key needed to 568 decrypt the JWE. This parameter allows originators to explicitly 569 signal a change of key to JWE recipients. 571 4.1.7. "x5u" (X.509 URL) Header Parameter 573 This parameter has the same meaning, syntax, and processing rules as 574 the "x5u" Header Parameter defined in Section 4.1.5 of [JWS], except 575 that the X.509 public key certificate or certificate chain [RFC5280] 576 contains the public key to which the JWE was encrypted; this can be 577 used to determine the private key needed to decrypt the JWE. 579 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 581 This parameter has the same meaning, syntax, and processing rules as 582 the "x5c" Header Parameter defined in Section 4.1.6 of [JWS], except 583 that the X.509 public key certificate or certificate chain [RFC5280] 584 contains the public key to which the JWE was encrypted; this can be 585 used to determine the private key needed to decrypt the JWE. 587 See Appendix B of [JWS] for an example "x5c" value. 589 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 591 This parameter has the same meaning, syntax, and processing rules as 592 the "x5t" Header Parameter defined in Section 4.1.7 of [JWS], except 593 that the certificate referenced by the thumbprint contains the public 594 key to which the JWE was encrypted; this can be used to determine the 595 private key needed to decrypt the JWE. Note that certificate 596 thumbprints are also sometimes known as certificate fingerprints. 598 4.1.10. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header 599 Parameter 601 This parameter has the same meaning, syntax, and processing rules as 602 the "x5t#S256" Header Parameter defined in Section 4.1.8 of [JWS], 603 except that the certificate referenced by the thumbprint contains the 604 public key to which the JWE was encrypted; this can be used to 605 determine the private key needed to decrypt the JWE. Note that 606 certificate thumbprints are also sometimes known as certificate 607 fingerprints. 609 4.1.11. "typ" (Type) Header Parameter 611 This parameter has the same meaning, syntax, and processing rules as 612 the "typ" Header Parameter defined in Section 4.1.9 of [JWS], except 613 that the type is that of this complete JWE. 615 4.1.12. "cty" (Content Type) Header Parameter 617 This parameter has the same meaning, syntax, and processing rules as 618 the "cty" Header Parameter defined in Section 4.1.10 of [JWS], except 619 that the type is that of the secured content (the plaintext). 621 4.1.13. "crit" (Critical) Header Parameter 623 This parameter has the same meaning, syntax, and processing rules as 624 the "crit" Header Parameter defined in Section 4.1.11 of [JWS], 625 except that Header Parameters for a JWE are being referred to, rather 626 than Header Parameters for a JWS. 628 4.2. Public Header Parameter Names 630 Additional Header Parameter names can be defined by those using JWEs. 631 However, in order to prevent collisions, any new Header Parameter 632 name should either be registered in the IANA JSON Web Signature and 633 Encryption Header Parameters registry defined in [JWS] or be a Public 634 Name: a value that contains a Collision-Resistant Name. In each 635 case, the definer of the name or value needs to take reasonable 636 precautions to make sure they are in control of the part of the 637 namespace they use to define the Header Parameter name. 639 New Header Parameters should be introduced sparingly, as they can 640 result in non-interoperable JWEs. 642 4.3. Private Header Parameter Names 644 A producer and consumer of a JWE may agree to use Header Parameter 645 names that are Private Names: names that are not Registered Header 646 Parameter names Section 4.1 or Public Header Parameter names 647 Section 4.2. Unlike Public Header Parameter names, Private Header 648 Parameter names are subject to collision and should be used with 649 caution. 651 5. Producing and Consuming JWEs 653 5.1. Message Encryption 655 The message encryption process is as follows. The order of the steps 656 is not significant in cases where there are no dependencies between 657 the inputs and outputs of the steps. 659 1. Determine the Key Management Mode employed by the algorithm used 660 to determine the Content Encryption Key (CEK) value. (This is 661 the algorithm recorded in the "alg" (algorithm) Header Parameter 662 of the resulting JWE.) 664 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 665 Wrapping are employed, generate a random Content Encryption Key 666 (CEK) value. See RFC 4086 [RFC4086] for considerations on 667 generating random values. The CEK MUST have a length equal to 668 that required for the content encryption algorithm. 670 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 671 employed, use the key agreement algorithm to compute the value 672 of the agreed upon key. When Direct Key Agreement is employed, 673 let the Content Encryption Key (CEK) be the agreed upon key. 674 When Key Agreement with Key Wrapping is employed, the agreed 675 upon key will be used to wrap the CEK. 677 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 678 Wrapping are employed, encrypt the CEK to the recipient and let 679 the result be the JWE Encrypted Key. 681 5. When Direct Key Agreement or Direct Encryption are employed, let 682 the JWE Encrypted Key be the empty octet sequence. 684 6. When Direct Encryption is employed, let the Content Encryption 685 Key (CEK) be the shared symmetric key. 687 7. Compute the encoded key value BASE64URL(JWE Encrypted Key). 689 8. If the JWE JSON Serialization is being used, repeat this process 690 (steps 1-7) for each recipient. 692 9. Generate a random JWE Initialization Vector of the correct size 693 for the content encryption algorithm (if required for the 694 algorithm); otherwise, let the JWE Initialization Vector be the 695 empty octet sequence. 697 10. Compute the encoded initialization vector value BASE64URL(JWE 698 Initialization Vector). 700 11. If a "zip" parameter was included, compress the Plaintext using 701 the specified compression algorithm and let M be the octet 702 sequence representing the compressed Plaintext; otherwise, let M 703 be the octet sequence representing the Plaintext. 705 12. Create the JSON object(s) containing the desired set of Header 706 Parameters, which together comprise the JOSE Header: if the JWE 707 Compact Serialization is being used, the JWE Protected Header, 708 or if the JWE JSON Serialization is being used, one or more of 709 the JWE Protected Header, the JWE Shared Unprotected Header, and 710 the JWE Per-Recipient Unprotected Header. 712 13. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 713 Protected Header)). If the JWE Protected Header is not present 714 (which can only happen when using the JWE JSON Serialization and 715 no "protected" member is present), let this value be the empty 716 string. 718 14. Let the Additional Authenticated Data encryption parameter be 719 ASCII(Encoded Protected Header). However if a JWE AAD value is 720 present (which can only be the case when using the JWE JSON 721 Serialization), instead let the Additional Authenticated Data 722 encryption parameter be ASCII(Encoded Protected Header || '.' || 723 BASE64URL(JWE AAD)). 725 15. Encrypt M using the CEK, the JWE Initialization Vector, and the 726 Additional Authenticated Data value using the specified content 727 encryption algorithm to create the JWE Ciphertext value and the 728 JWE Authentication Tag (which is the Authentication Tag output 729 from the encryption operation). 731 16. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext). 733 17. Compute the encoded authentication tag value BASE64URL(JWE 734 Authentication Tag). 736 18. If a JWE AAD value is present, compute the encoded AAD value 737 BASE64URL(JWE AAD). 739 19. Create the desired serialized output. The Compact Serialization 740 of this result is the string BASE64URL(UTF8(JWE Protected 741 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 742 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 743 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). The 744 JWE JSON Serialization is described in Section 7.2. 746 5.2. Message Decryption 748 The message decryption process is the reverse of the encryption 749 process. The order of the steps is not significant in cases where 750 there are no dependencies between the inputs and outputs of the 751 steps. If any of these steps fails, the encrypted content cannot be 752 validated. 754 When there are multiple recipients, it is an application decision 755 which of the recipients' encrypted content must successfully validate 756 for the JWE to be accepted. In some cases, encrypted content for all 757 recipients must successfully validate or the JWE will be considered 758 invalid. In other cases, only the encrypted content for a single 759 recipient needs to be successfully validated. However, in all cases, 760 the encrypted content for at least one recipient MUST successfully 761 validate or the JWE MUST be considered invalid. 763 1. Parse the JWE representation to extract the serialized values 764 for the components of the JWE. When using the JWE Compact 765 Serialization, these components are the base64url encoded 766 representations of the JWE Protected Header, the JWE Encrypted 767 Key, the JWE Initialization Vector, the JWE Ciphertext, and the 768 JWE Authentication Tag, and when using the JWE JSON 769 Serialization, these components also include the base64url 770 encoded representation of the JWE AAD and the unencoded JWE 771 Shared Unprotected Header and JWE Per-Recipient Unprotected 772 Header values. When using the JWE Compact Serialization, the 773 JWE Protected Header, the JWE Encrypted Key, the JWE 774 Initialization Vector, the JWE Ciphertext, and the JWE 775 Authentication Tag are represented as base64url encoded values 776 in that order, with each value being separated from the next by 777 a single period ('.') character, resulting in exactly four 778 delimiting period characters being used. The JWE JSON 779 Serialization is described in Section 7.2. 781 2. Base64url decode the encoded representations of the JWE 782 Protected Header, the JWE Encrypted Key, the JWE Initialization 783 Vector, the JWE Ciphertext, the JWE Authentication Tag, and the 784 JWE AAD, following the restriction that no line breaks, white 785 space, or other additional characters have been used. 787 3. Verify that the octet sequence resulting from decoding the 788 encoded JWE Protected Header is a UTF-8 encoded representation 789 of a completely valid JSON object conforming to RFC 7159 790 [RFC7159]; let the JWE Protected Header be this JSON object. 792 4. If using the JWE Compact Serialization, let the JOSE Header be 793 the JWE Protected Header. Otherwise, when using the JWE JSON 794 Serialization, let the JOSE Header be the union of the members 795 of the JWE Protected Header, the JWE Shared Unprotected Header 796 and the corresponding JWE Per-Recipient Unprotected Header, all 797 of which must be completely valid JSON objects. During this 798 step, verify that the resulting JOSE Header does not contain 799 duplicate Header Parameter names. When using the JWE JSON 800 Serialization, this restriction includes that the same Header 801 Parameter name also MUST NOT occur in distinct JSON object 802 values that together comprise the JOSE Header. 804 5. Verify that the implementation understands and can process all 805 fields that it is required to support, whether required by this 806 specification, by the algorithms being used, or by the "crit" 807 Header Parameter value, and that the values of those parameters 808 are also understood and supported. 810 6. Determine the Key Management Mode employed by the algorithm 811 specified by the "alg" (algorithm) Header Parameter. 813 7. Verify that the JWE uses a key known to the recipient. 815 8. When Direct Key Agreement or Key Agreement with Key Wrapping are 816 employed, use the key agreement algorithm to compute the value 817 of the agreed upon key. When Direct Key Agreement is employed, 818 let the Content Encryption Key (CEK) be the agreed upon key. 819 When Key Agreement with Key Wrapping is employed, the agreed 820 upon key will be used to decrypt the JWE Encrypted Key. 822 9. When Key Wrapping, Key Encryption, or Key Agreement with Key 823 Wrapping are employed, decrypt the JWE Encrypted Key to produce 824 the Content Encryption Key (CEK). The CEK MUST have a length 825 equal to that required for the content encryption algorithm. 826 Note that when there are multiple recipients, each recipient 827 will only be able decrypt any JWE Encrypted Key values that were 828 encrypted to a key in that recipient's possession. It is 829 therefore normal to only be able to decrypt one of the per- 830 recipient JWE Encrypted Key values to obtain the CEK value. 831 Also, see Section 11.5 for security considerations on mitigating 832 timing attacks. 834 10. When Direct Key Agreement or Direct Encryption are employed, 835 verify that the JWE Encrypted Key value is empty octet sequence. 837 11. When Direct Encryption is employed, let the Content Encryption 838 Key (CEK) be the shared symmetric key. 840 12. Record whether the CEK could be successfully determined for this 841 recipient or not. 843 13. If the JWE JSON Serialization is being used, repeat this process 844 (steps 4-12) for each recipient contained in the representation. 846 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 847 Protected Header)). If the JWE Protected Header is not present 848 (which can only happen when using the JWE JSON Serialization and 849 no "protected" member is present), let this value be the empty 850 string. 852 15. Let the Additional Authenticated Data encryption parameter be 853 ASCII(Encoded Protected Header). However if a JWE AAD value is 854 present (which can only be the case when using the JWE JSON 855 Serialization), instead let the Additional Authenticated Data 856 encryption parameter be ASCII(Encoded Protected Header || '.' || 857 BASE64URL(JWE AAD)). 859 16. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 860 Vector, the Additional Authenticated Data value, and the JWE 861 Authentication Tag (which is the Authentication Tag input to the 862 calculation) using the specified content encryption algorithm, 863 returning the decrypted plaintext and validating the JWE 864 Authentication Tag in the manner specified for the algorithm, 865 rejecting the input without emitting any decrypted output if the 866 JWE Authentication Tag is incorrect. 868 17. If a "zip" parameter was included, uncompress the decrypted 869 plaintext using the specified compression algorithm. 871 18. If there was no recipient for which all of the decryption steps 872 succeeded, then the JWE MUST be considered invalid. Otherwise, 873 output the Plaintext. In the JWE JSON Serialization case, also 874 return a result to the application indicating for which of the 875 recipients the decryption succeeded and failed. 877 Finally, note that it is an application decision which algorithms may 878 be used in a given context. Even if a JWE can be successfully 879 decrypted, unless the algorithms used in the JWE are acceptable to 880 the application, it SHOULD consider the JWE to be invalid. 882 5.3. String Comparison Rules 884 The string comparison rules for this specification are the same as 885 those defined in Section 5.3 of [JWS]. 887 6. Key Identification 889 The key identification methods for this specification are the same as 890 those defined in Section 6 of [JWS], except that the key being 891 identified is the public key to which the JWE was encrypted. 893 7. Serializations 895 JWEs use one of two serializations: the JWE Compact Serialization or 896 the JWE JSON Serialization. Applications using this specification 897 need to specify what serialization and serialization features are 898 used for that application. For instance, applications might specify 899 that only the JWE JSON Serialization is used, that only JWE JSON 900 Serialization support for a single recipient is used, or that support 901 for multiple recipients is used. JWE implementations only need to 902 implement the features needed for the applications they are designed 903 to support. 905 7.1. JWE Compact Serialization 907 The JWE Compact Serialization represents encrypted content as a 908 compact, URL-safe string. This string is: 910 BASE64URL(UTF8(JWE Protected Header)) || '.' || 911 BASE64URL(JWE Encrypted Key) || '.' || 912 BASE64URL(JWE Initialization Vector) || '.' || 913 BASE64URL(JWE Ciphertext) || '.' || 914 BASE64URL(JWE Authentication Tag) 916 Only one recipient is supported by the JWE Compact Serialization and 917 it provides no syntax to represent JWE Shared Unprotected Header, JWE 918 Per-Recipient Unprotected Header, or JWE AAD values. 920 7.2. JWE JSON Serialization 922 The JWE JSON Serialization represents encrypted content as a JSON 923 object. This representation is neither optimized for compactness nor 924 URL-safe. 926 Two closely related syntaxes are defined for the JWE JSON 927 Serialization: a fully general syntax, with which content can be 928 encrypted to more than one recipient, and a flattened syntax, which 929 is optimized for the single recipient case. 931 7.2.1. General JWE JSON Serialization Syntax 933 The following members are defined for use in top-level JSON objects 934 used for the fully general JWE JSON Serialization syntax: 936 protected 937 The "protected" member MUST be present and contain the value 938 BASE64URL(UTF8(JWE Protected Header)) when the JWE Protected 939 Header value is non-empty; otherwise, it MUST be absent. These 940 Header Parameter values are integrity protected. 942 unprotected 943 The "unprotected" member MUST be present and contain the value JWE 944 Shared Unprotected Header when the JWE Shared Unprotected Header 945 value is non-empty; otherwise, it MUST be absent. This value is 946 represented as an unencoded JSON object, rather than as a string. 947 These Header Parameter values are not integrity protected. 949 iv 950 The "iv" member MUST be present and contain the value 951 BASE64URL(JWE Initialization Vector) when the JWE Initialization 952 Vector value is non-empty; otherwise, it MUST be absent. 954 aad 955 The "aad" member MUST be present and contain the value 956 BASE64URL(JWE AAD)) when the JWE AAD value is non-empty; 957 otherwise, it MUST be absent. A JWE AAD value can be included to 958 supply a base64url encoded value to be integrity protected but not 959 encrypted. 961 ciphertext 962 The "ciphertext" member MUST be present and contain the value 963 BASE64URL(JWE Ciphertext). 965 tag 966 The "tag" member MUST be present and contain the value 967 BASE64URL(JWE Authentication Tag) when the JWE Authentication Tag 968 value is non-empty; otherwise, it MUST be absent. 970 recipients 971 The "recipients" member value MUST be an array of JSON objects. 972 Each object contains information specific to a single recipient. 973 This member MUST be present with exactly one array element per 974 recipient, even if some or all of the array element values are the 975 empty JSON object "{}" (which can happen when all Header Parameter 976 values are shared between all recipients and when no encrypted key 977 is used, such as when doing Direct Encryption). 979 The following members are defined for use in the JSON objects that 980 are elements of the "recipients" array: 982 header 983 The "header" member MUST be present and contain the value JWE Per- 984 Recipient Unprotected Header when the JWE Per-Recipient 985 Unprotected Header value is non-empty; otherwise, it MUST be 986 absent. This value is represented as an unencoded JSON object, 987 rather than as a string. These Header Parameter values are not 988 integrity protected. 990 encrypted_key 991 The "encrypted_key" member MUST be present and contain the value 992 BASE64URL(JWE Encrypted Key) when the JWE Encrypted Key value is 993 non-empty; otherwise, it MUST be absent. 995 At least one of the "header", "protected", and "unprotected" members 996 MUST be present so that "alg" and "enc" Header Parameter values are 997 conveyed for each recipient computation. 999 Additional members can be present in both the JSON objects defined 1000 above; if not understood by implementations encountering them, they 1001 MUST be ignored. 1003 Some Header Parameters, including the "alg" parameter, can be shared 1004 among all recipient computations. Header Parameters in the JWE 1005 Protected Header and JWE Shared Unprotected Header values are shared 1006 among all recipients. 1008 The Header Parameter values used when creating or validating per- 1009 recipient Ciphertext and Authentication Tag values are the union of 1010 the three sets of Header Parameter values that may be present: (1) 1011 the JWE Protected Header represented in the "protected" member, (2) 1012 the JWE Shared Unprotected Header represented in the "unprotected" 1013 member, and (3) the JWE Per-Recipient Unprotected Header represented 1014 in the "header" member of the recipient's array element. The union 1015 of these sets of Header Parameters comprises the JOSE Header. The 1016 Header Parameter names in the three locations MUST be disjoint. 1018 Each JWE Encrypted Key value is computed using the parameters of the 1019 corresponding JOSE Header value in the same manner as for the JWE 1020 Compact Serialization. This has the desirable property that each JWE 1021 Encrypted Key value in the "recipients" array is identical to the 1022 value that would have been computed for the same parameter in the JWE 1023 Compact Serialization. Likewise, the JWE Ciphertext and JWE 1024 Authentication Tag values match those produced for the JWE Compact 1025 Serialization, provided that the JWE Protected Header value (which 1026 represents the integrity protected Header Parameter values) matches 1027 that used in the JWE Compact Serialization. 1029 All recipients use the same JWE Protected Header, JWE Initialization 1030 Vector, JWE Ciphertext, and JWE Authentication Tag values, when 1031 present, resulting in potentially significant space savings if the 1032 message is large. Therefore, all Header Parameters that specify the 1033 treatment of the Plaintext value MUST be the same for all recipients. 1034 This primarily means that the "enc" (encryption algorithm) Header 1035 Parameter value in the JOSE Header for each recipient and any 1036 parameters of that algorithm MUST be the same. 1038 In summary, the syntax of a JWE using the general JWE JSON 1039 Serialization is as follows: 1041 { 1042 "protected":"", 1043 "unprotected":, 1044 "recipients":[ 1045 {"header":, 1046 "encrypted_key":""}, 1047 ... 1048 {"header":, 1049 "encrypted_key":""}], 1050 "aad":"", 1051 "iv":"", 1052 "ciphertext":"", 1053 "tag":"" 1054 } 1056 See Appendix A.4 for an example JWE using the general JWE JSON 1057 Serialization syntax. 1059 7.2.2. Flattened JWE JSON Serialization Syntax 1061 The flattened JWE JSON Serialization syntax is based upon the general 1062 syntax, but flattens it, optimizing it for the single recipient case. 1063 It flattens it by removing the "recipients" member and instead 1064 placing those members defined for use in the "recipients" array (the 1065 "header" and "encrypted_key" members) in the top-level JSON object 1066 (at the same level as the "ciphertext" member). 1068 The "recipients" member MUST NOT be present when using this syntax. 1069 Other than this syntax difference, JWE JSON Serialization objects 1070 using the flattened syntax are processed identically to those using 1071 the general syntax. 1073 In summary, the syntax of a JWE using the flattened JWE JSON 1074 Serialization is as follows: 1076 { 1077 "protected":"", 1078 "unprotected":, 1079 "header":, 1080 "encrypted_key":"", 1081 "aad":"", 1082 "iv":"", 1083 "ciphertext":"", 1084 "tag":"" 1085 } 1087 Note that when using the flattened syntax, just as when using the 1088 general syntax, any unprotected Header Parameter values can reside in 1089 either the "unprotected" member or the "header" member, or in both. 1091 See Appendix A.5 for an example JWE using the flattened JWE JSON 1092 Serialization syntax. 1094 8. TLS Requirements 1096 The TLS requirements for this specification are the same as those 1097 defined in Section 8 of [JWS]. 1099 9. Distinguishing between JWS and JWE Objects 1101 There are several ways of distinguishing whether an object is a JWS 1102 or JWE. All these methods will yield the same result for all legal 1103 input values; they may yield different results for malformed inputs. 1105 o If the object is using the JWS Compact Serialization or the JWE 1106 Compact Serialization, the number of base64url encoded segments 1107 separated by period ('.') characters differs for JWSs and JWEs. 1108 JWSs have three segments separated by two period ('.') characters. 1109 JWEs have five segments separated by four period ('.') characters. 1111 o If the object is using the JWS JSON Serialization or the JWE JSON 1112 Serialization, the members used will be different. JWSs have a 1113 "payload" member and JWEs do not. JWEs have a "ciphertext" member 1114 and JWSs do not. 1116 o The JOSE Header for a JWS can be distinguished from the JOSE 1117 Header for a JWE by examining the "alg" (algorithm) Header 1118 Parameter value. If the value represents a digital signature or 1119 MAC algorithm, or is the value "none", it is for a JWS; if it 1120 represents a Key Encryption, Key Wrapping, Direct Key Agreement, 1121 Key Agreement with Key Wrapping, or Direct Encryption algorithm, 1122 it is for a JWE. (Extracting the "alg" value to examine is 1123 straightforward when using the JWS Compact Serialization or the 1124 JWE Compact Serialization and may be more difficult when using the 1125 JWS JSON Serialization or the JWE JSON Serialization.) 1127 o The JOSE Header for a JWS can also be distinguished from the JOSE 1128 Header for a JWE by determining whether an "enc" (encryption 1129 algorithm) member exists. If the "enc" member exists, it is a 1130 JWE; otherwise, it is a JWS. 1132 10. IANA Considerations 1134 10.1. JSON Web Signature and Encryption Header Parameters Registration 1136 This specification registers the Header Parameter names defined in 1137 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1138 Parameters registry defined in [JWS]. 1140 10.1.1. Registry Contents 1142 o Header Parameter Name: "alg" 1143 o Header Parameter Description: Algorithm 1144 o Header Parameter Usage Location(s): JWE 1145 o Change Controller: IESG 1146 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1148 o Header Parameter Name: "enc" 1149 o Header Parameter Description: Encryption Algorithm 1150 o Header Parameter Usage Location(s): JWE 1151 o Change Controller: IESG 1152 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1154 o Header Parameter Name: "zip" 1155 o Header Parameter Description: Compression Algorithm 1156 o Header Parameter Usage Location(s): JWE 1157 o Change Controller: IESG 1158 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1160 o Header Parameter Name: "jku" 1161 o Header Parameter Description: JWK Set URL 1162 o Header Parameter Usage Location(s): JWE 1163 o Change Controller: IESG 1164 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1166 o Header Parameter Name: "jwk" 1167 o Header Parameter Description: JSON Web Key 1168 o Header Parameter Usage Location(s): JWE 1169 o Change Controller: IESG 1170 o Specification document(s): Section 4.1.5 of [[ this document ]] 1172 o Header Parameter Name: "kid" 1173 o Header Parameter Description: Key ID 1174 o Header Parameter Usage Location(s): JWE 1175 o Change Controller: IESG 1176 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1178 o Header Parameter Name: "x5u" 1179 o Header Parameter Description: X.509 URL 1180 o Header Parameter Usage Location(s): JWE 1181 o Change Controller: IESG 1182 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1184 o Header Parameter Name: "x5c" 1185 o Header Parameter Description: X.509 Certificate Chain 1186 o Header Parameter Usage Location(s): JWE 1187 o Change Controller: IESG 1188 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1190 o Header Parameter Name: "x5t" 1191 o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint 1192 o Header Parameter Usage Location(s): JWE 1193 o Change Controller: IESG 1194 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1195 o Header Parameter Name: "x5t#S256" 1196 o Header Parameter Description: X.509 Certificate SHA-256 Thumbprint 1197 o Header Parameter Usage Location(s): JWE 1198 o Change Controller: IESG 1199 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1201 o Header Parameter Name: "typ" 1202 o Header Parameter Description: Type 1203 o Header Parameter Usage Location(s): JWE 1204 o Change Controller: IESG 1205 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1207 o Header Parameter Name: "cty" 1208 o Header Parameter Description: Content Type 1209 o Header Parameter Usage Location(s): JWE 1210 o Change Controller: IESG 1211 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1213 o Header Parameter Name: "crit" 1214 o Header Parameter Description: Critical 1215 o Header Parameter Usage Location(s): JWE 1216 o Change Controller: IESG 1217 o Specification Document(s): Section 4.1.13 of [[ this document ]] 1219 11. Security Considerations 1221 All of the security issues that are pertinent to any cryptographic 1222 application must be addressed by JWS/JWE/JWK agents. Among these 1223 issues are protecting the user's asymmetric private and symmetric 1224 secret keys and employing countermeasures to various attacks. 1226 All the security considerations in the JWS specification also apply 1227 to this specification. Likewise, all the security considerations in 1228 XML Encryption 1.1 [W3C.REC-xmlenc-core1-20130411] also apply, other 1229 than those that are XML specific. 1231 11.1. Key Entropy and Random Values 1233 See Section 10.1 of [JWS] for security considerations on key entropy 1234 and random values. In addition to the uses of random values listed 1235 there, note that random values are also used for content encryption 1236 keys (CEKs) and initialization vectors (IVs) when performing 1237 encryption. 1239 11.2. Key Protection 1241 See Section 10.2 of [JWS] for security considerations on key 1242 protection. In addition to the keys listed there that must be 1243 protected, implementations performing encryption must protect the key 1244 encryption key and the content encryption key. Compromise of the key 1245 encryption key may result in the disclosure of all contents protected 1246 with that key. Similarly, compromise of the content encryption key 1247 may result in disclosure of the associated encrypted content. 1249 11.3. Using Matching Algorithm Strengths 1251 Algorithms of matching strengths should be used together whenever 1252 possible. For instance, when AES Key Wrap is used with a given key 1253 size, using the same key size is recommended when AES GCM is also 1254 used. If the key encryption and content encryption algorithms are 1255 different, the effective security is determined by the weaker of the 1256 two algorithms. 1258 Also, see RFC 3766 [RFC3766] for information on determining strengths 1259 for public keys used for exchanging symmetric keys. 1261 11.4. Adaptive Chosen-Ciphertext Attacks 1263 When decrypting, particular care must be taken not to allow the JWE 1264 recipient to be used as an oracle for decrypting messages. RFC 3218 1265 [RFC3218] should be consulted for specific countermeasures to attacks 1266 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1267 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1268 formatting error that can be detected and used to recover the CEK 1269 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1270 particularly important to report all formatting errors to the CEK, 1271 Additional Authenticated Data, or ciphertext as a single error when 1272 the encrypted content is rejected. 1274 Additionally, this type of attack can be prevented by restricting the 1275 use of a key to a limited set of algorithms -- usually one. This 1276 means, for instance, that if the key is marked as being for 1277 "RSA-OAEP" only, any attempt to decrypt a message using the "RSA1_5" 1278 algorithm with that key should fail immediately due to invalid use of 1279 the key. 1281 11.5. Timing Attacks 1283 To mitigate the attacks described in RFC 3218 [RFC3218], the 1284 recipient MUST NOT distinguish between format, padding, and length 1285 errors of encrypted keys. It is strongly recommended, in the event 1286 of receiving an improperly formatted key, that the recipient 1287 substitute a randomly generated CEK and proceed to the next step, to 1288 mitigate timing attacks. 1290 12. References 1292 12.1. Normative References 1294 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1295 draft-ietf-jose-json-web-algorithms (work in progress), 1296 December 2014. 1298 [JWK] Jones, M., "JSON Web Key (JWK)", 1299 draft-ietf-jose-json-web-key (work in progress), 1300 December 2014. 1302 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1303 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1304 in progress), December 2014. 1306 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1307 version 1.3", RFC 1951, May 1996. 1309 [RFC20] Cerf, V., "ASCII format for Network Interchange", RFC 20, 1310 October 1969. 1312 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1313 Requirement Levels", BCP 14, RFC 2119, March 1997. 1315 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1316 10646", STD 63, RFC 3629, November 2003. 1318 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1319 RFC 4949, August 2007. 1321 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1322 Housley, R., and W. Polk, "Internet X.509 Public Key 1323 Infrastructure Certificate and Certificate Revocation List 1324 (CRL) Profile", RFC 5280, May 2008. 1326 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1327 Interchange Format", RFC 7159, March 2014. 1329 12.2. Informative References 1331 [AES] National Institute of Standards and Technology (NIST), 1332 "Advanced Encryption Standard (AES)", FIPS PUB 197, 1333 November 2001. 1335 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1336 McGrew, D., Foley, J., and K. Paterson, "Authenticated 1337 Encryption with AES-CBC and HMAC-SHA", 1338 draft-mcgrew-aead-aes-cbc-hmac-sha2-05 (work in progress), 1339 July 2014. 1341 [I-D.rescorla-jsms] 1342 Rescorla, E. and J. Hildebrand, "JavaScript Message 1343 Security Format", draft-rescorla-jsms-00 (work in 1344 progress), March 2011. 1346 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1347 Encryption", September 2010. 1349 [NIST.800-38D] 1350 National Institute of Standards and Technology (NIST), 1351 "Recommendation for Block Cipher Modes of Operation: 1352 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 1353 December 2001. 1355 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1356 Cryptographic Message Syntax", RFC 3218, January 2002. 1358 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1359 Standards (PKCS) #1: RSA Cryptography Specifications 1360 Version 2.1", RFC 3447, February 2003. 1362 [RFC3766] Orman, H. and P. Hoffman, "Determining Strengths For 1363 Public Keys Used For Exchanging Symmetric Keys", BCP 86, 1364 RFC 3766, April 2004. 1366 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1367 Requirements for Security", BCP 106, RFC 4086, June 2005. 1369 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1370 RFC 5652, September 2009. 1372 [W3C.REC-xmlenc-core1-20130411] 1373 Eastlake, D., Reagle, J., Hirsch, F., and T. Roessler, 1374 "XML Encryption Syntax and Processing Version 1.1", World 1375 Wide Web Consortium Recommendation REC-xmlenc-core1- 1376 20130411, April 2013, 1377 . 1379 Appendix A. JWE Examples 1381 This section provides examples of JWE computations. 1383 A.1. Example JWE using RSAES OAEP and AES GCM 1385 This example encrypts the plaintext "The true sign of intelligence is 1386 not knowledge but imagination." to the recipient using RSAES OAEP for 1387 key encryption and AES GCM for content encryption. The 1388 representation of this plaintext (using JSON array notation) is: 1390 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1391 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1392 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1393 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1394 110, 97, 116, 105, 111, 110, 46] 1396 A.1.1. JOSE Header 1398 The following example JWE Protected Header declares that: 1400 o The Content Encryption Key is encrypted to the recipient using the 1401 RSAES OAEP algorithm to produce the JWE Encrypted Key. 1403 o Authenticated encryption is performed on the Plaintext using the 1404 AES GCM algorithm with a 256 bit key to produce the Ciphertext and 1405 the Authentication Tag. 1407 {"alg":"RSA-OAEP","enc":"A256GCM"} 1409 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1410 Header)) gives this value: 1412 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1414 A.1.2. Content Encryption Key (CEK) 1416 Generate a 256 bit random Content Encryption Key (CEK). In this 1417 example, the value (using JSON array notation) is: 1419 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1420 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1421 234, 64, 252] 1423 A.1.3. Key Encryption 1425 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1426 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1427 key represented in JSON Web Key [JWK] format below (with line breaks 1428 within values for display purposes only): 1430 {"kty":"RSA", 1431 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1432 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1433 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1434 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1435 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1436 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1437 "e":"AQAB", 1438 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1439 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1440 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1441 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1442 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1443 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ", 1444 "p":"1r52Xk46c-LsfB5P442p7atdPUrxQSy4mti_tZI3Mgf2EuFVbUoDBvaRQ- 1445 SWxkbkmoEzL7JXroSBjSrK3YIQgYdMgyAEPTPjXv_hI2_1eTSPVZfzL0lf 1446 fNn03IXqWF5MDFuoUYE0hzb2vhrlN_rKrbfDIwUbTrjjgieRbwC6Cl0", 1447 "q":"wLb35x7hmQWZsWJmB_vle87ihgZ19S8lBEROLIsZG4ayZVe9Hi9gDVCOBm 1448 UDdaDYVTSNx_8Fyw1YYa9XGrGnDew00J28cRUoeBB_jKI1oma0Orv1T9aX 1449 IWxKwd4gvxFImOWr3QRL9KEBRzk2RatUBnmDZJTIAfwTs0g68UZHvtc", 1450 "dp":"ZK-YwE7diUh0qR1tR7w8WHtolDx3MZ_OTowiFvgfeQ3SiresXjm9gZ5KL 1451 hMXvo-uz-KUJWDxS5pFQ_M0evdo1dKiRTjVw_x4NyqyXPM5nULPkcpU827 1452 rnpZzAJKpdhWAgqrXGKAECQH0Xt4taznjnd_zVpAmZZq60WPMBMfKcuE", 1453 "dq":"Dq0gfgJ1DdFGXiLvQEZnuKEN0UUmsJBxkjydc3j4ZYdBiMRAy86x0vHCj 1454 ywcMlYYg4yoC4YZa9hNVcsjqA3FeiL19rk8g6Qn29Tt0cj8qqyFpz9vNDB 1455 UfCAiJVeESOjJDZPYHdHY8v1b-o-Z2X5tvLx-TCekf7oxyeKDUqKWjis", 1456 "qi":"VIMpMYbPf47dT1w_zDUXfPimsSegnMOA1zTaX7aGk_8urY6R8-ZW1FxU7 1457 AlWAyLWybqq6t16VFd7hQd0y6flUK4SlOydB61gwanOsXGOAOv82cHq0E3 1458 eL4HrtZkUuKvnPrMnsUUFlfUdybVzxyjz9JF_XyaY14ardLSjf4L_FNY" 1459 } 1461 The resulting JWE Encrypted Key value is: 1463 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1464 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1465 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1466 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1467 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1468 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1469 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1470 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1471 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1472 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1473 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1474 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1475 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1476 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1477 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1478 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1479 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1480 117, 114, 135, 206] 1482 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1483 this value (with line breaks for display purposes only): 1485 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1486 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1487 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1488 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1489 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1490 6UklfCpIMfIjf7iGdXKHzg 1492 A.1.4. Initialization Vector 1494 Generate a random 96 bit JWE Initialization Vector. In this example, 1495 the value is: 1497 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1499 Encoding this JWE Initialization Vector as BASE64URL(JWE 1500 Initialization Vector) gives this value: 1502 48V1_ALb6US04U3b 1504 A.1.5. Additional Authenticated Data 1506 Let the Additional Authenticated Data encryption parameter be 1507 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1509 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1510 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1511 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1513 A.1.6. Content Encryption 1515 Perform authenticated encryption on the Plaintext with the AES GCM 1516 algorithm using the CEK as the encryption key, the JWE Initialization 1517 Vector, and the Additional Authenticated Data value above, requesting 1518 a 128 bit Authentication Tag output. The resulting Ciphertext is: 1520 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1521 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1522 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1523 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1524 160, 109, 64, 63, 192] 1525 The resulting Authentication Tag value is: 1527 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1528 210, 145] 1530 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1531 value (with line breaks for display purposes only): 1533 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1534 SdiwkIr3ajwQzaBtQD_A 1536 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1537 Tag) gives this value: 1539 XFBoMYUZodetZdvTiFvSkQ 1541 A.1.7. Complete Representation 1543 Assemble the final representation: The Compact Serialization of this 1544 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1545 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1546 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1547 Authentication Tag). 1549 The final result in this example (with line breaks for display 1550 purposes only) is: 1552 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1553 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1554 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1555 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1556 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1557 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1558 6UklfCpIMfIjf7iGdXKHzg. 1559 48V1_ALb6US04U3b. 1560 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1561 SdiwkIr3ajwQzaBtQD_A. 1562 XFBoMYUZodetZdvTiFvSkQ 1564 A.1.8. Validation 1566 This example illustrates the process of creating a JWE with RSAES 1567 OAEP for key encryption and AES GCM for content encryption. These 1568 results can be used to validate JWE decryption implementations for 1569 these algorithms. Note that since the RSAES OAEP computation 1570 includes random values, the encryption results above will not be 1571 completely reproducible. However, since the AES GCM computation is 1572 deterministic, the JWE Encrypted Ciphertext values will be the same 1573 for all encryptions performed using these inputs. 1575 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1577 This example encrypts the plaintext "Live long and prosper." to the 1578 recipient using RSAES-PKCS1-V1_5 for key encryption and 1579 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1580 of this plaintext (using JSON array notation) is: 1582 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1583 112, 114, 111, 115, 112, 101, 114, 46] 1585 A.2.1. JOSE Header 1587 The following example JWE Protected Header declares that: 1589 o The Content Encryption Key is encrypted to the recipient using the 1590 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. 1592 o Authenticated encryption is performed on the Plaintext using the 1593 AES_128_CBC_HMAC_SHA_256 algorithm to produce the Ciphertext and 1594 the Authentication Tag. 1596 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1598 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1599 Header)) gives this value: 1601 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1603 A.2.2. Content Encryption Key (CEK) 1605 Generate a 256 bit random Content Encryption Key (CEK). In this 1606 example, the key value is: 1608 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1609 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1610 44, 207] 1612 A.2.3. Key Encryption 1614 Encrypt the CEK with the recipient's public key using the RSAES- 1615 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1616 uses the RSA key represented in JSON Web Key [JWK] format below (with 1617 line breaks within values for display purposes only): 1619 {"kty":"RSA", 1620 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1621 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1622 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1623 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1624 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1625 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1626 "e":"AQAB", 1627 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1628 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1629 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1630 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1631 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1632 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ", 1633 "p":"9gY2w6I6S6L0juEKsbeDAwpd9WMfgqFoeA9vEyEUuk4kLwBKcoe1x4HG68 1634 ik918hdDSE9vDQSccA3xXHOAFOPJ8R9EeIAbTi1VwBYnbTp87X-xcPWlEP 1635 krdoUKW60tgs1aNd_Nnc9LEVVPMS390zbFxt8TN_biaBgelNgbC95sM", 1636 "q":"uKlCKvKv_ZJMVcdIs5vVSU_6cPtYI1ljWytExV_skstvRSNi9r66jdd9-y 1637 BhVfuG4shsp2j7rGnIio901RBeHo6TPKWVVykPu1iYhQXw1jIABfw-MVsN 1638 -3bQ76WLdt2SDxsHs7q7zPyUyHXmps7ycZ5c72wGkUwNOjYelmkiNS0", 1639 "dp":"w0kZbV63cVRvVX6yk3C8cMxo2qCM4Y8nsq1lmMSYhG4EcL6FWbX5h9yuv 1640 ngs4iLEFk6eALoUS4vIWEwcL4txw9LsWH_zKI-hwoReoP77cOdSL4AVcra 1641 Hawlkpyd2TWjE5evgbhWtOxnZee3cXJBkAi64Ik6jZxbvk-RR3pEhnCs", 1642 "dq":"o_8V14SezckO6CNLKs_btPdFiO9_kC1DsuUTd2LAfIIVeMZ7jn1Gus_Ff 1643 7B7IVx3p5KuBGOVF8L-qifLb6nQnLysgHDh132NDioZkhH7mI7hPG-PYE_ 1644 odApKdnqECHWw0J-F0JWnUd6D2B_1TvF9mXA2Qx-iGYn8OVV1Bsmp6qU", 1645 "qi":"eNho5yRBEBxhGBtQRww9QirZsB66TrfFReG_CcteI1aCneT0ELGhYlRlC 1646 tUkTRclIfuEPmNsNDPbLoLqqCVznFbvdB7x-Tl-m0l_eFTj2KiqwGqE9PZ 1647 B9nNTwMVvH3VRRSLWACvPnSiwP8N5Usy-WRXS-V7TbpxIhvepTfE0NNo" 1648 } 1650 The resulting JWE Encrypted Key value is: 1652 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1653 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1654 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1655 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1656 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1657 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1658 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1659 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1660 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1661 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1662 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1663 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1664 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1665 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1666 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1667 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1668 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1669 146, 114, 165, 204, 71, 136, 41, 252] 1671 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1672 this value (with line breaks for display purposes only): 1674 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1675 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1676 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1677 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1678 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1679 -B3oWh2TbqmScqXMR4gp_A 1681 A.2.4. Initialization Vector 1683 Generate a random 128 bit JWE Initialization Vector. In this 1684 example, the value is: 1686 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1687 101] 1689 Encoding this JWE Initialization Vector as BASE64URL(JWE 1690 Initialization Vector) gives this value: 1692 AxY8DCtDaGlsbGljb3RoZQ 1694 A.2.5. Additional Authenticated Data 1696 Let the Additional Authenticated Data encryption parameter be 1697 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1699 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1700 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1701 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1702 50, 73, 110, 48] 1704 A.2.6. Content Encryption 1706 Perform authenticated encryption on the Plaintext with the 1707 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1708 key, the JWE Initialization Vector, and the Additional Authenticated 1709 Data value above. The steps for doing this using the values from 1710 Appendix A.3 are detailed in Appendix B. The resulting Ciphertext 1711 is: 1713 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1714 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1715 112, 56, 102] 1717 The resulting Authentication Tag value is: 1719 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1720 191] 1722 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1723 value: 1725 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1727 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1728 Tag) gives this value: 1730 9hH0vgRfYgPnAHOd8stkvw 1732 A.2.7. Complete Representation 1734 Assemble the final representation: The Compact Serialization of this 1735 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1736 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1737 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1738 Authentication Tag). 1740 The final result in this example (with line breaks for display 1741 purposes only) is: 1743 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1744 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1745 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1746 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1747 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1748 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1749 -B3oWh2TbqmScqXMR4gp_A. 1750 AxY8DCtDaGlsbGljb3RoZQ. 1751 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1752 9hH0vgRfYgPnAHOd8stkvw 1754 A.2.8. Validation 1756 This example illustrates the process of creating a JWE with RSAES- 1757 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1758 encryption. These results can be used to validate JWE decryption 1759 implementations for these algorithms. Note that since the RSAES- 1760 PKCS1-V1_5 computation includes random values, the encryption results 1761 above will not be completely reproducible. However, since the AES 1762 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1763 will be the same for all encryptions performed using these inputs. 1765 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1767 This example encrypts the plaintext "Live long and prosper." to the 1768 recipient using AES Key Wrap for key encryption and 1769 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1770 of this plaintext (using JSON array notation) is: 1772 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1773 112, 114, 111, 115, 112, 101, 114, 46] 1775 A.3.1. JOSE Header 1777 The following example JWE Protected Header declares that: 1779 o The Content Encryption Key is encrypted to the recipient using the 1780 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1781 Encrypted Key. 1783 o Authenticated encryption is performed on the Plaintext using the 1784 AES_128_CBC_HMAC_SHA_256 algorithm to produce the Ciphertext and 1785 the Authentication Tag. 1787 {"alg":"A128KW","enc":"A128CBC-HS256"} 1789 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1790 Header)) gives this value: 1792 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1794 A.3.2. Content Encryption Key (CEK) 1796 Generate a 256 bit random Content Encryption Key (CEK). In this 1797 example, the value is: 1799 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1800 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1801 44, 207] 1803 A.3.3. Key Encryption 1805 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1806 algorithm to produce the JWE Encrypted Key. This example uses the 1807 symmetric key represented in JSON Web Key [JWK] format below: 1809 {"kty":"oct", 1810 "k":"GawgguFyGrWKav7AX4VKUg" 1811 } 1813 The resulting JWE Encrypted Key value is: 1815 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1816 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1817 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1819 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1820 this value: 1822 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1824 A.3.4. Initialization Vector 1826 Generate a random 128 bit JWE Initialization Vector. In this 1827 example, the value is: 1829 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1830 101] 1832 Encoding this JWE Initialization Vector as BASE64URL(JWE 1833 Initialization Vector) gives this value: 1835 AxY8DCtDaGlsbGljb3RoZQ 1837 A.3.5. Additional Authenticated Data 1839 Let the Additional Authenticated Data encryption parameter be 1840 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1842 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1843 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1844 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1845 110, 48] 1847 A.3.6. Content Encryption 1849 Perform authenticated encryption on the Plaintext with the 1850 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1851 key, the JWE Initialization Vector, and the Additional Authenticated 1852 Data value above. The steps for doing this using the values from 1853 this example are detailed in Appendix B. The resulting Ciphertext 1854 is: 1856 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1857 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1858 112, 56, 102] 1860 The resulting Authentication Tag value is: 1862 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1863 194, 85] 1865 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1866 value: 1868 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1870 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1871 Tag) gives this value: 1873 U0m_YmjN04DJvceFICbCVQ 1875 A.3.7. Complete Representation 1877 Assemble the final representation: The Compact Serialization of this 1878 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1879 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1880 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1881 Authentication Tag). 1883 The final result in this example (with line breaks for display 1884 purposes only) is: 1886 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1887 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1888 AxY8DCtDaGlsbGljb3RoZQ. 1889 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1890 U0m_YmjN04DJvceFICbCVQ 1892 A.3.8. Validation 1894 This example illustrates the process of creating a JWE with AES Key 1895 Wrap for key encryption and AES GCM for content encryption. These 1896 results can be used to validate JWE decryption implementations for 1897 these algorithms. Also, since both the AES Key Wrap and AES GCM 1898 computations are deterministic, the resulting JWE value will be the 1899 same for all encryptions performed using these inputs. Since the 1900 computation is reproducible, these results can also be used to 1901 validate JWE encryption implementations for these algorithms. 1903 A.4. Example JWE using General JWE JSON Serialization 1905 This section contains an example using the general JWE JSON 1906 Serialization syntax. This example demonstrates the capability for 1907 encrypting the same plaintext to multiple recipients. 1909 Two recipients are present in this example. The algorithm and key 1910 used for the first recipient are the same as that used in 1911 Appendix A.2. The algorithm and key used for the second recipient 1912 are the same as that used in Appendix A.3. The resulting JWE 1913 Encrypted Key values are therefore the same; those computations are 1914 not repeated here. 1916 The Plaintext, the Content Encryption Key (CEK), JWE Initialization 1917 Vector, and JWE Protected Header are shared by all recipients (which 1918 must be the case, since the Ciphertext and Authentication Tag are 1919 also shared). 1921 A.4.1. JWE Per-Recipient Unprotected Headers 1923 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1924 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1925 encrypt the CEK. Key ID values are supplied for both keys. The two 1926 per-recipient header values used to represent these algorithms and 1927 Key IDs are: 1929 {"alg":"RSA1_5","kid":"2011-04-29"} 1931 and 1933 {"alg":"A128KW","kid":"7"} 1935 A.4.2. JWE Protected Header 1937 Authenticated encryption is performed on the Plaintext using the 1938 AES_128_CBC_HMAC_SHA_256 algorithm to produce the common JWE 1939 Ciphertext and JWE Authentication Tag values. The JWE Protected 1940 Header value representing this is: 1942 {"enc":"A128CBC-HS256"} 1944 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1945 Header)) gives this value: 1947 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1949 A.4.3. JWE Unprotected Header 1951 This JWE uses the "jku" Header Parameter to reference a JWK Set. This 1952 is represented in the following JWE Unprotected Header value as: 1954 {"jku":"https://server.example.com/keys.jwks"} 1956 A.4.4. Complete JOSE Header Values 1958 Combining the per-recipient, protected, and unprotected header values 1959 supplied, the JOSE Header values used for the first and second 1960 recipient respectively are: 1962 {"alg":"RSA1_5", 1963 "kid":"2011-04-29", 1964 "enc":"A128CBC-HS256", 1965 "jku":"https://server.example.com/keys.jwks"} 1967 and 1969 {"alg":"A128KW", 1970 "kid":"7", 1971 "enc":"A128CBC-HS256", 1972 "jku":"https://server.example.com/keys.jwks"} 1974 A.4.5. Additional Authenticated Data 1976 Let the Additional Authenticated Data encryption parameter be 1977 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1979 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1980 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1982 A.4.6. Content Encryption 1984 Perform authenticated encryption on the Plaintext with the 1985 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1986 key, the JWE Initialization Vector, and the Additional Authenticated 1987 Data value above. The steps for doing this using the values from 1988 Appendix A.3 are detailed in Appendix B. The resulting Ciphertext 1989 is: 1991 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1992 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1993 112, 56, 102] 1995 The resulting Authentication Tag value is: 1997 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1998 207] 2000 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 2001 value: 2003 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 2005 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 2006 Tag) gives this value: 2008 Mz-VPPyU4RlcuYv1IwIvzw 2010 A.4.7. Complete JWE JSON Serialization Representation 2012 The complete JWE JSON Serialization for these values is as follows 2013 (with line breaks within values for display purposes only): 2015 { 2016 "protected": 2017 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 2018 "unprotected": 2019 {"jku":"https://server.example.com/keys.jwks"}, 2020 "recipients":[ 2021 {"header": 2022 {"alg":"RSA1_5","kid":"2011-04-29"}, 2023 "encrypted_key": 2024 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 2025 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 2026 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 2027 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 2028 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 2029 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 2030 {"header": 2031 {"alg":"A128KW","kid":"7"}, 2032 "encrypted_key": 2033 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 2034 "iv": 2035 "AxY8DCtDaGlsbGljb3RoZQ", 2036 "ciphertext": 2037 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 2038 "tag": 2039 "Mz-VPPyU4RlcuYv1IwIvzw" 2040 } 2042 A.5. Example JWE using Flattened JWE JSON Serialization 2044 This section contains an example using the flattened JWE JSON 2045 Serialization syntax. This example demonstrates the capability for 2046 encrypting the plaintext to a single recipient in a flattened JSON 2047 structure. 2049 The values in this example are the same as those for the second 2050 recipient of the previous example in Appendix A.4. 2052 The complete JWE JSON Serialization for these values is as follows 2053 (with line breaks within values for display purposes only): 2055 { 2056 "protected": 2057 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 2058 "unprotected": 2059 {"jku":"https://server.example.com/keys.jwks"}, 2060 "header": 2061 {"alg":"A128KW","kid":"7"}, 2062 "encrypted_key": 2063 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ", 2064 "iv": 2065 "AxY8DCtDaGlsbGljb3RoZQ", 2066 "ciphertext": 2067 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 2068 "tag": 2069 "Mz-VPPyU4RlcuYv1IwIvzw" 2070 } 2072 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 2074 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 2075 authenticated encryption computation using the values from the 2076 example in Appendix A.3. As described where this algorithm is 2077 defined in Sections 5.2 and 5.2.3 of JWA, the AES_CBC_HMAC_SHA2 2078 family of algorithms are implemented using Advanced Encryption 2079 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #7 2080 padding to perform the encryption and an HMAC SHA-2 function to 2081 perform the integrity calculation - in this case, HMAC SHA-256. 2083 B.1. Extract MAC_KEY and ENC_KEY from Key 2085 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example 2086 (using JSON array notation) is: 2088 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 2089 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 2090 44, 207] 2092 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 2093 which is: 2095 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 2096 206] 2098 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 2099 is: 2101 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 2102 207] 2104 Note that the MAC key comes before the encryption key in the input 2105 key K; this is in the opposite order of the algorithm names in the 2106 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 2108 B.2. Encrypt Plaintext to Create Ciphertext 2110 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 2111 using PKCS #7 padding using the ENC_KEY above. The Plaintext in this 2112 example is: 2114 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 2115 112, 114, 111, 115, 112, 101, 114, 46] 2117 The encryption result is as follows, which is the Ciphertext output: 2119 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 2120 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 2121 112, 56, 102] 2123 B.3. 64 Bit Big Endian Representation of AAD Length 2125 The Additional Authenticated Data (AAD) in this example is: 2127 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2128 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2129 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2130 110, 48] 2132 This AAD is 51 bytes long, which is 408 bits long. The octet string 2133 AL, which is the number of bits in AAD expressed as a big endian 64 2134 bit unsigned integer is: 2136 [0, 0, 0, 0, 0, 0, 1, 152] 2138 B.4. Initialization Vector Value 2140 The Initialization Vector value used in this example is: 2142 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 2143 101] 2145 B.5. Create Input to HMAC Computation 2147 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 2148 the AL value. The result of this concatenation is: 2150 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2151 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2152 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2153 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 2154 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 2155 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 2156 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 2158 B.6. Compute HMAC Value 2160 Compute the HMAC SHA-256 of the concatenated value above. This 2161 result M is: 2163 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2164 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 2165 86, 229, 116] 2167 B.7. Truncate HMAC Value to Create Authentication Tag 2169 Use the first half (128 bits) of the HMAC output M as the 2170 Authentication Tag output T. This truncated value is: 2172 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2173 194, 85] 2175 Appendix C. Acknowledgements 2177 Solutions for encrypting JSON content were also explored by JSON 2178 Simple Encryption [JSE] and JavaScript Message Security Format 2179 [I-D.rescorla-jsms], both of which significantly influenced this 2180 draft. This draft attempts to explicitly reuse as many of the 2181 relevant concepts from XML Encryption 1.1 2182 [W3C.REC-xmlenc-core1-20130411] and RFC 5652 [RFC5652] as possible, 2183 while utilizing simple, compact JSON-based data structures. 2185 Special thanks are due to John Bradley, Eric Rescorla, and Nat 2186 Sakimura for the discussions that helped inform the content of this 2187 specification, to Eric Rescorla and Joe Hildebrand for allowing the 2188 reuse of text from [I-D.rescorla-jsms] in this document, and to Eric 2189 Rescorla for co-authoring many drafts of this specification. 2191 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2192 Jay for validating the examples in this specification. 2194 This specification is the work of the JOSE Working Group, which 2195 includes dozens of active and dedicated participants. In particular, 2196 the following individuals contributed ideas, feedback, and wording 2197 that influenced this specification: 2199 Richard Barnes, John Bradley, Brian Campbell, Alissa Cooper, Breno de 2200 Medeiros, Stephen Farrell, Dick Hardt, Jeff Hodges, Russ Housley, 2201 Edmund Jay, Scott Kelly, Stephen Kent, Barry Leiba, James Manger, 2202 Matt Miller, Kathleen Moriarty, Tony Nadalin, Hideki Nara, Axel 2203 Nennker, Ray Polk, Emmanuel Raviart, Eric Rescorla, Pete Resnick, Nat 2204 Sakimura, Jim Schaad, Hannes Tschofenig, and Sean Turner. 2206 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2207 Sean Turner, Stephen Farrell, and Kathleen Moriarty served as 2208 Security area directors during the creation of this specification. 2210 Appendix D. Document History 2212 [[ to be removed by the RFC Editor before publication as an RFC ]] 2214 -38 2216 o Replaced uses of the phrases "JWS object" and "JWE object" with 2217 "JWS" and "JWE". 2219 o Added member names to the JWE JSON Serialization Overview. 2221 o Applied other minor editorial improvements. 2223 -37 2225 o Restricted algorithm names to using only ASCII characters. 2227 o When describing actions taken as a result of validation failures, 2228 changed statements about rejecting the JWE to statements about 2229 considering the JWE to be invalid. 2231 o Added the CRT parameter values to example RSA private key 2232 representations. 2234 -36 2236 o Defined a flattened JWE JSON Serialization syntax, which is 2237 optimized for the single recipient case. 2239 o Clarified where white space and line breaks may occur in JSON 2240 objects by referencing Section 2 of RFC 7159. 2242 -35 2244 o Addressed AppsDir reviews by Ray Polk. 2246 -34 2248 o Addressed IESG review comments by Barry Leiba, Alissa Cooper, Pete 2249 Resnick, Stephen Farrell, and Richard Barnes. 2251 -33 2253 o Noted that certificate thumbprints are also sometimes known as 2254 certificate fingerprints. 2256 o Changed to use the term "authenticated encryption" instead of 2257 "encryption", where appropriate. 2259 o Acknowledged additional contributors. 2261 -32 2263 o Addressed Gen-ART review comments by Russ Housley. 2265 o Addressed secdir review comments by Scott Kelly, Tero Kivinen, and 2266 Stephen Kent. 2268 -31 2270 o Updated the reference to draft-mcgrew-aead-aes-cbc-hmac-sha2. 2272 -30 2274 o Added subsection headings within the Overview section for the two 2275 serializations. 2277 o Added references and cleaned up the reference syntax in a few 2278 places. 2280 o Applied minor wording changes to the Security Considerations 2281 section and made other local editorial improvements. 2283 -29 2285 o Replaced the terms JWS Header, JWE Header, and JWT Header with a 2286 single JOSE Header term defined in the JWS specification. This 2287 also enabled a single Header Parameter definition to be used and 2288 reduced other areas of duplication between specifications. 2290 -28 2292 o Specified the use of PKCS #7 padding with AES CBC, rather than 2293 PKCS #5. (PKCS #7 is a superset of PKCS #5, and is appropriate 2294 for the 16 octet blocks used by AES CBC.) 2296 o Revised the introduction to the Security Considerations section. 2297 Also moved a security consideration item here from the JWA draft. 2299 -27 2301 o Described additional security considerations. 2303 o Added the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) header 2304 parameter. 2306 -26 2308 o Noted that octet sequences are depicted using JSON array notation. 2310 o Updated references, including to W3C specifications. 2312 -25 2314 o Corrected two external section number references that had changed. 2316 o Corrected a typo in an algorithm name in the prose of an example. 2318 -24 2320 o Corrected complete JSON Serialization example. 2322 o Replaced uses of the term "associated data" wherever it was used 2323 to refer to a data value with "additional authenticated data", 2324 since both terms were being used as synonyms, causing confusion. 2326 o Updated the JSON reference to RFC 7159. 2328 o Thanked Eric Rescorla for helping to author of most of the drafts 2329 of this specification and removed him from the current author 2330 list. 2332 -23 2334 o Corrected a use of the word "payload" to "plaintext". 2336 -22 2338 o Corrected RFC 2119 terminology usage. 2340 o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. 2342 -21 2344 o Changed some references from being normative to informative, 2345 addressing issue #90. 2347 o Applied review comments to the JSON Serialization section, 2348 addressing issue #178. 2350 -20 2352 o Made terminology definitions more consistent, addressing issue 2353 #165. 2355 o Restructured the JSON Serialization section to call out the 2356 parameters used in hanging lists, addressing issue #178. 2358 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 2359 addressing issue #90. 2361 -19 2363 o Reordered the key selection parameters. 2365 -18 2367 o Updated the mandatory-to-implement (MTI) language to say that 2368 applications using this specification need to specify what 2369 serialization and serialization features are used for that 2370 application, addressing issue #176. 2372 o Changes to address editorial and minor issues #89, #135, #165, 2373 #174, #175, #177, #179, and #180. 2375 o Used Header Parameter Description registry field. 2377 -17 2379 o Refined the "typ" and "cty" definitions to always be MIME Media 2380 Types, with the omission of "application/" prefixes recommended 2381 for brevity, addressing issue #50. 2383 o Updated the mandatory-to-implement (MTI) language to say that 2384 general-purpose implementations must implement the single 2385 recipient case for both serializations whereas special-purpose 2386 implementations can implement just one serialization if that meets 2387 the needs of the use cases the implementation is designed for, 2388 addressing issue #176. 2390 o Explicitly named all the logical components of a JWE and defined 2391 the processing rules and serializations in terms of those 2392 components, addressing issues #60, #61, and #62. 2394 o Replaced verbose repetitive phases such as "base64url encode the 2395 octets of the UTF-8 representation of X" with mathematical 2396 notation such as "BASE64URL(UTF8(X))". 2398 o Header Parameters and processing rules occurring in both JWS and 2399 JWE are now referenced in JWS by JWE, rather than duplicated, 2400 addressing issue #57. 2402 o Terms used in multiple documents are now defined in one place and 2403 incorporated by reference. Some lightly used or obvious terms 2404 were also removed. This addresses issue #58. 2406 -16 2408 o Changes to address editorial and minor issues #163, #168, #169, 2409 #170, #172, and #173. 2411 -15 2413 o Clarified that it is an application decision which recipients' 2414 encrypted content must successfully validate for the JWE to be 2415 accepted, addressing issue #35. 2417 o Changes to address editorial issues #34, #164, and #169. 2419 -14 2421 o Clarified that the "protected", "unprotected", "header", "iv", 2422 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2423 JSON Serialization when their values would be empty. Stated that 2424 the "recipients" array must always be present. 2426 -13 2428 o Added an "aad" (Additional Authenticated Data) member for the JWE 2429 JSON Serialization, enabling Additional Authenticated Data to be 2430 supplied that is not double base64url encoded, addressing issue 2431 #29. 2433 -12 2435 o Clarified that the "typ" and "cty" header parameters are used in 2436 an application-specific manner and have no effect upon the JWE 2437 processing. 2439 o Replaced the MIME types "application/jwe+json" and 2440 "application/jwe" with "application/jose+json" and 2441 "application/jose". 2443 o Stated that recipients MUST either reject JWEs with duplicate 2444 Header Parameter Names or use a JSON parser that returns only the 2445 lexically last duplicate member name. 2447 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2448 be with the algorithm descriptions that use them. 2450 o Added a Serializations section with parallel treatment of the JWE 2451 Compact Serialization and the JWE JSON Serialization and also 2452 moved the former Implementation Considerations content there. 2454 o Restored use of the term "AEAD". 2456 o Changed terminology from "block encryption" to "content 2457 encryption". 2459 -11 2461 o Added Key Identification section. 2463 o Removed the Encrypted Key value from the AAD computation since it 2464 is already effectively integrity protected by the encryption 2465 process. The AAD value now only contains the representation of 2466 the JWE Encrypted Header. 2468 o For the JWE JSON Serialization, enable Header Parameter values to 2469 be specified in any of three parameters: the "protected" member 2470 that is integrity protected and shared among all recipients, the 2471 "unprotected" member that is not integrity protected and shared 2472 among all recipients, and the "header" member that is not 2473 integrity protected and specific to a particular recipient. (This 2474 does not affect the JWE Compact Serialization, in which all Header 2475 Parameter values are in a single integrity protected JWE Header 2476 value.) 2478 o Shortened the names "authentication_tag" to "tag" and 2479 "initialization_vector" to "iv" in the JWE JSON Serialization, 2480 addressing issue #20. 2482 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2484 o Removed suggested compact serialization for multiple recipients. 2486 o Changed the MIME type name "application/jwe-js" to 2487 "application/jwe+json", addressing issue #22. 2489 o Tightened the description of the "crit" (critical) header 2490 parameter. 2492 -10 2494 o Changed the JWE processing rules for multiple recipients so that a 2495 single AAD value contains the header parameters and encrypted key 2496 values for all the recipients, enabling AES GCM to be safely used 2497 for multiple recipients. 2499 o Added an appendix suggesting a possible compact serialization for 2500 JWEs with multiple recipients. 2502 -09 2504 o Added JWE JSON Serialization, as specified by 2505 draft-jones-jose-jwe-json-serialization-04. 2507 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2508 parameter value. 2510 o Defined that the default action for header parameters that are not 2511 understood is to ignore them unless specifically designated as 2512 "MUST be understood" or included in the new "crit" (critical) 2513 header parameter list. This addressed issue #6. 2515 o Corrected "x5c" description. This addressed issue #12. 2517 o Changed from using the term "byte" to "octet" when referring to 8 2518 bit values. 2520 o Added Key Management Mode definitions to terminology section and 2521 used the defined terms to provide clearer key management 2522 instructions. This addressed issue #5. 2524 o Added text about preventing the recipient from behaving as an 2525 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2527 o Changed from using the term "Integrity Value" to "Authentication 2528 Tag". 2530 o Changed member name from "integrity_value" to "authentication_tag" 2531 in the JWE JSON Serialization. 2533 o Removed Initialization Vector from the AAD value since it is 2534 already integrity protected by all of the authenticated encryption 2535 algorithms specified in the JWA specification. 2537 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2538 and "A256CBC-HS512". The new algorithms perform the same 2539 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2540 but with the Initialization Vector and Authentication Tag values 2541 remaining separate from the Ciphertext value in the output 2542 representation. Also deleted the header parameters "epu" 2543 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2544 they are no longer used. 2546 -08 2548 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2549 since the term AEAD in the RFC 5116 sense implied the use of a 2550 particular data representation, rather than just referring to the 2551 class of algorithms that perform authenticated encryption with 2552 associated data. 2554 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2555 Tschofenig. Many of these simplified the terminology used. 2557 o Clarified statements of the form "This header parameter is 2558 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2560 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2561 Web Signature and Encryption Header Parameters registry. 2563 o Added seriesInfo information to Internet Draft references. 2565 -07 2566 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2568 o Updated values for example AES CBC calculations. 2570 o Made several local editorial changes to clean up loose ends left 2571 over from to the decision to only support block encryption methods 2572 providing integrity. One of these changes was to explicitly state 2573 that the "enc" (encryption method) algorithm must be an 2574 Authenticated Encryption algorithm with a specified key length. 2576 -06 2578 o Removed the "int" and "kdf" parameters and defined the new 2579 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2580 "A256CBC+HS512" to replace the former uses of AES CBC, which 2581 required the use of separate integrity and key derivation 2582 functions. 2584 o Included additional values in the Concat KDF calculation -- the 2585 desired output size and the algorithm value, and optionally 2586 PartyUInfo and PartyVInfo values. Added the optional header 2587 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2588 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2589 PartyVInfo). Updated the KDF examples accordingly. 2591 o Promoted Initialization Vector from being a header parameter to 2592 being a top-level JWE element. This saves approximately 16 bytes 2593 in the compact serialization, which is a significant savings for 2594 some use cases. Promoting the Initialization Vector out of the 2595 header also avoids repeating this shared value in the JSON 2596 serialization. 2598 o Changed "x5c" (X.509 Certificate Chain) representation from being 2599 a single string to being an array of strings, each containing a 2600 single base64 encoded DER certificate value, representing elements 2601 of the certificate chain. 2603 o Added an AES Key Wrap example. 2605 o Reordered the encryption steps so CMK creation is first, when 2606 required. 2608 o Correct statements in examples about which algorithms produce 2609 reproducible results. 2611 -05 2612 o Support both direct encryption using a shared or agreed upon 2613 symmetric key, and the use of a shared or agreed upon symmetric 2614 key to key wrap the CMK. 2616 o Added statement that "StringOrURI values are compared as case- 2617 sensitive strings with no transformations or canonicalizations 2618 applied". 2620 o Updated open issues. 2622 o Indented artwork elements to better distinguish them from the body 2623 text. 2625 -04 2627 o Refer to the registries as the primary sources of defined values 2628 and then secondarily reference the sections defining the initial 2629 contents of the registries. 2631 o Normatively reference XML Encryption 1.1 for its security 2632 considerations. 2634 o Reference draft-jones-jose-jwe-json-serialization instead of 2635 draft-jones-json-web-encryption-json-serialization. 2637 o Described additional open issues. 2639 o Applied editorial suggestions. 2641 -03 2643 o Added the "kdf" (key derivation function) header parameter to 2644 provide crypto agility for key derivation. The default KDF 2645 remains the Concat KDF with the SHA-256 digest function. 2647 o Reordered encryption steps so that the Encoded JWE Header is 2648 always created before it is needed as an input to the 2649 Authenticated Encryption "additional authenticated data" 2650 parameter. 2652 o Added the "cty" (content type) header parameter for declaring type 2653 information about the secured content, as opposed to the "typ" 2654 (type) header parameter, which declares type information about 2655 this object. 2657 o Moved description of how to determine whether a header is for a 2658 JWS or a JWE from the JWT spec to the JWE spec. 2660 o Added complete encryption examples for both Authenticated 2661 Encryption and non-Authenticated Encryption algorithms. 2663 o Added complete key derivation examples. 2665 o Added "Collision Resistant Namespace" to the terminology section. 2667 o Reference ITU.X690.1994 for DER encoding. 2669 o Added Registry Contents sections to populate registry values. 2671 o Numerous editorial improvements. 2673 -02 2675 o When using Authenticated Encryption algorithms (such as AES GCM), 2676 use the "additional authenticated data" parameter to provide 2677 integrity for the header, encrypted key, and ciphertext and use 2678 the resulting "authentication tag" value as the JWE Authentication 2679 Tag. 2681 o Defined KDF output key sizes. 2683 o Generalized text to allow key agreement to be employed as an 2684 alternative to key wrapping or key encryption. 2686 o Changed compression algorithm from gzip to DEFLATE. 2688 o Clarified that it is an error when a "kid" value is included and 2689 no matching key is found. 2691 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2692 rejected. 2694 o Clarified the relationship between "typ" header parameter values 2695 and MIME types. 2697 o Registered application/jwe MIME type and "JWE" typ header 2698 parameter value. 2700 o Simplified JWK terminology to get replace the "JWK Key Object" and 2701 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2702 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2703 between single keys and sets of keys. As part of this change, the 2704 Header Parameter Name for a public key value was changed from 2705 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2707 o Added suggestion on defining additional header parameters such as 2708 "x5t#S256" in the future for certificate thumbprints using hash 2709 algorithms other than SHA-1. 2711 o Specify RFC 2818 server identity validation, rather than RFC 6125 2712 (paralleling the same decision in the OAuth specs). 2714 o Generalized language to refer to Message Authentication Codes 2715 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2716 unless in a context specific to HMAC algorithms. 2718 o Reformatted to give each header parameter its own section heading. 2720 -01 2722 o Added an integrity check for non-Authenticated Encryption 2723 algorithms. 2725 o Added "jpk" and "x5c" header parameters for including JWK public 2726 keys and X.509 certificate chains directly in the header. 2728 o Clarified that this specification is defining the JWE Compact 2729 Serialization. Referenced the new JWE-JS spec, which defines the 2730 JWE JSON Serialization. 2732 o Added text "New header parameters should be introduced sparingly 2733 since an implementation that does not understand a parameter MUST 2734 reject the JWE". 2736 o Clarified that the order of the encryption and decryption steps is 2737 not significant in cases where there are no dependencies between 2738 the inputs and outputs of the steps. 2740 o Made other editorial improvements suggested by JOSE working group 2741 participants. 2743 -00 2745 o Created the initial IETF draft based upon 2746 draft-jones-json-web-encryption-02 with no normative changes. 2748 o Changed terminology to no longer call both digital signatures and 2749 HMACs "signatures". 2751 Authors' Addresses 2753 Michael B. Jones 2754 Microsoft 2756 Email: mbj@microsoft.com 2757 URI: http://self-issued.info/ 2759 Joe Hildebrand 2760 Cisco Systems, Inc. 2762 Email: jhildebr@cisco.com