idnits 2.17.1 draft-ietf-jose-json-web-encryption-36.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 (October 24, 2014) is 3462 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 1485 -- Looks like a reference, but probably isn't: '197' on line 1485 -- Looks like a reference, but probably isn't: '117' on line 1485 -- Looks like a reference, but probably isn't: '252' on line 1485 -- Looks like a reference, but probably isn't: '2' on line 1485 -- Looks like a reference, but probably isn't: '219' on line 1485 -- Looks like a reference, but probably isn't: '233' on line 1485 -- Looks like a reference, but probably isn't: '68' on line 1485 -- Looks like a reference, but probably isn't: '180' on line 1485 -- Looks like a reference, but probably isn't: '225' on line 1485 -- Looks like a reference, but probably isn't: '77' on line 1485 -- Looks like a reference, but probably isn't: '0' on line 2109 -- Looks like a reference, but probably isn't: '1' on line 2109 -- Looks like a reference, but probably isn't: '152' on line 2109 == 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: April 27, 2015 Cisco 6 October 24, 2014 8 JSON Web Encryption (JWE) 9 draft-ietf-jose-json-web-encryption-36 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 April 27, 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 . . . . . . . . . . . . . . . . . . 33 115 A.1.7. Complete Representation . . . . . . . . . . . . . . . 34 116 A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 34 117 A.2. Example JWE using RSAES-PKCS1-V1_5 and 118 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 35 119 A.2.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 35 120 A.2.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 35 121 A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 35 122 A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 37 123 A.2.5. Additional Authenticated Data . . . . . . . . . . . . 37 124 A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 37 125 A.2.7. Complete Representation . . . . . . . . . . . . . . . 38 126 A.2.8. Validation . . . . . . . . . . . . . . . . . . . . . . 38 127 A.3. Example JWE using AES Key Wrap and 128 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 38 129 A.3.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 39 130 A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 39 131 A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 39 132 A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 40 133 A.3.5. Additional Authenticated Data . . . . . . . . . . . . 40 134 A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 40 135 A.3.7. Complete Representation . . . . . . . . . . . . . . . 41 136 A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 41 137 A.4. Example JWE using General JWE JSON Serialization . . . . . 41 138 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 42 139 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 42 140 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 42 141 A.4.4. Complete JOSE Header Values . . . . . . . . . . . . . 42 142 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 43 143 A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 43 144 A.4.7. Complete JWE JSON Serialization Representation . . . . 43 146 A.5. Example JWE using Flattened JWE JSON Serialization . . . . 44 147 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 45 148 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 45 149 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 46 150 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 46 151 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 46 152 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 46 153 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 47 154 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 47 155 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 47 156 Appendix D. Document History . . . . . . . . . . . . . . . . . . 48 157 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 59 159 1. Introduction 161 JSON Web Encryption (JWE) represents encrypted content using 162 JavaScript Object Notation (JSON) [RFC7159] based data structures. 163 The JWE cryptographic mechanisms encrypt and provide integrity 164 protection for an arbitrary sequence of octets. 166 Two closely related serializations for 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 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 rejected. 758 In other cases, only the encrypted content for a single recipient 759 needs to be successfully validated. However, in all cases, the 760 encrypted content for at least one recipient MUST successfully 761 validate or the JWE MUST be rejected. 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 rejected. Otherwise, output the 873 Plaintext. In the JWE JSON Serialization case, also return a 874 result to the application indicating for which of the recipients 875 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 reject the JWE. 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 October 2014. 1301 [JWK] Jones, M., "JSON Web Key (JWK)", 1302 draft-ietf-jose-json-web-key (work in progress), 1303 October 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), October 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 } 1449 The resulting JWE Encrypted Key value is: 1451 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1452 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1453 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1454 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1455 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1456 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1457 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1458 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1459 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1460 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1461 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1462 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1463 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1464 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1465 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1466 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1467 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1468 117, 114, 135, 206] 1470 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1471 this value (with line breaks for display purposes only): 1473 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1474 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1475 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1476 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1477 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1478 6UklfCpIMfIjf7iGdXKHzg 1480 A.1.4. Initialization Vector 1482 Generate a random 96 bit JWE Initialization Vector. In this example, 1483 the value is: 1485 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1487 Encoding this JWE Initialization Vector as BASE64URL(JWE 1488 Initialization Vector) gives this value: 1490 48V1_ALb6US04U3b 1492 A.1.5. Additional Authenticated Data 1494 Let the Additional Authenticated Data encryption parameter be 1495 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1497 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1498 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1499 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1501 A.1.6. Content Encryption 1503 Perform authenticated encryption on the Plaintext with the AES GCM 1504 algorithm using the CEK as the encryption key, the JWE Initialization 1505 Vector, and the Additional Authenticated Data value above, requesting 1506 a 128 bit Authentication Tag output. The resulting Ciphertext is: 1508 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1509 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1510 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1511 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1512 160, 109, 64, 63, 192] 1514 The resulting Authentication Tag value is: 1516 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1517 210, 145] 1518 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1519 value (with line breaks for display purposes only): 1521 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1522 SdiwkIr3ajwQzaBtQD_A 1524 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1525 Tag) gives this value: 1527 XFBoMYUZodetZdvTiFvSkQ 1529 A.1.7. Complete Representation 1531 Assemble the final representation: The Compact Serialization of this 1532 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1533 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1534 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1535 Authentication Tag). 1537 The final result in this example (with line breaks for display 1538 purposes only) is: 1540 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1541 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1542 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1543 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1544 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1545 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1546 6UklfCpIMfIjf7iGdXKHzg. 1547 48V1_ALb6US04U3b. 1548 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1549 SdiwkIr3ajwQzaBtQD_A. 1550 XFBoMYUZodetZdvTiFvSkQ 1552 A.1.8. Validation 1554 This example illustrates the process of creating a JWE with RSAES 1555 OAEP for key encryption and AES GCM for content encryption. These 1556 results can be used to validate JWE decryption implementations for 1557 these algorithms. Note that since the RSAES OAEP computation 1558 includes random values, the encryption results above will not be 1559 completely reproducible. However, since the AES GCM computation is 1560 deterministic, the JWE Encrypted Ciphertext values will be the same 1561 for all encryptions performed using these inputs. 1563 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1565 This example encrypts the plaintext "Live long and prosper." to the 1566 recipient using RSAES-PKCS1-V1_5 for key encryption and 1567 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1568 of this plaintext (using JSON array notation) is: 1570 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1571 112, 114, 111, 115, 112, 101, 114, 46] 1573 A.2.1. JOSE Header 1575 The following example JWE Protected Header declares that: 1577 o The Content Encryption Key is encrypted to the recipient using the 1578 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. 1580 o Authenticated encryption is performed on the Plaintext using the 1581 AES_128_CBC_HMAC_SHA_256 algorithm to produce the Ciphertext and 1582 the Authentication Tag. 1584 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1586 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1587 Header)) gives this value: 1589 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1591 A.2.2. Content Encryption Key (CEK) 1593 Generate a 256 bit random Content Encryption Key (CEK). In this 1594 example, the key value is: 1596 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1597 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1598 44, 207] 1600 A.2.3. Key Encryption 1602 Encrypt the CEK with the recipient's public key using the RSAES- 1603 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1604 uses the RSA key represented in JSON Web Key [JWK] format below (with 1605 line breaks within values for display purposes only): 1607 {"kty":"RSA", 1608 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1609 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1610 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1611 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1612 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1613 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1614 "e":"AQAB", 1615 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1616 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1617 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1618 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1619 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1620 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1621 } 1623 The resulting JWE Encrypted Key value is: 1625 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1626 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1627 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1628 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1629 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1630 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1631 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1632 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1633 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1634 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1635 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1636 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1637 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1638 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1639 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1640 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1641 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1642 146, 114, 165, 204, 71, 136, 41, 252] 1644 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1645 this value (with line breaks for display purposes only): 1647 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1648 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1649 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1650 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1651 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1652 -B3oWh2TbqmScqXMR4gp_A 1654 A.2.4. Initialization Vector 1656 Generate a random 128 bit JWE Initialization Vector. In this 1657 example, the value is: 1659 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1660 101] 1662 Encoding this JWE Initialization Vector as BASE64URL(JWE 1663 Initialization Vector) gives this value: 1665 AxY8DCtDaGlsbGljb3RoZQ 1667 A.2.5. Additional Authenticated Data 1669 Let the Additional Authenticated Data encryption parameter be 1670 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1672 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1673 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1674 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1675 50, 73, 110, 48] 1677 A.2.6. Content Encryption 1679 Perform authenticated encryption on the Plaintext with the 1680 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1681 key, the JWE Initialization Vector, and the Additional Authenticated 1682 Data value above. The steps for doing this using the values from 1683 Appendix A.3 are detailed in Appendix B. The resulting Ciphertext 1684 is: 1686 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1687 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1688 112, 56, 102] 1690 The resulting Authentication Tag value is: 1692 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1693 191] 1695 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1696 value: 1698 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1700 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1701 Tag) gives this value: 1703 9hH0vgRfYgPnAHOd8stkvw 1705 A.2.7. Complete Representation 1707 Assemble the final representation: The Compact Serialization of this 1708 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1709 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1710 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1711 Authentication Tag). 1713 The final result in this example (with line breaks for display 1714 purposes only) is: 1716 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1717 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1718 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1719 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1720 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1721 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1722 -B3oWh2TbqmScqXMR4gp_A. 1723 AxY8DCtDaGlsbGljb3RoZQ. 1724 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1725 9hH0vgRfYgPnAHOd8stkvw 1727 A.2.8. Validation 1729 This example illustrates the process of creating a JWE with RSAES- 1730 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1731 encryption. These results can be used to validate JWE decryption 1732 implementations for these algorithms. Note that since the RSAES- 1733 PKCS1-V1_5 computation includes random values, the encryption results 1734 above will not be completely reproducible. However, since the AES 1735 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1736 will be the same for all encryptions performed using these inputs. 1738 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1740 This example encrypts the plaintext "Live long and prosper." to the 1741 recipient using AES Key Wrap for key encryption and 1742 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1743 of this plaintext (using JSON array notation) is: 1745 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1746 112, 114, 111, 115, 112, 101, 114, 46] 1748 A.3.1. JOSE Header 1750 The following example JWE Protected Header declares that: 1752 o The Content Encryption Key is encrypted to the recipient using the 1753 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1754 Encrypted Key. 1756 o Authenticated encryption is performed on the Plaintext using the 1757 AES_128_CBC_HMAC_SHA_256 algorithm to produce the Ciphertext and 1758 the Authentication Tag. 1760 {"alg":"A128KW","enc":"A128CBC-HS256"} 1762 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1763 Header)) gives this value: 1765 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1767 A.3.2. Content Encryption Key (CEK) 1769 Generate a 256 bit random Content Encryption Key (CEK). In this 1770 example, the value is: 1772 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1773 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1774 44, 207] 1776 A.3.3. Key Encryption 1778 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1779 algorithm to produce the JWE Encrypted Key. This example uses the 1780 symmetric key represented in JSON Web Key [JWK] format below: 1782 {"kty":"oct", 1783 "k":"GawgguFyGrWKav7AX4VKUg" 1784 } 1786 The resulting JWE Encrypted Key value is: 1788 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1789 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1790 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1792 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1793 this value: 1795 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1797 A.3.4. Initialization Vector 1799 Generate a random 128 bit JWE Initialization Vector. In this 1800 example, the value is: 1802 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1803 101] 1805 Encoding this JWE Initialization Vector as BASE64URL(JWE 1806 Initialization Vector) gives this value: 1808 AxY8DCtDaGlsbGljb3RoZQ 1810 A.3.5. Additional Authenticated Data 1812 Let the Additional Authenticated Data encryption parameter be 1813 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1815 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1816 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1817 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1818 110, 48] 1820 A.3.6. Content Encryption 1822 Perform authenticated encryption on the Plaintext with the 1823 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1824 key, the JWE Initialization Vector, and the Additional Authenticated 1825 Data value above. The steps for doing this using the values from 1826 this example are detailed in Appendix B. The resulting Ciphertext 1827 is: 1829 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1830 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1831 112, 56, 102] 1833 The resulting Authentication Tag value is: 1835 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1836 194, 85] 1838 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1839 value: 1841 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1843 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1844 Tag) gives this value: 1846 U0m_YmjN04DJvceFICbCVQ 1848 A.3.7. Complete Representation 1850 Assemble the final representation: The Compact Serialization of this 1851 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1852 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1853 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1854 Authentication Tag). 1856 The final result in this example (with line breaks for display 1857 purposes only) is: 1859 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1860 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1861 AxY8DCtDaGlsbGljb3RoZQ. 1862 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1863 U0m_YmjN04DJvceFICbCVQ 1865 A.3.8. Validation 1867 This example illustrates the process of creating a JWE with AES Key 1868 Wrap for key encryption and AES GCM for content encryption. These 1869 results can be used to validate JWE decryption implementations for 1870 these algorithms. Also, since both the AES Key Wrap and AES GCM 1871 computations are deterministic, the resulting JWE value will be the 1872 same for all encryptions performed using these inputs. Since the 1873 computation is reproducible, these results can also be used to 1874 validate JWE encryption implementations for these algorithms. 1876 A.4. Example JWE using General JWE JSON Serialization 1878 This section contains an example using the general JWE JSON 1879 Serialization syntax. This example demonstrates the capability for 1880 encrypting the same plaintext to multiple recipients. 1882 Two recipients are present in this example. The algorithm and key 1883 used for the first recipient are the same as that used in 1884 Appendix A.2. The algorithm and key used for the second recipient 1885 are the same as that used in Appendix A.3. The resulting JWE 1886 Encrypted Key values are therefore the same; those computations are 1887 not repeated here. 1889 The Plaintext, the Content Encryption Key (CEK), JWE Initialization 1890 Vector, and JWE Protected Header are shared by all recipients (which 1891 must be the case, since the Ciphertext and Authentication Tag are 1892 also shared). 1894 A.4.1. JWE Per-Recipient Unprotected Headers 1896 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1897 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1898 encrypt the CEK. Key ID values are supplied for both keys. The two 1899 per-recipient header values used to represent these algorithms and 1900 Key IDs are: 1902 {"alg":"RSA1_5","kid":"2011-04-29"} 1904 and 1906 {"alg":"A128KW","kid":"7"} 1908 A.4.2. JWE Protected Header 1910 Authenticated encryption is performed on the Plaintext using the 1911 AES_128_CBC_HMAC_SHA_256 algorithm to produce the common JWE 1912 Ciphertext and JWE Authentication Tag values. The JWE Protected 1913 Header value representing this is: 1915 {"enc":"A128CBC-HS256"} 1917 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1918 Header)) gives this value: 1920 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1922 A.4.3. JWE Unprotected Header 1924 This JWE uses the "jku" Header Parameter to reference a JWK Set. This 1925 is represented in the following JWE Unprotected Header value as: 1927 {"jku":"https://server.example.com/keys.jwks"} 1929 A.4.4. Complete JOSE Header Values 1931 Combining the per-recipient, protected, and unprotected header values 1932 supplied, the JOSE Header values used for the first and second 1933 recipient respectively are: 1935 {"alg":"RSA1_5", 1936 "kid":"2011-04-29", 1937 "enc":"A128CBC-HS256", 1938 "jku":"https://server.example.com/keys.jwks"} 1940 and 1942 {"alg":"A128KW", 1943 "kid":"7", 1944 "enc":"A128CBC-HS256", 1945 "jku":"https://server.example.com/keys.jwks"} 1947 A.4.5. Additional Authenticated Data 1949 Let the Additional Authenticated Data encryption parameter be 1950 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1952 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1953 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1955 A.4.6. Content Encryption 1957 Perform authenticated encryption on the Plaintext with the 1958 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1959 key, the JWE Initialization Vector, and the Additional Authenticated 1960 Data value above. The steps for doing this using the values from 1961 Appendix A.3 are detailed in Appendix B. The resulting Ciphertext 1962 is: 1964 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1965 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1966 112, 56, 102] 1968 The resulting Authentication Tag value is: 1970 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1971 207] 1973 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1974 value: 1976 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1978 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1979 Tag) gives this value: 1981 Mz-VPPyU4RlcuYv1IwIvzw 1983 A.4.7. Complete JWE JSON Serialization Representation 1985 The complete JWE JSON Serialization for these values is as follows 1986 (with line breaks within values for display purposes only): 1988 { 1989 "protected": 1990 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1991 "unprotected": 1992 {"jku":"https://server.example.com/keys.jwks"}, 1993 "recipients":[ 1994 {"header": 1995 {"alg":"RSA1_5","kid":"2011-04-29"}, 1996 "encrypted_key": 1997 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1998 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1999 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 2000 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 2001 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 2002 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 2003 {"header": 2004 {"alg":"A128KW","kid":"7"}, 2005 "encrypted_key": 2006 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 2007 "iv": 2008 "AxY8DCtDaGlsbGljb3RoZQ", 2009 "ciphertext": 2010 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 2011 "tag": 2012 "Mz-VPPyU4RlcuYv1IwIvzw" 2013 } 2015 A.5. Example JWE using Flattened JWE JSON Serialization 2017 This section contains an example using the flattened JWE JSON 2018 Serialization syntax. This example demonstrates the capability for 2019 encrypting the plaintext to a single recipient in a flattened JSON 2020 structure. 2022 The values in this example are the same as those for the second 2023 recipient of the previous example in Appendix A.4. 2025 The complete JWE JSON Serialization for these values is as follows 2026 (with line breaks within values for display purposes only): 2028 { 2029 "protected": 2030 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 2031 "unprotected": 2032 {"jku":"https://server.example.com/keys.jwks"}, 2033 "header": 2034 {"alg":"A128KW","kid":"7"}, 2035 "encrypted_key": 2036 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ", 2037 "iv": 2038 "AxY8DCtDaGlsbGljb3RoZQ", 2039 "ciphertext": 2040 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 2041 "tag": 2042 "Mz-VPPyU4RlcuYv1IwIvzw" 2043 } 2045 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 2047 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 2048 authenticated encryption computation using the values from the 2049 example in Appendix A.3. As described where this algorithm is 2050 defined in Sections 5.2 and 5.2.3 of JWA, the AES_CBC_HMAC_SHA2 2051 family of algorithms are implemented using Advanced Encryption 2052 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #7 2053 padding to perform the encryption and an HMAC SHA-2 function to 2054 perform the integrity calculation - in this case, HMAC SHA-256. 2056 B.1. Extract MAC_KEY and ENC_KEY from Key 2058 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example 2059 (using JSON array notation) is: 2061 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 2062 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 2063 44, 207] 2065 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 2066 which is: 2068 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 2069 206] 2071 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 2072 is: 2074 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 2075 207] 2077 Note that the MAC key comes before the encryption key in the input 2078 key K; this is in the opposite order of the algorithm names in the 2079 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 2081 B.2. Encrypt Plaintext to Create Ciphertext 2083 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 2084 using PKCS #7 padding using the ENC_KEY above. The Plaintext in this 2085 example is: 2087 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 2088 112, 114, 111, 115, 112, 101, 114, 46] 2090 The encryption result is as follows, which is the Ciphertext output: 2092 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 2093 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 2094 112, 56, 102] 2096 B.3. 64 Bit Big Endian Representation of AAD Length 2098 The Additional Authenticated Data (AAD) in this example is: 2100 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2101 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2102 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2103 110, 48] 2105 This AAD is 51 bytes long, which is 408 bits long. The octet string 2106 AL, which is the number of bits in AAD expressed as a big endian 64 2107 bit unsigned integer is: 2109 [0, 0, 0, 0, 0, 0, 1, 152] 2111 B.4. Initialization Vector Value 2113 The Initialization Vector value used in this example is: 2115 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 2116 101] 2118 B.5. Create Input to HMAC Computation 2120 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 2121 the AL value. The result of this concatenation is: 2123 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2124 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2125 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2126 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 2127 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 2128 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 2129 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 2131 B.6. Compute HMAC Value 2133 Compute the HMAC SHA-256 of the concatenated value above. This 2134 result M is: 2136 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2137 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 2138 86, 229, 116] 2140 B.7. Truncate HMAC Value to Create Authentication Tag 2142 Use the first half (128 bits) of the HMAC output M as the 2143 Authentication Tag output T. This truncated value is: 2145 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2146 194, 85] 2148 Appendix C. Acknowledgements 2150 Solutions for encrypting JSON content were also explored by JSON 2151 Simple Encryption [JSE] and JavaScript Message Security Format 2152 [I-D.rescorla-jsms], both of which significantly influenced this 2153 draft. This draft attempts to explicitly reuse as many of the 2154 relevant concepts from XML Encryption 1.1 2155 [W3C.REC-xmlenc-core1-20130411] and RFC 5652 [RFC5652] as possible, 2156 while utilizing simple, compact JSON-based data structures. 2158 Special thanks are due to John Bradley, Eric Rescorla, and Nat 2159 Sakimura for the discussions that helped inform the content of this 2160 specification, to Eric Rescorla and Joe Hildebrand for allowing the 2161 reuse of text from [I-D.rescorla-jsms] in this document, and to Eric 2162 Rescorla for co-authoring many drafts of this specification. 2164 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2165 Jay for validating the examples in this specification. 2167 This specification is the work of the JOSE Working Group, which 2168 includes dozens of active and dedicated participants. In particular, 2169 the following individuals contributed ideas, feedback, and wording 2170 that influenced this specification: 2172 Richard Barnes, John Bradley, Brian Campbell, Alissa Cooper, Breno de 2173 Medeiros, Stephen Farrell, Dick Hardt, Jeff Hodges, Russ Housley, 2174 Edmund Jay, Scott Kelly, Stephen Kent, Barry Leiba, James Manger, 2175 Matt Miller, Kathleen Moriarty, Tony Nadalin, Hideki Nara, Axel 2176 Nennker, Ray Polk, Emmanuel Raviart, Eric Rescorla, Pete Resnick, Nat 2177 Sakimura, Jim Schaad, Hannes Tschofenig, and Sean Turner. 2179 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2180 Sean Turner, Stephen Farrell, and Kathleen Moriarty served as 2181 Security area directors during the creation of this specification. 2183 Appendix D. Document History 2185 [[ to be removed by the RFC Editor before publication as an RFC ]] 2187 -36 2189 o Defined a flattened JWE JSON Serialization syntax, which is 2190 optimized for the single recipient case. 2192 o Clarified where white space and line breaks may occur in JSON 2193 objects by referencing Section 2 of RFC 7159. 2195 -35 2197 o Addressed AppsDir reviews by Ray Polk. 2199 -34 2201 o Addressed IESG review comments by Barry Leiba, Alissa Cooper, Pete 2202 Resnick, Stephen Farrell, and Richard Barnes. 2204 -33 2206 o Noted that certificate thumbprints are also sometimes known as 2207 certificate fingerprints. 2209 o Changed to use the term "authenticated encryption" instead of 2210 "encryption", where appropriate. 2212 o Acknowledged additional contributors. 2214 -32 2215 o Addressed Gen-ART review comments by Russ Housley. 2217 o Addressed secdir review comments by Scott Kelly, Tero Kivinen, and 2218 Stephen Kent. 2220 -31 2222 o Updated the reference to draft-mcgrew-aead-aes-cbc-hmac-sha2. 2224 -30 2226 o Added subsection headings within the Overview section for the two 2227 serializations. 2229 o Added references and cleaned up the reference syntax in a few 2230 places. 2232 o Applied minor wording changes to the Security Considerations 2233 section and made other local editorial improvements. 2235 -29 2237 o Replaced the terms JWS Header, JWE Header, and JWT Header with a 2238 single JOSE Header term defined in the JWS specification. This 2239 also enabled a single Header Parameter definition to be used and 2240 reduced other areas of duplication between specifications. 2242 -28 2244 o Specified the use of PKCS #7 padding with AES CBC, rather than 2245 PKCS #5. (PKCS #7 is a superset of PKCS #5, and is appropriate 2246 for the 16 octet blocks used by AES CBC.) 2248 o Revised the introduction to the Security Considerations section. 2249 Also moved a security consideration item here from the JWA draft. 2251 -27 2253 o Described additional security considerations. 2255 o Added the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) header 2256 parameter. 2258 -26 2260 o Noted that octet sequences are depicted using JSON array notation. 2262 o Updated references, including to W3C specifications. 2264 -25 2266 o Corrected two external section number references that had changed. 2268 o Corrected a typo in an algorithm name in the prose of an example. 2270 -24 2272 o Corrected complete JSON Serialization example. 2274 o Replaced uses of the term "associated data" wherever it was used 2275 to refer to a data value with "additional authenticated data", 2276 since both terms were being used as synonyms, causing confusion. 2278 o Updated the JSON reference to RFC 7159. 2280 o Thanked Eric Rescorla for helping to author of most of the drafts 2281 of this specification and removed him from the current author 2282 list. 2284 -23 2286 o Corrected a use of the word "payload" to "plaintext". 2288 -22 2290 o Corrected RFC 2119 terminology usage. 2292 o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. 2294 -21 2296 o Changed some references from being normative to informative, 2297 addressing issue #90. 2299 o Applied review comments to the JSON Serialization section, 2300 addressing issue #178. 2302 -20 2304 o Made terminology definitions more consistent, addressing issue 2305 #165. 2307 o Restructured the JSON Serialization section to call out the 2308 parameters used in hanging lists, addressing issue #178. 2310 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 2311 addressing issue #90. 2313 -19 2315 o Reordered the key selection parameters. 2317 -18 2319 o Updated the mandatory-to-implement (MTI) language to say that 2320 applications using this specification need to specify what 2321 serialization and serialization features are used for that 2322 application, addressing issue #176. 2324 o Changes to address editorial and minor issues #89, #135, #165, 2325 #174, #175, #177, #179, and #180. 2327 o Used Header Parameter Description registry field. 2329 -17 2331 o Refined the "typ" and "cty" definitions to always be MIME Media 2332 Types, with the omission of "application/" prefixes recommended 2333 for brevity, addressing issue #50. 2335 o Updated the mandatory-to-implement (MTI) language to say that 2336 general-purpose implementations must implement the single 2337 recipient case for both serializations whereas special-purpose 2338 implementations can implement just one serialization if that meets 2339 the needs of the use cases the implementation is designed for, 2340 addressing issue #176. 2342 o Explicitly named all the logical components of a JWE and defined 2343 the processing rules and serializations in terms of those 2344 components, addressing issues #60, #61, and #62. 2346 o Replaced verbose repetitive phases such as "base64url encode the 2347 octets of the UTF-8 representation of X" with mathematical 2348 notation such as "BASE64URL(UTF8(X))". 2350 o Header Parameters and processing rules occurring in both JWS and 2351 JWE are now referenced in JWS by JWE, rather than duplicated, 2352 addressing issue #57. 2354 o Terms used in multiple documents are now defined in one place and 2355 incorporated by reference. Some lightly used or obvious terms 2356 were also removed. This addresses issue #58. 2358 -16 2360 o Changes to address editorial and minor issues #163, #168, #169, 2361 #170, #172, and #173. 2363 -15 2365 o Clarified that it is an application decision which recipients' 2366 encrypted content must successfully validate for the JWE to be 2367 accepted, addressing issue #35. 2369 o Changes to address editorial issues #34, #164, and #169. 2371 -14 2373 o Clarified that the "protected", "unprotected", "header", "iv", 2374 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2375 JSON Serialization when their values would be empty. Stated that 2376 the "recipients" array must always be present. 2378 -13 2380 o Added an "aad" (Additional Authenticated Data) member for the JWE 2381 JSON Serialization, enabling Additional Authenticated Data to be 2382 supplied that is not double base64url encoded, addressing issue 2383 #29. 2385 -12 2387 o Clarified that the "typ" and "cty" header parameters are used in 2388 an application-specific manner and have no effect upon the JWE 2389 processing. 2391 o Replaced the MIME types "application/jwe+json" and 2392 "application/jwe" with "application/jose+json" and 2393 "application/jose". 2395 o Stated that recipients MUST either reject JWEs with duplicate 2396 Header Parameter Names or use a JSON parser that returns only the 2397 lexically last duplicate member name. 2399 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2400 be with the algorithm descriptions that use them. 2402 o Added a Serializations section with parallel treatment of the JWE 2403 Compact Serialization and the JWE JSON Serialization and also 2404 moved the former Implementation Considerations content there. 2406 o Restored use of the term "AEAD". 2408 o Changed terminology from "block encryption" to "content 2409 encryption". 2411 -11 2413 o Added Key Identification section. 2415 o Removed the Encrypted Key value from the AAD computation since it 2416 is already effectively integrity protected by the encryption 2417 process. The AAD value now only contains the representation of 2418 the JWE Encrypted Header. 2420 o For the JWE JSON Serialization, enable Header Parameter values to 2421 be specified in any of three parameters: the "protected" member 2422 that is integrity protected and shared among all recipients, the 2423 "unprotected" member that is not integrity protected and shared 2424 among all recipients, and the "header" member that is not 2425 integrity protected and specific to a particular recipient. (This 2426 does not affect the JWE Compact Serialization, in which all Header 2427 Parameter values are in a single integrity protected JWE Header 2428 value.) 2430 o Shortened the names "authentication_tag" to "tag" and 2431 "initialization_vector" to "iv" in the JWE JSON Serialization, 2432 addressing issue #20. 2434 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2436 o Removed suggested compact serialization for multiple recipients. 2438 o Changed the MIME type name "application/jwe-js" to 2439 "application/jwe+json", addressing issue #22. 2441 o Tightened the description of the "crit" (critical) header 2442 parameter. 2444 -10 2446 o Changed the JWE processing rules for multiple recipients so that a 2447 single AAD value contains the header parameters and encrypted key 2448 values for all the recipients, enabling AES GCM to be safely used 2449 for multiple recipients. 2451 o Added an appendix suggesting a possible compact serialization for 2452 JWEs with multiple recipients. 2454 -09 2456 o Added JWE JSON Serialization, as specified by 2457 draft-jones-jose-jwe-json-serialization-04. 2459 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2460 parameter value. 2462 o Defined that the default action for header parameters that are not 2463 understood is to ignore them unless specifically designated as 2464 "MUST be understood" or included in the new "crit" (critical) 2465 header parameter list. This addressed issue #6. 2467 o Corrected "x5c" description. This addressed issue #12. 2469 o Changed from using the term "byte" to "octet" when referring to 8 2470 bit values. 2472 o Added Key Management Mode definitions to terminology section and 2473 used the defined terms to provide clearer key management 2474 instructions. This addressed issue #5. 2476 o Added text about preventing the recipient from behaving as an 2477 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2479 o Changed from using the term "Integrity Value" to "Authentication 2480 Tag". 2482 o Changed member name from "integrity_value" to "authentication_tag" 2483 in the JWE JSON Serialization. 2485 o Removed Initialization Vector from the AAD value since it is 2486 already integrity protected by all of the authenticated encryption 2487 algorithms specified in the JWA specification. 2489 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2490 and "A256CBC-HS512". The new algorithms perform the same 2491 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2492 but with the Initialization Vector and Authentication Tag values 2493 remaining separate from the Ciphertext value in the output 2494 representation. Also deleted the header parameters "epu" 2495 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2496 they are no longer used. 2498 -08 2500 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2501 since the term AEAD in the RFC 5116 sense implied the use of a 2502 particular data representation, rather than just referring to the 2503 class of algorithms that perform authenticated encryption with 2504 associated data. 2506 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2507 Tschofenig. Many of these simplified the terminology used. 2509 o Clarified statements of the form "This header parameter is 2510 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2512 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2513 Web Signature and Encryption Header Parameters registry. 2515 o Added seriesInfo information to Internet Draft references. 2517 -07 2519 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2521 o Updated values for example AES CBC calculations. 2523 o Made several local editorial changes to clean up loose ends left 2524 over from to the decision to only support block encryption methods 2525 providing integrity. One of these changes was to explicitly state 2526 that the "enc" (encryption method) algorithm must be an 2527 Authenticated Encryption algorithm with a specified key length. 2529 -06 2531 o Removed the "int" and "kdf" parameters and defined the new 2532 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2533 "A256CBC+HS512" to replace the former uses of AES CBC, which 2534 required the use of separate integrity and key derivation 2535 functions. 2537 o Included additional values in the Concat KDF calculation -- the 2538 desired output size and the algorithm value, and optionally 2539 PartyUInfo and PartyVInfo values. Added the optional header 2540 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2541 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2542 PartyVInfo). Updated the KDF examples accordingly. 2544 o Promoted Initialization Vector from being a header parameter to 2545 being a top-level JWE element. This saves approximately 16 bytes 2546 in the compact serialization, which is a significant savings for 2547 some use cases. Promoting the Initialization Vector out of the 2548 header also avoids repeating this shared value in the JSON 2549 serialization. 2551 o Changed "x5c" (X.509 Certificate Chain) representation from being 2552 a single string to being an array of strings, each containing a 2553 single base64 encoded DER certificate value, representing elements 2554 of the certificate chain. 2556 o Added an AES Key Wrap example. 2558 o Reordered the encryption steps so CMK creation is first, when 2559 required. 2561 o Correct statements in examples about which algorithms produce 2562 reproducible results. 2564 -05 2566 o Support both direct encryption using a shared or agreed upon 2567 symmetric key, and the use of a shared or agreed upon symmetric 2568 key to key wrap the CMK. 2570 o Added statement that "StringOrURI values are compared as case- 2571 sensitive strings with no transformations or canonicalizations 2572 applied". 2574 o Updated open issues. 2576 o Indented artwork elements to better distinguish them from the body 2577 text. 2579 -04 2581 o Refer to the registries as the primary sources of defined values 2582 and then secondarily reference the sections defining the initial 2583 contents of the registries. 2585 o Normatively reference XML Encryption 1.1 for its security 2586 considerations. 2588 o Reference draft-jones-jose-jwe-json-serialization instead of 2589 draft-jones-json-web-encryption-json-serialization. 2591 o Described additional open issues. 2593 o Applied editorial suggestions. 2595 -03 2597 o Added the "kdf" (key derivation function) header parameter to 2598 provide crypto agility for key derivation. The default KDF 2599 remains the Concat KDF with the SHA-256 digest function. 2601 o Reordered encryption steps so that the Encoded JWE Header is 2602 always created before it is needed as an input to the 2603 Authenticated Encryption "additional authenticated data" 2604 parameter. 2606 o Added the "cty" (content type) header parameter for declaring type 2607 information about the secured content, as opposed to the "typ" 2608 (type) header parameter, which declares type information about 2609 this object. 2611 o Moved description of how to determine whether a header is for a 2612 JWS or a JWE from the JWT spec to the JWE spec. 2614 o Added complete encryption examples for both Authenticated 2615 Encryption and non-Authenticated Encryption algorithms. 2617 o Added complete key derivation examples. 2619 o Added "Collision Resistant Namespace" to the terminology section. 2621 o Reference ITU.X690.1994 for DER encoding. 2623 o Added Registry Contents sections to populate registry values. 2625 o Numerous editorial improvements. 2627 -02 2629 o When using Authenticated Encryption algorithms (such as AES GCM), 2630 use the "additional authenticated data" parameter to provide 2631 integrity for the header, encrypted key, and ciphertext and use 2632 the resulting "authentication tag" value as the JWE Authentication 2633 Tag. 2635 o Defined KDF output key sizes. 2637 o Generalized text to allow key agreement to be employed as an 2638 alternative to key wrapping or key encryption. 2640 o Changed compression algorithm from gzip to DEFLATE. 2642 o Clarified that it is an error when a "kid" value is included and 2643 no matching key is found. 2645 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2646 rejected. 2648 o Clarified the relationship between "typ" header parameter values 2649 and MIME types. 2651 o Registered application/jwe MIME type and "JWE" typ header 2652 parameter value. 2654 o Simplified JWK terminology to get replace the "JWK Key Object" and 2655 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2656 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2657 between single keys and sets of keys. As part of this change, the 2658 Header Parameter Name for a public key value was changed from 2659 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2661 o Added suggestion on defining additional header parameters such as 2662 "x5t#S256" in the future for certificate thumbprints using hash 2663 algorithms other than SHA-1. 2665 o Specify RFC 2818 server identity validation, rather than RFC 6125 2666 (paralleling the same decision in the OAuth specs). 2668 o Generalized language to refer to Message Authentication Codes 2669 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2670 unless in a context specific to HMAC algorithms. 2672 o Reformatted to give each header parameter its own section heading. 2674 -01 2676 o Added an integrity check for non-Authenticated Encryption 2677 algorithms. 2679 o Added "jpk" and "x5c" header parameters for including JWK public 2680 keys and X.509 certificate chains directly in the header. 2682 o Clarified that this specification is defining the JWE Compact 2683 Serialization. Referenced the new JWE-JS spec, which defines the 2684 JWE JSON Serialization. 2686 o Added text "New header parameters should be introduced sparingly 2687 since an implementation that does not understand a parameter MUST 2688 reject the JWE". 2690 o Clarified that the order of the encryption and decryption steps is 2691 not significant in cases where there are no dependencies between 2692 the inputs and outputs of the steps. 2694 o Made other editorial improvements suggested by JOSE working group 2695 participants. 2697 -00 2699 o Created the initial IETF draft based upon 2700 draft-jones-json-web-encryption-02 with no normative changes. 2702 o Changed terminology to no longer call both digital signatures and 2703 HMACs "signatures". 2705 Authors' Addresses 2707 Michael B. Jones 2708 Microsoft 2710 Email: mbj@microsoft.com 2711 URI: http://self-issued.info/ 2713 Joe Hildebrand 2714 Cisco Systems, Inc. 2716 Email: jhildebr@cisco.com