idnits 2.17.00 (12 Aug 2021) /tmp/idnits64286/draft-ietf-jose-json-web-encryption-34.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 14, 2014) is 2775 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 1431 -- Looks like a reference, but probably isn't: '197' on line 1431 -- Looks like a reference, but probably isn't: '117' on line 1431 -- Looks like a reference, but probably isn't: '252' on line 1431 -- Looks like a reference, but probably isn't: '2' on line 1431 -- Looks like a reference, but probably isn't: '219' on line 1431 -- Looks like a reference, but probably isn't: '233' on line 1431 -- Looks like a reference, but probably isn't: '68' on line 1431 -- Looks like a reference, but probably isn't: '180' on line 1431 -- Looks like a reference, but probably isn't: '225' on line 1431 -- Looks like a reference, but probably isn't: '77' on line 1431 -- Looks like a reference, but probably isn't: '0' on line 2026 -- Looks like a reference, but probably isn't: '1' on line 2026 -- Looks like a reference, but probably isn't: '152' on line 2026 == Unused Reference: 'AES' is defined on line 1280, but no explicit reference was found in the text == Outdated reference: draft-ietf-jose-json-web-algorithms has been published as RFC 7518 == Outdated reference: draft-ietf-jose-json-web-key has been published as RFC 7517 == Outdated reference: draft-ietf-jose-json-web-signature has been published as RFC 7515 ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 18 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track J. Hildebrand 5 Expires: April 17, 2015 Cisco 6 October 14, 2014 8 JSON Web Encryption (JWE) 9 draft-ietf-jose-json-web-encryption-34 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 17, 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 . . . . . . . . . . . . 11 64 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 12 65 4.1.2. "enc" (Encryption Algorithm) Header Parameter . . . . 12 66 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 12 67 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 13 68 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 13 69 4.1.6. "kid" (Key ID) Header Parameter . . . . . . . . . . . 13 70 4.1.7. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 13 71 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 13 72 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 73 Parameter . . . . . . . . . . . . . . . . . . . . . . 14 74 4.1.10. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) 75 Header Parameter . . . . . . . . . . . . . . . . . . . 14 76 4.1.11. "typ" (Type) Header Parameter . . . . . . . . . . . . 14 77 4.1.12. "cty" (Content Type) Header Parameter . . . . . . . . 14 78 4.1.13. "crit" (Critical) Header Parameter . . . . . . . . . . 14 79 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 14 80 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 15 81 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 15 82 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 15 83 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 17 84 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20 85 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20 86 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 20 87 7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 20 88 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21 89 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 23 90 9. Distinguishing between JWS and JWE Objects . . . . . . . . . . 23 91 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 92 10.1. JSON Web Signature and Encryption Header Parameters 93 Registration . . . . . . . . . . . . . . . . . . . . . . . 24 94 10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 24 95 11. Security Considerations . . . . . . . . . . . . . . . . . . . 26 96 11.1. Key Entropy and Random Values . . . . . . . . . . . . . . 26 97 11.2. Key Protection . . . . . . . . . . . . . . . . . . . . . . 27 98 11.3. Using Matching Algorithm Strengths . . . . . . . . . . . . 27 99 11.4. Adaptive Chosen-Ciphertext Attacks . . . . . . . . . . . . 27 100 11.5. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 27 101 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 102 12.1. Normative References . . . . . . . . . . . . . . . . . . . 28 103 12.2. Informative References . . . . . . . . . . . . . . . . . . 28 104 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 30 105 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 30 106 A.1.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 30 107 A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 30 108 A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 31 109 A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 32 110 A.1.5. Additional Authenticated Data . . . . . . . . . . . . 32 111 A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 32 112 A.1.7. Complete Representation . . . . . . . . . . . . . . . 33 113 A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 33 114 A.2. Example JWE using RSAES-PKCS1-V1_5 and 115 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 33 116 A.2.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 34 117 A.2.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 34 118 A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 34 119 A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 36 120 A.2.5. Additional Authenticated Data . . . . . . . . . . . . 36 121 A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 36 122 A.2.7. Complete Representation . . . . . . . . . . . . . . . 37 123 A.2.8. Validation . . . . . . . . . . . . . . . . . . . . . . 37 124 A.3. Example JWE using AES Key Wrap and 125 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 37 126 A.3.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 38 127 A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 38 128 A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 38 129 A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 39 130 A.3.5. Additional Authenticated Data . . . . . . . . . . . . 39 131 A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 39 132 A.3.7. Complete Representation . . . . . . . . . . . . . . . 40 133 A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 40 134 A.4. Example JWE using JWE JSON Serialization . . . . . . . . . 40 135 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 41 136 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 41 137 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 41 138 A.4.4. Complete JOSE Header Values . . . . . . . . . . . . . 41 139 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 42 140 A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 42 141 A.4.7. Complete JWE JSON Serialization Representation . . . . 42 142 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 43 143 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 43 144 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 44 145 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 44 146 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 45 147 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 45 148 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 45 149 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 45 150 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 45 151 Appendix D. Document History . . . . . . . . . . . . . . . . . . 46 152 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 57 154 1. Introduction 156 JSON Web Encryption (JWE) represents encrypted content using 157 JavaScript Object Notation (JSON) [RFC7159] based data structures. 158 The JWE cryptographic mechanisms encrypt and provide integrity 159 protection for an arbitrary sequence of octets. 161 Two closely related serializations for JWE objects are defined. The 162 JWE Compact Serialization is a compact, URL-safe representation 163 intended for space constrained environments such as HTTP 164 Authorization headers and URI query parameters. The JWE JSON 165 Serialization represents JWE objects as JSON objects and enables the 166 same content to be encrypted to multiple parties. Both share the 167 same cryptographic underpinnings. 169 Cryptographic algorithms and identifiers for use with this 170 specification are described in the separate JSON Web Algorithms (JWA) 171 [JWA] specification and IANA registries defined by that 172 specification. Related digital signature and MAC capabilities are 173 described in the separate JSON Web Signature (JWS) [JWS] 174 specification. 176 Names defined by this specification are short because a core goal is 177 for the resulting representations to be compact. 179 1.1. Notational Conventions 181 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 182 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 183 "OPTIONAL" in this document are to be interpreted as described in Key 184 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 185 these words are used without being spelled in uppercase then they are 186 to be interpreted with their normal natural language meanings. 188 BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per 189 Section 2 of [JWS]. 191 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 192 of STRING. 194 ASCII(STRING) denotes the octets of the ASCII [USASCII] 195 representation of STRING. 197 The concatenation of two values A and B is denoted as A || B. 199 2. Terminology 201 These terms defined by the JSON Web Signature (JWS) [JWS] 202 specification are incorporated into this specification: "JSON Web 203 Signature (JWS)", "Base64url Encoding", "Collision-Resistant Name", 204 "Header Parameter", "JOSE Header", and "StringOrURI". 206 These terms defined by the Internet Security Glossary, Version 2 207 [RFC4949] are incorporated into this specification: "Ciphertext" and 208 "Plaintext". 210 These terms are defined by this specification: 212 JSON Web Encryption (JWE) 213 A data structure representing an encrypted and integrity protected 214 message. 216 Authenticated Encryption with Associated Data (AEAD) 217 An AEAD algorithm is one that encrypts the Plaintext, allows 218 Additional Authenticated Data to be specified, and provides an 219 integrated content integrity check over the Ciphertext and 220 Additional Authenticated Data. AEAD algorithms accept two inputs, 221 the Plaintext and the Additional Authenticated Data value, and 222 produce two outputs, the Ciphertext and the Authentication Tag 223 value. AES Galois/Counter Mode (GCM) is one such algorithm. 225 Additional Authenticated Data (AAD) 226 An input to an AEAD operation that is integrity protected but not 227 encrypted. 229 Authentication Tag 230 An output of an AEAD operation that ensures the integrity of the 231 Ciphertext and the Additional Authenticated Data. Note that some 232 algorithms may not use an Authentication Tag, in which case this 233 value is the empty octet sequence. 235 Content Encryption Key (CEK) 236 A symmetric key for the AEAD algorithm used to encrypt the 237 Plaintext to produce the Ciphertext and the Authentication Tag. 239 JWE Encrypted Key 240 Encrypted Content Encryption Key (CEK) value. Note that for some 241 algorithms, the JWE Encrypted Key value is specified as being the 242 empty octet sequence. 244 JWE Initialization Vector 245 Initialization vector value used when encrypting the plaintext. 246 Note that some algorithms may not use an Initialization Vector, in 247 which case this value is the empty octet sequence. 249 JWE AAD 250 Additional value to be integrity protected by the authenticated 251 encryption operation. This can only be present when using the JWE 252 JSON Serialization. (Note that this can also be achieved when 253 using either serialization by including the AAD value as an 254 integrity protected Header Parameter value, but at the cost of the 255 value being double base64url encoded.) 257 JWE Ciphertext 258 Ciphertext value resulting from authenticated encryption of the 259 plaintext with additional authenticated data. 261 JWE Authentication Tag 262 Authentication Tag value resulting from authenticated encryption 263 of the plaintext with additional authenticated data. 265 JWE Protected Header 266 JSON object that contains the Header Parameters that are integrity 267 protected by the authenticated encryption operation. These 268 parameters apply to all recipients of the JWE. For the JWE 269 Compact Serialization, this comprises the entire JOSE Header. For 270 the JWE JSON Serialization, this is one component of the JOSE 271 Header. 273 JWE Shared Unprotected Header 274 JSON object that contains the Header Parameters that apply to all 275 recipients of the JWE that are not integrity protected. This can 276 only be present when using the JWE JSON Serialization. 278 JWE Per-Recipient Unprotected Header 279 JSON object that contains Header Parameters that apply to a single 280 recipient of the JWE. These Header Parameter values are not 281 integrity protected. This can only be present when using the JWE 282 JSON Serialization. 284 JWE Compact Serialization 285 A representation of the JWE as a compact, URL-safe string. 287 JWE JSON Serialization 288 A representation of the JWE as a JSON object. The JWE JSON 289 Serialization enables the same content to be encrypted to multiple 290 parties. This representation is neither optimized for compactness 291 nor URL-safe. 293 Key Management Mode 294 A method of determining the Content Encryption Key (CEK) value to 295 use. Each algorithm used for determining the CEK value uses a 296 specific Key Management Mode. Key Management Modes employed by 297 this specification are Key Encryption, Key Wrapping, Direct Key 298 Agreement, Key Agreement with Key Wrapping, and Direct Encryption. 300 Key Encryption 301 A Key Management Mode in which the Content Encryption Key (CEK) 302 value is encrypted to the intended recipient using an asymmetric 303 encryption algorithm. 305 Key Wrapping 306 A Key Management Mode in which the Content Encryption Key (CEK) 307 value is encrypted to the intended recipient using a symmetric key 308 wrapping algorithm. 310 Direct Key Agreement 311 A Key Management Mode in which a key agreement algorithm is used 312 to agree upon the Content Encryption Key (CEK) value. 314 Key Agreement with Key Wrapping 315 A Key Management Mode in which a key agreement algorithm is used 316 to agree upon a symmetric key used to encrypt the Content 317 Encryption Key (CEK) value to the intended recipient using a 318 symmetric key wrapping algorithm. 320 Direct Encryption 321 A Key Management Mode in which the Content Encryption Key (CEK) 322 value used is the secret symmetric key value shared between the 323 parties. 325 3. JSON Web Encryption (JWE) Overview 327 JWE represents encrypted content using JSON data structures and 328 base64url encoding. These JSON data structures MAY contain white 329 space and/or line breaks. A JWE represents these logical values 330 (each of which is defined in Section 2): 332 o JOSE Header 333 o JWE Encrypted Key 334 o JWE Initialization Vector 335 o JWE AAD 336 o JWE Ciphertext 337 o JWE Authentication Tag 339 For a JWE object, the JOSE Header members are the union of the 340 members of these values (each of which is defined in Section 2): 342 o JWE Protected Header 343 o JWE Shared Unprotected Header 344 o JWE Per-Recipient Unprotected Header 346 JWE utilizes authenticated encryption to ensure the confidentiality 347 and integrity of the Plaintext and the integrity of the JWE Protected 348 Header and the JWE AAD. 350 This document defines two serializations for JWE objects: a compact, 351 URL-safe serialization called the JWE Compact Serialization and a 352 JSON serialization called the JWE JSON Serialization. In both 353 serializations, the JWE Protected Header, JWE Encrypted Key, JWE 354 Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are 355 base64url encoded, since JSON lacks a way to directly represent 356 arbitrary octet sequences. When present, the JWE AAD is also 357 base64url encoded. 359 3.1. JWE Compact Serialization Overview 361 In the JWE Compact Serialization, no JWE Shared Unprotected Header or 362 JWE Per-Recipient Unprotected Header are used. In this case, the 363 JOSE Header and the JWE Protected Header are the same. 365 In the JWE Compact Serialization, a JWE object is represented as the 366 concatenation: 368 BASE64URL(UTF8(JWE Protected Header)) || '.' || 369 BASE64URL(JWE Encrypted Key) || '.' || 370 BASE64URL(JWE Initialization Vector) || '.' || 371 BASE64URL(JWE Ciphertext) || '.' || 372 BASE64URL(JWE Authentication Tag) 374 See Section 7.1 for more information about the JWE Compact 375 Serialization. 377 3.2. JWE JSON Serialization Overview 379 In the JWE JSON Serialization, one or more of the JWE Protected 380 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 381 Unprotected Header MUST be present. In this case, the members of the 382 JOSE Header are the union of the members of the JWE Protected Header, 383 JWE Shared Unprotected Header, and JWE Per-Recipient Unprotected 384 Header values that are present. 386 In the JWE JSON Serialization, a JWE object is represented as the 387 combination of these eight values, 388 BASE64URL(UTF8(JWE Protected Header)), 389 JWE Shared Unprotected Header, 390 JWE Per-Recipient Unprotected Header, 391 BASE64URL(JWE Encrypted Key), 392 BASE64URL(JWE Initialization Vector), 393 BASE64URL(JWE Ciphertext), 394 BASE64URL(JWE Authentication Tag), and 395 BASE64URL(JWE AAD), 396 with the six base64url encoded result strings and the two unprotected 397 JSON object values being represented as members within a JSON object. 398 The inclusion of some of these values is OPTIONAL. The JWE JSON 399 Serialization can also encrypt the plaintext to multiple recipients. 400 See Section 7.2 for more information about the JWE JSON 401 Serialization. 403 3.3. Example JWE 405 This example encrypts the plaintext "The true sign of intelligence is 406 not knowledge but imagination." to the recipient. 408 The following example JWE Protected Header declares that: 409 o the Content Encryption Key is encrypted to the recipient using the 410 RSAES OAEP [RFC3447] algorithm to produce the JWE Encrypted Key 411 and 412 o authenticated encryption is performed on the Plaintext using the 413 AES GCM [AES, NIST.800-38D] algorithm with a 256 bit key to 414 produce the Ciphertext and the Authentication Tag. 416 {"alg":"RSA-OAEP","enc":"A256GCM"} 418 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 419 Header)) gives this value: 421 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 423 The remaining steps to finish creating this JWE are: 424 o Generate a random Content Encryption Key (CEK). 425 o Encrypt the CEK with the recipient's public key using the RSAES 426 OAEP algorithm to produce the JWE Encrypted Key. 427 o Base64url encode the JWE Encrypted Key. 428 o Generate a random JWE Initialization Vector. 429 o Base64url encode the JWE Initialization Vector. 430 o Let the Additional Authenticated Data encryption parameter be 431 ASCII(BASE64URL(UTF8(JWE Protected Header))). 432 o Perform authenticated encryption on the Plaintext with the AES GCM 433 algorithm using the CEK as the encryption key, the JWE 434 Initialization Vector, and the Additional Authenticated Data 435 value, requesting a 128 bit Authentication Tag output. 437 o Base64url encode the Ciphertext. 438 o Base64url encode the Authentication Tag. 439 o Assemble the final representation: The Compact Serialization of 440 this result is the string BASE64URL(UTF8(JWE Protected Header)) || 441 '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE 442 Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' 443 || BASE64URL(JWE Authentication Tag). 445 The final result in this example (with line breaks for display 446 purposes only) is: 448 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 449 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 450 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 451 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 452 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 453 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 454 6UklfCpIMfIjf7iGdXKHzg. 455 48V1_ALb6US04U3b. 456 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 457 SdiwkIr3ajwQzaBtQD_A. 458 XFBoMYUZodetZdvTiFvSkQ 460 See Appendix A.1 for the complete details of computing this JWE. See 461 other parts of Appendix A for additional examples, including an 462 example using the JWE JSON Serialization in Appendix A.4. 464 4. JOSE Header 466 For a JWE object, the members of the JSON object(s) representing the 467 JOSE Header describe the encryption applied to the Plaintext and 468 optionally additional properties of the JWE. The Header Parameter 469 names within the JOSE Header MUST be unique, just as described in 470 Section 4 of [JWS]. The rules about handling Header Parameters that 471 are not understood by the implementation are also the same. The 472 classes of Header Parameter names are likewise the same. 474 4.1. Registered Header Parameter Names 476 The following Header Parameter names for use in JWE objects are 477 registered in the IANA JSON Web Signature and Encryption Header 478 Parameters registry defined in [JWS], with meanings as defined below. 480 As indicated by the common registry, JWSs and JWEs share a common 481 Header Parameter space; when a parameter is used by both 482 specifications, its usage must be compatible between the 483 specifications. 485 4.1.1. "alg" (Algorithm) Header Parameter 487 This parameter has the same meaning, syntax, and processing rules as 488 the "alg" Header Parameter defined in Section 4.1.1 of [JWS], except 489 that the Header Parameter identifies the cryptographic algorithm used 490 to encrypt or determine the value of the Content Encryption Key 491 (CEK). The encrypted content is not usable if the "alg" value does 492 not represent a supported algorithm, or if the recipient does not 493 have a key that can be used with that algorithm. 495 A list of defined "alg" values for this use can be found in the IANA 496 JSON Web Signature and Encryption Algorithms registry defined in 497 [JWA]; the initial contents of this registry are the values defined 498 in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. 500 4.1.2. "enc" (Encryption Algorithm) Header Parameter 502 The "enc" (encryption algorithm) Header Parameter identifies the 503 content encryption algorithm used to perform authenticated encryption 504 on the Plaintext to produce the Ciphertext and the Authentication 505 Tag. This algorithm MUST be an AEAD algorithm with a specified key 506 length. The recipient MUST reject the JWE if the "enc" value does 507 not represent a supported algorithm. "enc" values should either be 508 registered in the IANA JSON Web Signature and Encryption Algorithms 509 registry defined in [JWA] or be a value that contains a Collision- 510 Resistant Name. The "enc" value is a case-sensitive string 511 containing a StringOrURI value. This Header Parameter MUST be 512 present and MUST be understood and processed by implementations. 514 A list of defined "enc" values for this use can be found in the IANA 515 JSON Web Signature and Encryption Algorithms registry defined in 516 [JWA]; the initial contents of this registry are the values defined 517 in Section 5.1 of the JSON Web Algorithms (JWA) [JWA] specification. 519 4.1.3. "zip" (Compression Algorithm) Header Parameter 521 The "zip" (compression algorithm) applied to the Plaintext before 522 encryption, if any. The "zip" value defined by this specification 523 is: 525 o "DEF" - Compression with the DEFLATE [RFC1951] algorithm 527 Other values MAY be used. Compression algorithm values can be 528 registered in the IANA JSON Web Encryption Compression Algorithm 529 registry defined in [JWA]. The "zip" value is a case-sensitive 530 string. If no "zip" parameter is present, no compression is applied 531 to the Plaintext before encryption. This Header Parameter MUST be 532 integrity protected, and therefore MUST occur only within the JWE 533 Protected Header, when used. Use of this Header Parameter is 534 OPTIONAL. This Header Parameter MUST be understood and processed by 535 implementations. 537 4.1.4. "jku" (JWK Set URL) Header Parameter 539 This parameter has the same meaning, syntax, and processing rules as 540 the "jku" Header Parameter defined in Section 4.1.2 of [JWS], except 541 that the JWK Set resource contains the public key to which the JWE 542 was encrypted; this can be used to determine the private key needed 543 to decrypt the JWE. 545 4.1.5. "jwk" (JSON Web Key) Header Parameter 547 This parameter has the same meaning, syntax, and processing rules as 548 the "jwk" Header Parameter defined in Section 4.1.3 of [JWS], except 549 that the key is the public key to which the JWE was encrypted; this 550 can be used to determine the private key needed to decrypt the JWE. 552 4.1.6. "kid" (Key ID) Header Parameter 554 This parameter has the same meaning, syntax, and processing rules as 555 the "kid" Header Parameter defined in Section 4.1.4 of [JWS], except 556 that the key hint references the public key to which the JWE was 557 encrypted; this can be used to determine the private key needed to 558 decrypt the JWE. This parameter allows originators to explicitly 559 signal a change of key to JWE recipients. 561 4.1.7. "x5u" (X.509 URL) Header Parameter 563 This parameter has the same meaning, syntax, and processing rules as 564 the "x5u" Header Parameter defined in Section 4.1.5 of [JWS], except 565 that the X.509 public key certificate or certificate chain [RFC5280] 566 contains the public key to which the JWE was encrypted; this can be 567 used to determine the private key needed to decrypt the JWE. 569 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 571 This parameter has the same meaning, syntax, and processing rules as 572 the "x5c" Header Parameter defined in Section 4.1.6 of [JWS], except 573 that the X.509 public key certificate or certificate chain [RFC5280] 574 contains the public key to which the JWE was encrypted; this can be 575 used to determine the private key needed to decrypt the JWE. 577 See Appendix B of [JWS] for an example "x5c" value. 579 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 581 This parameter has the same meaning, syntax, and processing rules as 582 the "x5t" Header Parameter defined in Section 4.1.7 of [JWS], except 583 that the certificate referenced by the thumbprint contains the public 584 key to which the JWE was encrypted; this can be used to determine the 585 private key needed to decrypt the JWE. Note that certificate 586 thumbprints are also sometimes known as certificate fingerprints. 588 4.1.10. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header 589 Parameter 591 This parameter has the same meaning, syntax, and processing rules as 592 the "x5t#S256" Header Parameter defined in Section 4.1.8 of [JWS], 593 except that the certificate referenced by the thumbprint contains the 594 public key to which the JWE was encrypted; this can be used to 595 determine the private key needed to decrypt the JWE. Note that 596 certificate thumbprints are also sometimes known as certificate 597 fingerprints. 599 4.1.11. "typ" (Type) Header Parameter 601 This parameter has the same meaning, syntax, and processing rules as 602 the "typ" Header Parameter defined in Section 4.1.9 of [JWS], except 603 that the type is that of this complete JWE object. 605 4.1.12. "cty" (Content Type) Header Parameter 607 This parameter has the same meaning, syntax, and processing rules as 608 the "cty" Header Parameter defined in Section 4.1.10 of [JWS], except 609 that the type is that of the secured content (the plaintext). 611 4.1.13. "crit" (Critical) Header Parameter 613 This parameter has the same meaning, syntax, and processing rules as 614 the "crit" Header Parameter defined in Section 4.1.11 of [JWS], 615 except that Header Parameters for a JWE object are being referred to, 616 rather than Header Parameters for a JWS object. 618 4.2. Public Header Parameter Names 620 Additional Header Parameter names can be defined by those using JWEs. 621 However, in order to prevent collisions, any new Header Parameter 622 name should either be registered in the IANA JSON Web Signature and 623 Encryption Header Parameters registry defined in [JWS] or be a Public 624 Name: a value that contains a Collision-Resistant Name. In each 625 case, the definer of the name or value needs to take reasonable 626 precautions to make sure they are in control of the part of the 627 namespace they use to define the Header Parameter name. 629 New Header Parameters should be introduced sparingly, as they can 630 result in non-interoperable JWEs. 632 4.3. Private Header Parameter Names 634 A producer and consumer of a JWE may agree to use Header Parameter 635 names that are Private Names: names that are not Registered Header 636 Parameter names Section 4.1 or Public Header Parameter names 637 Section 4.2. Unlike Public Header Parameter names, Private Header 638 Parameter names are subject to collision and should be used with 639 caution. 641 5. Producing and Consuming JWEs 643 5.1. Message Encryption 645 The message encryption process is as follows. The order of the steps 646 is not significant in cases where there are no dependencies between 647 the inputs and outputs of the steps. 649 1. Determine the Key Management Mode employed by the algorithm used 650 to determine the Content Encryption Key (CEK) value. (This is 651 the algorithm recorded in the "alg" (algorithm) Header Parameter 652 of the resulting JWE.) 654 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 655 Wrapping are employed, generate a random Content Encryption Key 656 (CEK) value. See RFC 4086 [RFC4086] for considerations on 657 generating random values. The CEK MUST have a length equal to 658 that required for the content encryption algorithm. 660 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 661 employed, use the key agreement algorithm to compute the value 662 of the agreed upon key. When Direct Key Agreement is employed, 663 let the Content Encryption Key (CEK) be the agreed upon key. 664 When Key Agreement with Key Wrapping is employed, the agreed 665 upon key will be used to wrap the CEK. 667 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 668 Wrapping are employed, encrypt the CEK to the recipient and let 669 the result be the JWE Encrypted Key. 671 5. When Direct Key Agreement or Direct Encryption are employed, let 672 the JWE Encrypted Key be the empty octet sequence. 674 6. When Direct Encryption is employed, let the Content Encryption 675 Key (CEK) be the shared symmetric key. 677 7. Compute the encoded key value BASE64URL(JWE Encrypted Key). 679 8. If the JWE JSON Serialization is being used, repeat this process 680 (steps 1-7) for each recipient. 682 9. Generate a random JWE Initialization Vector of the correct size 683 for the content encryption algorithm (if required for the 684 algorithm); otherwise, let the JWE Initialization Vector be the 685 empty octet sequence. 687 10. Compute the encoded initialization vector value BASE64URL(JWE 688 Initialization Vector). 690 11. If a "zip" parameter was included, compress the Plaintext using 691 the specified compression algorithm and let M be the octet 692 sequence representing the compressed Plaintext; otherwise, let M 693 be the octet sequence representing the Plaintext. 695 12. Create the JSON object(s) containing the desired set of Header 696 Parameters, which together comprise the JOSE Header: if the JWE 697 Compact Serialization is being used, the JWE Protected Header, 698 or if the JWE JSON Serialization is being used, one or more of 699 the JWE Protected Header, the JWE Shared Unprotected Header, and 700 the JWE Per-Recipient Unprotected Header. 702 13. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 703 Protected Header)). If the JWE Protected Header is not present 704 (which can only happen when using the JWE JSON Serialization and 705 no "protected" member is present), let this value be the empty 706 string. 708 14. Let the Additional Authenticated Data encryption parameter be 709 ASCII(Encoded Protected Header). However if a JWE AAD value is 710 present (which can only be the case when using the JWE JSON 711 Serialization), instead let the Additional Authenticated Data 712 encryption parameter be ASCII(Encoded Protected Header || '.' || 713 BASE64URL(JWE AAD)). 715 15. Encrypt M using the CEK, the JWE Initialization Vector, and the 716 Additional Authenticated Data value using the specified content 717 encryption algorithm to create the JWE Ciphertext value and the 718 JWE Authentication Tag (which is the Authentication Tag output 719 from the encryption operation). 721 16. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext). 723 17. Compute the encoded authentication tag value BASE64URL(JWE 724 Authentication Tag). 726 18. If a JWE AAD value is present, compute the encoded AAD value 727 BASE64URL(JWE AAD). 729 19. Create the desired serialized output. The Compact Serialization 730 of this result is the string BASE64URL(UTF8(JWE Protected 731 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 732 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 733 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). The 734 JWE JSON Serialization is described in Section 7.2. 736 5.2. Message Decryption 738 The message decryption process is the reverse of the encryption 739 process. The order of the steps is not significant in cases where 740 there are no dependencies between the inputs and outputs of the 741 steps. If any of these steps fails, the encrypted content cannot be 742 validated. 744 When there are multiple recipients, it is an application decision 745 which of the recipients' encrypted content must successfully validate 746 for the JWE to be accepted. In some cases, encrypted content for all 747 recipients must successfully validate or the JWE will be rejected. 748 In other cases, only the encrypted content for a single recipient 749 needs to be successfully validated. However, in all cases, the 750 encrypted content for at least one recipient MUST successfully 751 validate or the JWE MUST be rejected. 753 1. Parse the JWE representation to extract the serialized values 754 for the components of the JWE. When using the JWE Compact 755 Serialization, these components are the base64url encoded 756 representations of the JWE Protected Header, the JWE Encrypted 757 Key, the JWE Initialization Vector, the JWE Ciphertext, and the 758 JWE Authentication Tag, and when using the JWE JSON 759 Serialization, these components also include the base64url 760 encoded representation of the JWE AAD and the unencoded JWE 761 Shared Unprotected Header and JWE Per-Recipient Unprotected 762 Header values. When using the JWE Compact Serialization, the 763 JWE Protected Header, the JWE Encrypted Key, the JWE 764 Initialization Vector, the JWE Ciphertext, and the JWE 765 Authentication Tag are represented as base64url encoded values 766 in that order, separated by four period ('.') characters. The 767 JWE JSON Serialization is described in Section 7.2. 769 2. Base64url decode the encoded representations of the JWE 770 Protected Header, the JWE Encrypted Key, the JWE Initialization 771 Vector, the JWE Ciphertext, the JWE Authentication Tag, and the 772 JWE AAD, following the restriction that no line breaks, white 773 space, or other additional characters have been used. 775 3. Verify that the octet sequence resulting from decoding the 776 encoded JWE Protected Header is a UTF-8 encoded representation 777 of a completely valid JSON object conforming to RFC 7159 778 [RFC7159]; let the JWE Protected Header be this JSON object. 780 4. If using the JWE Compact Serialization, let the JOSE Header be 781 the JWE Protected Header. Otherwise, when using the JWE JSON 782 Serialization, let the JOSE Header be the union of the members 783 of the JWE Protected Header, the JWE Shared Unprotected Header 784 and the corresponding JWE Per-Recipient Unprotected Header, all 785 of which must be completely valid JSON objects. During this 786 step, verify that the resulting JOSE Header does not contain 787 duplicate Header Parameter names. When using the JWE JSON 788 Serialization, this restriction includes that the same Header 789 Parameter name also MUST NOT occur in distinct JSON object 790 values that together comprise the JOSE Header. 792 5. Verify that the implementation understands and can process all 793 fields that it is required to support, whether required by this 794 specification, by the algorithms being used, or by the "crit" 795 Header Parameter value, and that the values of those parameters 796 are also understood and supported. 798 6. Determine the Key Management Mode employed by the algorithm 799 specified by the "alg" (algorithm) Header Parameter. 801 7. Verify that the JWE uses a key known to the recipient. 803 8. When Direct Key Agreement or Key Agreement with Key Wrapping are 804 employed, use the key agreement algorithm to compute the value 805 of the agreed upon key. When Direct Key Agreement is employed, 806 let the Content Encryption Key (CEK) be the agreed upon key. 807 When Key Agreement with Key Wrapping is employed, the agreed 808 upon key will be used to decrypt the JWE Encrypted Key. 810 9. When Key Wrapping, Key Encryption, or Key Agreement with Key 811 Wrapping are employed, decrypt the JWE Encrypted Key to produce 812 the Content Encryption Key (CEK). The CEK MUST have a length 813 equal to that required for the content encryption algorithm. 814 Note that when there are multiple recipients, each recipient 815 will only be able decrypt any JWE Encrypted Key values that were 816 encrypted to a key in that recipient's possession. It is 817 therefore normal to only be able to decrypt one of the per- 818 recipient JWE Encrypted Key values to obtain the CEK value. 819 Also, see Section 11.5 for security considerations on mitigating 820 timing attacks. 822 10. When Direct Key Agreement or Direct Encryption are employed, 823 verify that the JWE Encrypted Key value is empty octet sequence. 825 11. When Direct Encryption is employed, let the Content Encryption 826 Key (CEK) be the shared symmetric key. 828 12. Record whether the CEK could be successfully determined for this 829 recipient or not. 831 13. If the JWE JSON Serialization is being used, repeat this process 832 (steps 4-12) for each recipient contained in the representation. 834 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 835 Protected Header)). If the JWE Protected Header is not present 836 (which can only happen when using the JWE JSON Serialization and 837 no "protected" member is present), let this value be the empty 838 string. 840 15. Let the Additional Authenticated Data encryption parameter be 841 ASCII(Encoded Protected Header). However if a JWE AAD value is 842 present (which can only be the case when using the JWE JSON 843 Serialization), instead let the Additional Authenticated Data 844 encryption parameter be ASCII(Encoded Protected Header || '.' || 845 BASE64URL(JWE AAD)). 847 16. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 848 Vector, the Additional Authenticated Data value, and the JWE 849 Authentication Tag (which is the Authentication Tag input to the 850 calculation) using the specified content encryption algorithm, 851 returning the decrypted plaintext and validating the JWE 852 Authentication Tag in the manner specified for the algorithm, 853 rejecting the input without emitting any decrypted output if the 854 JWE Authentication Tag is incorrect. 856 17. If a "zip" parameter was included, uncompress the decrypted 857 plaintext using the specified compression algorithm. 859 18. If there was no recipient for which all of the decryption steps 860 succeeded, then the JWE MUST be rejected. Otherwise, output the 861 Plaintext. In the JWE JSON Serialization case, also return a 862 result to the application indicating for which of the recipients 863 the decryption succeeded and failed. 865 Finally, note that it is an application decision which algorithms may 866 be used in a given context. Even if a JWE can be successfully 867 decrypted, unless the algorithms used in the JWE are acceptable to 868 the application, it SHOULD reject the JWE. 870 5.3. String Comparison Rules 872 The string comparison rules for this specification are the same as 873 those defined in Section 5.3 of [JWS]. 875 6. Key Identification 877 The key identification methods for this specification are the same as 878 those defined in Section 6 of [JWS], except that the key being 879 identified is the public key to which the JWE was encrypted. 881 7. Serializations 883 JWE objects use one of two serializations, the JWE Compact 884 Serialization or the JWE JSON Serialization. Applications using this 885 specification need to specify what serialization and serialization 886 features are used for that application. For instance, applications 887 might specify that only the JWE JSON Serialization is used, that only 888 JWE JSON Serialization support for a single recipient is used, or 889 that support for multiple recipients is used. JWE implementations 890 only need to implement the features needed for the applications they 891 are designed to support. 893 7.1. JWE Compact Serialization 895 The JWE Compact Serialization represents encrypted content as a 896 compact, URL-safe string. This string is: 898 BASE64URL(UTF8(JWE Protected Header)) || '.' || 899 BASE64URL(JWE Encrypted Key) || '.' || 900 BASE64URL(JWE Initialization Vector) || '.' || 901 BASE64URL(JWE Ciphertext) || '.' || 902 BASE64URL(JWE Authentication Tag) 904 Only one recipient is supported by the JWE Compact Serialization and 905 it provides no syntax to represent JWE Shared Unprotected Header, JWE 906 Per-Recipient Unprotected Header, or JWE AAD values. 908 7.2. JWE JSON Serialization 910 The JWE JSON Serialization represents encrypted content as a JSON 911 object. Content using the JWE JSON Serialization can be encrypted to 912 more than one recipient. This representation is neither optimized 913 for compactness nor URL-safe. 915 The following members are defined for use in top-level JSON objects 916 used for the JWE JSON Serialization: 918 protected 919 The "protected" member MUST be present and contain the value 920 BASE64URL(UTF8(JWE Protected Header)) when the JWE Protected 921 Header value is non-empty; otherwise, it MUST be absent. These 922 Header Parameter values are integrity protected. 924 unprotected 925 The "unprotected" member MUST be present and contain the value JWE 926 Shared Unprotected Header when the JWE Shared Unprotected Header 927 value is non-empty; otherwise, it MUST be absent. This value is 928 represented as an unencoded JSON object, rather than as a string. 929 These Header Parameter values are not integrity protected. 931 iv 932 The "iv" member MUST be present and contain the value 933 BASE64URL(JWE Initialization Vector) when the JWE Initialization 934 Vector value is non-empty; otherwise, it MUST be absent. 936 aad 937 The "aad" member MUST be present and contain the value 938 BASE64URL(JWE AAD)) when the JWE AAD value is non-empty; 939 otherwise, it MUST be absent. A JWE AAD value can be included to 940 supply a base64url encoded value to be integrity protected but not 941 encrypted. 943 ciphertext 944 The "ciphertext" member MUST be present and contain the value 945 BASE64URL(JWE Ciphertext). 947 tag 948 The "tag" member MUST be present and contain the value 949 BASE64URL(JWE Authentication Tag) when the JWE Authentication Tag 950 value is non-empty; otherwise, it MUST be absent. 952 recipients 953 The "recipients" member value MUST be an array of JSON objects. 954 Each object contains information specific to a single recipient. 955 This member MUST be present with exactly one array element per 956 recipient, even if some or all of the array element values are the 957 empty JSON object "{}" (which can happen when all Header Parameter 958 values are shared between all recipients and when no encrypted key 959 is used, such as when doing Direct Encryption). 961 The following members are defined for use in the JSON objects that 962 are elements of the "recipients" array: 964 header 965 The "header" member MUST be present and contain the value JWE Per- 966 Recipient Unprotected Header when the JWE Per-Recipient 967 Unprotected Header value is non-empty; otherwise, it MUST be 968 absent. This value is represented as an unencoded JSON object, 969 rather than as a string. These Header Parameter values are not 970 integrity protected. 972 encrypted_key 973 The "encrypted_key" member MUST be present and contain the value 974 BASE64URL(JWE Encrypted Key) when the JWE Encrypted Key value is 975 non-empty; otherwise, it MUST be absent. 977 At least one of the "header", "protected", and "unprotected" members 978 MUST be present so that "alg" and "enc" Header Parameter values are 979 conveyed for each recipient computation. 981 Additional members can be present in both the JSON objects defined 982 above; if not understood by implementations encountering them, they 983 MUST be ignored. 985 Some Header Parameters, including the "alg" parameter, can be shared 986 among all recipient computations. Header Parameters in the JWE 987 Protected Header and JWE Shared Unprotected Header values are shared 988 among all recipients. 990 The Header Parameter values used when creating or validating per- 991 recipient Ciphertext and Authentication Tag values are the union of 992 the three sets of Header Parameter values that may be present: (1) 993 the JWE Protected Header represented in the "protected" member, (2) 994 the JWE Shared Unprotected Header represented in the "unprotected" 995 member, and (3) the JWE Per-Recipient Unprotected Header represented 996 in the "header" member of the recipient's array element. The union 997 of these sets of Header Parameters comprises the JOSE Header. The 998 Header Parameter names in the three locations MUST be disjoint. 1000 Each JWE Encrypted Key value is computed using the parameters of the 1001 corresponding JOSE Header value in the same manner as for the JWE 1002 Compact Serialization. This has the desirable property that each JWE 1003 Encrypted Key value in the "recipients" array is identical to the 1004 value that would have been computed for the same parameter in the JWE 1005 Compact Serialization. Likewise, the JWE Ciphertext and JWE 1006 Authentication Tag values match those produced for the JWE Compact 1007 Serialization, provided that the JWE Protected Header value (which 1008 represents the integrity-protected Header Parameter values) matches 1009 that used in the JWE Compact Serialization. 1011 All recipients use the same JWE Protected Header, JWE Initialization 1012 Vector, JWE Ciphertext, and JWE Authentication Tag values, when 1013 present, resulting in potentially significant space savings if the 1014 message is large. Therefore, all Header Parameters that specify the 1015 treatment of the Plaintext value MUST be the same for all recipients. 1016 This primarily means that the "enc" (encryption algorithm) Header 1017 Parameter value in the JOSE Header for each recipient and any 1018 parameters of that algorithm MUST be the same. 1020 In summary, the syntax of a JWE using the JWE JSON Serialization is 1021 as follows: 1023 {"protected":"", 1024 "unprotected":, 1025 "recipients":[ 1026 {"header":, 1027 "encrypted_key":""}, 1028 ... 1029 {"header":, 1030 "encrypted_key":""}], 1031 "aad":"", 1032 "iv":"", 1033 "ciphertext":"", 1034 "tag":"" 1035 } 1037 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1038 Serialization. 1040 8. TLS Requirements 1042 The TLS requirements for this specification are the same as those 1043 defined in Section 8 of [JWS]. 1045 9. Distinguishing between JWS and JWE Objects 1047 There are several ways of distinguishing whether an object is a JWS 1048 or JWE object. All these methods will yield the same result for all 1049 legal input values; they may yield different results for malformed 1050 inputs. 1052 o If the object is using the JWS Compact Serialization or the JWE 1053 Compact Serialization, the number of base64url encoded segments 1054 separated by period ('.') characters differs for JWSs and JWEs. 1055 JWSs have three segments separated by two period ('.') characters. 1056 JWEs have five segments separated by four period ('.') characters. 1058 o If the object is using the JWS JSON Serialization or the JWE JSON 1059 Serialization, the members used will be different. JWSs have a 1060 "signatures" member and JWEs do not. JWEs have a "recipients" 1061 member and JWSs do not. 1063 o The JOSE Header for a JWS object can be distinguished from the 1064 JOSE Header for a JWE object by examining the "alg" (algorithm) 1065 Header Parameter value. If the value represents a digital 1066 signature or MAC algorithm, or is the value "none", it is for a 1067 JWS; if it represents a Key Encryption, Key Wrapping, Direct Key 1068 Agreement, Key Agreement with Key Wrapping, or Direct Encryption 1069 algorithm, it is for a JWE. (Extracting the "alg" value to 1070 examine is straightforward when using the JWS Compact 1071 Serialization or the JWE Compact Serialization and may be more 1072 difficult when using the JWS JSON Serialization or the JWE JSON 1073 Serialization.) 1075 o The JOSE Header for a JWS object can also be distinguished from 1076 the JOSE Header for a JWE object by determining whether an "enc" 1077 (encryption algorithm) member exists. If the "enc" member exists, 1078 it is a JWE; otherwise, it is a JWS. 1080 10. IANA Considerations 1082 10.1. JSON Web Signature and Encryption Header Parameters Registration 1084 This specification registers the Header Parameter names defined in 1085 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1086 Parameters registry defined in [JWS]. 1088 10.1.1. Registry Contents 1090 o Header Parameter Name: "alg" 1091 o Header Parameter Description: Algorithm 1092 o Header Parameter Usage Location(s): JWE 1093 o Change Controller: IESG 1094 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1095 o Header Parameter Name: "enc" 1096 o Header Parameter Description: Encryption Algorithm 1097 o Header Parameter Usage Location(s): JWE 1098 o Change Controller: IESG 1099 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1101 o Header Parameter Name: "zip" 1102 o Header Parameter Description: Compression Algorithm 1103 o Header Parameter Usage Location(s): JWE 1104 o Change Controller: IESG 1105 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1107 o Header Parameter Name: "jku" 1108 o Header Parameter Description: JWK Set URL 1109 o Header Parameter Usage Location(s): JWE 1110 o Change Controller: IESG 1111 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1113 o Header Parameter Name: "jwk" 1114 o Header Parameter Description: JSON Web Key 1115 o Header Parameter Usage Location(s): JWE 1116 o Change Controller: IESG 1117 o Specification document(s): Section 4.1.5 of [[ this document ]] 1119 o Header Parameter Name: "kid" 1120 o Header Parameter Description: Key ID 1121 o Header Parameter Usage Location(s): JWE 1122 o Change Controller: IESG 1123 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1125 o Header Parameter Name: "x5u" 1126 o Header Parameter Description: X.509 URL 1127 o Header Parameter Usage Location(s): JWE 1128 o Change Controller: IESG 1129 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1131 o Header Parameter Name: "x5c" 1132 o Header Parameter Description: X.509 Certificate Chain 1133 o Header Parameter Usage Location(s): JWE 1134 o Change Controller: IESG 1135 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1137 o Header Parameter Name: "x5t" 1138 o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint 1139 o Header Parameter Usage Location(s): JWE 1140 o Change Controller: IESG 1141 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1143 o Header Parameter Name: "x5t#S256" 1144 o Header Parameter Description: X.509 Certificate SHA-256 Thumbprint 1145 o Header Parameter Usage Location(s): JWE 1146 o Change Controller: IESG 1147 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1149 o Header Parameter Name: "typ" 1150 o Header Parameter Description: Type 1151 o Header Parameter Usage Location(s): JWE 1152 o Change Controller: IESG 1153 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1155 o Header Parameter Name: "cty" 1156 o Header Parameter Description: Content Type 1157 o Header Parameter Usage Location(s): JWE 1158 o Change Controller: IESG 1159 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1161 o Header Parameter Name: "crit" 1162 o Header Parameter Description: Critical 1163 o Header Parameter Usage Location(s): JWE 1164 o Change Controller: IESG 1165 o Specification Document(s): Section 4.1.13 of [[ this document ]] 1167 11. Security Considerations 1169 All of the security issues that are pertinent to any cryptographic 1170 application must be addressed by JWS/JWE/JWK agents. Among these 1171 issues are protecting the user's asymmetric private and symmetric 1172 secret keys and employing countermeasures to various attacks. 1174 All the security considerations in the JWS specification also apply 1175 to this specification. Likewise, all the security considerations in 1176 XML Encryption 1.1 [W3C.REC-xmlenc-core1-20130411] also apply, other 1177 than those that are XML specific. 1179 11.1. Key Entropy and Random Values 1181 See Section 10.1 of [JWS] for security considerations on key entropy 1182 and random values. In addition to the uses of random values listed 1183 there, note that random values are also used for content encryption 1184 keys (CEKs) and initialization vectors (IVs) when performing 1185 encryption. 1187 11.2. Key Protection 1189 See Section 10.2 of [JWS] for security considerations on key 1190 protection. In addition to the keys listed there that must be 1191 protected, implementations performing encryption must protect the key 1192 encryption key and the content encryption key. Compromise of the key 1193 encryption key may result in the disclosure of all contents protected 1194 with that key. Similarly, compromise of the content encryption key 1195 may result in disclosure of the associated encrypted content. 1197 11.3. Using Matching Algorithm Strengths 1199 Algorithms of matching strengths should be used together whenever 1200 possible. For instance, when AES Key Wrap is used with a given key 1201 size, using the same key size is recommended when AES GCM is also 1202 used. If the key encryption and content encryption algorithms are 1203 different, the effective security is determined by the weaker of the 1204 two algorithms. 1206 Also, see RFC 3766 [RFC3766] for information on determining strengths 1207 for public keys used for exchanging symmetric keys. 1209 11.4. Adaptive Chosen-Ciphertext Attacks 1211 When decrypting, particular care must be taken not to allow the JWE 1212 recipient to be used as an oracle for decrypting messages. RFC 3218 1213 [RFC3218] should be consulted for specific countermeasures to attacks 1214 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1215 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1216 formatting error that can be detected and used to recover the CEK 1217 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1218 particularly important to report all formatting errors to the CEK, 1219 Additional Authenticated Data, or ciphertext as a single error when 1220 the encrypted content is rejected. 1222 Additionally, this type of attack can be prevented by restricting the 1223 use of a key to a limited set of algorithms -- usually one. This 1224 means, for instance, that if the key is marked as being for 1225 "RSA-OAEP" only, any attempt to decrypt a message using the "RSA1_5" 1226 algorithm with that key should fail immediately due to invalid use of 1227 the key. 1229 11.5. Timing Attacks 1231 To mitigate the attacks described in RFC 3218 [RFC3218], the 1232 recipient MUST NOT distinguish between format, padding, and length 1233 errors of encrypted keys. It is strongly recommended, in the event 1234 of receiving an improperly formatted key, that the recipient 1235 substitute a randomly generated CEK and proceed to the next step, to 1236 mitigate timing attacks. 1238 12. References 1240 12.1. Normative References 1242 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1243 draft-ietf-jose-json-web-algorithms (work in progress), 1244 October 2014. 1246 [JWK] Jones, M., "JSON Web Key (JWK)", 1247 draft-ietf-jose-json-web-key (work in progress), 1248 October 2014. 1250 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1251 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1252 in progress), October 2014. 1254 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1255 version 1.3", RFC 1951, May 1996. 1257 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1258 Requirement Levels", BCP 14, RFC 2119, March 1997. 1260 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1261 10646", STD 63, RFC 3629, November 2003. 1263 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1264 RFC 4949, August 2007. 1266 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1267 Housley, R., and W. Polk, "Internet X.509 Public Key 1268 Infrastructure Certificate and Certificate Revocation List 1269 (CRL) Profile", RFC 5280, May 2008. 1271 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1272 Interchange Format", RFC 7159, March 2014. 1274 [USASCII] American National Standards Institute, "Coded Character 1275 Set -- 7-bit American Standard Code for Information 1276 Interchange", ANSI X3.4, 1986. 1278 12.2. Informative References 1280 [AES] National Institute of Standards and Technology (NIST), 1281 "Advanced Encryption Standard (AES)", FIPS PUB 197, 1282 November 2001. 1284 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1285 McGrew, D., Foley, J., and K. Paterson, "Authenticated 1286 Encryption with AES-CBC and HMAC-SHA", 1287 draft-mcgrew-aead-aes-cbc-hmac-sha2-05 (work in progress), 1288 July 2014. 1290 [I-D.rescorla-jsms] 1291 Rescorla, E. and J. Hildebrand, "JavaScript Message 1292 Security Format", draft-rescorla-jsms-00 (work in 1293 progress), March 2011. 1295 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1296 Encryption", September 2010. 1298 [NIST.800-38D] 1299 National Institute of Standards and Technology (NIST), 1300 "Recommendation for Block Cipher Modes of Operation: 1301 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 1302 December 2001. 1304 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1305 Cryptographic Message Syntax", RFC 3218, January 2002. 1307 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1308 Standards (PKCS) #1: RSA Cryptography Specifications 1309 Version 2.1", RFC 3447, February 2003. 1311 [RFC3766] Orman, H. and P. Hoffman, "Determining Strengths For 1312 Public Keys Used For Exchanging Symmetric Keys", BCP 86, 1313 RFC 3766, April 2004. 1315 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1316 Requirements for Security", BCP 106, RFC 4086, June 2005. 1318 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1319 RFC 5652, September 2009. 1321 [W3C.REC-xmlenc-core1-20130411] 1322 Eastlake, D., Reagle, J., Hirsch, F., and T. Roessler, 1323 "XML Encryption Syntax and Processing Version 1.1", World 1324 Wide Web Consortium Recommendation REC-xmlenc-core1- 1325 20130411, April 2013, 1326 . 1328 Appendix A. JWE Examples 1330 This section provides examples of JWE computations. 1332 A.1. Example JWE using RSAES OAEP and AES GCM 1334 This example encrypts the plaintext "The true sign of intelligence is 1335 not knowledge but imagination." to the recipient using RSAES OAEP for 1336 key encryption and AES GCM for content encryption. The 1337 representation of this plaintext (using JSON array notation) is: 1339 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1340 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1341 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1342 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1343 110, 97, 116, 105, 111, 110, 46] 1345 A.1.1. JOSE Header 1347 The following example JWE Protected Header declares that: 1349 o the Content Encryption Key is encrypted to the recipient using the 1350 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1352 o authenticated encryption is performed on the Plaintext using the 1353 AES GCM algorithm with a 256 bit key to produce the Ciphertext and 1354 the Authentication Tag. 1356 {"alg":"RSA-OAEP","enc":"A256GCM"} 1358 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1359 Header)) gives this value: 1361 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1363 A.1.2. Content Encryption Key (CEK) 1365 Generate a 256 bit random Content Encryption Key (CEK). In this 1366 example, the value (using JSON array notation) is: 1368 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1369 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1370 234, 64, 252] 1372 A.1.3. Key Encryption 1374 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1375 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1376 key represented in JSON Web Key [JWK] format below (with line breaks 1377 within values for display purposes only): 1379 {"kty":"RSA", 1380 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1381 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1382 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1383 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1384 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1385 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1386 "e":"AQAB", 1387 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1388 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1389 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1390 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1391 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1392 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ" 1393 } 1395 The resulting JWE Encrypted Key value is: 1397 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1398 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1399 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1400 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1401 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1402 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1403 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1404 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1405 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1406 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1407 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1408 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1409 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1410 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1411 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1412 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1413 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1414 117, 114, 135, 206] 1416 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1417 this value (with line breaks for display purposes only): 1419 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1420 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1421 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1422 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1423 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1424 6UklfCpIMfIjf7iGdXKHzg 1426 A.1.4. Initialization Vector 1428 Generate a random 96 bit JWE Initialization Vector. In this example, 1429 the value is: 1431 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1433 Encoding this JWE Initialization Vector as BASE64URL(JWE 1434 Initialization Vector) gives this value: 1436 48V1_ALb6US04U3b 1438 A.1.5. Additional Authenticated Data 1440 Let the Additional Authenticated Data encryption parameter be 1441 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1443 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1444 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1445 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1447 A.1.6. Content Encryption 1449 Perform authenticated encryption on the Plaintext with the AES GCM 1450 algorithm using the CEK as the encryption key, the JWE Initialization 1451 Vector, and the Additional Authenticated Data value above, requesting 1452 a 128 bit Authentication Tag output. The resulting Ciphertext is: 1454 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1455 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1456 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1457 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1458 160, 109, 64, 63, 192] 1460 The resulting Authentication Tag value is: 1462 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1463 210, 145] 1465 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1466 value (with line breaks for display purposes only): 1468 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1469 SdiwkIr3ajwQzaBtQD_A 1471 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1472 Tag) gives this value: 1474 XFBoMYUZodetZdvTiFvSkQ 1476 A.1.7. Complete Representation 1478 Assemble the final representation: The Compact Serialization of this 1479 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1480 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1481 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1482 Authentication Tag). 1484 The final result in this example (with line breaks for display 1485 purposes only) is: 1487 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1488 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1489 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1490 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1491 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1492 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1493 6UklfCpIMfIjf7iGdXKHzg. 1494 48V1_ALb6US04U3b. 1495 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1496 SdiwkIr3ajwQzaBtQD_A. 1497 XFBoMYUZodetZdvTiFvSkQ 1499 A.1.8. Validation 1501 This example illustrates the process of creating a JWE with RSAES 1502 OAEP for key encryption and AES GCM for content encryption. These 1503 results can be used to validate JWE decryption implementations for 1504 these algorithms. Note that since the RSAES OAEP computation 1505 includes random values, the encryption results above will not be 1506 completely reproducible. However, since the AES GCM computation is 1507 deterministic, the JWE Encrypted Ciphertext values will be the same 1508 for all encryptions performed using these inputs. 1510 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1512 This example encrypts the plaintext "Live long and prosper." to the 1513 recipient using RSAES-PKCS1-V1_5 for key encryption and 1514 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1515 of this plaintext (using JSON array notation) is: 1517 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1518 112, 114, 111, 115, 112, 101, 114, 46] 1520 A.2.1. JOSE Header 1522 The following example JWE Protected Header declares that: 1524 o the Content Encryption Key is encrypted to the recipient using the 1525 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1527 o authenticated encryption is performed on the Plaintext using the 1528 AES_128_CBC_HMAC_SHA_256 algorithm to produce the Ciphertext and 1529 the Authentication Tag. 1531 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1533 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1534 Header)) gives this value: 1536 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1538 A.2.2. Content Encryption Key (CEK) 1540 Generate a 256 bit random Content Encryption Key (CEK). In this 1541 example, the key value is: 1543 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1544 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1545 44, 207] 1547 A.2.3. Key Encryption 1549 Encrypt the CEK with the recipient's public key using the RSAES- 1550 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1551 uses the RSA key represented in JSON Web Key [JWK] format below (with 1552 line breaks within values for display purposes only): 1554 {"kty":"RSA", 1555 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1556 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1557 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1558 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1559 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1560 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1561 "e":"AQAB", 1562 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1563 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1564 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1565 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1566 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1567 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1568 } 1570 The resulting JWE Encrypted Key value is: 1572 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1573 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1574 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1575 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1576 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1577 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1578 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1579 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1580 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1581 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1582 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1583 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1584 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1585 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1586 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1587 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1588 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1589 146, 114, 165, 204, 71, 136, 41, 252] 1591 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1592 this value (with line breaks for display purposes only): 1594 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1595 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1596 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1597 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1598 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1599 -B3oWh2TbqmScqXMR4gp_A 1601 A.2.4. Initialization Vector 1603 Generate a random 128 bit JWE Initialization Vector. In this 1604 example, the value is: 1606 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1607 101] 1609 Encoding this JWE Initialization Vector as BASE64URL(JWE 1610 Initialization Vector) gives this value: 1612 AxY8DCtDaGlsbGljb3RoZQ 1614 A.2.5. Additional Authenticated Data 1616 Let the Additional Authenticated Data encryption parameter be 1617 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1619 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1620 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1621 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1622 50, 73, 110, 48] 1624 A.2.6. Content Encryption 1626 Perform authenticated encryption on the Plaintext with the 1627 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1628 key, the JWE Initialization Vector, and the Additional Authenticated 1629 Data value above. The steps for doing this using the values from 1630 Appendix A.3 are detailed in Appendix B. The resulting Ciphertext 1631 is: 1633 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1634 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1635 112, 56, 102] 1637 The resulting Authentication Tag value is: 1639 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1640 191] 1642 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1643 value: 1645 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1647 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1648 Tag) gives this value: 1650 9hH0vgRfYgPnAHOd8stkvw 1652 A.2.7. Complete Representation 1654 Assemble the final representation: The Compact Serialization of this 1655 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1656 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1657 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1658 Authentication Tag). 1660 The final result in this example (with line breaks for display 1661 purposes only) is: 1663 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1664 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1665 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1666 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1667 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1668 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1669 -B3oWh2TbqmScqXMR4gp_A. 1670 AxY8DCtDaGlsbGljb3RoZQ. 1671 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1672 9hH0vgRfYgPnAHOd8stkvw 1674 A.2.8. Validation 1676 This example illustrates the process of creating a JWE with RSAES- 1677 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1678 encryption. These results can be used to validate JWE decryption 1679 implementations for these algorithms. Note that since the RSAES- 1680 PKCS1-V1_5 computation includes random values, the encryption results 1681 above will not be completely reproducible. However, since the AES 1682 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1683 will be the same for all encryptions performed using these inputs. 1685 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1687 This example encrypts the plaintext "Live long and prosper." to the 1688 recipient using AES Key Wrap for key encryption and 1689 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1690 of this plaintext (using JSON array notation) is: 1692 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1693 112, 114, 111, 115, 112, 101, 114, 46] 1695 A.3.1. JOSE Header 1697 The following example JWE Protected Header declares that: 1699 o the Content Encryption Key is encrypted to the recipient using the 1700 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1701 Encrypted Key and 1703 o authenticated encryption is performed on the Plaintext using the 1704 AES_128_CBC_HMAC_SHA_256 algorithm to produce the Ciphertext and 1705 the Authentication Tag. 1707 {"alg":"A128KW","enc":"A128CBC-HS256"} 1709 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1710 Header)) gives this value: 1712 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1714 A.3.2. Content Encryption Key (CEK) 1716 Generate a 256 bit random Content Encryption Key (CEK). In this 1717 example, the value is: 1719 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1720 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1721 44, 207] 1723 A.3.3. Key Encryption 1725 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1726 algorithm to produce the JWE Encrypted Key. This example uses the 1727 symmetric key represented in JSON Web Key [JWK] format below: 1729 {"kty":"oct", 1730 "k":"GawgguFyGrWKav7AX4VKUg" 1731 } 1733 The resulting JWE Encrypted Key value is: 1735 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1736 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1737 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1739 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1740 this value: 1742 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1744 A.3.4. Initialization Vector 1746 Generate a random 128 bit JWE Initialization Vector. In this 1747 example, the value is: 1749 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1750 101] 1752 Encoding this JWE Initialization Vector as BASE64URL(JWE 1753 Initialization Vector) gives this value: 1755 AxY8DCtDaGlsbGljb3RoZQ 1757 A.3.5. Additional Authenticated Data 1759 Let the Additional Authenticated Data encryption parameter be 1760 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1762 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1763 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1764 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1765 110, 48] 1767 A.3.6. Content Encryption 1769 Perform authenticated encryption on the Plaintext with the 1770 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1771 key, the JWE Initialization Vector, and the Additional Authenticated 1772 Data value above. The steps for doing this using the values from 1773 this example are detailed in Appendix B. The resulting Ciphertext 1774 is: 1776 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1777 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1778 112, 56, 102] 1780 The resulting Authentication Tag value is: 1782 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1783 194, 85] 1785 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1786 value: 1788 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1790 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1791 Tag) gives this value: 1793 U0m_YmjN04DJvceFICbCVQ 1795 A.3.7. Complete Representation 1797 Assemble the final representation: The Compact Serialization of this 1798 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1799 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1800 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1801 Authentication Tag). 1803 The final result in this example (with line breaks for display 1804 purposes only) is: 1806 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1807 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1808 AxY8DCtDaGlsbGljb3RoZQ. 1809 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1810 U0m_YmjN04DJvceFICbCVQ 1812 A.3.8. Validation 1814 This example illustrates the process of creating a JWE with AES Key 1815 Wrap for key encryption and AES GCM for content encryption. These 1816 results can be used to validate JWE decryption implementations for 1817 these algorithms. Also, since both the AES Key Wrap and AES GCM 1818 computations are deterministic, the resulting JWE value will be the 1819 same for all encryptions performed using these inputs. Since the 1820 computation is reproducible, these results can also be used to 1821 validate JWE encryption implementations for these algorithms. 1823 A.4. Example JWE using JWE JSON Serialization 1825 This section contains an example using the JWE JSON Serialization. 1826 This example demonstrates the capability for encrypting the same 1827 plaintext to multiple recipients. 1829 Two recipients are present in this example. The algorithm and key 1830 used for the first recipient are the same as that used in 1831 Appendix A.2. The algorithm and key used for the second recipient 1832 are the same as that used in Appendix A.3. The resulting JWE 1833 Encrypted Key values are therefore the same; those computations are 1834 not repeated here. 1836 The Plaintext, the Content Encryption Key (CEK), JWE Initialization 1837 Vector, and JWE Protected Header are shared by all recipients (which 1838 must be the case, since the Ciphertext and Authentication Tag are 1839 also shared). 1841 A.4.1. JWE Per-Recipient Unprotected Headers 1843 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1844 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1845 encrypt the CEK. Key ID values are supplied for both keys. The two 1846 per-recipient header values used to represent these algorithms and 1847 Key IDs are: 1849 {"alg":"RSA1_5","kid":"2011-04-29"} 1851 and 1853 {"alg":"A128KW","kid":"7"} 1855 A.4.2. JWE Protected Header 1857 Authenticated encryption is performed on the Plaintext using the 1858 AES_128_CBC_HMAC_SHA_256 algorithm to produce the common JWE 1859 Ciphertext and JWE Authentication Tag values. The JWE Protected 1860 Header value representing this is: 1862 {"enc":"A128CBC-HS256"} 1864 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1865 Header)) gives this value: 1867 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1869 A.4.3. JWE Unprotected Header 1871 This JWE uses the "jku" Header Parameter to reference a JWK Set. This 1872 is represented in the following JWE Unprotected Header value as: 1874 {"jku":"https://server.example.com/keys.jwks"} 1876 A.4.4. Complete JOSE Header Values 1878 Combining the per-recipient, protected, and unprotected header values 1879 supplied, the JOSE Header values used for the first and second 1880 recipient respectively are: 1882 {"alg":"RSA1_5", 1883 "kid":"2011-04-29", 1884 "enc":"A128CBC-HS256", 1885 "jku":"https://server.example.com/keys.jwks"} 1887 and 1889 {"alg":"A128KW", 1890 "kid":"7", 1891 "enc":"A128CBC-HS256", 1892 "jku":"https://server.example.com/keys.jwks"} 1894 A.4.5. Additional Authenticated Data 1896 Let the Additional Authenticated Data encryption parameter be 1897 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1899 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1900 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1902 A.4.6. Content Encryption 1904 Perform authenticated encryption on the Plaintext with the 1905 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1906 key, the JWE Initialization Vector, and the Additional Authenticated 1907 Data value above. The steps for doing this using the values from 1908 Appendix A.3 are detailed in Appendix B. The resulting Ciphertext 1909 is: 1911 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1912 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1913 112, 56, 102] 1915 The resulting Authentication Tag value is: 1917 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1918 207] 1920 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1921 value: 1923 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1925 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1926 Tag) gives this value: 1928 Mz-VPPyU4RlcuYv1IwIvzw 1930 A.4.7. Complete JWE JSON Serialization Representation 1932 The complete JSON Web Encryption JSON Serialization for these values 1933 is as follows (with line breaks within values for display purposes 1934 only): 1936 {"protected": 1937 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1938 "unprotected": 1939 {"jku":"https://server.example.com/keys.jwks"}, 1940 "recipients":[ 1941 {"header": 1942 {"alg":"RSA1_5","kid":"2011-04-29"}, 1943 "encrypted_key": 1944 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1945 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1946 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 1947 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 1948 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 1949 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 1950 {"header": 1951 {"alg":"A128KW","kid":"7"}, 1952 "encrypted_key": 1953 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1954 "iv": 1955 "AxY8DCtDaGlsbGljb3RoZQ", 1956 "ciphertext": 1957 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1958 "tag": 1959 "Mz-VPPyU4RlcuYv1IwIvzw" 1960 } 1962 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 1964 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 1965 authenticated encryption computation using the values from the 1966 example in Appendix A.3. As described where this algorithm is 1967 defined in Sections 5.2 and 5.2.3 of JWA, the AES_CBC_HMAC_SHA2 1968 family of algorithms are implemented using Advanced Encryption 1969 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #7 1970 padding to perform the encryption and an HMAC SHA-2 function to 1971 perform the integrity calculation - in this case, HMAC SHA-256. 1973 B.1. Extract MAC_KEY and ENC_KEY from Key 1975 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example 1976 (using JSON array notation) is: 1978 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1979 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1980 44, 207] 1982 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 1983 which is: 1985 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1986 206] 1988 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 1989 is: 1991 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 1992 207] 1994 Note that the MAC key comes before the encryption key in the input 1995 key K; this is in the opposite order of the algorithm names in the 1996 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 1998 B.2. Encrypt Plaintext to Create Ciphertext 2000 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 2001 using PKCS #7 padding using the ENC_KEY above. The Plaintext in this 2002 example is: 2004 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 2005 112, 114, 111, 115, 112, 101, 114, 46] 2007 The encryption result is as follows, which is the Ciphertext output: 2009 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 2010 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 2011 112, 56, 102] 2013 B.3. 64 Bit Big Endian Representation of AAD Length 2015 The Additional Authenticated Data (AAD) in this example is: 2017 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2018 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2019 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2020 110, 48] 2022 This AAD is 51 bytes long, which is 408 bits long. The octet string 2023 AL, which is the number of bits in AAD expressed as a big endian 64 2024 bit unsigned integer is: 2026 [0, 0, 0, 0, 0, 0, 1, 152] 2028 B.4. Initialization Vector Value 2030 The Initialization Vector value used in this example is: 2032 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 2033 101] 2035 B.5. Create Input to HMAC Computation 2037 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 2038 the AL value. The result of this concatenation is: 2040 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2041 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2042 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2043 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 2044 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 2045 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 2046 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 2048 B.6. Compute HMAC Value 2050 Compute the HMAC SHA-256 of the concatenated value above. This 2051 result M is: 2053 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2054 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 2055 86, 229, 116] 2057 B.7. Truncate HMAC Value to Create Authentication Tag 2059 Use the first half (128 bits) of the HMAC output M as the 2060 Authentication Tag output T. This truncated value is: 2062 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2063 194, 85] 2065 Appendix C. Acknowledgements 2067 Solutions for encrypting JSON content were also explored by JSON 2068 Simple Encryption [JSE] and JavaScript Message Security Format 2069 [I-D.rescorla-jsms], both of which significantly influenced this 2070 draft. This draft attempts to explicitly reuse as many of the 2071 relevant concepts from XML Encryption 1.1 2072 [W3C.REC-xmlenc-core1-20130411] and RFC 5652 [RFC5652] as possible, 2073 while utilizing simple, compact JSON-based data structures. 2075 Special thanks are due to John Bradley, Eric Rescorla, and Nat 2076 Sakimura for the discussions that helped inform the content of this 2077 specification, to Eric Rescorla and Joe Hildebrand for allowing the 2078 reuse of text from [I-D.rescorla-jsms] in this document, and to Eric 2079 Rescorla for co-authoring many drafts of this specification. 2081 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2082 Jay for validating the examples in this specification. 2084 This specification is the work of the JOSE Working Group, which 2085 includes dozens of active and dedicated participants. In particular, 2086 the following individuals contributed ideas, feedback, and wording 2087 that influenced this specification: 2089 Richard Barnes, John Bradley, Brian Campbell, Alissa Cooper, Breno de 2090 Medeiros, Stephen Farrell, Dick Hardt, Jeff Hodges, Russ Housley, 2091 Edmund Jay, Scott Kelly, Stephen Kent, Barry Leiba, James Manger, 2092 Matt Miller, Kathleen Moriarty, Tony Nadalin, Hideki Nara, Axel 2093 Nennker, Emmanuel Raviart, Eric Rescorla, Pete Resnick, Nat Sakimura, 2094 Jim Schaad, Hannes Tschofenig, and Sean Turner. 2096 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2097 Sean Turner, Stephen Farrell, and Kathleen Moriarty served as 2098 Security area directors during the creation of this specification. 2100 Appendix D. Document History 2102 [[ to be removed by the RFC Editor before publication as an RFC ]] 2104 -34 2106 o Addressed IESG review comments by Barry Leiba, Alissa Cooper, Pete 2107 Resnick, Stephen Farrell, and Richard Barnes. 2109 -33 2111 o Noted that certificate thumbprints are also sometimes known as 2112 certificate fingerprints. 2114 o Changed to use the term "authenticated encryption" instead of 2115 "encryption", where appropriate. 2117 o Acknowledged additional contributors. 2119 -32 2120 o Addressed Gen-ART review comments by Russ Housley. 2122 o Addressed secdir review comments by Scott Kelly, Tero Kivinen, and 2123 Stephen Kent. 2125 -31 2127 o Updated the reference to draft-mcgrew-aead-aes-cbc-hmac-sha2. 2129 -30 2131 o Added subsection headings within the Overview section for the two 2132 serializations. 2134 o Added references and cleaned up the reference syntax in a few 2135 places. 2137 o Applied minor wording changes to the Security Considerations 2138 section and made other local editorial improvements. 2140 -29 2142 o Replaced the terms JWS Header, JWE Header, and JWT Header with a 2143 single JOSE Header term defined in the JWS specification. This 2144 also enabled a single Header Parameter definition to be used and 2145 reduced other areas of duplication between specifications. 2147 -28 2149 o Specified the use of PKCS #7 padding with AES CBC, rather than 2150 PKCS #5. (PKCS #7 is a superset of PKCS #5, and is appropriate 2151 for the 16 octet blocks used by AES CBC.) 2153 o Revised the introduction to the Security Considerations section. 2154 Also moved a security consideration item here from the JWA draft. 2156 -27 2158 o Described additional security considerations. 2160 o Added the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) header 2161 parameter. 2163 -26 2165 o Noted that octet sequences are depicted using JSON array notation. 2167 o Updated references, including to W3C specifications. 2169 -25 2171 o Corrected two external section number references that had changed. 2173 o Corrected a typo in an algorithm name in the prose of an example. 2175 -24 2177 o Corrected complete JSON Serialization example. 2179 o Replaced uses of the term "associated data" wherever it was used 2180 to refer to a data value with "additional authenticated data", 2181 since both terms were being used as synonyms, causing confusion. 2183 o Updated the JSON reference to RFC 7159. 2185 o Thanked Eric Rescorla for helping to author of most of the drafts 2186 of this specification and removed him from the current author 2187 list. 2189 -23 2191 o Corrected a use of the word "payload" to "plaintext". 2193 -22 2195 o Corrected RFC 2119 terminology usage. 2197 o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. 2199 -21 2201 o Changed some references from being normative to informative, 2202 addressing issue #90. 2204 o Applied review comments to the JSON Serialization section, 2205 addressing issue #178. 2207 -20 2209 o Made terminology definitions more consistent, addressing issue 2210 #165. 2212 o Restructured the JSON Serialization section to call out the 2213 parameters used in hanging lists, addressing issue #178. 2215 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 2216 addressing issue #90. 2218 -19 2220 o Reordered the key selection parameters. 2222 -18 2224 o Updated the mandatory-to-implement (MTI) language to say that 2225 applications using this specification need to specify what 2226 serialization and serialization features are used for that 2227 application, addressing issue #176. 2229 o Changes to address editorial and minor issues #89, #135, #165, 2230 #174, #175, #177, #179, and #180. 2232 o Used Header Parameter Description registry field. 2234 -17 2236 o Refined the "typ" and "cty" definitions to always be MIME Media 2237 Types, with the omission of "application/" prefixes recommended 2238 for brevity, addressing issue #50. 2240 o Updated the mandatory-to-implement (MTI) language to say that 2241 general-purpose implementations must implement the single 2242 recipient case for both serializations whereas special-purpose 2243 implementations can implement just one serialization if that meets 2244 the needs of the use cases the implementation is designed for, 2245 addressing issue #176. 2247 o Explicitly named all the logical components of a JWE and defined 2248 the processing rules and serializations in terms of those 2249 components, addressing issues #60, #61, and #62. 2251 o Replaced verbose repetitive phases such as "base64url encode the 2252 octets of the UTF-8 representation of X" with mathematical 2253 notation such as "BASE64URL(UTF8(X))". 2255 o Header Parameters and processing rules occurring in both JWS and 2256 JWE are now referenced in JWS by JWE, rather than duplicated, 2257 addressing issue #57. 2259 o Terms used in multiple documents are now defined in one place and 2260 incorporated by reference. Some lightly used or obvious terms 2261 were also removed. This addresses issue #58. 2263 -16 2265 o Changes to address editorial and minor issues #163, #168, #169, 2266 #170, #172, and #173. 2268 -15 2270 o Clarified that it is an application decision which recipients' 2271 encrypted content must successfully validate for the JWE to be 2272 accepted, addressing issue #35. 2274 o Changes to address editorial issues #34, #164, and #169. 2276 -14 2278 o Clarified that the "protected", "unprotected", "header", "iv", 2279 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2280 JSON Serialization when their values would be empty. Stated that 2281 the "recipients" array must always be present. 2283 -13 2285 o Added an "aad" (Additional Authenticated Data) member for the JWE 2286 JSON Serialization, enabling Additional Authenticated Data to be 2287 supplied that is not double base64url encoded, addressing issue 2288 #29. 2290 -12 2292 o Clarified that the "typ" and "cty" header parameters are used in 2293 an application-specific manner and have no effect upon the JWE 2294 processing. 2296 o Replaced the MIME types "application/jwe+json" and 2297 "application/jwe" with "application/jose+json" and 2298 "application/jose". 2300 o Stated that recipients MUST either reject JWEs with duplicate 2301 Header Parameter Names or use a JSON parser that returns only the 2302 lexically last duplicate member name. 2304 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2305 be with the algorithm descriptions that use them. 2307 o Added a Serializations section with parallel treatment of the JWE 2308 Compact Serialization and the JWE JSON Serialization and also 2309 moved the former Implementation Considerations content there. 2311 o Restored use of the term "AEAD". 2313 o Changed terminology from "block encryption" to "content 2314 encryption". 2316 -11 2318 o Added Key Identification section. 2320 o Removed the Encrypted Key value from the AAD computation since it 2321 is already effectively integrity protected by the encryption 2322 process. The AAD value now only contains the representation of 2323 the JWE Encrypted Header. 2325 o For the JWE JSON Serialization, enable Header Parameter values to 2326 be specified in any of three parameters: the "protected" member 2327 that is integrity protected and shared among all recipients, the 2328 "unprotected" member that is not integrity protected and shared 2329 among all recipients, and the "header" member that is not 2330 integrity protected and specific to a particular recipient. (This 2331 does not affect the JWE Compact Serialization, in which all Header 2332 Parameter values are in a single integrity protected JWE Header 2333 value.) 2335 o Shortened the names "authentication_tag" to "tag" and 2336 "initialization_vector" to "iv" in the JWE JSON Serialization, 2337 addressing issue #20. 2339 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2341 o Removed suggested compact serialization for multiple recipients. 2343 o Changed the MIME type name "application/jwe-js" to 2344 "application/jwe+json", addressing issue #22. 2346 o Tightened the description of the "crit" (critical) header 2347 parameter. 2349 -10 2351 o Changed the JWE processing rules for multiple recipients so that a 2352 single AAD value contains the header parameters and encrypted key 2353 values for all the recipients, enabling AES GCM to be safely used 2354 for multiple recipients. 2356 o Added an appendix suggesting a possible compact serialization for 2357 JWEs with multiple recipients. 2359 -09 2361 o Added JWE JSON Serialization, as specified by 2362 draft-jones-jose-jwe-json-serialization-04. 2364 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2365 parameter value. 2367 o Defined that the default action for header parameters that are not 2368 understood is to ignore them unless specifically designated as 2369 "MUST be understood" or included in the new "crit" (critical) 2370 header parameter list. This addressed issue #6. 2372 o Corrected "x5c" description. This addressed issue #12. 2374 o Changed from using the term "byte" to "octet" when referring to 8 2375 bit values. 2377 o Added Key Management Mode definitions to terminology section and 2378 used the defined terms to provide clearer key management 2379 instructions. This addressed issue #5. 2381 o Added text about preventing the recipient from behaving as an 2382 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2384 o Changed from using the term "Integrity Value" to "Authentication 2385 Tag". 2387 o Changed member name from "integrity_value" to "authentication_tag" 2388 in the JWE JSON Serialization. 2390 o Removed Initialization Vector from the AAD value since it is 2391 already integrity protected by all of the authenticated encryption 2392 algorithms specified in the JWA specification. 2394 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2395 and "A256CBC-HS512". The new algorithms perform the same 2396 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2397 but with the Initialization Vector and Authentication Tag values 2398 remaining separate from the Ciphertext value in the output 2399 representation. Also deleted the header parameters "epu" 2400 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2401 they are no longer used. 2403 -08 2405 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2406 since the term AEAD in the RFC 5116 sense implied the use of a 2407 particular data representation, rather than just referring to the 2408 class of algorithms that perform authenticated encryption with 2409 associated data. 2411 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2412 Tschofenig. Many of these simplified the terminology used. 2414 o Clarified statements of the form "This header parameter is 2415 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2417 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2418 Web Signature and Encryption Header Parameters registry. 2420 o Added seriesInfo information to Internet Draft references. 2422 -07 2424 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2426 o Updated values for example AES CBC calculations. 2428 o Made several local editorial changes to clean up loose ends left 2429 over from to the decision to only support block encryption methods 2430 providing integrity. One of these changes was to explicitly state 2431 that the "enc" (encryption method) algorithm must be an 2432 Authenticated Encryption algorithm with a specified key length. 2434 -06 2436 o Removed the "int" and "kdf" parameters and defined the new 2437 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2438 "A256CBC+HS512" to replace the former uses of AES CBC, which 2439 required the use of separate integrity and key derivation 2440 functions. 2442 o Included additional values in the Concat KDF calculation -- the 2443 desired output size and the algorithm value, and optionally 2444 PartyUInfo and PartyVInfo values. Added the optional header 2445 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2446 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2447 PartyVInfo). Updated the KDF examples accordingly. 2449 o Promoted Initialization Vector from being a header parameter to 2450 being a top-level JWE element. This saves approximately 16 bytes 2451 in the compact serialization, which is a significant savings for 2452 some use cases. Promoting the Initialization Vector out of the 2453 header also avoids repeating this shared value in the JSON 2454 serialization. 2456 o Changed "x5c" (X.509 Certificate Chain) representation from being 2457 a single string to being an array of strings, each containing a 2458 single base64 encoded DER certificate value, representing elements 2459 of the certificate chain. 2461 o Added an AES Key Wrap example. 2463 o Reordered the encryption steps so CMK creation is first, when 2464 required. 2466 o Correct statements in examples about which algorithms produce 2467 reproducible results. 2469 -05 2471 o Support both direct encryption using a shared or agreed upon 2472 symmetric key, and the use of a shared or agreed upon symmetric 2473 key to key wrap the CMK. 2475 o Added statement that "StringOrURI values are compared as case- 2476 sensitive strings with no transformations or canonicalizations 2477 applied". 2479 o Updated open issues. 2481 o Indented artwork elements to better distinguish them from the body 2482 text. 2484 -04 2486 o Refer to the registries as the primary sources of defined values 2487 and then secondarily reference the sections defining the initial 2488 contents of the registries. 2490 o Normatively reference XML Encryption 1.1 for its security 2491 considerations. 2493 o Reference draft-jones-jose-jwe-json-serialization instead of 2494 draft-jones-json-web-encryption-json-serialization. 2496 o Described additional open issues. 2498 o Applied editorial suggestions. 2500 -03 2502 o Added the "kdf" (key derivation function) header parameter to 2503 provide crypto agility for key derivation. The default KDF 2504 remains the Concat KDF with the SHA-256 digest function. 2506 o Reordered encryption steps so that the Encoded JWE Header is 2507 always created before it is needed as an input to the 2508 Authenticated Encryption "additional authenticated data" 2509 parameter. 2511 o Added the "cty" (content type) header parameter for declaring type 2512 information about the secured content, as opposed to the "typ" 2513 (type) header parameter, which declares type information about 2514 this object. 2516 o Moved description of how to determine whether a header is for a 2517 JWS or a JWE from the JWT spec to the JWE spec. 2519 o Added complete encryption examples for both Authenticated 2520 Encryption and non-Authenticated Encryption algorithms. 2522 o Added complete key derivation examples. 2524 o Added "Collision Resistant Namespace" to the terminology section. 2526 o Reference ITU.X690.1994 for DER encoding. 2528 o Added Registry Contents sections to populate registry values. 2530 o Numerous editorial improvements. 2532 -02 2534 o When using Authenticated Encryption algorithms (such as AES GCM), 2535 use the "additional authenticated data" parameter to provide 2536 integrity for the header, encrypted key, and ciphertext and use 2537 the resulting "authentication tag" value as the JWE Authentication 2538 Tag. 2540 o Defined KDF output key sizes. 2542 o Generalized text to allow key agreement to be employed as an 2543 alternative to key wrapping or key encryption. 2545 o Changed compression algorithm from gzip to DEFLATE. 2547 o Clarified that it is an error when a "kid" value is included and 2548 no matching key is found. 2550 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2551 rejected. 2553 o Clarified the relationship between "typ" header parameter values 2554 and MIME types. 2556 o Registered application/jwe MIME type and "JWE" typ header 2557 parameter value. 2559 o Simplified JWK terminology to get replace the "JWK Key Object" and 2560 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2561 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2562 between single keys and sets of keys. As part of this change, the 2563 Header Parameter Name for a public key value was changed from 2564 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2566 o Added suggestion on defining additional header parameters such as 2567 "x5t#S256" in the future for certificate thumbprints using hash 2568 algorithms other than SHA-1. 2570 o Specify RFC 2818 server identity validation, rather than RFC 6125 2571 (paralleling the same decision in the OAuth specs). 2573 o Generalized language to refer to Message Authentication Codes 2574 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2575 unless in a context specific to HMAC algorithms. 2577 o Reformatted to give each header parameter its own section heading. 2579 -01 2581 o Added an integrity check for non-Authenticated Encryption 2582 algorithms. 2584 o Added "jpk" and "x5c" header parameters for including JWK public 2585 keys and X.509 certificate chains directly in the header. 2587 o Clarified that this specification is defining the JWE Compact 2588 Serialization. Referenced the new JWE-JS spec, which defines the 2589 JWE JSON Serialization. 2591 o Added text "New header parameters should be introduced sparingly 2592 since an implementation that does not understand a parameter MUST 2593 reject the JWE". 2595 o Clarified that the order of the encryption and decryption steps is 2596 not significant in cases where there are no dependencies between 2597 the inputs and outputs of the steps. 2599 o Made other editorial improvements suggested by JOSE working group 2600 participants. 2602 -00 2604 o Created the initial IETF draft based upon 2605 draft-jones-json-web-encryption-02 with no normative changes. 2607 o Changed terminology to no longer call both digital signatures and 2608 HMACs "signatures". 2610 Authors' Addresses 2612 Michael B. Jones 2613 Microsoft 2615 Email: mbj@microsoft.com 2616 URI: http://self-issued.info/ 2618 Joe Hildebrand 2619 Cisco Systems, Inc. 2621 Email: jhildebr@cisco.com