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