idnits 2.17.1 draft-ietf-jose-json-web-encryption-40.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 (January 13, 2015) is 3384 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 1502 -- Looks like a reference, but probably isn't: '197' on line 1502 -- Looks like a reference, but probably isn't: '117' on line 1502 -- Looks like a reference, but probably isn't: '252' on line 1502 -- Looks like a reference, but probably isn't: '2' on line 1502 -- Looks like a reference, but probably isn't: '219' on line 1502 -- Looks like a reference, but probably isn't: '233' on line 1502 -- Looks like a reference, but probably isn't: '68' on line 1502 -- Looks like a reference, but probably isn't: '180' on line 1502 -- Looks like a reference, but probably isn't: '225' on line 1502 -- Looks like a reference, but probably isn't: '77' on line 1502 -- Looks like a reference, but probably isn't: '0' on line 2142 -- Looks like a reference, but probably isn't: '1' on line 2142 -- Looks like a reference, but probably isn't: '152' on line 2142 == Unused Reference: 'AES' is defined on line 1336, 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE' -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 18 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track J. Hildebrand 5 Expires: July 17, 2015 Cisco 6 January 13, 2015 8 JSON Web Encryption (JWE) 9 draft-ietf-jose-json-web-encryption-40 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 July 17, 2015. 38 Copyright Notice 40 Copyright (c) 2015 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 58 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 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 . . . . . . . . . . . . 12 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 . . . . 13 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 . . . 14 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 . . . . . . . . . . . . . . 15 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 . . . . . . . . . . 25 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 . . . . . . . . . . . . . . . . . . . . . . 29 104 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 105 12.1. Normative References . . . . . . . . . . . . . . . . . . . 29 106 12.2. Informative References . . . . . . . . . . . . . . . . . . 30 107 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 31 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 . . . . . . . . . . . . . . . . . . . . 32 112 A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 33 113 A.1.5. Additional Authenticated Data . . . . . . . . . . . . 33 114 A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 34 115 A.1.7. Complete Representation . . . . . . . . . . . . . . . 34 116 A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 35 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) . . . . . . . . . . . . . 36 121 A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 36 122 A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 38 123 A.2.5. Additional Authenticated Data . . . . . . . . . . . . 38 124 A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 38 125 A.2.7. Complete Representation . . . . . . . . . . . . . . . 39 126 A.2.8. Validation . . . . . . . . . . . . . . . . . . . . . . 39 127 A.3. Example JWE using AES Key Wrap and 128 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 40 129 A.3.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 40 130 A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 40 131 A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 40 132 A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 41 133 A.3.5. Additional Authenticated Data . . . . . . . . . . . . 41 134 A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 41 135 A.3.7. Complete Representation . . . . . . . . . . . . . . . 42 136 A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 42 137 A.4. Example JWE using General JWE JSON Serialization . . . . . 43 138 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 43 139 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 43 140 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 44 141 A.4.4. Complete JOSE Header Values . . . . . . . . . . . . . 44 142 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 44 143 A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 44 144 A.4.7. Complete JWE JSON Serialization Representation . . . . 45 146 A.5. Example JWE using Flattened JWE JSON Serialization . . . . 46 147 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 46 148 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 46 149 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 47 150 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 47 151 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 48 152 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 48 153 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 48 154 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 48 155 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 48 156 Appendix D. Document History . . . . . . . . . . . . . . . . . . 49 157 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 61 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, where STRING is a sequence of zero or more Unicode 197 [UNICODE] characters. 199 ASCII(STRING) denotes the octets of the ASCII [RFC20] representation 200 of STRING, where STRING is a sequence of zero or more ASCII 201 characters. 203 The concatenation of two values A and B is denoted as A || B. 205 2. Terminology 207 These terms defined by the JSON Web Signature (JWS) [JWS] 208 specification are incorporated into this specification: "JSON Web 209 Signature (JWS)", "Base64url Encoding", "Collision-Resistant Name", 210 "Header Parameter", "JOSE Header", and "StringOrURI". 212 These terms defined by the Internet Security Glossary, Version 2 213 [RFC4949] are incorporated into this specification: "Ciphertext", 214 "Digital Signature", "Message Authentication Code (MAC)", and 215 "Plaintext". 217 These terms are defined by this specification: 219 JSON Web Encryption (JWE) 220 A data structure representing an encrypted and integrity protected 221 message. 223 Authenticated Encryption with Associated Data (AEAD) 224 An AEAD algorithm is one that encrypts the Plaintext, allows 225 Additional Authenticated Data to be specified, and provides an 226 integrated content integrity check over the Ciphertext and 227 Additional Authenticated Data. AEAD algorithms accept two inputs, 228 the Plaintext and the Additional Authenticated Data value, and 229 produce two outputs, the Ciphertext and the Authentication Tag 230 value. AES Galois/Counter Mode (GCM) is one such algorithm. 232 Additional Authenticated Data (AAD) 233 An input to an AEAD operation that is integrity protected but not 234 encrypted. 236 Authentication Tag 237 An output of an AEAD operation that ensures the integrity of the 238 Ciphertext and the Additional Authenticated Data. Note that some 239 algorithms may not use an Authentication Tag, in which case this 240 value is the empty octet sequence. 242 Content Encryption Key (CEK) 243 A symmetric key for the AEAD algorithm used to encrypt the 244 Plaintext to produce the Ciphertext and the Authentication Tag. 246 JWE Encrypted Key 247 Encrypted Content Encryption Key (CEK) value. Note that for some 248 algorithms, the JWE Encrypted Key value is specified as being the 249 empty octet sequence. 251 JWE Initialization Vector 252 Initialization vector value used when encrypting the plaintext. 253 Note that some algorithms may not use an Initialization Vector, in 254 which case this value is the empty octet sequence. 256 JWE AAD 257 Additional value to be integrity protected by the authenticated 258 encryption operation. This can only be present when using the JWE 259 JSON Serialization. (Note that this can also be achieved when 260 using either serialization by including the AAD value as an 261 integrity protected Header Parameter value, but at the cost of the 262 value being double base64url encoded.) 264 JWE Ciphertext 265 Ciphertext value resulting from authenticated encryption of the 266 plaintext with additional authenticated data. 268 JWE Authentication Tag 269 Authentication Tag value resulting from authenticated encryption 270 of the plaintext with additional authenticated data. 272 JWE Protected Header 273 JSON object that contains the Header Parameters that are integrity 274 protected by the authenticated encryption operation. These 275 parameters apply to all recipients of the JWE. For the JWE 276 Compact Serialization, this comprises the entire JOSE Header. For 277 the JWE JSON Serialization, this is one component of the JOSE 278 Header. 280 JWE Shared Unprotected Header 281 JSON object that contains the Header Parameters that apply to all 282 recipients of the JWE that are not integrity protected. This can 283 only be present when using the JWE JSON Serialization. 285 JWE Per-Recipient Unprotected Header 286 JSON object that contains Header Parameters that apply to a single 287 recipient of the JWE. These Header Parameter values are not 288 integrity protected. This can only be present when using the JWE 289 JSON Serialization. 291 JWE Compact Serialization 292 A representation of the JWE as a compact, URL-safe string. 294 JWE JSON Serialization 295 A representation of the JWE as a JSON object. The JWE JSON 296 Serialization enables the same content to be encrypted to multiple 297 parties. This representation is neither optimized for compactness 298 nor URL-safe. 300 Key Management Mode 301 A method of determining the Content Encryption Key (CEK) value to 302 use. Each algorithm used for determining the CEK value uses a 303 specific Key Management Mode. Key Management Modes employed by 304 this specification are Key Encryption, Key Wrapping, Direct Key 305 Agreement, Key Agreement with Key Wrapping, and Direct Encryption. 307 Key Encryption 308 A Key Management Mode in which the Content Encryption Key (CEK) 309 value is encrypted to the intended recipient using an asymmetric 310 encryption algorithm. 312 Key Wrapping 313 A Key Management Mode in which the Content Encryption Key (CEK) 314 value is encrypted to the intended recipient using a symmetric key 315 wrapping algorithm. 317 Direct Key Agreement 318 A Key Management Mode in which a key agreement algorithm is used 319 to agree upon the Content Encryption Key (CEK) value. 321 Key Agreement with Key Wrapping 322 A Key Management Mode in which a key agreement algorithm is used 323 to agree upon a symmetric key used to encrypt the Content 324 Encryption Key (CEK) value to the intended recipient using a 325 symmetric key wrapping algorithm. 327 Direct Encryption 328 A Key Management Mode in which the Content Encryption Key (CEK) 329 value used is the secret symmetric key value shared between the 330 parties. 332 3. JSON Web Encryption (JWE) Overview 334 JWE represents encrypted content using JSON data structures and 335 base64url encoding. These JSON data structures MAY contain white 336 space and/or line breaks before or after any JSON values or 337 structural characters, in accordance with Section 2 of RFC 7159 338 [RFC7159]. A JWE represents these logical values (each of which is 339 defined in Section 2): 341 o JOSE Header 342 o JWE Encrypted Key 343 o JWE Initialization Vector 344 o JWE AAD 345 o JWE Ciphertext 346 o JWE Authentication Tag 348 For a JWE, the JOSE Header members are the union of the members of 349 these values (each of which is defined in Section 2): 351 o JWE Protected Header 352 o JWE Shared Unprotected Header 353 o JWE Per-Recipient Unprotected Header 355 JWE utilizes authenticated encryption to ensure the confidentiality 356 and integrity of the Plaintext and the integrity of the JWE Protected 357 Header and the JWE AAD. 359 This document defines two serializations for JWEs: a compact, URL- 360 safe serialization called the JWE Compact Serialization and a JSON 361 serialization called the JWE JSON Serialization. In both 362 serializations, the JWE Protected Header, JWE Encrypted Key, JWE 363 Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are 364 base64url encoded, since JSON lacks a way to directly represent 365 arbitrary octet sequences. When present, the JWE AAD is also 366 base64url encoded. 368 3.1. JWE Compact Serialization Overview 370 In the JWE Compact Serialization, no JWE Shared Unprotected Header or 371 JWE Per-Recipient Unprotected Header are used. In this case, the 372 JOSE Header and the JWE Protected Header are the same. 374 In the JWE Compact Serialization, a JWE is represented as the 375 concatenation: 377 BASE64URL(UTF8(JWE Protected Header)) || '.' || 378 BASE64URL(JWE Encrypted Key) || '.' || 379 BASE64URL(JWE Initialization Vector) || '.' || 380 BASE64URL(JWE Ciphertext) || '.' || 381 BASE64URL(JWE Authentication Tag) 383 See Section 7.1 for more information about the JWE Compact 384 Serialization. 386 3.2. JWE JSON Serialization Overview 388 In the JWE JSON Serialization, one or more of the JWE Protected 389 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 390 Unprotected Header MUST be present. In this case, the members of the 391 JOSE Header are the union of the members of the JWE Protected Header, 392 JWE Shared Unprotected Header, and JWE Per-Recipient Unprotected 393 Header values that are present. 395 In the JWE JSON Serialization, a JWE is represented as a JSON object 396 containing some or all of these eight members: 397 "protected", with the value BASE64URL(UTF8(JWE Protected Header)) 398 "unprotected", with the value JWE Shared Unprotected Header 399 "header", with the value JWE Per-Recipient Unprotected Header 400 "encrypted_key", with the value BASE64URL(JWE Encrypted Key) 401 "iv", with the value BASE64URL(JWE Initialization Vector) 402 "ciphertext", with the value BASE64URL(JWE Ciphertext) 403 "tag", with the value BASE64URL(JWE Authentication Tag) 404 "aad", with the value BASE64URL(JWE AAD) 406 The six base64url encoded result strings and the two unprotected JSON 407 object values are represented as members within a JSON object. The 408 inclusion of some of these values is OPTIONAL. The JWE JSON 409 Serialization can also encrypt the plaintext to multiple recipients. 410 See Section 7.2 for more information about the JWE JSON 411 Serialization. 413 3.3. Example JWE 415 This example encrypts the plaintext "The true sign of intelligence is 416 not knowledge but imagination." to the recipient. 418 The following example JWE Protected Header declares that: 420 o The Content Encryption Key is encrypted to the recipient using the 421 RSAES OAEP [RFC3447] algorithm to produce the JWE Encrypted Key. 423 o Authenticated encryption is performed on the Plaintext using the 424 AES GCM [AES, NIST.800-38D] algorithm with a 256 bit key to 425 produce the Ciphertext and the Authentication Tag. 427 {"alg":"RSA-OAEP","enc":"A256GCM"} 429 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 430 Header)) gives this value: 432 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 434 The remaining steps to finish creating this JWE are: 435 o Generate a random Content Encryption Key (CEK). 436 o Encrypt the CEK with the recipient's public key using the RSAES 437 OAEP algorithm to produce the JWE Encrypted Key. 439 o Base64url encode the JWE Encrypted Key. 440 o Generate a random JWE Initialization Vector. 441 o Base64url encode the JWE Initialization Vector. 442 o Let the Additional Authenticated Data encryption parameter be 443 ASCII(BASE64URL(UTF8(JWE Protected Header))). 444 o Perform authenticated encryption on the Plaintext with the AES GCM 445 algorithm using the CEK as the encryption key, the JWE 446 Initialization Vector, and the Additional Authenticated Data 447 value, requesting a 128 bit Authentication Tag output. 448 o Base64url encode the Ciphertext. 449 o Base64url encode the Authentication Tag. 450 o Assemble the final representation: The Compact Serialization of 451 this result is the string BASE64URL(UTF8(JWE Protected Header)) || 452 '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE 453 Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' 454 || BASE64URL(JWE Authentication Tag). 456 The final result in this example (with line breaks for display 457 purposes only) is: 459 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 460 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 461 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 462 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 463 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 464 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 465 6UklfCpIMfIjf7iGdXKHzg. 466 48V1_ALb6US04U3b. 467 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 468 SdiwkIr3ajwQzaBtQD_A. 469 XFBoMYUZodetZdvTiFvSkQ 471 See Appendix A.1 for the complete details of computing this JWE. See 472 Appendix A for additional examples, including examples using the JWE 473 JSON Serialization in Sections A.4 and A.5. 475 4. JOSE Header 477 For a JWE, the members of the JSON object(s) representing the JOSE 478 Header describe the encryption applied to the Plaintext and 479 optionally additional properties of the JWE. The Header Parameter 480 names within the JOSE Header MUST be unique, just as described in 481 Section 4 of [JWS]. The rules about handling Header Parameters that 482 are not understood by the implementation are also the same. The 483 classes of Header Parameter names are likewise the same. 485 4.1. Registered Header Parameter Names 487 The following Header Parameter names for use in JWEs are registered 488 in the IANA JSON Web Signature and Encryption Header Parameters 489 registry defined in [JWS], with meanings as defined below. 491 As indicated by the common registry, JWSs and JWEs share a common 492 Header Parameter space; when a parameter is used by both 493 specifications, its usage must be compatible between the 494 specifications. 496 4.1.1. "alg" (Algorithm) Header Parameter 498 This parameter has the same meaning, syntax, and processing rules as 499 the "alg" Header Parameter defined in Section 4.1.1 of [JWS], except 500 that the Header Parameter identifies the cryptographic algorithm used 501 to encrypt or determine the value of the Content Encryption Key 502 (CEK). The encrypted content is not usable if the "alg" value does 503 not represent a supported algorithm, or if the recipient does not 504 have a key that can be used with that algorithm. 506 A list of defined "alg" values for this use can be found in the IANA 507 JSON Web Signature and Encryption Algorithms registry defined in 508 [JWA]; the initial contents of this registry are the values defined 509 in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. 511 4.1.2. "enc" (Encryption Algorithm) Header Parameter 513 The "enc" (encryption algorithm) Header Parameter identifies the 514 content encryption algorithm used to perform authenticated encryption 515 on the Plaintext to produce the Ciphertext and the Authentication 516 Tag. This algorithm MUST be an AEAD algorithm with a specified key 517 length. The encrypted content is not usable if the "enc" value does 518 not represent a supported algorithm. "enc" values should either be 519 registered in the IANA JSON Web Signature and Encryption Algorithms 520 registry defined in [JWA] or be a value that contains a Collision- 521 Resistant Name. The "enc" value is a case-sensitive ASCII string 522 containing a StringOrURI value. This Header Parameter MUST be 523 present and MUST be understood and processed by implementations. 525 A list of defined "enc" values for this use can be found in the IANA 526 JSON Web Signature and Encryption Algorithms registry defined in 527 [JWA]; the initial contents of this registry are the values defined 528 in Section 5.1 of the JSON Web Algorithms (JWA) [JWA] specification. 530 4.1.3. "zip" (Compression Algorithm) Header Parameter 532 The "zip" (compression algorithm) applied to the Plaintext before 533 encryption, if any. The "zip" value defined by this specification 534 is: 536 o "DEF" - Compression with the DEFLATE [RFC1951] algorithm 538 Other values MAY be used. Compression algorithm values can be 539 registered in the IANA JSON Web Encryption Compression Algorithm 540 registry defined in [JWA]. The "zip" value is a case-sensitive 541 string. If no "zip" parameter is present, no compression is applied 542 to the Plaintext before encryption. When used, this Header Parameter 543 MUST be integrity protected; therefore, it MUST occur only within the 544 JWE Protected Header. Use of this Header Parameter is OPTIONAL. 545 This Header Parameter MUST be understood and processed by 546 implementations. 548 4.1.4. "jku" (JWK Set URL) Header Parameter 550 This parameter has the same meaning, syntax, and processing rules as 551 the "jku" Header Parameter defined in Section 4.1.2 of [JWS], except 552 that the JWK Set resource contains the public key to which the JWE 553 was encrypted; this can be used to determine the private key needed 554 to decrypt the JWE. 556 4.1.5. "jwk" (JSON Web Key) Header Parameter 558 This parameter has the same meaning, syntax, and processing rules as 559 the "jwk" Header Parameter defined in Section 4.1.3 of [JWS], except 560 that the key is the public key to which the JWE was encrypted; this 561 can be used to determine the private key needed to decrypt the JWE. 563 4.1.6. "kid" (Key ID) Header Parameter 565 This parameter has the same meaning, syntax, and processing rules as 566 the "kid" Header Parameter defined in Section 4.1.4 of [JWS], except 567 that the key hint references the public key to which the JWE was 568 encrypted; this can be used to determine the private key needed to 569 decrypt the JWE. This parameter allows originators to explicitly 570 signal a change of key to JWE recipients. 572 4.1.7. "x5u" (X.509 URL) Header Parameter 574 This parameter has the same meaning, syntax, and processing rules as 575 the "x5u" Header Parameter defined in Section 4.1.5 of [JWS], except 576 that the X.509 public key certificate or certificate chain [RFC5280] 577 contains the public key to which the JWE was encrypted; this can be 578 used to determine the private key needed to decrypt the JWE. 580 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 582 This parameter has the same meaning, syntax, and processing rules as 583 the "x5c" Header Parameter defined in Section 4.1.6 of [JWS], except 584 that the X.509 public key certificate or certificate chain [RFC5280] 585 contains the public key to which the JWE was encrypted; this can be 586 used to determine the private key needed to decrypt the JWE. 588 See Appendix B of [JWS] for an example "x5c" value. 590 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 592 This parameter has the same meaning, syntax, and processing rules as 593 the "x5t" Header Parameter defined in Section 4.1.7 of [JWS], except 594 that the certificate referenced by the thumbprint contains the public 595 key to which the JWE was encrypted; this can be used to determine the 596 private key needed to decrypt the JWE. Note that certificate 597 thumbprints are also sometimes known as certificate fingerprints. 599 4.1.10. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header 600 Parameter 602 This parameter has the same meaning, syntax, and processing rules as 603 the "x5t#S256" Header Parameter defined in Section 4.1.8 of [JWS], 604 except that the certificate referenced by the thumbprint contains the 605 public key to which the JWE was encrypted; this can be used to 606 determine the private key needed to decrypt the JWE. Note that 607 certificate thumbprints are also sometimes known as certificate 608 fingerprints. 610 4.1.11. "typ" (Type) Header Parameter 612 This parameter has the same meaning, syntax, and processing rules as 613 the "typ" Header Parameter defined in Section 4.1.9 of [JWS], except 614 that the type is that of this complete JWE. 616 4.1.12. "cty" (Content Type) Header Parameter 618 This parameter has the same meaning, syntax, and processing rules as 619 the "cty" Header Parameter defined in Section 4.1.10 of [JWS], except 620 that the type is that of the secured content (the plaintext). 622 4.1.13. "crit" (Critical) Header Parameter 624 This parameter has the same meaning, syntax, and processing rules as 625 the "crit" Header Parameter defined in Section 4.1.11 of [JWS], 626 except that Header Parameters for a JWE are being referred to, rather 627 than Header Parameters for a JWS. 629 4.2. Public Header Parameter Names 631 Additional Header Parameter names can be defined by those using JWEs. 632 However, in order to prevent collisions, any new Header Parameter 633 name should either be registered in the IANA JSON Web Signature and 634 Encryption Header Parameters registry defined in [JWS] or be a Public 635 Name: a value that contains a Collision-Resistant Name. In each 636 case, the definer of the name or value needs to take reasonable 637 precautions to make sure they are in control of the part of the 638 namespace they use to define the Header Parameter name. 640 New Header Parameters should be introduced sparingly, as they can 641 result in non-interoperable JWEs. 643 4.3. Private Header Parameter Names 645 A producer and consumer of a JWE may agree to use Header Parameter 646 names that are Private Names: names that are not Registered Header 647 Parameter names Section 4.1 or Public Header Parameter names 648 Section 4.2. Unlike Public Header Parameter names, Private Header 649 Parameter names are subject to collision and should be used with 650 caution. 652 5. Producing and Consuming JWEs 654 5.1. Message Encryption 656 The message encryption process is as follows. The order of the steps 657 is not significant in cases where there are no dependencies between 658 the inputs and outputs of the steps. 660 1. Determine the Key Management Mode employed by the algorithm used 661 to determine the Content Encryption Key (CEK) value. (This is 662 the algorithm recorded in the "alg" (algorithm) Header Parameter 663 of the resulting JWE.) 665 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 666 Wrapping are employed, generate a random Content Encryption Key 667 (CEK) value. See RFC 4086 [RFC4086] for considerations on 668 generating random values. The CEK MUST have a length equal to 669 that required for the content encryption algorithm. 671 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 672 employed, use the key agreement algorithm to compute the value 673 of the agreed upon key. When Direct Key Agreement is employed, 674 let the Content Encryption Key (CEK) be the agreed upon key. 675 When Key Agreement with Key Wrapping is employed, the agreed 676 upon key will be used to wrap the CEK. 678 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 679 Wrapping are employed, encrypt the CEK to the recipient and let 680 the result be the JWE Encrypted Key. 682 5. When Direct Key Agreement or Direct Encryption are employed, let 683 the JWE Encrypted Key be the empty octet sequence. 685 6. When Direct Encryption is employed, let the Content Encryption 686 Key (CEK) be the shared symmetric key. 688 7. Compute the encoded key value BASE64URL(JWE Encrypted Key). 690 8. If the JWE JSON Serialization is being used, repeat this process 691 (steps 1-7) for each recipient. 693 9. Generate a random JWE Initialization Vector of the correct size 694 for the content encryption algorithm (if required for the 695 algorithm); otherwise, let the JWE Initialization Vector be the 696 empty octet sequence. 698 10. Compute the encoded initialization vector value BASE64URL(JWE 699 Initialization Vector). 701 11. If a "zip" parameter was included, compress the Plaintext using 702 the specified compression algorithm and let M be the octet 703 sequence representing the compressed Plaintext; otherwise, let M 704 be the octet sequence representing the Plaintext. 706 12. Create the JSON object(s) containing the desired set of Header 707 Parameters, which together comprise the JOSE Header: if the JWE 708 Compact Serialization is being used, the JWE Protected Header, 709 or if the JWE JSON Serialization is being used, one or more of 710 the JWE Protected Header, the JWE Shared Unprotected Header, and 711 the JWE Per-Recipient Unprotected Header. 713 13. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 714 Protected Header)). If the JWE Protected Header is not present 715 (which can only happen when using the JWE JSON Serialization and 716 no "protected" member is present), let this value be the empty 717 string. 719 14. Let the Additional Authenticated Data encryption parameter be 720 ASCII(Encoded Protected Header). However if a JWE AAD value is 721 present (which can only be the case when using the JWE JSON 722 Serialization), instead let the Additional Authenticated Data 723 encryption parameter be ASCII(Encoded Protected Header || '.' || 724 BASE64URL(JWE AAD)). 726 15. Encrypt M using the CEK, the JWE Initialization Vector, and the 727 Additional Authenticated Data value using the specified content 728 encryption algorithm to create the JWE Ciphertext value and the 729 JWE Authentication Tag (which is the Authentication Tag output 730 from the encryption operation). 732 16. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext). 734 17. Compute the encoded authentication tag value BASE64URL(JWE 735 Authentication Tag). 737 18. If a JWE AAD value is present, compute the encoded AAD value 738 BASE64URL(JWE AAD). 740 19. Create the desired serialized output. The Compact Serialization 741 of this result is the string BASE64URL(UTF8(JWE Protected 742 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 743 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 744 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). The 745 JWE JSON Serialization is described in Section 7.2. 747 5.2. Message Decryption 749 The message decryption process is the reverse of the encryption 750 process. The order of the steps is not significant in cases where 751 there are no dependencies between the inputs and outputs of the 752 steps. If any of these steps fails, the encrypted content cannot be 753 validated. 755 When there are multiple recipients, it is an application decision 756 which of the recipients' encrypted content must successfully validate 757 for the JWE to be accepted. In some cases, encrypted content for all 758 recipients must successfully validate or the JWE will be considered 759 invalid. In other cases, only the encrypted content for a single 760 recipient needs to be successfully validated. However, in all cases, 761 the encrypted content for at least one recipient MUST successfully 762 validate or the JWE MUST be considered invalid. 764 1. Parse the JWE representation to extract the serialized values 765 for the components of the JWE. When using the JWE Compact 766 Serialization, these components are the base64url encoded 767 representations of the JWE Protected Header, the JWE Encrypted 768 Key, the JWE Initialization Vector, the JWE Ciphertext, and the 769 JWE Authentication Tag, and when using the JWE JSON 770 Serialization, these components also include the base64url 771 encoded representation of the JWE AAD and the unencoded JWE 772 Shared Unprotected Header and JWE Per-Recipient Unprotected 773 Header values. When using the JWE Compact Serialization, the 774 JWE Protected Header, the JWE Encrypted Key, the JWE 775 Initialization Vector, the JWE Ciphertext, and the JWE 776 Authentication Tag are represented as base64url encoded values 777 in that order, with each value being separated from the next by 778 a single period ('.') character, resulting in exactly four 779 delimiting period characters being used. The JWE JSON 780 Serialization is described in Section 7.2. 782 2. Base64url decode the encoded representations of the JWE 783 Protected Header, the JWE Encrypted Key, the JWE Initialization 784 Vector, the JWE Ciphertext, the JWE Authentication Tag, and the 785 JWE AAD, following the restriction that no line breaks, white 786 space, or other additional characters have been used. 788 3. Verify that the octet sequence resulting from decoding the 789 encoded JWE Protected Header is a UTF-8 encoded representation 790 of a completely valid JSON object conforming to RFC 7159 791 [RFC7159]; let the JWE Protected Header be this JSON object. 793 4. If using the JWE Compact Serialization, let the JOSE Header be 794 the JWE Protected Header. Otherwise, when using the JWE JSON 795 Serialization, let the JOSE Header be the union of the members 796 of the JWE Protected Header, the JWE Shared Unprotected Header 797 and the corresponding JWE Per-Recipient Unprotected Header, all 798 of which must be completely valid JSON objects. During this 799 step, verify that the resulting JOSE Header does not contain 800 duplicate Header Parameter names. When using the JWE JSON 801 Serialization, this restriction includes that the same Header 802 Parameter name also MUST NOT occur in distinct JSON object 803 values that together comprise the JOSE Header. 805 5. Verify that the implementation understands and can process all 806 fields that it is required to support, whether required by this 807 specification, by the algorithms being used, or by the "crit" 808 Header Parameter value, and that the values of those parameters 809 are also understood and supported. 811 6. Determine the Key Management Mode employed by the algorithm 812 specified by the "alg" (algorithm) Header Parameter. 814 7. Verify that the JWE uses a key known to the recipient. 816 8. When Direct Key Agreement or Key Agreement with Key Wrapping are 817 employed, use the key agreement algorithm to compute the value 818 of the agreed upon key. When Direct Key Agreement is employed, 819 let the Content Encryption Key (CEK) be the agreed upon key. 820 When Key Agreement with Key Wrapping is employed, the agreed 821 upon key will be used to decrypt the JWE Encrypted Key. 823 9. When Key Wrapping, Key Encryption, or Key Agreement with Key 824 Wrapping are employed, decrypt the JWE Encrypted Key to produce 825 the Content Encryption Key (CEK). The CEK MUST have a length 826 equal to that required for the content encryption algorithm. 827 Note that when there are multiple recipients, each recipient 828 will only be able decrypt any JWE Encrypted Key values that were 829 encrypted to a key in that recipient's possession. It is 830 therefore normal to only be able to decrypt one of the per- 831 recipient JWE Encrypted Key values to obtain the CEK value. 832 Also, see Section 11.5 for security considerations on mitigating 833 timing attacks. 835 10. When Direct Key Agreement or Direct Encryption are employed, 836 verify that the JWE Encrypted Key value is empty octet sequence. 838 11. When Direct Encryption is employed, let the Content Encryption 839 Key (CEK) be the shared symmetric key. 841 12. Record whether the CEK could be successfully determined for this 842 recipient or not. 844 13. If the JWE JSON Serialization is being used, repeat this process 845 (steps 4-12) for each recipient contained in the representation. 847 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 848 Protected Header)). If the JWE Protected Header is not present 849 (which can only happen when using the JWE JSON Serialization and 850 no "protected" member is present), let this value be the empty 851 string. 853 15. Let the Additional Authenticated Data encryption parameter be 854 ASCII(Encoded Protected Header). However if a JWE AAD value is 855 present (which can only be the case when using the JWE JSON 856 Serialization), instead let the Additional Authenticated Data 857 encryption parameter be ASCII(Encoded Protected Header || '.' || 858 BASE64URL(JWE AAD)). 860 16. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 861 Vector, the Additional Authenticated Data value, and the JWE 862 Authentication Tag (which is the Authentication Tag input to the 863 calculation) using the specified content encryption algorithm, 864 returning the decrypted plaintext and validating the JWE 865 Authentication Tag in the manner specified for the algorithm, 866 rejecting the input without emitting any decrypted output if the 867 JWE Authentication Tag is incorrect. 869 17. If a "zip" parameter was included, uncompress the decrypted 870 plaintext using the specified compression algorithm. 872 18. If there was no recipient for which all of the decryption steps 873 succeeded, then the JWE MUST be considered invalid. Otherwise, 874 output the Plaintext. In the JWE JSON Serialization case, also 875 return a result to the application indicating for which of the 876 recipients the decryption succeeded and failed. 878 Finally, note that it is an application decision which algorithms may 879 be used in a given context. Even if a JWE can be successfully 880 decrypted, unless the algorithms used in the JWE are acceptable to 881 the application, it SHOULD consider the JWE to be invalid. 883 5.3. String Comparison Rules 885 The string comparison rules for this specification are the same as 886 those defined in Section 5.3 of [JWS]. 888 6. Key Identification 890 The key identification methods for this specification are the same as 891 those defined in Section 6 of [JWS], except that the key being 892 identified is the public key to which the JWE was encrypted. 894 7. Serializations 896 JWEs use one of two serializations: the JWE Compact Serialization or 897 the JWE JSON Serialization. Applications using this specification 898 need to specify what serialization and serialization features are 899 used for that application. For instance, applications might specify 900 that only the JWE JSON Serialization is used, that only JWE JSON 901 Serialization support for a single recipient is used, or that support 902 for multiple recipients is used. JWE implementations only need to 903 implement the features needed for the applications they are designed 904 to support. 906 7.1. JWE Compact Serialization 908 The JWE Compact Serialization represents encrypted content as a 909 compact, URL-safe string. This string is: 911 BASE64URL(UTF8(JWE Protected Header)) || '.' || 912 BASE64URL(JWE Encrypted Key) || '.' || 913 BASE64URL(JWE Initialization Vector) || '.' || 914 BASE64URL(JWE Ciphertext) || '.' || 915 BASE64URL(JWE Authentication Tag) 917 Only one recipient is supported by the JWE Compact Serialization and 918 it provides no syntax to represent JWE Shared Unprotected Header, JWE 919 Per-Recipient Unprotected Header, or JWE AAD values. 921 7.2. JWE JSON Serialization 923 The JWE JSON Serialization represents encrypted content as a JSON 924 object. This representation is neither optimized for compactness nor 925 URL-safe. 927 Two closely related syntaxes are defined for the JWE JSON 928 Serialization: a fully general syntax, with which content can be 929 encrypted to more than one recipient, and a flattened syntax, which 930 is optimized for the single recipient case. 932 7.2.1. General JWE JSON Serialization Syntax 934 The following members are defined for use in top-level JSON objects 935 used for the fully general JWE JSON Serialization syntax: 937 protected 938 The "protected" member MUST be present and contain the value 939 BASE64URL(UTF8(JWE Protected Header)) when the JWE Protected 940 Header value is non-empty; otherwise, it MUST be absent. These 941 Header Parameter values are integrity protected. 943 unprotected 944 The "unprotected" member MUST be present and contain the value JWE 945 Shared Unprotected Header when the JWE Shared Unprotected Header 946 value is non-empty; otherwise, it MUST be absent. This value is 947 represented as an unencoded JSON object, rather than as a string. 948 These Header Parameter values are not integrity protected. 950 iv 951 The "iv" member MUST be present and contain the value 952 BASE64URL(JWE Initialization Vector) when the JWE Initialization 953 Vector value is non-empty; otherwise, it MUST be absent. 955 aad 956 The "aad" member MUST be present and contain the value 957 BASE64URL(JWE AAD)) when the JWE AAD value is non-empty; 958 otherwise, it MUST be absent. A JWE AAD value can be included to 959 supply a base64url encoded value to be integrity protected but not 960 encrypted. 962 ciphertext 963 The "ciphertext" member MUST be present and contain the value 964 BASE64URL(JWE Ciphertext). 966 tag 967 The "tag" member MUST be present and contain the value 968 BASE64URL(JWE Authentication Tag) when the JWE Authentication Tag 969 value is non-empty; otherwise, it MUST be absent. 971 recipients 972 The "recipients" member value MUST be an array of JSON objects. 973 Each object contains information specific to a single recipient. 974 This member MUST be present with exactly one array element per 975 recipient, even if some or all of the array element values are the 976 empty JSON object "{}" (which can happen when all Header Parameter 977 values are shared between all recipients and when no encrypted key 978 is used, such as when doing Direct Encryption). 980 The following members are defined for use in the JSON objects that 981 are elements of the "recipients" array: 983 header 984 The "header" member MUST be present and contain the value JWE Per- 985 Recipient Unprotected Header when the JWE Per-Recipient 986 Unprotected Header value is non-empty; otherwise, it MUST be 987 absent. This value is represented as an unencoded JSON object, 988 rather than as a string. These Header Parameter values are not 989 integrity protected. 991 encrypted_key 992 The "encrypted_key" member MUST be present and contain the value 993 BASE64URL(JWE Encrypted Key) when the JWE Encrypted Key value is 994 non-empty; otherwise, it MUST be absent. 996 At least one of the "header", "protected", and "unprotected" members 997 MUST be present so that "alg" and "enc" Header Parameter values are 998 conveyed for each recipient computation. 1000 Additional members can be present in both the JSON objects defined 1001 above; if not understood by implementations encountering them, they 1002 MUST be ignored. 1004 Some Header Parameters, including the "alg" parameter, can be shared 1005 among all recipient computations. Header Parameters in the JWE 1006 Protected Header and JWE Shared Unprotected Header values are shared 1007 among all recipients. 1009 The Header Parameter values used when creating or validating per- 1010 recipient Ciphertext and Authentication Tag values are the union of 1011 the three sets of Header Parameter values that may be present: (1) 1012 the JWE Protected Header represented in the "protected" member, (2) 1013 the JWE Shared Unprotected Header represented in the "unprotected" 1014 member, and (3) the JWE Per-Recipient Unprotected Header represented 1015 in the "header" member of the recipient's array element. The union 1016 of these sets of Header Parameters comprises the JOSE Header. The 1017 Header Parameter names in the three locations MUST be disjoint. 1019 Each JWE Encrypted Key value is computed using the parameters of the 1020 corresponding JOSE Header value in the same manner as for the JWE 1021 Compact Serialization. This has the desirable property that each JWE 1022 Encrypted Key value in the "recipients" array is identical to the 1023 value that would have been computed for the same parameter in the JWE 1024 Compact Serialization. Likewise, the JWE Ciphertext and JWE 1025 Authentication Tag values match those produced for the JWE Compact 1026 Serialization, provided that the JWE Protected Header value (which 1027 represents the integrity protected Header Parameter values) matches 1028 that used in the JWE Compact Serialization. 1030 All recipients use the same JWE Protected Header, JWE Initialization 1031 Vector, JWE Ciphertext, and JWE Authentication Tag values, when 1032 present, resulting in potentially significant space savings if the 1033 message is large. Therefore, all Header Parameters that specify the 1034 treatment of the Plaintext value MUST be the same for all recipients. 1035 This primarily means that the "enc" (encryption algorithm) Header 1036 Parameter value in the JOSE Header for each recipient and any 1037 parameters of that algorithm MUST be the same. 1039 In summary, the syntax of a JWE using the general JWE JSON 1040 Serialization is as follows: 1042 { 1043 "protected":"", 1044 "unprotected":, 1045 "recipients":[ 1046 {"header":, 1047 "encrypted_key":""}, 1048 ... 1049 {"header":, 1050 "encrypted_key":""}], 1051 "aad":"", 1052 "iv":"", 1053 "ciphertext":"", 1054 "tag":"" 1056 } 1058 See Appendix A.4 for an example JWE using the general JWE JSON 1059 Serialization syntax. 1061 7.2.2. Flattened JWE JSON Serialization Syntax 1063 The flattened JWE JSON Serialization syntax is based upon the general 1064 syntax, but flattens it, optimizing it for the single recipient case. 1065 It flattens it by removing the "recipients" member and instead 1066 placing those members defined for use in the "recipients" array (the 1067 "header" and "encrypted_key" members) in the top-level JSON object 1068 (at the same level as the "ciphertext" member). 1070 The "recipients" member MUST NOT be present when using this syntax. 1071 Other than this syntax difference, JWE JSON Serialization objects 1072 using the flattened syntax are processed identically to those using 1073 the general syntax. 1075 In summary, the syntax of a JWE using the flattened JWE JSON 1076 Serialization is as follows: 1078 { 1079 "protected":"", 1080 "unprotected":, 1081 "header":, 1082 "encrypted_key":"", 1083 "aad":"", 1084 "iv":"", 1085 "ciphertext":"", 1086 "tag":"" 1087 } 1089 Note that when using the flattened syntax, just as when using the 1090 general syntax, any unprotected Header Parameter values can reside in 1091 either the "unprotected" member or the "header" member, or in both. 1093 See Appendix A.5 for an example JWE using the flattened JWE JSON 1094 Serialization syntax. 1096 8. TLS Requirements 1098 The TLS requirements for this specification are the same as those 1099 defined in Section 8 of [JWS]. 1101 9. Distinguishing between JWS and JWE Objects 1103 There are several ways of distinguishing whether an object is a JWS 1104 or JWE. All these methods will yield the same result for all legal 1105 input values; they may yield different results for malformed inputs. 1107 o If the object is using the JWS Compact Serialization or the JWE 1108 Compact Serialization, the number of base64url encoded segments 1109 separated by period ('.') characters differs for JWSs and JWEs. 1110 JWSs have three segments separated by two period ('.') characters. 1111 JWEs have five segments separated by four period ('.') characters. 1113 o If the object is using the JWS JSON Serialization or the JWE JSON 1114 Serialization, the members used will be different. JWSs have a 1115 "payload" member and JWEs do not. JWEs have a "ciphertext" member 1116 and JWSs do not. 1118 o The JOSE Header for a JWS can be distinguished from the JOSE 1119 Header for a JWE by examining the "alg" (algorithm) Header 1120 Parameter value. If the value represents a digital signature or 1121 MAC algorithm, or is the value "none", it is for a JWS; if it 1122 represents a Key Encryption, Key Wrapping, Direct Key Agreement, 1123 Key Agreement with Key Wrapping, or Direct Encryption algorithm, 1124 it is for a JWE. (Extracting the "alg" value to examine is 1125 straightforward when using the JWS Compact Serialization or the 1126 JWE Compact Serialization and may be more difficult when using the 1127 JWS JSON Serialization or the JWE JSON Serialization.) 1129 o The JOSE Header for a JWS can also be distinguished from the JOSE 1130 Header for a JWE by determining whether an "enc" (encryption 1131 algorithm) member exists. If the "enc" member exists, it is a 1132 JWE; otherwise, it is a JWS. 1134 10. IANA Considerations 1136 10.1. JSON Web Signature and Encryption Header Parameters Registration 1138 This specification registers the Header Parameter names defined in 1139 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1140 Parameters registry defined in [JWS]. 1142 10.1.1. Registry Contents 1144 o Header Parameter Name: "alg" 1145 o Header Parameter Description: Algorithm 1146 o Header Parameter Usage Location(s): JWE 1147 o Change Controller: IESG 1148 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1150 o Header Parameter Name: "enc" 1151 o Header Parameter Description: Encryption Algorithm 1152 o Header Parameter Usage Location(s): JWE 1153 o Change Controller: IESG 1154 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1156 o Header Parameter Name: "zip" 1157 o Header Parameter Description: Compression Algorithm 1158 o Header Parameter Usage Location(s): JWE 1159 o Change Controller: IESG 1160 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1162 o Header Parameter Name: "jku" 1163 o Header Parameter Description: JWK Set URL 1164 o Header Parameter Usage Location(s): JWE 1165 o Change Controller: IESG 1166 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1168 o Header Parameter Name: "jwk" 1169 o Header Parameter Description: JSON Web Key 1170 o Header Parameter Usage Location(s): JWE 1171 o Change Controller: IESG 1172 o Specification document(s): Section 4.1.5 of [[ this document ]] 1174 o Header Parameter Name: "kid" 1175 o Header Parameter Description: Key ID 1176 o Header Parameter Usage Location(s): JWE 1177 o Change Controller: IESG 1178 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1180 o Header Parameter Name: "x5u" 1181 o Header Parameter Description: X.509 URL 1182 o Header Parameter Usage Location(s): JWE 1183 o Change Controller: IESG 1184 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1186 o Header Parameter Name: "x5c" 1187 o Header Parameter Description: X.509 Certificate Chain 1188 o Header Parameter Usage Location(s): JWE 1189 o Change Controller: IESG 1190 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1191 o Header Parameter Name: "x5t" 1192 o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint 1193 o Header Parameter Usage Location(s): JWE 1194 o Change Controller: IESG 1195 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1197 o Header Parameter Name: "x5t#S256" 1198 o Header Parameter Description: X.509 Certificate SHA-256 Thumbprint 1199 o Header Parameter Usage Location(s): JWE 1200 o Change Controller: IESG 1201 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1203 o Header Parameter Name: "typ" 1204 o Header Parameter Description: Type 1205 o Header Parameter Usage Location(s): JWE 1206 o Change Controller: IESG 1207 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1209 o Header Parameter Name: "cty" 1210 o Header Parameter Description: Content Type 1211 o Header Parameter Usage Location(s): JWE 1212 o Change Controller: IESG 1213 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1215 o Header Parameter Name: "crit" 1216 o Header Parameter Description: Critical 1217 o Header Parameter Usage Location(s): JWE 1218 o Change Controller: IESG 1219 o Specification Document(s): Section 4.1.13 of [[ this document ]] 1221 11. Security Considerations 1223 All of the security issues that are pertinent to any cryptographic 1224 application must be addressed by JWS/JWE/JWK agents. Among these 1225 issues are protecting the user's asymmetric private and symmetric 1226 secret keys and employing countermeasures to various attacks. 1228 All the security considerations in the JWS specification also apply 1229 to this specification. Likewise, all the security considerations in 1230 XML Encryption 1.1 [W3C.REC-xmlenc-core1-20130411] also apply, other 1231 than those that are XML specific. 1233 11.1. Key Entropy and Random Values 1235 See Section 10.1 of [JWS] for security considerations on key entropy 1236 and random values. In addition to the uses of random values listed 1237 there, note that random values are also used for content encryption 1238 keys (CEKs) and initialization vectors (IVs) when performing 1239 encryption. 1241 11.2. Key Protection 1243 See Section 10.2 of [JWS] for security considerations on key 1244 protection. In addition to the keys listed there that must be 1245 protected, implementations performing encryption must protect the key 1246 encryption key and the content encryption key. Compromise of the key 1247 encryption key may result in the disclosure of all contents protected 1248 with that key. Similarly, compromise of the content encryption key 1249 may result in disclosure of the associated encrypted content. 1251 11.3. Using Matching Algorithm Strengths 1253 Algorithms of matching strengths should be used together whenever 1254 possible. For instance, when AES Key Wrap is used with a given key 1255 size, using the same key size is recommended when AES GCM is also 1256 used. If the key encryption and content encryption algorithms are 1257 different, the effective security is determined by the weaker of the 1258 two algorithms. 1260 Also, see RFC 3766 [RFC3766] for information on determining strengths 1261 for public keys used for exchanging symmetric keys. 1263 11.4. Adaptive Chosen-Ciphertext Attacks 1265 When decrypting, particular care must be taken not to allow the JWE 1266 recipient to be used as an oracle for decrypting messages. RFC 3218 1267 [RFC3218] should be consulted for specific countermeasures to attacks 1268 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1269 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1270 formatting error that can be detected and used to recover the CEK 1271 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1272 particularly important to report all formatting errors to the CEK, 1273 Additional Authenticated Data, or ciphertext as a single error when 1274 the encrypted content is rejected. 1276 Additionally, this type of attack can be prevented by restricting the 1277 use of a key to a limited set of algorithms -- usually one. This 1278 means, for instance, that if the key is marked as being for 1279 "RSA-OAEP" only, any attempt to decrypt a message using the "RSA1_5" 1280 algorithm with that key should fail immediately due to invalid use of 1281 the key. 1283 11.5. Timing Attacks 1285 To mitigate the attacks described in RFC 3218 [RFC3218], the 1286 recipient MUST NOT distinguish between format, padding, and length 1287 errors of encrypted keys. It is strongly recommended, in the event 1288 of receiving an improperly formatted key, that the recipient 1289 substitute a randomly generated CEK and proceed to the next step, to 1290 mitigate timing attacks. 1292 12. References 1294 12.1. Normative References 1296 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1297 draft-ietf-jose-json-web-algorithms (work in progress), 1298 January 2015. 1300 [JWK] Jones, M., "JSON Web Key (JWK)", 1301 draft-ietf-jose-json-web-key (work in progress), 1302 January 2015. 1304 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1305 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1306 in progress), January 2015. 1308 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1309 version 1.3", RFC 1951, May 1996. 1311 [RFC20] Cerf, V., "ASCII format for Network Interchange", RFC 20, 1312 October 1969. 1314 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1315 Requirement Levels", BCP 14, RFC 2119, March 1997. 1317 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1318 10646", STD 63, RFC 3629, November 2003. 1320 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1321 RFC 4949, August 2007. 1323 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1324 Housley, R., and W. Polk, "Internet X.509 Public Key 1325 Infrastructure Certificate and Certificate Revocation List 1326 (CRL) Profile", RFC 5280, May 2008. 1328 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1329 Interchange Format", RFC 7159, March 2014. 1331 [UNICODE] The Unicode Consortium, "The Unicode Standard", 1991-, 1332 . 1334 12.2. Informative References 1336 [AES] National Institute of Standards and Technology (NIST), 1337 "Advanced Encryption Standard (AES)", FIPS PUB 197, 1338 November 2001. 1340 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1341 McGrew, D., Foley, J., and K. Paterson, "Authenticated 1342 Encryption with AES-CBC and HMAC-SHA", 1343 draft-mcgrew-aead-aes-cbc-hmac-sha2-05 (work in progress), 1344 July 2014. 1346 [I-D.rescorla-jsms] 1347 Rescorla, E. and J. Hildebrand, "JavaScript Message 1348 Security Format", draft-rescorla-jsms-00 (work in 1349 progress), March 2011. 1351 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1352 Encryption", September 2010. 1354 [NIST.800-38D] 1355 National Institute of Standards and Technology (NIST), 1356 "Recommendation for Block Cipher Modes of Operation: 1357 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 1358 December 2001. 1360 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1361 Cryptographic Message Syntax", RFC 3218, January 2002. 1363 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1364 Standards (PKCS) #1: RSA Cryptography Specifications 1365 Version 2.1", RFC 3447, February 2003. 1367 [RFC3766] Orman, H. and P. Hoffman, "Determining Strengths For 1368 Public Keys Used For Exchanging Symmetric Keys", BCP 86, 1369 RFC 3766, April 2004. 1371 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1372 Requirements for Security", BCP 106, RFC 4086, June 2005. 1374 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1375 RFC 5652, September 2009. 1377 [W3C.REC-xmlenc-core1-20130411] 1378 Eastlake, D., Reagle, J., Hirsch, F., and T. Roessler, 1379 "XML Encryption Syntax and Processing Version 1.1", World 1380 Wide Web Consortium Recommendation REC-xmlenc-core1- 1381 20130411, April 2013, 1382 . 1384 Appendix A. JWE Examples 1386 This section provides examples of JWE computations. 1388 A.1. Example JWE using RSAES OAEP and AES GCM 1390 This example encrypts the plaintext "The true sign of intelligence is 1391 not knowledge but imagination." to the recipient using RSAES OAEP for 1392 key encryption and AES GCM for content encryption. The 1393 representation of this plaintext (using JSON array notation) is: 1395 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1396 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1397 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1398 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1399 110, 97, 116, 105, 111, 110, 46] 1401 A.1.1. JOSE Header 1403 The following example JWE Protected Header declares that: 1405 o The Content Encryption Key is encrypted to the recipient using the 1406 RSAES OAEP algorithm to produce the JWE Encrypted Key. 1408 o Authenticated encryption is performed on the Plaintext using the 1409 AES GCM algorithm with a 256 bit key to produce the Ciphertext and 1410 the Authentication Tag. 1412 {"alg":"RSA-OAEP","enc":"A256GCM"} 1414 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1415 Header)) gives this value: 1417 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1419 A.1.2. Content Encryption Key (CEK) 1421 Generate a 256 bit random Content Encryption Key (CEK). In this 1422 example, the value (using JSON array notation) is: 1424 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1425 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1426 234, 64, 252] 1428 A.1.3. Key Encryption 1430 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1431 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1432 key represented in JSON Web Key [JWK] format below (with line breaks 1433 within values for display purposes only): 1435 {"kty":"RSA", 1436 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1437 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1438 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1439 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1440 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1441 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1442 "e":"AQAB", 1443 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1444 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1445 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1446 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1447 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1448 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ", 1449 "p":"1r52Xk46c-LsfB5P442p7atdPUrxQSy4mti_tZI3Mgf2EuFVbUoDBvaRQ- 1450 SWxkbkmoEzL7JXroSBjSrK3YIQgYdMgyAEPTPjXv_hI2_1eTSPVZfzL0lf 1451 fNn03IXqWF5MDFuoUYE0hzb2vhrlN_rKrbfDIwUbTrjjgieRbwC6Cl0", 1452 "q":"wLb35x7hmQWZsWJmB_vle87ihgZ19S8lBEROLIsZG4ayZVe9Hi9gDVCOBm 1453 UDdaDYVTSNx_8Fyw1YYa9XGrGnDew00J28cRUoeBB_jKI1oma0Orv1T9aX 1454 IWxKwd4gvxFImOWr3QRL9KEBRzk2RatUBnmDZJTIAfwTs0g68UZHvtc", 1455 "dp":"ZK-YwE7diUh0qR1tR7w8WHtolDx3MZ_OTowiFvgfeQ3SiresXjm9gZ5KL 1456 hMXvo-uz-KUJWDxS5pFQ_M0evdo1dKiRTjVw_x4NyqyXPM5nULPkcpU827 1457 rnpZzAJKpdhWAgqrXGKAECQH0Xt4taznjnd_zVpAmZZq60WPMBMfKcuE", 1458 "dq":"Dq0gfgJ1DdFGXiLvQEZnuKEN0UUmsJBxkjydc3j4ZYdBiMRAy86x0vHCj 1459 ywcMlYYg4yoC4YZa9hNVcsjqA3FeiL19rk8g6Qn29Tt0cj8qqyFpz9vNDB 1460 UfCAiJVeESOjJDZPYHdHY8v1b-o-Z2X5tvLx-TCekf7oxyeKDUqKWjis", 1461 "qi":"VIMpMYbPf47dT1w_zDUXfPimsSegnMOA1zTaX7aGk_8urY6R8-ZW1FxU7 1462 AlWAyLWybqq6t16VFd7hQd0y6flUK4SlOydB61gwanOsXGOAOv82cHq0E3 1463 eL4HrtZkUuKvnPrMnsUUFlfUdybVzxyjz9JF_XyaY14ardLSjf4L_FNY" 1464 } 1466 The resulting JWE Encrypted Key value is: 1468 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1469 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1470 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1471 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1472 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1473 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1474 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1475 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1476 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1477 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1478 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1479 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1480 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1481 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1482 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1483 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1484 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1485 117, 114, 135, 206] 1487 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1488 this value (with line breaks for display purposes only): 1490 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1491 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1492 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1493 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1494 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1495 6UklfCpIMfIjf7iGdXKHzg 1497 A.1.4. Initialization Vector 1499 Generate a random 96 bit JWE Initialization Vector. In this example, 1500 the value is: 1502 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1504 Encoding this JWE Initialization Vector as BASE64URL(JWE 1505 Initialization Vector) gives this value: 1507 48V1_ALb6US04U3b 1509 A.1.5. Additional Authenticated Data 1511 Let the Additional Authenticated Data encryption parameter be 1512 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1514 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1515 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1516 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1518 A.1.6. Content Encryption 1520 Perform authenticated encryption on the Plaintext with the AES GCM 1521 algorithm using the CEK as the encryption key, the JWE Initialization 1522 Vector, and the Additional Authenticated Data value above, requesting 1523 a 128 bit Authentication Tag output. The resulting Ciphertext is: 1525 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1526 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1527 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1528 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1529 160, 109, 64, 63, 192] 1531 The resulting Authentication Tag value is: 1533 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1534 210, 145] 1536 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1537 value (with line breaks for display purposes only): 1539 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1540 SdiwkIr3ajwQzaBtQD_A 1542 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1543 Tag) gives this value: 1545 XFBoMYUZodetZdvTiFvSkQ 1547 A.1.7. Complete Representation 1549 Assemble the final representation: The Compact Serialization of this 1550 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1551 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1552 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1553 Authentication Tag). 1555 The final result in this example (with line breaks for display 1556 purposes only) is: 1558 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1559 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1560 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1561 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1562 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1563 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1564 6UklfCpIMfIjf7iGdXKHzg. 1565 48V1_ALb6US04U3b. 1566 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1567 SdiwkIr3ajwQzaBtQD_A. 1568 XFBoMYUZodetZdvTiFvSkQ 1570 A.1.8. Validation 1572 This example illustrates the process of creating a JWE with RSAES 1573 OAEP for key encryption and AES GCM for content encryption. These 1574 results can be used to validate JWE decryption implementations for 1575 these algorithms. Note that since the RSAES OAEP computation 1576 includes random values, the encryption results above will not be 1577 completely reproducible. However, since the AES GCM computation is 1578 deterministic, the JWE Encrypted Ciphertext values will be the same 1579 for all encryptions performed using these inputs. 1581 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1583 This example encrypts the plaintext "Live long and prosper." to the 1584 recipient using RSAES-PKCS1-V1_5 for key encryption and 1585 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1586 of this plaintext (using JSON array notation) is: 1588 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1589 112, 114, 111, 115, 112, 101, 114, 46] 1591 A.2.1. JOSE Header 1593 The following example JWE Protected Header declares that: 1595 o The Content Encryption Key is encrypted to the recipient using the 1596 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. 1598 o Authenticated encryption is performed on the Plaintext using the 1599 AES_128_CBC_HMAC_SHA_256 algorithm to produce the Ciphertext and 1600 the Authentication Tag. 1602 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1604 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1605 Header)) gives this value: 1607 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1609 A.2.2. Content Encryption Key (CEK) 1611 Generate a 256 bit random Content Encryption Key (CEK). In this 1612 example, the key value is: 1614 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1615 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1616 44, 207] 1618 A.2.3. Key Encryption 1620 Encrypt the CEK with the recipient's public key using the RSAES- 1621 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1622 uses the RSA key represented in JSON Web Key [JWK] format below (with 1623 line breaks within values for display purposes only): 1625 {"kty":"RSA", 1626 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1627 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1628 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1629 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1630 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1631 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1632 "e":"AQAB", 1633 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1634 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1635 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1636 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1637 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1638 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ", 1639 "p":"9gY2w6I6S6L0juEKsbeDAwpd9WMfgqFoeA9vEyEUuk4kLwBKcoe1x4HG68 1640 ik918hdDSE9vDQSccA3xXHOAFOPJ8R9EeIAbTi1VwBYnbTp87X-xcPWlEP 1641 krdoUKW60tgs1aNd_Nnc9LEVVPMS390zbFxt8TN_biaBgelNgbC95sM", 1642 "q":"uKlCKvKv_ZJMVcdIs5vVSU_6cPtYI1ljWytExV_skstvRSNi9r66jdd9-y 1643 BhVfuG4shsp2j7rGnIio901RBeHo6TPKWVVykPu1iYhQXw1jIABfw-MVsN 1644 -3bQ76WLdt2SDxsHs7q7zPyUyHXmps7ycZ5c72wGkUwNOjYelmkiNS0", 1645 "dp":"w0kZbV63cVRvVX6yk3C8cMxo2qCM4Y8nsq1lmMSYhG4EcL6FWbX5h9yuv 1646 ngs4iLEFk6eALoUS4vIWEwcL4txw9LsWH_zKI-hwoReoP77cOdSL4AVcra 1647 Hawlkpyd2TWjE5evgbhWtOxnZee3cXJBkAi64Ik6jZxbvk-RR3pEhnCs", 1648 "dq":"o_8V14SezckO6CNLKs_btPdFiO9_kC1DsuUTd2LAfIIVeMZ7jn1Gus_Ff 1649 7B7IVx3p5KuBGOVF8L-qifLb6nQnLysgHDh132NDioZkhH7mI7hPG-PYE_ 1650 odApKdnqECHWw0J-F0JWnUd6D2B_1TvF9mXA2Qx-iGYn8OVV1Bsmp6qU", 1651 "qi":"eNho5yRBEBxhGBtQRww9QirZsB66TrfFReG_CcteI1aCneT0ELGhYlRlC 1652 tUkTRclIfuEPmNsNDPbLoLqqCVznFbvdB7x-Tl-m0l_eFTj2KiqwGqE9PZ 1653 B9nNTwMVvH3VRRSLWACvPnSiwP8N5Usy-WRXS-V7TbpxIhvepTfE0NNo" 1654 } 1656 The resulting JWE Encrypted Key value is: 1658 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1659 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1660 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1661 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1662 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1663 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1664 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1665 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1666 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1667 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1668 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1669 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1670 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1671 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1672 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1673 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1674 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1675 146, 114, 165, 204, 71, 136, 41, 252] 1677 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1678 this value (with line breaks for display purposes only): 1680 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1681 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1682 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1683 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1684 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1685 -B3oWh2TbqmScqXMR4gp_A 1687 A.2.4. Initialization Vector 1689 Generate a random 128 bit JWE Initialization Vector. In this 1690 example, the value is: 1692 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1693 101] 1695 Encoding this JWE Initialization Vector as BASE64URL(JWE 1696 Initialization Vector) gives this value: 1698 AxY8DCtDaGlsbGljb3RoZQ 1700 A.2.5. Additional Authenticated Data 1702 Let the Additional Authenticated Data encryption parameter be 1703 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1705 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1706 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1707 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1708 50, 73, 110, 48] 1710 A.2.6. Content Encryption 1712 Perform authenticated encryption on the Plaintext with the 1713 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1714 key, the JWE Initialization Vector, and the Additional Authenticated 1715 Data value above. The steps for doing this using the values from 1716 Appendix A.3 are detailed in Appendix B. The resulting Ciphertext 1717 is: 1719 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1720 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1721 112, 56, 102] 1723 The resulting Authentication Tag value is: 1725 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1726 191] 1728 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1729 value: 1731 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1733 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1734 Tag) gives this value: 1736 9hH0vgRfYgPnAHOd8stkvw 1738 A.2.7. Complete Representation 1740 Assemble the final representation: The Compact Serialization of this 1741 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1742 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1743 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1744 Authentication Tag). 1746 The final result in this example (with line breaks for display 1747 purposes only) is: 1749 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1750 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1751 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1752 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1753 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1754 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1755 -B3oWh2TbqmScqXMR4gp_A. 1756 AxY8DCtDaGlsbGljb3RoZQ. 1757 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1758 9hH0vgRfYgPnAHOd8stkvw 1760 A.2.8. Validation 1762 This example illustrates the process of creating a JWE with RSAES- 1763 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1764 encryption. These results can be used to validate JWE decryption 1765 implementations for these algorithms. Note that since the RSAES- 1766 PKCS1-V1_5 computation includes random values, the encryption results 1767 above will not be completely reproducible. However, since the AES 1768 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1769 will be the same for all encryptions performed using these inputs. 1771 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1773 This example encrypts the plaintext "Live long and prosper." to the 1774 recipient using AES Key Wrap for key encryption and 1775 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1776 of this plaintext (using JSON array notation) is: 1778 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1779 112, 114, 111, 115, 112, 101, 114, 46] 1781 A.3.1. JOSE Header 1783 The following example JWE Protected Header declares that: 1785 o The Content Encryption Key is encrypted to the recipient using the 1786 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1787 Encrypted Key. 1789 o Authenticated encryption is performed on the Plaintext using the 1790 AES_128_CBC_HMAC_SHA_256 algorithm to produce the Ciphertext and 1791 the Authentication Tag. 1793 {"alg":"A128KW","enc":"A128CBC-HS256"} 1795 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1796 Header)) gives this value: 1798 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1800 A.3.2. Content Encryption Key (CEK) 1802 Generate a 256 bit random Content Encryption Key (CEK). In this 1803 example, the value is: 1805 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1806 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1807 44, 207] 1809 A.3.3. Key Encryption 1811 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1812 algorithm to produce the JWE Encrypted Key. This example uses the 1813 symmetric key represented in JSON Web Key [JWK] format below: 1815 {"kty":"oct", 1816 "k":"GawgguFyGrWKav7AX4VKUg" 1817 } 1819 The resulting JWE Encrypted Key value is: 1821 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1822 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1823 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1825 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1826 this value: 1828 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1830 A.3.4. Initialization Vector 1832 Generate a random 128 bit JWE Initialization Vector. In this 1833 example, the value is: 1835 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1836 101] 1838 Encoding this JWE Initialization Vector as BASE64URL(JWE 1839 Initialization Vector) gives this value: 1841 AxY8DCtDaGlsbGljb3RoZQ 1843 A.3.5. Additional Authenticated Data 1845 Let the Additional Authenticated Data encryption parameter be 1846 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1848 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1849 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1850 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1851 110, 48] 1853 A.3.6. Content Encryption 1855 Perform authenticated encryption on the Plaintext with the 1856 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1857 key, the JWE Initialization Vector, and the Additional Authenticated 1858 Data value above. The steps for doing this using the values from 1859 this example are detailed in Appendix B. The resulting Ciphertext 1860 is: 1862 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1863 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1864 112, 56, 102] 1866 The resulting Authentication Tag value is: 1868 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1869 194, 85] 1871 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1872 value: 1874 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1876 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1877 Tag) gives this value: 1879 U0m_YmjN04DJvceFICbCVQ 1881 A.3.7. Complete Representation 1883 Assemble the final representation: The Compact Serialization of this 1884 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1885 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1886 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1887 Authentication Tag). 1889 The final result in this example (with line breaks for display 1890 purposes only) is: 1892 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1893 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1894 AxY8DCtDaGlsbGljb3RoZQ. 1895 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1896 U0m_YmjN04DJvceFICbCVQ 1898 A.3.8. Validation 1900 This example illustrates the process of creating a JWE with AES Key 1901 Wrap for key encryption and AES GCM for content encryption. These 1902 results can be used to validate JWE decryption implementations for 1903 these algorithms. Also, since both the AES Key Wrap and AES GCM 1904 computations are deterministic, the resulting JWE value will be the 1905 same for all encryptions performed using these inputs. Since the 1906 computation is reproducible, these results can also be used to 1907 validate JWE encryption implementations for these algorithms. 1909 A.4. Example JWE using General JWE JSON Serialization 1911 This section contains an example using the general JWE JSON 1912 Serialization syntax. This example demonstrates the capability for 1913 encrypting the same plaintext to multiple recipients. 1915 Two recipients are present in this example. The algorithm and key 1916 used for the first recipient are the same as that used in 1917 Appendix A.2. The algorithm and key used for the second recipient 1918 are the same as that used in Appendix A.3. The resulting JWE 1919 Encrypted Key values are therefore the same; those computations are 1920 not repeated here. 1922 The Plaintext, the Content Encryption Key (CEK), JWE Initialization 1923 Vector, and JWE Protected Header are shared by all recipients (which 1924 must be the case, since the Ciphertext and Authentication Tag are 1925 also shared). 1927 A.4.1. JWE Per-Recipient Unprotected Headers 1929 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1930 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1931 encrypt the CEK. Key ID values are supplied for both keys. The two 1932 per-recipient header values used to represent these algorithms and 1933 Key IDs are: 1935 {"alg":"RSA1_5","kid":"2011-04-29"} 1937 and 1939 {"alg":"A128KW","kid":"7"} 1941 A.4.2. JWE Protected Header 1943 Authenticated encryption is performed on the Plaintext using the 1944 AES_128_CBC_HMAC_SHA_256 algorithm to produce the common JWE 1945 Ciphertext and JWE Authentication Tag values. The JWE Protected 1946 Header value representing this is: 1948 {"enc":"A128CBC-HS256"} 1950 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1951 Header)) gives this value: 1953 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1955 A.4.3. JWE Unprotected Header 1957 This JWE uses the "jku" Header Parameter to reference a JWK Set. This 1958 is represented in the following JWE Unprotected Header value as: 1960 {"jku":"https://server.example.com/keys.jwks"} 1962 A.4.4. Complete JOSE Header Values 1964 Combining the per-recipient, protected, and unprotected header values 1965 supplied, the JOSE Header values used for the first and second 1966 recipient respectively are: 1968 {"alg":"RSA1_5", 1969 "kid":"2011-04-29", 1970 "enc":"A128CBC-HS256", 1971 "jku":"https://server.example.com/keys.jwks"} 1973 and 1975 {"alg":"A128KW", 1976 "kid":"7", 1977 "enc":"A128CBC-HS256", 1978 "jku":"https://server.example.com/keys.jwks"} 1980 A.4.5. Additional Authenticated Data 1982 Let the Additional Authenticated Data encryption parameter be 1983 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1985 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1986 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1988 A.4.6. Content Encryption 1990 Perform authenticated encryption on the Plaintext with the 1991 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1992 key, the JWE Initialization Vector, and the Additional Authenticated 1993 Data value above. The steps for doing this using the values from 1994 Appendix A.3 are detailed in Appendix B. The resulting Ciphertext 1995 is: 1997 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1998 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1999 112, 56, 102] 2001 The resulting Authentication Tag value is: 2003 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 2004 207] 2006 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 2007 value: 2009 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 2011 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 2012 Tag) gives this value: 2014 Mz-VPPyU4RlcuYv1IwIvzw 2016 A.4.7. Complete JWE JSON Serialization Representation 2018 The complete JWE JSON Serialization for these values is as follows 2019 (with line breaks within values for display purposes only): 2021 { 2022 "protected": 2023 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 2024 "unprotected": 2025 {"jku":"https://server.example.com/keys.jwks"}, 2026 "recipients":[ 2027 {"header": 2028 {"alg":"RSA1_5","kid":"2011-04-29"}, 2029 "encrypted_key": 2030 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 2031 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 2032 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 2033 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 2034 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 2035 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 2036 {"header": 2037 {"alg":"A128KW","kid":"7"}, 2038 "encrypted_key": 2039 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 2040 "iv": 2041 "AxY8DCtDaGlsbGljb3RoZQ", 2042 "ciphertext": 2043 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 2044 "tag": 2045 "Mz-VPPyU4RlcuYv1IwIvzw" 2046 } 2048 A.5. Example JWE using Flattened JWE JSON Serialization 2050 This section contains an example using the flattened JWE JSON 2051 Serialization syntax. This example demonstrates the capability for 2052 encrypting the plaintext to a single recipient in a flattened JSON 2053 structure. 2055 The values in this example are the same as those for the second 2056 recipient of the previous example in Appendix A.4. 2058 The complete JWE JSON Serialization for these values is as follows 2059 (with line breaks within values for display purposes only): 2061 { 2062 "protected": 2063 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 2064 "unprotected": 2065 {"jku":"https://server.example.com/keys.jwks"}, 2066 "header": 2067 {"alg":"A128KW","kid":"7"}, 2068 "encrypted_key": 2069 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ", 2070 "iv": 2071 "AxY8DCtDaGlsbGljb3RoZQ", 2072 "ciphertext": 2073 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 2074 "tag": 2075 "Mz-VPPyU4RlcuYv1IwIvzw" 2076 } 2078 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 2080 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 2081 authenticated encryption computation using the values from the 2082 example in Appendix A.3. As described where this algorithm is 2083 defined in Sections 5.2 and 5.2.3 of JWA, the AES_CBC_HMAC_SHA2 2084 family of algorithms are implemented using Advanced Encryption 2085 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #7 2086 padding to perform the encryption and an HMAC SHA-2 function to 2087 perform the integrity calculation - in this case, HMAC SHA-256. 2089 B.1. Extract MAC_KEY and ENC_KEY from Key 2091 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example 2092 (using JSON array notation) is: 2094 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 2095 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 2096 44, 207] 2098 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 2099 which is: 2101 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 2102 206] 2104 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 2105 is: 2107 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 2108 207] 2110 Note that the MAC key comes before the encryption key in the input 2111 key K; this is in the opposite order of the algorithm names in the 2112 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 2114 B.2. Encrypt Plaintext to Create Ciphertext 2116 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 2117 using PKCS #7 padding using the ENC_KEY above. The Plaintext in this 2118 example is: 2120 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 2121 112, 114, 111, 115, 112, 101, 114, 46] 2123 The encryption result is as follows, which is the Ciphertext output: 2125 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 2126 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 2127 112, 56, 102] 2129 B.3. 64 Bit Big Endian Representation of AAD Length 2131 The Additional Authenticated Data (AAD) in this example is: 2133 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2134 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2135 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2136 110, 48] 2138 This AAD is 51 bytes long, which is 408 bits long. The octet string 2139 AL, which is the number of bits in AAD expressed as a big endian 64 2140 bit unsigned integer is: 2142 [0, 0, 0, 0, 0, 0, 1, 152] 2144 B.4. Initialization Vector Value 2146 The Initialization Vector value used in this example is: 2148 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 2149 101] 2151 B.5. Create Input to HMAC Computation 2153 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 2154 the AL value. The result of this concatenation is: 2156 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2157 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2158 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2159 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 2160 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 2161 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 2162 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 2164 B.6. Compute HMAC Value 2166 Compute the HMAC SHA-256 of the concatenated value above. This 2167 result M is: 2169 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2170 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 2171 86, 229, 116] 2173 B.7. Truncate HMAC Value to Create Authentication Tag 2175 Use the first half (128 bits) of the HMAC output M as the 2176 Authentication Tag output T. This truncated value is: 2178 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2179 194, 85] 2181 Appendix C. Acknowledgements 2183 Solutions for encrypting JSON content were also explored by JSON 2184 Simple Encryption [JSE] and JavaScript Message Security Format 2185 [I-D.rescorla-jsms], both of which significantly influenced this 2186 draft. This draft attempts to explicitly reuse as many of the 2187 relevant concepts from XML Encryption 1.1 2188 [W3C.REC-xmlenc-core1-20130411] and RFC 5652 [RFC5652] as possible, 2189 while utilizing simple, compact JSON-based data structures. 2191 Special thanks are due to John Bradley, Eric Rescorla, and Nat 2192 Sakimura for the discussions that helped inform the content of this 2193 specification, to Eric Rescorla and Joe Hildebrand for allowing the 2194 reuse of text from [I-D.rescorla-jsms] in this document, and to Eric 2195 Rescorla for co-authoring many drafts of this specification. 2197 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2198 Jay for validating the examples in this specification. 2200 This specification is the work of the JOSE Working Group, which 2201 includes dozens of active and dedicated participants. In particular, 2202 the following individuals contributed ideas, feedback, and wording 2203 that influenced this specification: 2205 Richard Barnes, John Bradley, Brian Campbell, Alissa Cooper, Breno de 2206 Medeiros, Stephen Farrell, Dick Hardt, Jeff Hodges, Russ Housley, 2207 Edmund Jay, Scott Kelly, Stephen Kent, Barry Leiba, James Manger, 2208 Matt Miller, Kathleen Moriarty, Tony Nadalin, Hideki Nara, Axel 2209 Nennker, Ray Polk, Emmanuel Raviart, Eric Rescorla, Pete Resnick, Nat 2210 Sakimura, Jim Schaad, Hannes Tschofenig, and Sean Turner. 2212 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2213 Sean Turner, Stephen Farrell, and Kathleen Moriarty served as 2214 Security area directors during the creation of this specification. 2216 Appendix D. Document History 2218 [[ to be removed by the RFC Editor before publication as an RFC ]] 2220 -40 2222 o Clarified the definitions of UTF8(STRING) and ASCII(STRING). 2224 -39 2226 o No changes were made, other than to the version number and date. 2228 -38 2230 o Replaced uses of the phrases "JWS object" and "JWE object" with 2231 "JWS" and "JWE". 2233 o Added member names to the JWE JSON Serialization Overview. 2235 o Applied other minor editorial improvements. 2237 -37 2238 o Restricted algorithm names to using only ASCII characters. 2240 o When describing actions taken as a result of validation failures, 2241 changed statements about rejecting the JWE to statements about 2242 considering the JWE to be invalid. 2244 o Added the CRT parameter values to example RSA private key 2245 representations. 2247 -36 2249 o Defined a flattened JWE JSON Serialization syntax, which is 2250 optimized for the single recipient case. 2252 o Clarified where white space and line breaks may occur in JSON 2253 objects by referencing Section 2 of RFC 7159. 2255 -35 2257 o Addressed AppsDir reviews by Ray Polk. 2259 -34 2261 o Addressed IESG review comments by Barry Leiba, Alissa Cooper, Pete 2262 Resnick, Stephen Farrell, and Richard Barnes. 2264 -33 2266 o Noted that certificate thumbprints are also sometimes known as 2267 certificate fingerprints. 2269 o Changed to use the term "authenticated encryption" instead of 2270 "encryption", where appropriate. 2272 o Acknowledged additional contributors. 2274 -32 2276 o Addressed Gen-ART review comments by Russ Housley. 2278 o Addressed secdir review comments by Scott Kelly, Tero Kivinen, and 2279 Stephen Kent. 2281 -31 2283 o Updated the reference to draft-mcgrew-aead-aes-cbc-hmac-sha2. 2285 -30 2286 o Added subsection headings within the Overview section for the two 2287 serializations. 2289 o Added references and cleaned up the reference syntax in a few 2290 places. 2292 o Applied minor wording changes to the Security Considerations 2293 section and made other local editorial improvements. 2295 -29 2297 o Replaced the terms JWS Header, JWE Header, and JWT Header with a 2298 single JOSE Header term defined in the JWS specification. This 2299 also enabled a single Header Parameter definition to be used and 2300 reduced other areas of duplication between specifications. 2302 -28 2304 o Specified the use of PKCS #7 padding with AES CBC, rather than 2305 PKCS #5. (PKCS #7 is a superset of PKCS #5, and is appropriate 2306 for the 16 octet blocks used by AES CBC.) 2308 o Revised the introduction to the Security Considerations section. 2309 Also moved a security consideration item here from the JWA draft. 2311 -27 2313 o Described additional security considerations. 2315 o Added the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) header 2316 parameter. 2318 -26 2320 o Noted that octet sequences are depicted using JSON array notation. 2322 o Updated references, including to W3C specifications. 2324 -25 2326 o Corrected two external section number references that had changed. 2328 o Corrected a typo in an algorithm name in the prose of an example. 2330 -24 2332 o Corrected complete JSON Serialization example. 2334 o Replaced uses of the term "associated data" wherever it was used 2335 to refer to a data value with "additional authenticated data", 2336 since both terms were being used as synonyms, causing confusion. 2338 o Updated the JSON reference to RFC 7159. 2340 o Thanked Eric Rescorla for helping to author of most of the drafts 2341 of this specification and removed him from the current author 2342 list. 2344 -23 2346 o Corrected a use of the word "payload" to "plaintext". 2348 -22 2350 o Corrected RFC 2119 terminology usage. 2352 o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. 2354 -21 2356 o Changed some references from being normative to informative, 2357 addressing issue #90. 2359 o Applied review comments to the JSON Serialization section, 2360 addressing issue #178. 2362 -20 2364 o Made terminology definitions more consistent, addressing issue 2365 #165. 2367 o Restructured the JSON Serialization section to call out the 2368 parameters used in hanging lists, addressing issue #178. 2370 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 2371 addressing issue #90. 2373 -19 2375 o Reordered the key selection parameters. 2377 -18 2379 o Updated the mandatory-to-implement (MTI) language to say that 2380 applications using this specification need to specify what 2381 serialization and serialization features are used for that 2382 application, addressing issue #176. 2384 o Changes to address editorial and minor issues #89, #135, #165, 2385 #174, #175, #177, #179, and #180. 2387 o Used Header Parameter Description registry field. 2389 -17 2391 o Refined the "typ" and "cty" definitions to always be MIME Media 2392 Types, with the omission of "application/" prefixes recommended 2393 for brevity, addressing issue #50. 2395 o Updated the mandatory-to-implement (MTI) language to say that 2396 general-purpose implementations must implement the single 2397 recipient case for both serializations whereas special-purpose 2398 implementations can implement just one serialization if that meets 2399 the needs of the use cases the implementation is designed for, 2400 addressing issue #176. 2402 o Explicitly named all the logical components of a JWE and defined 2403 the processing rules and serializations in terms of those 2404 components, addressing issues #60, #61, and #62. 2406 o Replaced verbose repetitive phases such as "base64url encode the 2407 octets of the UTF-8 representation of X" with mathematical 2408 notation such as "BASE64URL(UTF8(X))". 2410 o Header Parameters and processing rules occurring in both JWS and 2411 JWE are now referenced in JWS by JWE, rather than duplicated, 2412 addressing issue #57. 2414 o Terms used in multiple documents are now defined in one place and 2415 incorporated by reference. Some lightly used or obvious terms 2416 were also removed. This addresses issue #58. 2418 -16 2420 o Changes to address editorial and minor issues #163, #168, #169, 2421 #170, #172, and #173. 2423 -15 2425 o Clarified that it is an application decision which recipients' 2426 encrypted content must successfully validate for the JWE to be 2427 accepted, addressing issue #35. 2429 o Changes to address editorial issues #34, #164, and #169. 2431 -14 2433 o Clarified that the "protected", "unprotected", "header", "iv", 2434 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2435 JSON Serialization when their values would be empty. Stated that 2436 the "recipients" array must always be present. 2438 -13 2440 o Added an "aad" (Additional Authenticated Data) member for the JWE 2441 JSON Serialization, enabling Additional Authenticated Data to be 2442 supplied that is not double base64url encoded, addressing issue 2443 #29. 2445 -12 2447 o Clarified that the "typ" and "cty" header parameters are used in 2448 an application-specific manner and have no effect upon the JWE 2449 processing. 2451 o Replaced the MIME types "application/jwe+json" and 2452 "application/jwe" with "application/jose+json" and 2453 "application/jose". 2455 o Stated that recipients MUST either reject JWEs with duplicate 2456 Header Parameter Names or use a JSON parser that returns only the 2457 lexically last duplicate member name. 2459 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2460 be with the algorithm descriptions that use them. 2462 o Added a Serializations section with parallel treatment of the JWE 2463 Compact Serialization and the JWE JSON Serialization and also 2464 moved the former Implementation Considerations content there. 2466 o Restored use of the term "AEAD". 2468 o Changed terminology from "block encryption" to "content 2469 encryption". 2471 -11 2473 o Added Key Identification section. 2475 o Removed the Encrypted Key value from the AAD computation since it 2476 is already effectively integrity protected by the encryption 2477 process. The AAD value now only contains the representation of 2478 the JWE Encrypted Header. 2480 o For the JWE JSON Serialization, enable Header Parameter values to 2481 be specified in any of three parameters: the "protected" member 2482 that is integrity protected and shared among all recipients, the 2483 "unprotected" member that is not integrity protected and shared 2484 among all recipients, and the "header" member that is not 2485 integrity protected and specific to a particular recipient. (This 2486 does not affect the JWE Compact Serialization, in which all Header 2487 Parameter values are in a single integrity protected JWE Header 2488 value.) 2490 o Shortened the names "authentication_tag" to "tag" and 2491 "initialization_vector" to "iv" in the JWE JSON Serialization, 2492 addressing issue #20. 2494 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2496 o Removed suggested compact serialization for multiple recipients. 2498 o Changed the MIME type name "application/jwe-js" to 2499 "application/jwe+json", addressing issue #22. 2501 o Tightened the description of the "crit" (critical) header 2502 parameter. 2504 -10 2506 o Changed the JWE processing rules for multiple recipients so that a 2507 single AAD value contains the header parameters and encrypted key 2508 values for all the recipients, enabling AES GCM to be safely used 2509 for multiple recipients. 2511 o Added an appendix suggesting a possible compact serialization for 2512 JWEs with multiple recipients. 2514 -09 2516 o Added JWE JSON Serialization, as specified by 2517 draft-jones-jose-jwe-json-serialization-04. 2519 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2520 parameter value. 2522 o Defined that the default action for header parameters that are not 2523 understood is to ignore them unless specifically designated as 2524 "MUST be understood" or included in the new "crit" (critical) 2525 header parameter list. This addressed issue #6. 2527 o Corrected "x5c" description. This addressed issue #12. 2529 o Changed from using the term "byte" to "octet" when referring to 8 2530 bit values. 2532 o Added Key Management Mode definitions to terminology section and 2533 used the defined terms to provide clearer key management 2534 instructions. This addressed issue #5. 2536 o Added text about preventing the recipient from behaving as an 2537 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2539 o Changed from using the term "Integrity Value" to "Authentication 2540 Tag". 2542 o Changed member name from "integrity_value" to "authentication_tag" 2543 in the JWE JSON Serialization. 2545 o Removed Initialization Vector from the AAD value since it is 2546 already integrity protected by all of the authenticated encryption 2547 algorithms specified in the JWA specification. 2549 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2550 and "A256CBC-HS512". The new algorithms perform the same 2551 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2552 but with the Initialization Vector and Authentication Tag values 2553 remaining separate from the Ciphertext value in the output 2554 representation. Also deleted the header parameters "epu" 2555 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2556 they are no longer used. 2558 -08 2560 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2561 since the term AEAD in the RFC 5116 sense implied the use of a 2562 particular data representation, rather than just referring to the 2563 class of algorithms that perform authenticated encryption with 2564 associated data. 2566 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2567 Tschofenig. Many of these simplified the terminology used. 2569 o Clarified statements of the form "This header parameter is 2570 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2572 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2573 Web Signature and Encryption Header Parameters registry. 2575 o Added seriesInfo information to Internet Draft references. 2577 -07 2579 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2581 o Updated values for example AES CBC calculations. 2583 o Made several local editorial changes to clean up loose ends left 2584 over from to the decision to only support block encryption methods 2585 providing integrity. One of these changes was to explicitly state 2586 that the "enc" (encryption method) algorithm must be an 2587 Authenticated Encryption algorithm with a specified key length. 2589 -06 2591 o Removed the "int" and "kdf" parameters and defined the new 2592 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2593 "A256CBC+HS512" to replace the former uses of AES CBC, which 2594 required the use of separate integrity and key derivation 2595 functions. 2597 o Included additional values in the Concat KDF calculation -- the 2598 desired output size and the algorithm value, and optionally 2599 PartyUInfo and PartyVInfo values. Added the optional header 2600 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2601 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2602 PartyVInfo). Updated the KDF examples accordingly. 2604 o Promoted Initialization Vector from being a header parameter to 2605 being a top-level JWE element. This saves approximately 16 bytes 2606 in the compact serialization, which is a significant savings for 2607 some use cases. Promoting the Initialization Vector out of the 2608 header also avoids repeating this shared value in the JSON 2609 serialization. 2611 o Changed "x5c" (X.509 Certificate Chain) representation from being 2612 a single string to being an array of strings, each containing a 2613 single base64 encoded DER certificate value, representing elements 2614 of the certificate chain. 2616 o Added an AES Key Wrap example. 2618 o Reordered the encryption steps so CMK creation is first, when 2619 required. 2621 o Correct statements in examples about which algorithms produce 2622 reproducible results. 2624 -05 2626 o Support both direct encryption using a shared or agreed upon 2627 symmetric key, and the use of a shared or agreed upon symmetric 2628 key to key wrap the CMK. 2630 o Added statement that "StringOrURI values are compared as case- 2631 sensitive strings with no transformations or canonicalizations 2632 applied". 2634 o Updated open issues. 2636 o Indented artwork elements to better distinguish them from the body 2637 text. 2639 -04 2641 o Refer to the registries as the primary sources of defined values 2642 and then secondarily reference the sections defining the initial 2643 contents of the registries. 2645 o Normatively reference XML Encryption 1.1 for its security 2646 considerations. 2648 o Reference draft-jones-jose-jwe-json-serialization instead of 2649 draft-jones-json-web-encryption-json-serialization. 2651 o Described additional open issues. 2653 o Applied editorial suggestions. 2655 -03 2657 o Added the "kdf" (key derivation function) header parameter to 2658 provide crypto agility for key derivation. The default KDF 2659 remains the Concat KDF with the SHA-256 digest function. 2661 o Reordered encryption steps so that the Encoded JWE Header is 2662 always created before it is needed as an input to the 2663 Authenticated Encryption "additional authenticated data" 2664 parameter. 2666 o Added the "cty" (content type) header parameter for declaring type 2667 information about the secured content, as opposed to the "typ" 2668 (type) header parameter, which declares type information about 2669 this object. 2671 o Moved description of how to determine whether a header is for a 2672 JWS or a JWE from the JWT spec to the JWE spec. 2674 o Added complete encryption examples for both Authenticated 2675 Encryption and non-Authenticated Encryption algorithms. 2677 o Added complete key derivation examples. 2679 o Added "Collision Resistant Namespace" to the terminology section. 2681 o Reference ITU.X690.1994 for DER encoding. 2683 o Added Registry Contents sections to populate registry values. 2685 o Numerous editorial improvements. 2687 -02 2689 o When using Authenticated Encryption algorithms (such as AES GCM), 2690 use the "additional authenticated data" parameter to provide 2691 integrity for the header, encrypted key, and ciphertext and use 2692 the resulting "authentication tag" value as the JWE Authentication 2693 Tag. 2695 o Defined KDF output key sizes. 2697 o Generalized text to allow key agreement to be employed as an 2698 alternative to key wrapping or key encryption. 2700 o Changed compression algorithm from gzip to DEFLATE. 2702 o Clarified that it is an error when a "kid" value is included and 2703 no matching key is found. 2705 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2706 rejected. 2708 o Clarified the relationship between "typ" header parameter values 2709 and MIME types. 2711 o Registered application/jwe MIME type and "JWE" typ header 2712 parameter value. 2714 o Simplified JWK terminology to get replace the "JWK Key Object" and 2715 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2716 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2717 between single keys and sets of keys. As part of this change, the 2718 Header Parameter Name for a public key value was changed from 2719 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2721 o Added suggestion on defining additional header parameters such as 2722 "x5t#S256" in the future for certificate thumbprints using hash 2723 algorithms other than SHA-1. 2725 o Specify RFC 2818 server identity validation, rather than RFC 6125 2726 (paralleling the same decision in the OAuth specs). 2728 o Generalized language to refer to Message Authentication Codes 2729 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2730 unless in a context specific to HMAC algorithms. 2732 o Reformatted to give each header parameter its own section heading. 2734 -01 2736 o Added an integrity check for non-Authenticated Encryption 2737 algorithms. 2739 o Added "jpk" and "x5c" header parameters for including JWK public 2740 keys and X.509 certificate chains directly in the header. 2742 o Clarified that this specification is defining the JWE Compact 2743 Serialization. Referenced the new JWE-JS spec, which defines the 2744 JWE JSON Serialization. 2746 o Added text "New header parameters should be introduced sparingly 2747 since an implementation that does not understand a parameter MUST 2748 reject the JWE". 2750 o Clarified that the order of the encryption and decryption steps is 2751 not significant in cases where there are no dependencies between 2752 the inputs and outputs of the steps. 2754 o Made other editorial improvements suggested by JOSE working group 2755 participants. 2757 -00 2759 o Created the initial IETF draft based upon 2760 draft-jones-json-web-encryption-02 with no normative changes. 2762 o Changed terminology to no longer call both digital signatures and 2763 HMACs "signatures". 2765 Authors' Addresses 2767 Michael B. Jones 2768 Microsoft 2770 Email: mbj@microsoft.com 2771 URI: http://self-issued.info/ 2773 Joe Hildebrand 2774 Cisco Systems, Inc. 2776 Email: jhildebr@cisco.com