idnits 2.17.1 draft-ietf-jose-json-web-encryption-22.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 (March 2, 2014) is 3706 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 1391 -- Looks like a reference, but probably isn't: '197' on line 1391 -- Looks like a reference, but probably isn't: '117' on line 1391 -- Looks like a reference, but probably isn't: '252' on line 1391 -- Looks like a reference, but probably isn't: '2' on line 1391 -- Looks like a reference, but probably isn't: '219' on line 1391 -- Looks like a reference, but probably isn't: '233' on line 1391 -- Looks like a reference, but probably isn't: '68' on line 1391 -- Looks like a reference, but probably isn't: '180' on line 1391 -- Looks like a reference, but probably isn't: '225' on line 1391 -- Looks like a reference, but probably isn't: '77' on line 1391 -- Looks like a reference, but probably isn't: '0' on line 1977 -- Looks like a reference, but probably isn't: '1' on line 1977 -- Looks like a reference, but probably isn't: '152' on line 1977 -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMAScript' ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Obsolete normative reference: RFC 7158 (Obsoleted by RFC 7159) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' == Outdated reference: A later version (-05) exists of draft-mcgrew-aead-aes-cbc-hmac-sha2-01 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 18 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track E. Rescorla 5 Expires: September 3, 2014 RTFM 6 J. Hildebrand 7 Cisco 8 March 2, 2014 10 JSON Web Encryption (JWE) 11 draft-ietf-jose-json-web-encryption-22 13 Abstract 15 JSON Web Encryption (JWE) represents encrypted content using 16 JavaScript Object Notation (JSON) based data structures. 17 Cryptographic algorithms and identifiers for use with this 18 specification are described in the separate JSON Web Algorithms (JWA) 19 specification and IANA registries defined by that specification. 20 Related digital signature and MAC capabilities are described in the 21 separate JSON Web Signature (JWS) specification. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on September 3, 2014. 40 Copyright Notice 42 Copyright (c) 2014 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 9 61 3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 11 62 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 12 63 4.1. Registered Header Parameter Names . . . . . . . . . . . . 13 64 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 13 65 4.1.2. "enc" (Encryption Algorithm) Header Parameter . . . . 13 66 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 13 67 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 14 68 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 14 69 4.1.6. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14 70 4.1.7. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 14 71 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 15 72 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 73 Parameter . . . . . . . . . . . . . . . . . . . . . . 15 74 4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 15 75 4.1.11. "cty" (Content Type) Header Parameter . . . . . . . . 15 76 4.1.12. "crit" (Critical) Header Parameter . . . . . . . . . . 15 77 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15 78 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 16 79 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 16 80 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 16 81 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 18 82 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 21 83 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 21 84 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 21 85 7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 21 86 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21 87 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 24 88 9. Distinguishing between JWS and JWE Objects . . . . . . . . . . 24 89 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 90 10.1. JSON Web Signature and Encryption Header Parameters 91 Registration . . . . . . . . . . . . . . . . . . . . . . . 25 92 10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25 93 11. Security Considerations . . . . . . . . . . . . . . . . . . . 27 94 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 95 12.1. Normative References . . . . . . . . . . . . . . . . . . . 28 96 12.2. Informative References . . . . . . . . . . . . . . . . . . 28 97 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 29 98 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 29 99 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 29 100 A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 30 101 A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 30 102 A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 31 103 A.1.5. Additional Authenticated Data . . . . . . . . . . . . 31 104 A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 32 105 A.1.7. Complete Representation . . . . . . . . . . . . . . . 32 106 A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 33 107 A.2. Example JWE using RSAES-PKCS1-V1_5 and 108 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 33 109 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 33 110 A.2.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 34 111 A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 34 112 A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 35 113 A.2.5. Additional Authenticated Data . . . . . . . . . . . . 35 114 A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 35 115 A.2.7. Complete Representation . . . . . . . . . . . . . . . 36 116 A.2.8. Validation . . . . . . . . . . . . . . . . . . . . . . 36 117 A.3. Example JWE using AES Key Wrap and 118 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 37 119 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 37 120 A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 37 121 A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 37 122 A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 38 123 A.3.5. Additional Authenticated Data . . . . . . . . . . . . 38 124 A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 38 125 A.3.7. Complete Representation . . . . . . . . . . . . . . . 39 126 A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 39 127 A.4. Example JWE using JWE JSON Serialization . . . . . . . . . 40 128 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 40 129 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 40 130 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 41 131 A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 41 132 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 41 133 A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 41 134 A.4.7. Complete JWE JSON Serialization Representation . . . . 42 135 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 42 136 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 43 137 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 43 138 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 44 139 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 44 140 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 44 141 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 44 142 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 44 143 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 45 144 Appendix D. Document History . . . . . . . . . . . . . . . . . . 45 145 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 54 147 1. Introduction 149 JSON Web Encryption (JWE) represents encrypted content using 150 JavaScript Object Notation (JSON) [RFC7158] based data structures. 151 The JWE cryptographic mechanisms encrypt and provide integrity 152 protection for an arbitrary sequence of octets. 154 Two closely related serializations for JWE objects are defined. The 155 JWE Compact Serialization is a compact, URL-safe representation 156 intended for space constrained environments such as HTTP 157 Authorization headers and URI query parameters. The JWE JSON 158 Serialization represents JWE objects as JSON objects and enables the 159 same content to be encrypted to multiple parties. Both share the 160 same cryptographic underpinnings. 162 Cryptographic algorithms and identifiers for use with this 163 specification are described in the separate JSON Web Algorithms (JWA) 164 [JWA] specification and IANA registries defined by that 165 specification. Related digital signature and MAC capabilities are 166 described in the separate JSON Web Signature (JWS) [JWS] 167 specification. 169 Names defined by this specification are short because a core goal is 170 for the resulting representations to be compact. 172 1.1. Notational Conventions 174 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 175 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 176 "OPTIONAL" in this document are to be interpreted as described in Key 177 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 178 these words are used without being spelled in uppercase then they are 179 to be interpreted with their normal natural language meanings. 181 BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per 182 Section 2. 184 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 185 of STRING. 187 ASCII(STRING) denotes the octets of the ASCII [USASCII] 188 representation of STRING. 190 The concatenation of two values A and B is denoted as A || B. 192 2. Terminology 194 These terms defined by the JSON Web Signature (JWS) [JWS] 195 specification are incorporated into this specification: "JSON Web 196 Signature (JWS)", "Base64url Encoding", "Collision-Resistant Name", 197 and "StringOrURI". 199 These terms are defined for use by this specification: 201 JSON Web Encryption (JWE) 202 A data structure representing an encrypted and integrity protected 203 message. 205 Authenticated Encryption with Associated Data (AEAD) 206 An AEAD algorithm is one that encrypts the Plaintext, allows 207 Additional Authenticated Data to be specified, and provides an 208 integrated content integrity check over the Ciphertext and 209 Additional Authenticated Data. AEAD algorithms accept two inputs, 210 the Plaintext and the Additional Authenticated Data value, and 211 produce two outputs, the Ciphertext and the Authentication Tag 212 value. AES Galois/Counter Mode (GCM) is one such algorithm. 214 Plaintext 215 The sequence of octets to be encrypted -- a.k.a., the message. 216 The plaintext can contain an arbitrary sequence of octets. 218 Ciphertext 219 An encrypted representation of the Plaintext. 221 Additional Authenticated Data (AAD) 222 An input to an AEAD operation that is integrity protected but not 223 encrypted. 225 Authentication Tag 226 An output of an AEAD operation that ensures the integrity of the 227 Ciphertext and the Additional Authenticated Data. Note that some 228 algorithms may not use an Authentication Tag, in which case this 229 value is the empty octet sequence. 231 Content Encryption Key (CEK) 232 A symmetric key for the AEAD algorithm used to encrypt the 233 Plaintext for the recipient to produce the Ciphertext and the 234 Authentication Tag. 236 JWE Header 237 JSON object containing the parameters describing the cryptographic 238 operations and parameters employed. The JWE Header members are 239 the union of the members of the JWE Protected Header, the JWE 240 Shared Unprotected Header, and the JWE Per-Recipient Unprotected 241 Header. The members of the JWE Header are Header Parameters. 243 JWE Encrypted Key 244 Encrypted Content Encryption Key (CEK) value. Note that for some 245 algorithms, the JWE Encrypted Key value is specified as being the 246 empty octet sequence. 248 JWE Initialization Vector 249 Initialization Vector value used when encrypting the plaintext. 250 Note that some algorithms may not use an Initialization Vector, in 251 which case this value is the empty octet sequence. 253 JWE AAD 254 Additional value to be integrity protected by the authenticated 255 encryption operation. This can only be present when using the JWE 256 JSON Serialization. (Note that this can also be achieved when 257 using either serialization by including the AAD value as an 258 integrity protected Header Parameter value, but at the cost of the 259 value being double base64url encoded.) 261 JWE Ciphertext 262 Ciphertext value resulting from authenticated encryption of the 263 plaintext with additional associated data. 265 JWE Authentication Tag 266 Authentication Tag value resulting from authenticated encryption 267 of the plaintext with additional associated data. 269 Header Parameter 270 A name/value pair that is member of the JWE Header. 272 JWE Protected Header 273 JSON object that contains the JWE Header Parameters that are 274 integrity protected by the authenticated encryption operation. 275 These parameters apply to all recipients of the JWE. For the JWE 276 Compact Serialization, this comprises the entire JWE Header. For 277 the JWE JSON Serialization, this is one component of the JWE 278 Header. 280 JWE Shared Unprotected Header 281 JSON object that contains the JWE Header Parameters that apply to 282 all recipients of the JWE that are not integrity protected. This 283 can only be present when using the JWE JSON Serialization. 285 JWE Per-Recipient Unprotected Header 286 JSON object that contains JWE Header Parameters that apply to a 287 single recipient of the JWE. These Header Parameter values are 288 not integrity protected. This can only be present when using the 289 JWE JSON Serialization. 291 JWE Compact Serialization 292 A representation of the JWE as a compact, URL-safe string. 294 JWE JSON Serialization 295 A representation of the JWE as a JSON object. The JWE JSON 296 Serialization enables the same content to be encrypted to multiple 297 parties. This representation is neither optimized for compactness 298 nor URL-safe. 300 Key Management Mode 301 A method of determining the Content Encryption Key (CEK) value to 302 use. Each algorithm used for determining the CEK value uses a 303 specific Key Management Mode. Key Management Modes employed by 304 this specification are Key Encryption, Key Wrapping, Direct Key 305 Agreement, Key Agreement with Key Wrapping, and Direct Encryption. 307 Key Encryption 308 A Key Management Mode in which the Content Encryption Key (CEK) 309 value is encrypted to the intended recipient using an asymmetric 310 encryption algorithm. 312 Key Wrapping 313 A Key Management Mode in which the Content Encryption Key (CEK) 314 value is encrypted to the intended recipient using a symmetric key 315 wrapping algorithm. 317 Direct Key Agreement 318 A Key Management Mode in which a key agreement algorithm is used 319 to agree upon the Content Encryption Key (CEK) value. 321 Key Agreement with Key Wrapping 322 A Key Management Mode in which a key agreement algorithm is used 323 to agree upon a symmetric key used to encrypt the Content 324 Encryption Key (CEK) value to the intended recipient using a 325 symmetric key wrapping algorithm. 327 Direct Encryption 328 A Key Management Mode in which the Content Encryption Key (CEK) 329 value used is the secret symmetric key value shared between the 330 parties. 332 3. JSON Web Encryption (JWE) Overview 334 JWE represents encrypted content using JSON data structures and 335 base64url encoding. A JWE represents these logical values: 337 JWE Header 338 JSON object containing the parameters describing the cryptographic 339 operations and parameters employed. The JWE Header members are 340 the union of the members of the JWE Protected Header, the JWE 341 Shared Unprotected Header, and the JWE Per-Recipient Unprotected 342 Header, as described below. 344 JWE Encrypted Key 345 Encrypted Content Encryption Key (CEK) value. 347 JWE Initialization Vector 348 Initialization Vector value used when encrypting the plaintext. 350 JWE AAD 351 Additional value to be integrity protected by the authenticated 352 encryption operation. 354 JWE Ciphertext 355 Ciphertext value resulting from authenticated encryption of the 356 plaintext with additional associated data. 358 JWE Authentication Tag 359 Authentication Tag value resulting from authenticated encryption 360 of the plaintext with additional associated data. 362 The JWE Header represents the combination of these logical values: 364 JWE Protected Header 365 JSON object that contains the JWE Header Parameters that are 366 integrity protected by the authenticated encryption operation. 367 These parameters apply to all recipients of the JWE. 369 JWE Shared Unprotected Header 370 JSON object that contains the JWE Header Parameters that apply to 371 all recipients of the JWE that are not integrity protected. 373 JWE Per-Recipient Unprotected Header 374 JSON object that contains JWE Header Parameters that apply to a 375 single recipient of the JWE. These Header Parameter values are 376 not integrity protected. 378 This document defines two serializations for JWE objects: a compact, 379 URL-safe serialization called the JWE Compact Serialization and a 380 JSON serialization called the JWE JSON Serialization. In both 381 serializations, the JWE Protected Header, JWE Encrypted Key, JWE 382 Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are 383 base64url encoded for transmission, since JSON lacks a way to 384 directly represent octet sequences. When present, the JWE AAD is 385 also base64url encoded for transmission. 387 In the JWE Compact Serialization, no JWE Shared Unprotected Header or 388 JWE Per-Recipient Unprotected Header are used. In this case, the JWE 389 Header and the JWE Protected Header are the same. 391 In the JWE Compact Serialization, a JWE object is represented as the 392 combination of these five string values, 393 BASE64URL(UTF8(JWE Protected Header)), 394 BASE64URL(JWE Encrypted Key), 395 BASE64URL(JWE Initialization Vector), 396 BASE64URL(JWE Ciphertext), and 397 BASE64URL(JWE Authentication Tag), 398 concatenated in that order, with the five strings being separated by 399 four period ('.') characters. 401 In the JWE JSON Serialization, one or more of the JWE Protected 402 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 403 Unprotected Header MUST be present. In this case, the members of the 404 JWE Header are the combination of the members of the JWE Protected 405 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 406 Unprotected Header values that are present. 408 In the JWE JSON Serialization, a JWE object is represented as the 409 combination of these eight values, 410 BASE64URL(UTF8(JWE Protected Header)), 411 JWE Shared Unprotected Header, 412 JWE Per-Recipient Unprotected Header, 413 BASE64URL(JWE Encrypted Key), 414 BASE64URL(JWE Initialization Vector), 415 BASE64URL(JWE Ciphertext), 416 BASE64URL(JWE Authentication Tag), and 417 BASE64URL(JWE AAD), 418 with the six base64url encoding result strings and the two 419 unprotected JSON object values being represented as members within a 420 JSON object. The inclusion of some of these values is OPTIONAL. The 421 JWE JSON Serialization can also encrypt the plaintext to multiple 422 recipients. See Section 7.2 for more information about the JWE JSON 423 Serialization. 425 JWE utilizes authenticated encryption to ensure the confidentiality 426 and integrity of the Plaintext and the integrity of the JWE Protected 427 Header and the JWE AAD. 429 3.1. Example JWE 431 This example encrypts the plaintext "The true sign of intelligence is 432 not knowledge but imagination." to the recipient using RSAES OAEP for 433 key encryption and AES GCM for content encryption. 435 The following example JWE Protected Header declares that: 437 o the Content Encryption Key is encrypted to the recipient using the 438 RSAES OAEP algorithm to produce the JWE Encrypted Key and 440 o the Plaintext is encrypted using the AES GCM algorithm with a 256 441 bit key to produce the Ciphertext. 443 {"alg":"RSA-OAEP","enc":"A256GCM"} 445 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 446 Header)) gives this value: 448 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 450 The remaining steps to finish creating this JWE are: 452 o Generate a random Content Encryption Key (CEK). 454 o Encrypt the CEK with the recipient's public key using the RSAES 455 OAEP algorithm to produce the JWE Encrypted Key. 457 o Base64url encode the JWE Encrypted Key. 459 o Generate a random JWE Initialization Vector. 461 o Base64url encode the JWE Initialization Vector. 463 o Let the Additional Authenticated Data encryption parameter be 464 ASCII(BASE64URL(UTF8(JWE Protected Header))). 466 o Encrypt the Plaintext with AES GCM using the CEK as the encryption 467 key, the JWE Initialization Vector, and the Additional 468 Authenticated Data value, requesting a 128 bit Authentication Tag 469 output. 471 o Base64url encode the Ciphertext. 473 o Base64url encode the Authentication Tag. 475 o Assemble the final representation: The Compact Serialization of 476 this result is the string BASE64URL(UTF8(JWE Protected Header)) || 477 '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE 478 Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' 479 || BASE64URL(JWE Authentication Tag). 481 The final result in this example (with line breaks for display 482 purposes only) is: 484 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 485 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 486 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 487 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 488 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 489 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 490 6UklfCpIMfIjf7iGdXKHzg. 491 48V1_ALb6US04U3b. 492 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 493 SdiwkIr3ajwQzaBtQD_A. 494 XFBoMYUZodetZdvTiFvSkQ 496 See Appendix A.1 for the complete details of computing this JWE. See 497 other parts of Appendix A for additional examples. 499 4. JWE Header 501 The members of the JSON object(s) representing the JWE Header 502 describe the encryption applied to the Plaintext and optionally 503 additional properties of the JWE. The Header Parameter names within 504 the JWE Header MUST be unique; recipients MUST either reject JWEs 505 with duplicate Header Parameter names or use a JSON parser that 506 returns only the lexically last duplicate member name, as specified 507 in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. 509 Implementations are required to understand the specific Header 510 Parameters defined by this specification that are designated as "MUST 511 be understood" and process them in the manner defined in this 512 specification. All other Header Parameters defined by this 513 specification that are not so designated MUST be ignored when not 514 understood. Unless listed as a critical Header Parameter, per 515 Section 4.1.12, all Header Parameters not defined by this 516 specification MUST be ignored when not understood. 518 There are three classes of Header Parameter names: Registered Header 519 Parameter names, Public Header Parameter names, and Private Header 520 Parameter names. 522 4.1. Registered Header Parameter Names 524 The following Header Parameter names are registered in the IANA JSON 525 Web Signature and Encryption Header Parameters registry defined in 526 [JWS], with meanings as defined below. 528 As indicated by the common registry, JWSs and JWEs share a common 529 Header Parameter space; when a parameter is used by both 530 specifications, its usage must be compatible between the 531 specifications. 533 4.1.1. "alg" (Algorithm) Header Parameter 535 This parameter has the same meaning, syntax, and processing rules as 536 the "alg" Header Parameter defined in Section 4.1.1 of [JWS], except 537 that the Header Parameter identifies the cryptographic algorithm used 538 to encrypt or determine the value of the Content Encryption Key 539 (CEK). The encrypted content is not usable if the "alg" value does 540 not represent a supported algorithm, or if the recipient does not 541 have a key that can be used with that algorithm. 543 A list of defined "alg" values for this use can be found in the IANA 544 JSON Web Signature and Encryption Algorithms registry defined in 545 [JWA]; the initial contents of this registry are the values defined 546 in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. 548 4.1.2. "enc" (Encryption Algorithm) Header Parameter 550 The "enc" (encryption algorithm) Header Parameter identifies the 551 content encryption algorithm used to encrypt the Plaintext to produce 552 the Ciphertext. This algorithm MUST be an AEAD algorithm with a 553 specified key length. The recipient MUST reject the JWE if the "enc" 554 value does not represent a supported algorithm. "enc" values should 555 either be registered in the IANA JSON Web Signature and Encryption 556 Algorithms registry defined in [JWA] or be a value that contains a 557 Collision-Resistant Name. The "enc" value is a case-sensitive string 558 containing a StringOrURI value. This Header Parameter MUST be 559 present and MUST be understood and processed by implementations. 561 A list of defined "enc" values for this use can be found in the IANA 562 JSON Web Signature and Encryption Algorithms registry defined in 563 [JWA]; the initial contents of this registry are the values defined 564 in Section 5.1 of the JSON Web Algorithms (JWA) [JWA] specification. 566 4.1.3. "zip" (Compression Algorithm) Header Parameter 568 The "zip" (compression algorithm) applied to the Plaintext before 569 encryption, if any. The "zip" value defined by this specification 570 is: 572 o "DEF" - Compression with the DEFLATE [RFC1951] algorithm 574 Other values MAY be used. Compression algorithm values can be 575 registered in the IANA JSON Web Encryption Compression Algorithm 576 registry defined in [JWA]. The "zip" value is a case-sensitive 577 string. If no "zip" parameter is present, no compression is applied 578 to the Plaintext before encryption. This Header Parameter MUST be 579 integrity protected, and therefore MUST occur only within the JWE 580 Protected Header, when used. Use of this Header Parameter is 581 OPTIONAL. This Header Parameter MUST be understood and processed by 582 implementations. 584 4.1.4. "jku" (JWK Set URL) Header Parameter 586 This parameter has the same meaning, syntax, and processing rules as 587 the "jku" Header Parameter defined in Section 4.1.2 of [JWS], except 588 that the JWK Set resource contains the public key to which the JWE 589 was encrypted; this can be used to determine the private key needed 590 to decrypt the JWE. 592 4.1.5. "jwk" (JSON Web Key) Header Parameter 594 This parameter has the same meaning, syntax, and processing rules as 595 the "jwk" Header Parameter defined in Section 4.1.3 of [JWS], except 596 that the key is the public key to which the JWE was encrypted; this 597 can be used to determine the private key needed to decrypt the JWE. 599 4.1.6. "kid" (Key ID) Header Parameter 601 This parameter has the same meaning, syntax, and processing rules as 602 the "kid" Header Parameter defined in Section 4.1.4 of [JWS], except 603 that the key hint references the public key to which the JWE was 604 encrypted; this can be used to determine the private key needed to 605 decrypt the JWE. This parameter allows originators to explicitly 606 signal a change of key to JWE recipients. 608 4.1.7. "x5u" (X.509 URL) Header Parameter 610 This parameter has the same meaning, syntax, and processing rules as 611 the "x5u" Header Parameter defined in Section 4.1.5 of [JWS], except 612 that the X.509 public key certificate or certificate chain [RFC5280] 613 contains the public key to which the JWE was encrypted; this can be 614 used to determine the private key needed to decrypt the JWE. 616 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 618 This parameter has the same meaning, syntax, and processing rules as 619 the "x5c" Header Parameter defined in Section 4.1.6 of [JWS], except 620 that the X.509 public key certificate or certificate chain [RFC5280] 621 contains the public key to which the JWE was encrypted; this can be 622 used to determine the private key needed to decrypt the JWE. 624 See Appendix B of [JWS] for an example "x5c" value. 626 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 628 This parameter has the same meaning, syntax, and processing rules as 629 the "x5t" Header Parameter defined in Section 4.1.7 of [JWS], except 630 that certificate referenced by the thumbprint contains the public key 631 to which the JWE was encrypted; this can be used to determine the 632 private key needed to decrypt the JWE. 634 4.1.10. "typ" (Type) Header Parameter 636 This parameter has the same meaning, syntax, and processing rules as 637 the "typ" Header Parameter defined in Section 4.1.8 of [JWS], except 638 that the type is of this complete JWE object. 640 4.1.11. "cty" (Content Type) Header Parameter 642 This parameter has the same meaning, syntax, and processing rules as 643 the "cty" Header Parameter defined in Section 4.1.9 of [JWS], except 644 that the type is of the secured content (the payload). 646 4.1.12. "crit" (Critical) Header Parameter 648 This parameter has the same meaning, syntax, and processing rules as 649 the "crit" Header Parameter defined in Section 4.1.10 of [JWS], 650 except that JWE Header Parameters are being referred to, rather than 651 JWS Header Parameters. 653 4.2. Public Header Parameter Names 655 Additional Header Parameter names can be defined by those using JWEs. 656 However, in order to prevent collisions, any new Header Parameter 657 name should either be registered in the IANA JSON Web Signature and 658 Encryption Header Parameters registry defined in [JWS] or be a Public 659 Name: a value that contains a Collision-Resistant Name. In each 660 case, the definer of the name or value needs to take reasonable 661 precautions to make sure they are in control of the part of the 662 namespace they use to define the Header Parameter name. 664 New Header Parameters should be introduced sparingly, as they can 665 result in non-interoperable JWEs. 667 4.3. Private Header Parameter Names 669 A producer and consumer of a JWE may agree to use Header Parameter 670 names that are Private Names: names that are not Registered Header 671 Parameter names Section 4.1 or Public Header Parameter names 672 Section 4.2. Unlike Public Header Parameter names, Private Header 673 Parameter names are subject to collision and should be used with 674 caution. 676 5. Producing and Consuming JWEs 678 5.1. Message Encryption 680 The message encryption process is as follows. The order of the steps 681 is not significant in cases where there are no dependencies between 682 the inputs and outputs of the steps. 684 1. Determine the Key Management Mode employed by the algorithm used 685 to determine the Content Encryption Key (CEK) value. (This is 686 the algorithm recorded in the "alg" (algorithm) Header Parameter 687 of the resulting JWE.) 689 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 690 Wrapping are employed, generate a random Content Encryption Key 691 (CEK) value. See RFC 4086 [RFC4086] for considerations on 692 generating random values. The CEK MUST have a length equal to 693 that required for the content encryption algorithm. 695 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 696 employed, use the key agreement algorithm to compute the value 697 of the agreed upon key. When Direct Key Agreement is employed, 698 let the Content Encryption Key (CEK) be the agreed upon key. 699 When Key Agreement with Key Wrapping is employed, the agreed 700 upon key will be used to wrap the CEK. 702 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 703 Wrapping are employed, encrypt the CEK to the recipient and let 704 the result be the JWE Encrypted Key. 706 5. When Direct Key Agreement or Direct Encryption are employed, let 707 the JWE Encrypted Key be the empty octet sequence. 709 6. When Direct Encryption is employed, let the Content Encryption 710 Key (CEK) be the shared symmetric key. 712 7. Compute the encoded key value BASE64URL(JWE Encrypted Key). 714 8. If the JWE JSON Serialization is being used, repeat this process 715 (steps 1-7) for each recipient. 717 9. Generate a random JWE Initialization Vector of the correct size 718 for the content encryption algorithm (if required for the 719 algorithm); otherwise, let the JWE Initialization Vector be the 720 empty octet sequence. 722 10. Compute the encoded initialization vector value BASE64URL(JWE 723 Initialization Vector). 725 11. If a "zip" parameter was included, compress the Plaintext using 726 the specified compression algorithm. 728 12. Serialize the (compressed) Plaintext into an octet sequence M. 730 13. Create the JSON object(s) containing the desired set of Header 731 Parameters, which together comprise the JWE Header: the JWE 732 Protected Header, and if the JWE JSON Serialization is being 733 used, the JWE Shared Unprotected Header and the JWE Per- 734 Recipient Unprotected Header. 736 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 737 Protected Header)). If the JWE Protected Header is not present 738 (which can only happen when using the JWE JSON Serialization and 739 no "protected" member is present), let this value be the empty 740 string. 742 15. Let the Additional Authenticated Data encryption parameter be 743 ASCII(Encoded Protected Header). However if a JWE AAD value is 744 present (which can only be the case when using the JWE JSON 745 Serialization), instead let the Additional Authenticated Data 746 encryption parameter be ASCII(Encoded Protected Header || '.' || 747 BASE64URL(JWE AAD)). 749 16. Encrypt M using the CEK, the JWE Initialization Vector, and the 750 Additional Authenticated Data value using the specified content 751 encryption algorithm to create the JWE Ciphertext value and the 752 JWE Authentication Tag (which is the Authentication Tag output 753 from the encryption operation). 755 17. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext). 757 18. Compute the encoded authentication tag value BASE64URL(JWE 758 Authentication Tag). 760 19. The five encoded values are used in both the JWE Compact 761 Serialization and the JWE JSON Serialization representations. 763 20. If a JWE AAD value is present, compute the encoded AAD value 764 BASE64URL(JWE AAD). 766 21. Create the desired serialized output. The Compact Serialization 767 of this result is the string BASE64URL(UTF8(JWE Protected 768 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 769 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 770 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). The 771 JWE JSON Serialization is described in Section 7.2. 773 5.2. Message Decryption 775 The message decryption process is the reverse of the encryption 776 process. The order of the steps is not significant in cases where 777 there are no dependencies between the inputs and outputs of the 778 steps. If any of these steps fails, the encrypted content cannot be 779 validated. 781 It is an application decision which recipients' encrypted content 782 must successfully validate for the JWE to be accepted. In some 783 cases, encrypted content for all recipients must successfully 784 validate or the JWE will be rejected. In other cases, only the 785 encrypted content for a single recipient needs to be successfully 786 validated. However, in all cases, the encrypted content for at least 787 one recipient MUST successfully validate or the JWE MUST be rejected. 789 1. Parse the JWE representation to extract the serialized values 790 for the components of the JWE -- when using the JWE Compact 791 Serialization, the base64url encoded representations of the JWE 792 Protected Header, the JWE Encrypted Key, the JWE Initialization 793 Vector, the JWE Ciphertext, and the JWE Authentication Tag, and 794 when using the JWE JSON Serialization, also the base64url 795 encoded representation of the JWE AAD and the unencoded JWE 796 Shared Unprotected Header and JWE Per-Recipient Unprotected 797 Header values. When using the JWE Compact Serialization, the 798 JWE Protected Header, the JWE Encrypted Key, the JWE 799 Initialization Vector, the JWE Ciphertext, and the JWE 800 Authentication Tag are represented as base64url encoded values 801 in that order, separated by four period ('.') characters. The 802 JWE JSON Serialization is described in Section 7.2. 804 2. The encoded representations of the JWE Protected Header, the JWE 805 Encrypted Key, the JWE Initialization Vector, the JWE 806 Ciphertext, the JWE Authentication Tag, and the JWE AAD MUST be 807 successfully base64url decoded following the restriction that no 808 padding characters have been used. 810 3. The octet sequence resulting from decoding the encoded JWE 811 Protected Header MUST be a UTF-8 encoded representation of a 812 completely valid JSON object conforming to [RFC7158], which is 813 the JWE Protected Header. 815 4. If using the JWE Compact Serialization, let the JWE Header be 816 the JWE Protected Header; otherwise, when using the JWE JSON 817 Serialization, let the JWE Header be the union of the members of 818 the JWE Protected Header, the JWE Shared Unprotected Header and 819 the corresponding JWE Per-Recipient Unprotected Header, all of 820 which must be completely valid JSON objects. 822 5. The resulting JWE Header MUST NOT contain duplicate Header 823 Parameter names. When using the JWE JSON Serialization, this 824 restriction includes that the same Header Parameter name also 825 MUST NOT occur in distinct JSON object values that together 826 comprise the JWE Header. 828 6. Verify that the implementation understands and can process all 829 fields that it is required to support, whether required by this 830 specification, by the algorithms being used, or by the "crit" 831 Header Parameter value, and that the values of those parameters 832 are also understood and supported. 834 7. Determine the Key Management Mode employed by the algorithm 835 specified by the "alg" (algorithm) Header Parameter. 837 8. Verify that the JWE uses a key known to the recipient. 839 9. When Direct Key Agreement or Key Agreement with Key Wrapping are 840 employed, use the key agreement algorithm to compute the value 841 of the agreed upon key. When Direct Key Agreement is employed, 842 let the Content Encryption Key (CEK) be the agreed upon key. 843 When Key Agreement with Key Wrapping is employed, the agreed 844 upon key will be used to decrypt the JWE Encrypted Key. 846 10. When Key Wrapping, Key Encryption, or Key Agreement with Key 847 Wrapping are employed, decrypt the JWE Encrypted Key to produce 848 the Content Encryption Key (CEK). The CEK MUST have a length 849 equal to that required for the content encryption algorithm. 850 Note that when there are multiple recipients, each recipient 851 will only be able decrypt any JWE Encrypted Key values that were 852 encrypted to a key in that recipient's possession. It is 853 therefore normal to only be able to decrypt one of the per- 854 recipient JWE Encrypted Key values to obtain the CEK value. To 855 mitigate the attacks described in RFC 3218 [RFC3218], the 856 recipient MUST NOT distinguish between format, padding, and 857 length errors of encrypted keys. It is strongly recommended, in 858 the event of receiving an improperly formatted key, that the 859 receiver substitute a randomly generated CEK and proceed to the 860 next step, to mitigate timing attacks. 862 11. When Direct Key Agreement or Direct Encryption are employed, 863 verify that the JWE Encrypted Key value is empty octet sequence. 865 12. When Direct Encryption is employed, let the Content Encryption 866 Key (CEK) be the shared symmetric key. 868 13. If the JWE JSON Serialization is being used, repeat this process 869 (steps 4-12) for each recipient contained in the representation 870 until the CEK value has been determined. 872 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 873 Protected Header)). If the JWE Protected Header is not present 874 (which can only happen when using the JWE JSON Serialization and 875 no "protected" member is present), let this value be the empty 876 string. 878 15. Let the Additional Authenticated Data encryption parameter be 879 ASCII(Encoded Protected Header). However if a JWE AAD value is 880 present (which can only be the case when using the JWE JSON 881 Serialization), instead let the Additional Authenticated Data 882 encryption parameter be ASCII(Encoded Protected Header || '.' || 883 BASE64URL(JWE AAD)). 885 16. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 886 Vector, the Additional Authenticated Data value, and the JWE 887 Authentication Tag (which is the Authentication Tag input to the 888 calculation) using the specified content encryption algorithm, 889 returning the decrypted plaintext and validating the JWE 890 Authentication Tag in the manner specified for the algorithm, 891 rejecting the input without emitting any decrypted output if the 892 JWE Authentication Tag is incorrect. 894 17. If a "zip" parameter was included, uncompress the decrypted 895 plaintext using the specified compression algorithm. 897 18. If all the previous steps succeeded, output the resulting 898 Plaintext. 900 5.3. String Comparison Rules 902 The string comparison rules for this specification are the same as 903 those defined in Section 5.3 of [JWS]. 905 6. Key Identification 907 The key identification methods for this specification are the same as 908 those defined in Section 6 of [JWS], except that the key being 909 identified is the public key to which the JWE was encrypted. 911 7. Serializations 913 JWE objects use one of two serializations, the JWE Compact 914 Serialization or the JWE JSON Serialization. Applications using this 915 specification need to specify what serialization and serialization 916 features are used for that application. For instance, applications 917 might specify that only the JWE JSON Serialization is used, that only 918 JWE JSON Serialization support for a single recipient is used, or 919 that support for multiple recipients is used. JWE implementations 920 only need to implement the features needed for the applications they 921 are designed to support. 923 7.1. JWE Compact Serialization 925 The JWE Compact Serialization represents encrypted content as a 926 compact URL-safe string. This string is BASE64URL(UTF8(JWE Protected 927 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 928 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 929 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). Only one 930 recipient is supported by the JWE Compact Serialization and it 931 provides no syntax to represent JWE Shared Unprotected Header, JWE 932 Per-Recipient Unprotected Header, or JWE AAD values. 934 7.2. JWE JSON Serialization 936 The JWE JSON Serialization represents encrypted content as a JSON 937 object. Content using the JWE JSON Serialization can be encrypted to 938 more than one recipient. This representation is neither optimized 939 for compactness nor URL-safe. 941 The following members are defined for use in top-level JSON objects 942 used for the JWE JSON Serialization: 944 protected 945 The "protected" member MUST be present and contain the value 946 BASE64URL(UTF8(JWE Protected Header)) when the JWE Protected 947 Header value is non-empty; otherwise, it MUST be absent. These 948 Header Parameter values are integrity protected. 950 unprotected 951 The "unprotected" member MUST be present and contain the value JWE 952 Shared Unprotected Header when the JWE Shared Unprotected Header 953 value is non-empty; otherwise, it MUST be absent. This value is 954 represented as an unencoded JSON object, rather than as a string. 955 These Header Parameter values are not integrity protected. 957 iv 958 The "iv" member MUST be present and contain the value 959 BASE64URL(JWE Initialization Vector) when the JWE Initialization 960 Vector value is non-empty; otherwise, it MUST be absent. 962 aad 963 The "aad" member MUST be present and contain the value 964 BASE64URL(JWE AAD)) when the JWE AAD value is non-empty; 965 otherwise, it MUST be absent. A JWE AAD value can be included to 966 supply a base64url encoded value to be integrity protected but not 967 encrypted. 969 ciphertext 970 The "ciphertext" member MUST be present and contain the value 971 BASE64URL(JWE Ciphertext). 973 tag 974 The "tag" member MUST be present and contain the value 975 BASE64URL(JWE Authentication Tag) when the JWE Authentication Tag 976 value is non-empty; otherwise, it MUST be absent. 978 recipients 979 The "recipients" member value MUST be an array of JSON objects. 980 Each object contains information specific to a single recipient. 981 This member MUST be present, even if the array elements contain 982 only the empty JSON object "{}" (which can happen when all Header 983 Parameter values are shared between all recipients and when no 984 encrypted key is used, such as when doing Direct Encryption). 986 The following members are defined for use in the JSON objects that 987 are elements of the "recipients" array: 989 header 990 The "header" member MUST be present and contain the value JWE Per- 991 Recipient Unprotected Header when the JWE Per-Recipient 992 Unprotected Header value is non-empty; otherwise, it MUST be 993 absent. This value is represented as an unencoded JSON object, 994 rather than as a string. These Header Parameter values are not 995 integrity protected. 997 encrypted_key 998 The "encrypted_key" member MUST be present and contain the value 999 BASE64URL(JWE Encrypted Key) when the JWE Encrypted Key value is 1000 non-empty; otherwise, it MUST be absent. 1002 At least one of the "header", "protected", and "unprotected" members 1003 MUST be present so that "alg" and "enc" Header Parameter values are 1004 conveyed for each recipient computation. 1006 Additional members can be present in both the JSON objects defined 1007 above; if not understood by implementations encountering them, they 1008 MUST be ignored. 1010 Some Header Parameters, including the "alg" parameter, can be shared 1011 among all recipient computations. Header Parameters in the JWE 1012 Protected Header and JWE Shared Unprotected Header values are shared 1013 among all recipients. 1015 The Header Parameter values used when creating or validating per- 1016 recipient Ciphertext and Authentication Tag values are the union of 1017 the three sets of Header Parameter values that may be present: (1) 1018 the JWE Protected Header represented in the "protected" member, (2) 1019 the JWE Shared Unprotected Header represented in the "unprotected" 1020 member, and (3) the JWE Per-Recipient Unprotected Header represented 1021 in the "header" member of the recipient's array element. The union 1022 of these sets of Header Parameters comprises the JWE Header. The 1023 Header Parameter names in the three locations MUST be disjoint. 1025 Each JWE Encrypted Key value is computed using the parameters of the 1026 corresponding JWE Header value in the same manner as for the JWE 1027 Compact Serialization. This has the desirable property that each JWE 1028 Encrypted Key value in the "recipients" array is identical to the 1029 value that would have been computed for the same parameter in the JWE 1030 Compact Serialization. Likewise, the JWE Ciphertext and JWE 1031 Authentication Tag values match those produced for the JWE Compact 1032 Serialization, provided that the JWE Protected Header value (which 1033 represents the integrity-protected Header Parameter values) matches 1034 that used in the JWE Compact Serialization. 1036 All recipients use the same JWE Protected Header, JWE Initialization 1037 Vector, JWE Ciphertext, and JWE Authentication Tag values, when 1038 present, resulting in potentially significant space savings if the 1039 message is large. Therefore, all Header Parameters that specify the 1040 treatment of the Plaintext value MUST be the same for all recipients. 1041 This primarily means that the "enc" (encryption algorithm) Header 1042 Parameter value in the JWE Header for each recipient and any 1043 parameters of that algorithm MUST be the same. 1045 In summary, the syntax of a JWE using the JWE JSON Serialization is 1046 as follows: 1048 {"protected":"", 1049 "unprotected":, 1050 "recipients":[ 1051 {"header":, 1052 "encrypted_key":""}, 1053 ... 1054 {"header":, 1055 "encrypted_key":""}], 1056 "aad":"", 1057 "iv":"", 1058 "ciphertext":"", 1059 "tag":"" 1060 } 1062 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1063 Serialization. 1065 8. TLS Requirements 1067 The TLS requirements for this specification are the same as those 1068 defined in Section 8 of [JWS]. 1070 9. Distinguishing between JWS and JWE Objects 1072 There are several ways of distinguishing whether an object is a JWS 1073 or JWE object. All these methods will yield the same result for all 1074 legal input values; they may yield different results for malformed 1075 inputs. 1077 o If the object is using the JWS Compact Serialization or the JWE 1078 Compact Serialization, the number of base64url encoded segments 1079 separated by period ('.') characters differs for JWSs and JWEs. 1080 JWSs have three segments separated by two period ('.') characters. 1081 JWEs have five segments separated by four period ('.') characters. 1083 o If the object is using the JWS JSON Serialization or the JWE JSON 1084 Serialization, the members used will be different. JWSs have a 1085 "signatures" member and JWEs do not. JWEs have a "recipients" 1086 member and JWSs do not. 1088 o A JWS Header can be distinguished from a JWE header by examining 1089 the "alg" (algorithm) Header Parameter value. If the value 1090 represents a digital signature or MAC algorithm, or is the value 1091 "none", it is for a JWS; if it represents a Key Encryption, Key 1092 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 1093 or Direct Encryption algorithm, it is for a JWE. (Extracting the 1094 "alg" value to examine is straightforward when using the JWS 1095 Compact Serialization or the JWE Compact Serialization and may be 1096 more difficult when using the JWS JSON Serialization or the JWE 1097 JSON Serialization.) 1099 o A JWS Header can also be distinguished from a JWE header by 1100 determining whether an "enc" (encryption algorithm) member exists. 1101 If the "enc" member exists, it is a JWE; otherwise, it is a JWS. 1103 10. IANA Considerations 1105 10.1. JSON Web Signature and Encryption Header Parameters Registration 1107 This specification registers the Header Parameter names defined in 1108 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1109 Parameters registry defined in [JWS]. 1111 10.1.1. Registry Contents 1113 o Header Parameter Name: "alg" 1114 o Header Parameter Description: Algorithm 1115 o Header Parameter Usage Location(s): JWE 1116 o Change Controller: IESG 1117 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1119 o Header Parameter Name: "enc" 1120 o Header Parameter Description: Encryption Algorithm 1121 o Header Parameter Usage Location(s): JWE 1122 o Change Controller: IESG 1123 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1125 o Header Parameter Name: "zip" 1126 o Header Parameter Description: Compression Algorithm 1127 o Header Parameter Usage Location(s): JWE 1128 o Change Controller: IESG 1129 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1131 o Header Parameter Name: "jku" 1132 o Header Parameter Description: JWK Set URL 1133 o Header Parameter Usage Location(s): JWE 1134 o Change Controller: IESG 1135 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1137 o Header Parameter Name: "jwk" 1138 o Header Parameter Description: JSON Web Key 1139 o Header Parameter Usage Location(s): JWE 1140 o Change Controller: IESG 1141 o Specification document(s): Section 4.1.5 of [[ this document ]] 1143 o Header Parameter Name: "kid" 1144 o Header Parameter Description: Key ID 1145 o Header Parameter Usage Location(s): JWE 1146 o Change Controller: IESG 1147 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1149 o Header Parameter Name: "x5u" 1150 o Header Parameter Description: X.509 URL 1151 o Header Parameter Usage Location(s): JWE 1152 o Change Controller: IESG 1153 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1155 o Header Parameter Name: "x5c" 1156 o Header Parameter Description: X.509 Certificate Chain 1157 o Header Parameter Usage Location(s): JWE 1158 o Change Controller: IESG 1159 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1161 o Header Parameter Name: "x5t" 1162 o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint 1163 o Header Parameter Usage Location(s): JWE 1164 o Change Controller: IESG 1165 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1167 o Header Parameter Name: "typ" 1168 o Header Parameter Description: Type 1169 o Header Parameter Usage Location(s): JWE 1170 o Change Controller: IESG 1171 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1173 o Header Parameter Name: "cty" 1174 o Header Parameter Description: Content Type 1175 o Header Parameter Usage Location(s): JWE 1176 o Change Controller: IESG 1177 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1179 o Header Parameter Name: "crit" 1180 o Header Parameter Description: Critical 1181 o Header Parameter Usage Location(s): JWE 1182 o Change Controller: IESG 1183 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1185 11. Security Considerations 1187 All of the security issues faced by any cryptographic application 1188 must be faced by a JWS/JWE/JWK agent. Among these issues are 1189 protecting the user's private and symmetric keys, preventing various 1190 attacks, and helping the user avoid mistakes such as inadvertently 1191 encrypting a message for the wrong recipient. The entire list of 1192 security considerations is beyond the scope of this document. 1194 All the security considerations in the JWS specification also apply 1195 to this specification. Likewise, all the security considerations in 1196 XML Encryption 1.1 [W3C.CR-xmlenc-core1-20120313] also apply, other 1197 than those that are XML specific. 1199 When decrypting, particular care must be taken not to allow the JWE 1200 recipient to be used as an oracle for decrypting messages. RFC 3218 1201 [RFC3218] should be consulted for specific countermeasures to attacks 1202 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1203 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1204 formatting error that can be detected and used to recover the CEK 1205 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1206 particularly important to report all formatting errors to the CEK, 1207 Additional Authenticated Data, or ciphertext as a single error when 1208 the encrypted content is rejected. 1210 Additionally, this type of attack can be prevented by the use of "key 1211 tainting". This method restricts the use of a key to a limited set 1212 of algorithms -- usually one. This means, for instance, that if the 1213 key is marked as being for "RSA-OAEP" only, any attempt to decrypt a 1214 message using the "RSA1_5" algorithm with that key would fail 1215 immediately due to invalid use of the key. 1217 12. References 1218 12.1. Normative References 1220 [ECMAScript] 1221 Ecma International, "ECMAScript Language Specification, 1222 5.1 Edition", ECMA 262, June 2011. 1224 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1225 draft-ietf-jose-json-web-algorithms (work in progress), 1226 March 2014. 1228 [JWK] Jones, M., "JSON Web Key (JWK)", 1229 draft-ietf-jose-json-web-key (work in progress), 1230 March 2014. 1232 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1233 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1234 in progress), March 2014. 1236 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1237 version 1.3", RFC 1951, May 1996. 1239 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1240 Requirement Levels", BCP 14, RFC 2119, March 1997. 1242 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1243 10646", STD 63, RFC 3629, November 2003. 1245 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1246 Housley, R., and W. Polk, "Internet X.509 Public Key 1247 Infrastructure Certificate and Certificate Revocation List 1248 (CRL) Profile", RFC 5280, May 2008. 1250 [RFC7158] Bray, T., "The JavaScript Object Notation (JSON) Data 1251 Interchange Format", RFC 7158, March 2014. 1253 [USASCII] American National Standards Institute, "Coded Character 1254 Set -- 7-bit American Standard Code for Information 1255 Interchange", ANSI X3.4, 1986. 1257 12.2. Informative References 1259 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1260 McGrew, D. and K. Paterson, "Authenticated Encryption with 1261 AES-CBC and HMAC-SHA", 1262 draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), 1263 October 2012. 1265 [I-D.rescorla-jsms] 1266 Rescorla, E. and J. Hildebrand, "JavaScript Message 1267 Security Format", draft-rescorla-jsms-00 (work in 1268 progress), March 2011. 1270 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1271 Encryption", September 2010. 1273 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1274 Cryptographic Message Syntax", RFC 3218, January 2002. 1276 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1277 Requirements for Security", BCP 106, RFC 4086, June 2005. 1279 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1280 RFC 5652, September 2009. 1282 [W3C.CR-xmlenc-core1-20120313] 1283 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 1284 "XML Encryption Syntax and Processing Version 1.1", World 1285 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1286 March 2012, 1287 . 1289 Appendix A. JWE Examples 1291 This section provides examples of JWE computations. 1293 A.1. Example JWE using RSAES OAEP and AES GCM 1295 This example encrypts the plaintext "The true sign of intelligence is 1296 not knowledge but imagination." to the recipient using RSAES OAEP for 1297 key encryption and AES GCM for content encryption. The 1298 representation of this plaintext is: 1300 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1301 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1302 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1303 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1304 110, 97, 116, 105, 111, 110, 46] 1306 A.1.1. JWE Header 1308 The following example JWE Protected Header declares that: 1310 o the Content Encryption Key is encrypted to the recipient using the 1311 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1313 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1314 bit key to produce the Ciphertext. 1316 {"alg":"RSA-OAEP","enc":"A256GCM"} 1318 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1319 Header)) gives this value: 1321 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1323 A.1.2. Content Encryption Key (CEK) 1325 Generate a 256 bit random Content Encryption Key (CEK). In this 1326 example, the value is: 1328 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1329 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1330 234, 64, 252] 1332 A.1.3. Key Encryption 1334 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1335 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1336 key represented in JSON Web Key [JWK] format below (with line breaks 1337 for display purposes only): 1339 {"kty":"RSA", 1340 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1341 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1342 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1343 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1344 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1345 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1346 "e":"AQAB", 1347 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1348 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1349 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1350 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1351 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1352 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ" 1353 } 1355 The resulting JWE Encrypted Key value is: 1357 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1358 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1359 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1360 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1361 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1362 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1363 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1364 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1365 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1366 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1367 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1368 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1369 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1370 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1371 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1372 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1373 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1374 117, 114, 135, 206] 1376 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1377 this value (with line breaks for display purposes only): 1379 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1380 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1381 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1382 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1383 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1384 6UklfCpIMfIjf7iGdXKHzg 1386 A.1.4. Initialization Vector 1388 Generate a random 96 bit JWE Initialization Vector. In this example, 1389 the value is: 1391 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1393 Encoding this JWE Initialization Vector as BASE64URL(JWE 1394 Initialization Vector) gives this value: 1396 48V1_ALb6US04U3b 1398 A.1.5. Additional Authenticated Data 1400 Let the Additional Authenticated Data encryption parameter be 1401 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1403 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1404 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1405 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1407 A.1.6. Content Encryption 1409 Encrypt the Plaintext with AES GCM using the CEK as the encryption 1410 key, the JWE Initialization Vector, and the Additional Authenticated 1411 Data value above, requesting a 128 bit Authentication Tag output. 1412 The resulting Ciphertext is: 1414 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1415 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1416 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1417 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1418 160, 109, 64, 63, 192] 1420 The resulting Authentication Tag value is: 1422 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1423 210, 145] 1425 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1426 value (with line breaks for display purposes only): 1428 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1429 SdiwkIr3ajwQzaBtQD_A 1431 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1432 Tag) gives this value: 1434 XFBoMYUZodetZdvTiFvSkQ 1436 A.1.7. Complete Representation 1438 Assemble the final representation: The Compact Serialization of this 1439 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1440 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1441 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1442 Authentication Tag). 1444 The final result in this example (with line breaks for display 1445 purposes only) is: 1447 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1448 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1449 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1450 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1451 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1452 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1453 6UklfCpIMfIjf7iGdXKHzg. 1454 48V1_ALb6US04U3b. 1455 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1456 SdiwkIr3ajwQzaBtQD_A. 1457 XFBoMYUZodetZdvTiFvSkQ 1459 A.1.8. Validation 1461 This example illustrates the process of creating a JWE with RSAES 1462 OAEP for key encryption and AES GCM for content encryption. These 1463 results can be used to validate JWE decryption implementations for 1464 these algorithms. Note that since the RSAES OAEP computation 1465 includes random values, the encryption results above will not be 1466 completely reproducible. However, since the AES GCM computation is 1467 deterministic, the JWE Encrypted Ciphertext values will be the same 1468 for all encryptions performed using these inputs. 1470 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1472 This example encrypts the plaintext "Live long and prosper." to the 1473 recipient using RSAES-PKCS1-V1_5 for key encryption and 1474 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1475 of this plaintext is: 1477 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1478 112, 114, 111, 115, 112, 101, 114, 46] 1480 A.2.1. JWE Header 1482 The following example JWE Protected Header declares that: 1484 o the Content Encryption Key is encrypted to the recipient using the 1485 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1487 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1488 algorithm to produce the Ciphertext. 1490 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1492 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1493 Header)) gives this value: 1495 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1497 A.2.2. Content Encryption Key (CEK) 1499 Generate a 256 bit random Content Encryption Key (CEK). In this 1500 example, the key value is: 1502 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1503 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1504 44, 207] 1506 A.2.3. Key Encryption 1508 Encrypt the CEK with the recipient's public key using the RSAES- 1509 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1510 uses the RSA key represented in JSON Web Key [JWK] format below (with 1511 line breaks for display purposes only): 1513 {"kty":"RSA", 1514 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1515 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1516 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1517 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1518 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1519 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1520 "e":"AQAB", 1521 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1522 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1523 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1524 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1525 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1526 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1527 } 1529 The resulting JWE Encrypted Key value is: 1531 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1532 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1533 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1534 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1535 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1536 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1537 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1538 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1539 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1540 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1541 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1542 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1543 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1544 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1545 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1546 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1547 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1548 146, 114, 165, 204, 71, 136, 41, 252] 1550 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1551 this value (with line breaks for display purposes only): 1553 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1554 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1555 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1556 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1557 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1558 -B3oWh2TbqmScqXMR4gp_A 1560 A.2.4. Initialization Vector 1562 Generate a random 128 bit JWE Initialization Vector. In this 1563 example, the value is: 1565 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1566 101] 1568 Encoding this JWE Initialization Vector as BASE64URL(JWE 1569 Initialization Vector) gives this value: 1571 AxY8DCtDaGlsbGljb3RoZQ 1573 A.2.5. Additional Authenticated Data 1575 Let the Additional Authenticated Data encryption parameter be 1576 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1578 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1579 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1580 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1581 50, 73, 110, 48] 1583 A.2.6. Content Encryption 1585 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1586 the encryption key, the JWE Initialization Vector, and the Additional 1587 Authenticated Data value above. The steps for doing this using the 1588 values from Appendix A.3 are detailed in Appendix B. The resulting 1589 Ciphertext is: 1591 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1592 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1593 112, 56, 102] 1595 The resulting Authentication Tag value is: 1597 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1598 191] 1600 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1601 value: 1603 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1605 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1606 Tag) gives this value: 1608 9hH0vgRfYgPnAHOd8stkvw 1610 A.2.7. Complete Representation 1612 Assemble the final representation: The Compact Serialization of this 1613 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1614 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1615 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1616 Authentication Tag). 1618 The final result in this example (with line breaks for display 1619 purposes only) is: 1621 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1622 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1623 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1624 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1625 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1626 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1627 -B3oWh2TbqmScqXMR4gp_A. 1628 AxY8DCtDaGlsbGljb3RoZQ. 1629 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1630 9hH0vgRfYgPnAHOd8stkvw 1632 A.2.8. Validation 1634 This example illustrates the process of creating a JWE with RSAES- 1635 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1636 encryption. These results can be used to validate JWE decryption 1637 implementations for these algorithms. Note that since the RSAES- 1638 PKCS1-V1_5 computation includes random values, the encryption results 1639 above will not be completely reproducible. However, since the AES 1640 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1641 will be the same for all encryptions performed using these inputs. 1643 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1645 This example encrypts the plaintext "Live long and prosper." to the 1646 recipient using AES Key Wrap for key encryption and AES GCM for 1647 content encryption. The representation of this plaintext is: 1649 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1650 112, 114, 111, 115, 112, 101, 114, 46] 1652 A.3.1. JWE Header 1654 The following example JWE Protected Header declares that: 1656 o the Content Encryption Key is encrypted to the recipient using the 1657 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1658 Encrypted Key and 1660 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1661 algorithm to produce the Ciphertext. 1663 {"alg":"A128KW","enc":"A128CBC-HS256"} 1665 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1666 Header)) gives this value: 1668 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1670 A.3.2. Content Encryption Key (CEK) 1672 Generate a 256 bit random Content Encryption Key (CEK). In this 1673 example, the value is: 1675 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1676 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1677 44, 207] 1679 A.3.3. Key Encryption 1681 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1682 algorithm to produce the JWE Encrypted Key. This example uses the 1683 symmetric key represented in JSON Web Key [JWK] format below: 1685 {"kty":"oct", 1686 "k":"GawgguFyGrWKav7AX4VKUg" 1687 } 1689 The resulting JWE Encrypted Key value is: 1691 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1692 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1693 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1695 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1696 this value: 1698 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1700 A.3.4. Initialization Vector 1702 Generate a random 128 bit JWE Initialization Vector. In this 1703 example, the value is: 1705 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1706 101] 1708 Encoding this JWE Initialization Vector as BASE64URL(JWE 1709 Initialization Vector) gives this value: 1711 AxY8DCtDaGlsbGljb3RoZQ 1713 A.3.5. Additional Authenticated Data 1715 Let the Additional Authenticated Data encryption parameter be 1716 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1718 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1719 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1720 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1721 110, 48] 1723 A.3.6. Content Encryption 1725 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1726 the encryption key, the JWE Initialization Vector, and the Additional 1727 Authenticated Data value above. The steps for doing this using the 1728 values from this example are detailed in Appendix B. The resulting 1729 Ciphertext is: 1731 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1732 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1733 112, 56, 102] 1735 The resulting Authentication Tag value is: 1737 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1738 194, 85] 1740 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1741 value: 1743 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1745 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1746 Tag) gives this value: 1748 U0m_YmjN04DJvceFICbCVQ 1750 A.3.7. Complete Representation 1752 Assemble the final representation: The Compact Serialization of this 1753 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1754 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1755 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1756 Authentication Tag). 1758 The final result in this example (with line breaks for display 1759 purposes only) is: 1761 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1762 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1763 AxY8DCtDaGlsbGljb3RoZQ. 1764 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1765 U0m_YmjN04DJvceFICbCVQ 1767 A.3.8. Validation 1769 This example illustrates the process of creating a JWE with AES Key 1770 Wrap for key encryption and AES GCM for content encryption. These 1771 results can be used to validate JWE decryption implementations for 1772 these algorithms. Also, since both the AES Key Wrap and AES GCM 1773 computations are deterministic, the resulting JWE value will be the 1774 same for all encryptions performed using these inputs. Since the 1775 computation is reproducible, these results can also be used to 1776 validate JWE encryption implementations for these algorithms. 1778 A.4. Example JWE using JWE JSON Serialization 1780 This section contains an example using the JWE JSON Serialization. 1781 This example demonstrates the capability for encrypting the same 1782 plaintext to multiple recipients. 1784 Two recipients are present in this example. The algorithm and key 1785 used for the first recipient are the same as that used in 1786 Appendix A.2. The algorithm and key used for the second recipient 1787 are the same as that used in Appendix A.3. The resulting JWE 1788 Encrypted Key values are therefore the same; those computations are 1789 not repeated here. 1791 The Plaintext, the Content Encryption Key (CEK), Initialization 1792 Vector, and JWE Protected Header are shared by all recipients (which 1793 must be the case, since the Ciphertext and Authentication Tag are 1794 also shared). 1796 A.4.1. JWE Per-Recipient Unprotected Headers 1798 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1799 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1800 encrypt the CEK. Key ID values are supplied for both keys. The two 1801 per-recipient header values used to represent these algorithms and 1802 Key IDs are: 1804 {"alg":"RSA1_5","kid":"2011-04-29"} 1806 and 1808 {"alg":"A128KW","kid":"7"} 1810 A.4.2. JWE Protected Header 1812 The Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1813 algorithm to produce the common JWE Ciphertext and JWE Authentication 1814 Tag values. The JWE Protected Header value representing this is: 1816 {"enc":"A128CBC-HS256"} 1818 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1819 Header)) gives this value: 1821 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1823 A.4.3. JWE Unprotected Header 1825 This JWE uses the "jku" Header Parameter to reference a JWK Set. This 1826 is represented in the following JWE Unprotected Header value as: 1828 {"jku":"https://server.example.com/keys.jwks"} 1830 A.4.4. Complete JWE Header Values 1832 Combining the per-recipient, protected, and unprotected header values 1833 supplied, the JWE Header values used for the first and second 1834 recipient respectively are: 1836 {"alg":"RSA1_5", 1837 "kid":"2011-04-29", 1838 "enc":"A128CBC-HS256", 1839 "jku":"https://server.example.com/keys.jwks"} 1841 and 1843 {"alg":"A128KW", 1844 "kid":"7", 1845 "enc":"A128CBC-HS256", 1846 "jku":"https://server.example.com/keys.jwks"} 1848 A.4.5. Additional Authenticated Data 1850 Let the Additional Authenticated Data encryption parameter be 1851 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1853 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1854 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1856 A.4.6. Content Encryption 1858 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1859 the encryption key, the JWE Initialization Vector, and the Additional 1860 Authenticated Data value above. The steps for doing this using the 1861 values from Appendix A.3 are detailed in Appendix B. The resulting 1862 Ciphertext is: 1864 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1865 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1866 112, 56, 102] 1868 The resulting Authentication Tag value is: 1870 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1871 207] 1873 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1874 value: 1876 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1878 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1879 Tag) gives this value: 1881 Mz-VPPyU4RlcuYv1IwIvzw 1883 A.4.7. Complete JWE JSON Serialization Representation 1885 The complete JSON Web Encryption JSON Serialization for these values 1886 is as follows (with line breaks for display purposes only): 1888 {"protected": 1889 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1890 "unprotected": 1891 {"jku":"https://server.example.com/keys.jwks"}, 1892 "recipients":[ 1893 {"header": 1894 {"alg":"RSA1_5"}, 1895 "encrypted_key": 1896 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1897 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1898 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 1899 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 1900 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 1901 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 1902 {"header": 1903 {"alg":"A128KW"}, 1904 "encrypted_key": 1905 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1906 "iv": 1907 "AxY8DCtDaGlsbGljb3RoZQ", 1908 "ciphertext": 1909 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1910 "tag": 1911 "Mz-VPPyU4RlcuYv1IwIvzw" 1912 } 1914 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 1916 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 1917 authenticated encryption computation using the values from the 1918 example in Appendix A.3. As described where this algorithm is 1919 defined in Sections 4.8 and 4.8.3 of JWA, the AES_CBC_HMAC_SHA2 1920 family of algorithms are implemented using Advanced Encryption 1921 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #5 1922 padding to perform the encryption and an HMAC SHA-2 function to 1923 perform the integrity calculation - in this case, HMAC SHA-256. 1925 B.1. Extract MAC_KEY and ENC_KEY from Key 1927 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example is: 1929 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1930 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1931 44, 207] 1933 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 1934 which is: 1936 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1937 206] 1939 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 1940 is: 1942 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 1943 207] 1945 Note that the MAC key comes before the encryption key in the input 1946 key K; this is in the opposite order of the algorithm names in the 1947 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 1949 B.2. Encrypt Plaintext to Create Ciphertext 1951 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 1952 using PKCS #5 padding using the ENC_KEY above. The Plaintext in this 1953 example is: 1955 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1956 112, 114, 111, 115, 112, 101, 114, 46] 1958 The encryption result is as follows, which is the Ciphertext output: 1960 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1961 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1962 112, 56, 102] 1964 B.3. 64 Bit Big Endian Representation of AAD Length 1966 The Additional Authenticated Data (AAD) in this example is: 1968 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1969 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1970 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1971 110, 48] 1973 This AAD is 51 bytes long, which is 408 bits long. The octet string 1974 AL, which is the number of bits in AAD expressed as a big endian 64 1975 bit unsigned integer is: 1977 [0, 0, 0, 0, 0, 0, 1, 152] 1979 B.4. Initialization Vector Value 1981 The Initialization Vector value used in this example is: 1983 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1984 101] 1986 B.5. Create Input to HMAC Computation 1988 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 1989 the AL value. The result of this concatenation is: 1991 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1992 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1993 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1994 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 1995 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 1996 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 1997 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 1999 B.6. Compute HMAC Value 2001 Compute the HMAC SHA-256 of the concatenated value above. This 2002 result M is: 2004 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2005 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 2006 86, 229, 116] 2008 B.7. Truncate HMAC Value to Create Authentication Tag 2010 Use the first half (128 bits) of the HMAC output M as the 2011 Authentication Tag output T. This truncated value is: 2013 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2014 194, 85] 2016 Appendix C. Acknowledgements 2018 Solutions for encrypting JSON content were also explored by JSON 2019 Simple Encryption [JSE] and JavaScript Message Security Format 2020 [I-D.rescorla-jsms], both of which significantly influenced this 2021 draft. This draft attempts to explicitly reuse as many of the 2022 relevant concepts from XML Encryption 1.1 2023 [W3C.CR-xmlenc-core1-20120313] and RFC 5652 [RFC5652] as possible, 2024 while utilizing simple, compact JSON-based data structures. 2026 Special thanks are due to John Bradley and Nat Sakimura for the 2027 discussions that helped inform the content of this specification and 2028 to Eric Rescorla and Joe Hildebrand for allowing the reuse of text 2029 from [I-D.rescorla-jsms] in this document. 2031 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2032 Jay for validating the examples in this specification. 2034 This specification is the work of the JOSE Working Group, which 2035 includes dozens of active and dedicated participants. In particular, 2036 the following individuals contributed ideas, feedback, and wording 2037 that influenced this specification: 2039 Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick 2040 Hardt, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Tony 2041 Nadalin, Axel Nennker, Emmanuel Raviart, Nat Sakimura, Jim Schaad, 2042 Hannes Tschofenig, and Sean Turner. 2044 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2045 Sean Turner and Stephen Farrell served as Security area directors 2046 during the creation of this specification. 2048 Appendix D. Document History 2050 [[ to be removed by the RFC Editor before publication as an RFC ]] 2052 -22 2054 o Corrected RFC 2119 terminology usage. 2056 o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. 2058 -21 2059 o Changed some references from being normative to informative, 2060 addressing issue #90. 2062 o Applied review comments to the JSON Serialization section, 2063 addressing issue #178. 2065 -20 2067 o Made terminology definitions more consistent, addressing issue 2068 #165. 2070 o Restructured the JSON Serialization section to call out the 2071 parameters used in hanging lists, addressing issue #178. 2073 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 2074 addressing issue #90. 2076 -19 2078 o Reordered the key selection parameters. 2080 -18 2082 o Updated the mandatory-to-implement (MTI) language to say that 2083 applications using this specification need to specify what 2084 serialization and serialization features are used for that 2085 application, addressing issue #176. 2087 o Changes to address editorial and minor issues #89, #135, #165, 2088 #174, #175, #177, #179, and #180. 2090 o Used Header Parameter Description registry field. 2092 -17 2094 o Refined the "typ" and "cty" definitions to always be MIME Media 2095 Types, with the omission of "application/" prefixes recommended 2096 for brevity, addressing issue #50. 2098 o Updated the mandatory-to-implement (MTI) language to say that 2099 general-purpose implementations must implement the single 2100 recipient case for both serializations whereas special-purpose 2101 implementations can implement just one serialization if that meets 2102 the needs of the use cases the implementation is designed for, 2103 addressing issue #176. 2105 o Explicitly named all the logical components of a JWE and defined 2106 the processing rules and serializations in terms of those 2107 components, addressing issues #60, #61, and #62. 2109 o Replaced verbose repetitive phases such as "base64url encode the 2110 octets of the UTF-8 representation of X" with mathematical 2111 notation such as "BASE64URL(UTF8(X))". 2113 o Header Parameters and processing rules occurring in both JWS and 2114 JWE are now referenced in JWS by JWE, rather than duplicated, 2115 addressing issue #57. 2117 o Terms used in multiple documents are now defined in one place and 2118 incorporated by reference. Some lightly used or obvious terms 2119 were also removed. This addresses issue #58. 2121 -16 2123 o Changes to address editorial and minor issues #163, #168, #169, 2124 #170, #172, and #173. 2126 -15 2128 o Clarified that it is an application decision which recipients' 2129 encrypted content must successfully validate for the JWE to be 2130 accepted, addressing issue #35. 2132 o Changes to address editorial issues #34, #164, and #169. 2134 -14 2136 o Clarified that the "protected", "unprotected", "header", "iv", 2137 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2138 JSON Serialization when their values would be empty. Stated that 2139 the "recipients" array must always be present. 2141 -13 2143 o Added an "aad" (Additional Authenticated Data) member for the JWE 2144 JSON Serialization, enabling Additional Authenticated Data to be 2145 supplied that is not double base64url encoded, addressing issue 2146 #29. 2148 -12 2150 o Clarified that the "typ" and "cty" header parameters are used in 2151 an application-specific manner and have no effect upon the JWE 2152 processing. 2154 o Replaced the MIME types "application/jwe+json" and 2155 "application/jwe" with "application/jose+json" and 2156 "application/jose". 2158 o Stated that recipients MUST either reject JWEs with duplicate 2159 Header Parameter Names or use a JSON parser that returns only the 2160 lexically last duplicate member name. 2162 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2163 be with the algorithm descriptions that use them. 2165 o Added a Serializations section with parallel treatment of the JWE 2166 Compact Serialization and the JWE JSON Serialization and also 2167 moved the former Implementation Considerations content there. 2169 o Restored use of the term "AEAD". 2171 o Changed terminology from "block encryption" to "content 2172 encryption". 2174 -11 2176 o Added Key Identification section. 2178 o Removed the Encrypted Key value from the AAD computation since it 2179 is already effectively integrity protected by the encryption 2180 process. The AAD value now only contains the representation of 2181 the JWE Encrypted Header. 2183 o For the JWE JSON Serialization, enable Header Parameter values to 2184 be specified in any of three parameters: the "protected" member 2185 that is integrity protected and shared among all recipients, the 2186 "unprotected" member that is not integrity protected and shared 2187 among all recipients, and the "header" member that is not 2188 integrity protected and specific to a particular recipient. (This 2189 does not affect the JWE Compact Serialization, in which all Header 2190 Parameter values are in a single integrity protected JWE Header 2191 value.) 2193 o Shortened the names "authentication_tag" to "tag" and 2194 "initialization_vector" to "iv" in the JWE JSON Serialization, 2195 addressing issue #20. 2197 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2199 o Removed suggested compact serialization for multiple recipients. 2201 o Changed the MIME type name "application/jwe-js" to 2202 "application/jwe+json", addressing issue #22. 2204 o Tightened the description of the "crit" (critical) header 2205 parameter. 2207 -10 2209 o Changed the JWE processing rules for multiple recipients so that a 2210 single AAD value contains the header parameters and encrypted key 2211 values for all the recipients, enabling AES GCM to be safely used 2212 for multiple recipients. 2214 o Added an appendix suggesting a possible compact serialization for 2215 JWEs with multiple recipients. 2217 -09 2219 o Added JWE JSON Serialization, as specified by 2220 draft-jones-jose-jwe-json-serialization-04. 2222 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2223 parameter value. 2225 o Defined that the default action for header parameters that are not 2226 understood is to ignore them unless specifically designated as 2227 "MUST be understood" or included in the new "crit" (critical) 2228 header parameter list. This addressed issue #6. 2230 o Corrected "x5c" description. This addressed issue #12. 2232 o Changed from using the term "byte" to "octet" when referring to 8 2233 bit values. 2235 o Added Key Management Mode definitions to terminology section and 2236 used the defined terms to provide clearer key management 2237 instructions. This addressed issue #5. 2239 o Added text about preventing the recipient from behaving as an 2240 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2242 o Changed from using the term "Integrity Value" to "Authentication 2243 Tag". 2245 o Changed member name from "integrity_value" to "authentication_tag" 2246 in the JWE JSON Serialization. 2248 o Removed Initialization Vector from the AAD value since it is 2249 already integrity protected by all of the authenticated encryption 2250 algorithms specified in the JWA specification. 2252 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2253 and "A256CBC-HS512". The new algorithms perform the same 2254 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2255 but with the Initialization Vector and Authentication Tag values 2256 remaining separate from the Ciphertext value in the output 2257 representation. Also deleted the header parameters "epu" 2258 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2259 they are no longer used. 2261 -08 2263 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2264 since the term AEAD in the RFC 5116 sense implied the use of a 2265 particular data representation, rather than just referring to the 2266 class of algorithms that perform authenticated encryption with 2267 associated data. 2269 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2270 Tschofenig. Many of these simplified the terminology used. 2272 o Clarified statements of the form "This header parameter is 2273 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2275 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2276 Web Signature and Encryption Header Parameters registry. 2278 o Added seriesInfo information to Internet Draft references. 2280 -07 2282 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2284 o Updated values for example AES CBC calculations. 2286 o Made several local editorial changes to clean up loose ends left 2287 over from to the decision to only support block encryption methods 2288 providing integrity. One of these changes was to explicitly state 2289 that the "enc" (encryption method) algorithm must be an 2290 Authenticated Encryption algorithm with a specified key length. 2292 -06 2294 o Removed the "int" and "kdf" parameters and defined the new 2295 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2296 "A256CBC+HS512" to replace the former uses of AES CBC, which 2297 required the use of separate integrity and key derivation 2298 functions. 2300 o Included additional values in the Concat KDF calculation -- the 2301 desired output size and the algorithm value, and optionally 2302 PartyUInfo and PartyVInfo values. Added the optional header 2303 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2304 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2305 PartyVInfo). Updated the KDF examples accordingly. 2307 o Promoted Initialization Vector from being a header parameter to 2308 being a top-level JWE element. This saves approximately 16 bytes 2309 in the compact serialization, which is a significant savings for 2310 some use cases. Promoting the Initialization Vector out of the 2311 header also avoids repeating this shared value in the JSON 2312 serialization. 2314 o Changed "x5c" (X.509 Certificate Chain) representation from being 2315 a single string to being an array of strings, each containing a 2316 single base64 encoded DER certificate value, representing elements 2317 of the certificate chain. 2319 o Added an AES Key Wrap example. 2321 o Reordered the encryption steps so CMK creation is first, when 2322 required. 2324 o Correct statements in examples about which algorithms produce 2325 reproducible results. 2327 -05 2329 o Support both direct encryption using a shared or agreed upon 2330 symmetric key, and the use of a shared or agreed upon symmetric 2331 key to key wrap the CMK. 2333 o Added statement that "StringOrURI values are compared as case- 2334 sensitive strings with no transformations or canonicalizations 2335 applied". 2337 o Updated open issues. 2339 o Indented artwork elements to better distinguish them from the body 2340 text. 2342 -04 2343 o Refer to the registries as the primary sources of defined values 2344 and then secondarily reference the sections defining the initial 2345 contents of the registries. 2347 o Normatively reference XML Encryption 1.1 2348 [W3C.CR-xmlenc-core1-20120313] for its security considerations. 2350 o Reference draft-jones-jose-jwe-json-serialization instead of 2351 draft-jones-json-web-encryption-json-serialization. 2353 o Described additional open issues. 2355 o Applied editorial suggestions. 2357 -03 2359 o Added the "kdf" (key derivation function) header parameter to 2360 provide crypto agility for key derivation. The default KDF 2361 remains the Concat KDF with the SHA-256 digest function. 2363 o Reordered encryption steps so that the Encoded JWE Header is 2364 always created before it is needed as an input to the 2365 Authenticated Encryption "additional authenticated data" 2366 parameter. 2368 o Added the "cty" (content type) header parameter for declaring type 2369 information about the secured content, as opposed to the "typ" 2370 (type) header parameter, which declares type information about 2371 this object. 2373 o Moved description of how to determine whether a header is for a 2374 JWS or a JWE from the JWT spec to the JWE spec. 2376 o Added complete encryption examples for both Authenticated 2377 Encryption and non-Authenticated Encryption algorithms. 2379 o Added complete key derivation examples. 2381 o Added "Collision Resistant Namespace" to the terminology section. 2383 o Reference ITU.X690.1994 for DER encoding. 2385 o Added Registry Contents sections to populate registry values. 2387 o Numerous editorial improvements. 2389 -02 2390 o When using Authenticated Encryption algorithms (such as AES GCM), 2391 use the "additional authenticated data" parameter to provide 2392 integrity for the header, encrypted key, and ciphertext and use 2393 the resulting "authentication tag" value as the JWE Authentication 2394 Tag. 2396 o Defined KDF output key sizes. 2398 o Generalized text to allow key agreement to be employed as an 2399 alternative to key wrapping or key encryption. 2401 o Changed compression algorithm from gzip to DEFLATE. 2403 o Clarified that it is an error when a "kid" value is included and 2404 no matching key is found. 2406 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2407 rejected. 2409 o Clarified the relationship between "typ" header parameter values 2410 and MIME types. 2412 o Registered application/jwe MIME type and "JWE" typ header 2413 parameter value. 2415 o Simplified JWK terminology to get replace the "JWK Key Object" and 2416 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2417 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2418 between single keys and sets of keys. As part of this change, the 2419 Header Parameter Name for a public key value was changed from 2420 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2422 o Added suggestion on defining additional header parameters such as 2423 "x5t#S256" in the future for certificate thumbprints using hash 2424 algorithms other than SHA-1. 2426 o Specify RFC 2818 server identity validation, rather than RFC 6125 2427 (paralleling the same decision in the OAuth specs). 2429 o Generalized language to refer to Message Authentication Codes 2430 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2431 unless in a context specific to HMAC algorithms. 2433 o Reformatted to give each header parameter its own section heading. 2435 -01 2436 o Added an integrity check for non-Authenticated Encryption 2437 algorithms. 2439 o Added "jpk" and "x5c" header parameters for including JWK public 2440 keys and X.509 certificate chains directly in the header. 2442 o Clarified that this specification is defining the JWE Compact 2443 Serialization. Referenced the new JWE-JS spec, which defines the 2444 JWE JSON Serialization. 2446 o Added text "New header parameters should be introduced sparingly 2447 since an implementation that does not understand a parameter MUST 2448 reject the JWE". 2450 o Clarified that the order of the encryption and decryption steps is 2451 not significant in cases where there are no dependencies between 2452 the inputs and outputs of the steps. 2454 o Made other editorial improvements suggested by JOSE working group 2455 participants. 2457 -00 2459 o Created the initial IETF draft based upon 2460 draft-jones-json-web-encryption-02 with no normative changes. 2462 o Changed terminology to no longer call both digital signatures and 2463 HMACs "signatures". 2465 Authors' Addresses 2467 Michael B. Jones 2468 Microsoft 2470 Email: mbj@microsoft.com 2471 URI: http://self-issued.info/ 2473 Eric Rescorla 2474 RTFM, Inc. 2476 Email: ekr@rtfm.com 2477 Joe Hildebrand 2478 Cisco Systems, Inc. 2480 Email: jhildebr@cisco.com