idnits 2.17.1 draft-ietf-jose-json-web-encryption-25.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 31, 2014) is 3650 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 1389 -- Looks like a reference, but probably isn't: '197' on line 1389 -- Looks like a reference, but probably isn't: '117' on line 1389 -- Looks like a reference, but probably isn't: '252' on line 1389 -- Looks like a reference, but probably isn't: '2' on line 1389 -- Looks like a reference, but probably isn't: '219' on line 1389 -- Looks like a reference, but probably isn't: '233' on line 1389 -- Looks like a reference, but probably isn't: '68' on line 1389 -- Looks like a reference, but probably isn't: '180' on line 1389 -- Looks like a reference, but probably isn't: '225' on line 1389 -- Looks like a reference, but probably isn't: '77' on line 1389 -- Looks like a reference, but probably isn't: '0' on line 1976 -- Looks like a reference, but probably isn't: '1' on line 1976 -- Looks like a reference, but probably isn't: '152' on line 1976 -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMAScript' ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- 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 J. Hildebrand 5 Expires: October 2, 2014 Cisco 6 March 31, 2014 8 JSON Web Encryption (JWE) 9 draft-ietf-jose-json-web-encryption-25 11 Abstract 13 JSON Web Encryption (JWE) represents encrypted content using 14 JavaScript Object Notation (JSON) based data structures. 15 Cryptographic algorithms and identifiers for use with this 16 specification are described in the separate JSON Web Algorithms (JWA) 17 specification and IANA registries defined by that specification. 18 Related digital signature and MAC capabilities are described in the 19 separate JSON Web Signature (JWS) specification. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on October 2, 2014. 38 Copyright Notice 40 Copyright (c) 2014 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 8 59 3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 10 60 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11 61 4.1. Registered Header Parameter Names . . . . . . . . . . . . 12 62 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 12 63 4.1.2. "enc" (Encryption Algorithm) Header Parameter . . . . 12 64 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 12 65 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 13 66 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 13 67 4.1.6. "kid" (Key ID) Header Parameter . . . . . . . . . . . 13 68 4.1.7. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 13 69 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 14 70 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 71 Parameter . . . . . . . . . . . . . . . . . . . . . . 14 72 4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 14 73 4.1.11. "cty" (Content Type) Header Parameter . . . . . . . . 14 74 4.1.12. "crit" (Critical) Header Parameter . . . . . . . . . . 14 75 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 14 76 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 15 77 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 15 78 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 15 79 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 17 80 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20 81 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20 82 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 20 83 7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 20 84 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 20 85 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 23 86 9. Distinguishing between JWS and JWE Objects . . . . . . . . . . 23 87 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 88 10.1. JSON Web Signature and Encryption Header Parameters 89 Registration . . . . . . . . . . . . . . . . . . . . . . . 24 90 10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 24 91 11. Security Considerations . . . . . . . . . . . . . . . . . . . 26 92 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 93 12.1. Normative References . . . . . . . . . . . . . . . . . . . 27 94 12.2. Informative References . . . . . . . . . . . . . . . . . . 27 95 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 28 96 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 28 97 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 28 98 A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 29 99 A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 29 100 A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 30 101 A.1.5. Additional Authenticated Data . . . . . . . . . . . . 30 102 A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 31 103 A.1.7. Complete Representation . . . . . . . . . . . . . . . 31 104 A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 32 105 A.2. Example JWE using RSAES-PKCS1-V1_5 and 106 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 32 107 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 32 108 A.2.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 33 109 A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 33 110 A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 34 111 A.2.5. Additional Authenticated Data . . . . . . . . . . . . 34 112 A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 34 113 A.2.7. Complete Representation . . . . . . . . . . . . . . . 35 114 A.2.8. Validation . . . . . . . . . . . . . . . . . . . . . . 35 115 A.3. Example JWE using AES Key Wrap and 116 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 36 117 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 36 118 A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 36 119 A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 36 120 A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 37 121 A.3.5. Additional Authenticated Data . . . . . . . . . . . . 37 122 A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 37 123 A.3.7. Complete Representation . . . . . . . . . . . . . . . 38 124 A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 38 125 A.4. Example JWE using JWE JSON Serialization . . . . . . . . . 39 126 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 39 127 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 39 128 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 40 129 A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 40 130 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 40 131 A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 40 132 A.4.7. Complete JWE JSON Serialization Representation . . . . 41 133 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 41 134 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 42 135 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 42 136 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 43 137 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 43 138 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 43 139 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 43 140 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 43 141 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 44 142 Appendix D. Document History . . . . . . . . . . . . . . . . . . 44 143 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 54 145 1. Introduction 147 JSON Web Encryption (JWE) represents encrypted content using 148 JavaScript Object Notation (JSON) [RFC7159] based data structures. 149 The JWE cryptographic mechanisms encrypt and provide integrity 150 protection for an arbitrary sequence of octets. 152 Two closely related serializations for JWE objects are defined. The 153 JWE Compact Serialization is a compact, URL-safe representation 154 intended for space constrained environments such as HTTP 155 Authorization headers and URI query parameters. The JWE JSON 156 Serialization represents JWE objects as JSON objects and enables the 157 same content to be encrypted to multiple parties. Both share the 158 same cryptographic underpinnings. 160 Cryptographic algorithms and identifiers for use with this 161 specification are described in the separate JSON Web Algorithms (JWA) 162 [JWA] specification and IANA registries defined by that 163 specification. Related digital signature and MAC capabilities are 164 described in the separate JSON Web Signature (JWS) [JWS] 165 specification. 167 Names defined by this specification are short because a core goal is 168 for the resulting representations to be compact. 170 1.1. Notational Conventions 172 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 173 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 174 "OPTIONAL" in this document are to be interpreted as described in Key 175 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 176 these words are used without being spelled in uppercase then they are 177 to be interpreted with their normal natural language meanings. 179 BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per 180 Section 2. 182 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 183 of STRING. 185 ASCII(STRING) denotes the octets of the ASCII [USASCII] 186 representation of STRING. 188 The concatenation of two values A and B is denoted as A || B. 190 2. Terminology 192 These terms defined by the JSON Web Signature (JWS) [JWS] 193 specification are incorporated into this specification: "JSON Web 194 Signature (JWS)", "Base64url Encoding", "Collision-Resistant Name", 195 and "StringOrURI". 197 These terms are defined for use by this specification: 199 JSON Web Encryption (JWE) 200 A data structure representing an encrypted and integrity protected 201 message. 203 Authenticated Encryption with Associated Data (AEAD) 204 An AEAD algorithm is one that encrypts the Plaintext, allows 205 Additional Authenticated Data to be specified, and provides an 206 integrated content integrity check over the Ciphertext and 207 Additional Authenticated Data. AEAD algorithms accept two inputs, 208 the Plaintext and the Additional Authenticated Data value, and 209 produce two outputs, the Ciphertext and the Authentication Tag 210 value. AES Galois/Counter Mode (GCM) is one such algorithm. 212 Plaintext 213 The sequence of octets to be encrypted -- a.k.a., the message. 214 The plaintext can contain an arbitrary sequence of octets. 216 Ciphertext 217 An encrypted representation of the Plaintext. 219 Additional Authenticated Data (AAD) 220 An input to an AEAD operation that is integrity protected but not 221 encrypted. 223 Authentication Tag 224 An output of an AEAD operation that ensures the integrity of the 225 Ciphertext and the Additional Authenticated Data. Note that some 226 algorithms may not use an Authentication Tag, in which case this 227 value is the empty octet sequence. 229 Content Encryption Key (CEK) 230 A symmetric key for the AEAD algorithm used to encrypt the 231 Plaintext for the recipient to produce the Ciphertext and the 232 Authentication Tag. 234 JWE Header 235 JSON object containing the parameters describing the cryptographic 236 operations and parameters employed. The JWE Header members are 237 the union of the members of the JWE Protected Header, the JWE 238 Shared Unprotected Header, and the JWE Per-Recipient Unprotected 239 Header. The members of the JWE Header are Header Parameters. 241 JWE Encrypted Key 242 Encrypted Content Encryption Key (CEK) value. Note that for some 243 algorithms, the JWE Encrypted Key value is specified as being the 244 empty octet sequence. 246 JWE Initialization Vector 247 Initialization Vector value used when encrypting the plaintext. 248 Note that some algorithms may not use an Initialization Vector, in 249 which case this value is the empty octet sequence. 251 JWE AAD 252 Additional value to be integrity protected by the authenticated 253 encryption operation. This can only be present when using the JWE 254 JSON Serialization. (Note that this can also be achieved when 255 using either serialization by including the AAD value as an 256 integrity protected Header Parameter value, but at the cost of the 257 value being double base64url encoded.) 259 JWE Ciphertext 260 Ciphertext value resulting from authenticated encryption of the 261 plaintext with additional authenticated data. 263 JWE Authentication Tag 264 Authentication Tag value resulting from authenticated encryption 265 of the plaintext with additional authenticated data. 267 Header Parameter 268 A name/value pair that is member of the JWE Header. 270 JWE Protected Header 271 JSON object that contains the JWE Header Parameters that are 272 integrity protected by the authenticated encryption operation. 273 These parameters apply to all recipients of the JWE. For the JWE 274 Compact Serialization, this comprises the entire JWE Header. For 275 the JWE JSON Serialization, this is one component of the JWE 276 Header. 278 JWE Shared Unprotected Header 279 JSON object that contains the JWE Header Parameters that apply to 280 all recipients of the JWE that are not integrity protected. This 281 can only be present when using the JWE JSON Serialization. 283 JWE Per-Recipient Unprotected Header 284 JSON object that contains JWE Header Parameters that apply to a 285 single recipient of the JWE. These Header Parameter values are 286 not integrity protected. This can only be present when using the 287 JWE JSON Serialization. 289 JWE Compact Serialization 290 A representation of the JWE as a compact, URL-safe string. 292 JWE JSON Serialization 293 A representation of the JWE as a JSON object. The JWE JSON 294 Serialization enables the same content to be encrypted to multiple 295 parties. This representation is neither optimized for compactness 296 nor URL-safe. 298 Key Management Mode 299 A method of determining the Content Encryption Key (CEK) value to 300 use. Each algorithm used for determining the CEK value uses a 301 specific Key Management Mode. Key Management Modes employed by 302 this specification are Key Encryption, Key Wrapping, Direct Key 303 Agreement, Key Agreement with Key Wrapping, and Direct Encryption. 305 Key Encryption 306 A Key Management Mode in which the Content Encryption Key (CEK) 307 value is encrypted to the intended recipient using an asymmetric 308 encryption algorithm. 310 Key Wrapping 311 A Key Management Mode in which the Content Encryption Key (CEK) 312 value is encrypted to the intended recipient using a symmetric key 313 wrapping algorithm. 315 Direct Key Agreement 316 A Key Management Mode in which a key agreement algorithm is used 317 to agree upon the Content Encryption Key (CEK) value. 319 Key Agreement with Key Wrapping 320 A Key Management Mode in which a key agreement algorithm is used 321 to agree upon a symmetric key used to encrypt the Content 322 Encryption Key (CEK) value to the intended recipient using a 323 symmetric key wrapping algorithm. 325 Direct Encryption 326 A Key Management Mode in which the Content Encryption Key (CEK) 327 value used is the secret symmetric key value shared between the 328 parties. 330 3. JSON Web Encryption (JWE) Overview 332 JWE represents encrypted content using JSON data structures and 333 base64url encoding. A JWE represents these logical values: 335 JWE Header 336 JSON object containing the parameters describing the cryptographic 337 operations and parameters employed. The JWE Header members are 338 the union of the members of the JWE Protected Header, the JWE 339 Shared Unprotected Header, and the JWE Per-Recipient Unprotected 340 Header, as described below. 342 JWE Encrypted Key 343 Encrypted Content Encryption Key (CEK) value. 345 JWE Initialization Vector 346 Initialization Vector value used when encrypting the plaintext. 348 JWE AAD 349 Additional value to be integrity protected by the authenticated 350 encryption operation. 352 JWE Ciphertext 353 Ciphertext value resulting from authenticated encryption of the 354 plaintext with additional authenticated data. 356 JWE Authentication Tag 357 Authentication Tag value resulting from authenticated encryption 358 of the plaintext with additional authenticated data. 360 The JWE Header represents the combination of these logical values: 362 JWE Protected Header 363 JSON object that contains the JWE Header Parameters that are 364 integrity protected by the authenticated encryption operation. 365 These parameters apply to all recipients of the JWE. 367 JWE Shared Unprotected Header 368 JSON object that contains the JWE Header Parameters that apply to 369 all recipients of the JWE that are not integrity protected. 371 JWE Per-Recipient Unprotected Header 372 JSON object that contains JWE Header Parameters that apply to a 373 single recipient of the JWE. These Header Parameter values are 374 not integrity protected. 376 This document defines two serializations for JWE objects: a compact, 377 URL-safe serialization called the JWE Compact Serialization and a 378 JSON serialization called the JWE JSON Serialization. In both 379 serializations, the JWE Protected Header, JWE Encrypted Key, JWE 380 Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are 381 base64url encoded for transmission, since JSON lacks a way to 382 directly represent octet sequences. When present, the JWE AAD is 383 also base64url encoded for transmission. 385 In the JWE Compact Serialization, no JWE Shared Unprotected Header or 386 JWE Per-Recipient Unprotected Header are used. In this case, the JWE 387 Header and the JWE Protected Header are the same. 389 In the JWE Compact Serialization, a JWE object is represented as the 390 combination of these five string values, 391 BASE64URL(UTF8(JWE Protected Header)), 392 BASE64URL(JWE Encrypted Key), 393 BASE64URL(JWE Initialization Vector), 394 BASE64URL(JWE Ciphertext), and 395 BASE64URL(JWE Authentication Tag), 396 concatenated in that order, with the five strings being separated by 397 four period ('.') characters. 399 In the JWE JSON Serialization, one or more of the JWE Protected 400 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 401 Unprotected Header MUST be present. In this case, the members of the 402 JWE Header are the combination of the members of the JWE Protected 403 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 404 Unprotected Header values that are present. 406 In the JWE JSON Serialization, a JWE object is represented as the 407 combination of these eight values, 408 BASE64URL(UTF8(JWE Protected Header)), 409 JWE Shared Unprotected Header, 410 JWE Per-Recipient Unprotected Header, 411 BASE64URL(JWE Encrypted Key), 412 BASE64URL(JWE Initialization Vector), 413 BASE64URL(JWE Ciphertext), 414 BASE64URL(JWE Authentication Tag), and 415 BASE64URL(JWE AAD), 416 with the six base64url encoding result strings and the two 417 unprotected JSON object values being represented as members within a 418 JSON object. The inclusion of some of these values is OPTIONAL. The 419 JWE JSON Serialization can also encrypt the plaintext to multiple 420 recipients. See Section 7.2 for more information about the JWE JSON 421 Serialization. 423 JWE utilizes authenticated encryption to ensure the confidentiality 424 and integrity of the Plaintext and the integrity of the JWE Protected 425 Header and the JWE AAD. 427 3.1. Example JWE 429 This example encrypts the plaintext "The true sign of intelligence is 430 not knowledge but imagination." to the recipient using RSAES OAEP for 431 key encryption and AES GCM for content encryption. 433 The following example JWE Protected Header declares that: 435 o the Content Encryption Key is encrypted to the recipient using the 436 RSAES OAEP algorithm to produce the JWE Encrypted Key and 438 o the Plaintext is encrypted using the AES GCM algorithm with a 256 439 bit key to produce the Ciphertext. 441 {"alg":"RSA-OAEP","enc":"A256GCM"} 443 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 444 Header)) gives this value: 446 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 448 The remaining steps to finish creating this JWE are: 450 o Generate a random Content Encryption Key (CEK). 452 o Encrypt the CEK with the recipient's public key using the RSAES 453 OAEP algorithm to produce the JWE Encrypted Key. 455 o Base64url encode the JWE Encrypted Key. 457 o Generate a random JWE Initialization Vector. 459 o Base64url encode the JWE Initialization Vector. 461 o Let the Additional Authenticated Data encryption parameter be 462 ASCII(BASE64URL(UTF8(JWE Protected Header))). 464 o Encrypt the Plaintext with AES GCM using the CEK as the encryption 465 key, the JWE Initialization Vector, and the Additional 466 Authenticated Data value, requesting a 128 bit Authentication Tag 467 output. 469 o Base64url encode the Ciphertext. 471 o Base64url encode the Authentication Tag. 473 o Assemble the final representation: The Compact Serialization of 474 this result is the string BASE64URL(UTF8(JWE Protected Header)) || 475 '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE 476 Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' 477 || BASE64URL(JWE Authentication Tag). 479 The final result in this example (with line breaks for display 480 purposes only) is: 482 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 483 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 484 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 485 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 486 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 487 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 488 6UklfCpIMfIjf7iGdXKHzg. 489 48V1_ALb6US04U3b. 490 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 491 SdiwkIr3ajwQzaBtQD_A. 492 XFBoMYUZodetZdvTiFvSkQ 494 See Appendix A.1 for the complete details of computing this JWE. See 495 other parts of Appendix A for additional examples. 497 4. JWE Header 499 The members of the JSON object(s) representing the JWE Header 500 describe the encryption applied to the Plaintext and optionally 501 additional properties of the JWE. The Header Parameter names within 502 the JWE Header MUST be unique; recipients MUST either reject JWEs 503 with duplicate Header Parameter names or use a JSON parser that 504 returns only the lexically last duplicate member name, as specified 505 in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. 507 Implementations are required to understand the specific Header 508 Parameters defined by this specification that are designated as "MUST 509 be understood" and process them in the manner defined in this 510 specification. All other Header Parameters defined by this 511 specification that are not so designated MUST be ignored when not 512 understood. Unless listed as a critical Header Parameter, per 513 Section 4.1.12, all Header Parameters not defined by this 514 specification MUST be ignored when not understood. 516 There are three classes of Header Parameter names: Registered Header 517 Parameter names, Public Header Parameter names, and Private Header 518 Parameter names. 520 4.1. Registered Header Parameter Names 522 The following Header Parameter names are registered in the IANA JSON 523 Web Signature and Encryption Header Parameters registry defined in 524 [JWS], with meanings as defined below. 526 As indicated by the common registry, JWSs and JWEs share a common 527 Header Parameter space; when a parameter is used by both 528 specifications, its usage must be compatible between the 529 specifications. 531 4.1.1. "alg" (Algorithm) Header Parameter 533 This parameter has the same meaning, syntax, and processing rules as 534 the "alg" Header Parameter defined in Section 4.1.1 of [JWS], except 535 that the Header Parameter identifies the cryptographic algorithm used 536 to encrypt or determine the value of the Content Encryption Key 537 (CEK). The encrypted content is not usable if the "alg" value does 538 not represent a supported algorithm, or if the recipient does not 539 have a key that can be used with that algorithm. 541 A list of defined "alg" values for this use can be found in the IANA 542 JSON Web Signature and Encryption Algorithms registry defined in 543 [JWA]; the initial contents of this registry are the values defined 544 in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. 546 4.1.2. "enc" (Encryption Algorithm) Header Parameter 548 The "enc" (encryption algorithm) Header Parameter identifies the 549 content encryption algorithm used to encrypt the Plaintext to produce 550 the Ciphertext. This algorithm MUST be an AEAD algorithm with a 551 specified key length. The recipient MUST reject the JWE if the "enc" 552 value does not represent a supported algorithm. "enc" values should 553 either be registered in the IANA JSON Web Signature and Encryption 554 Algorithms registry defined in [JWA] or be a value that contains a 555 Collision-Resistant Name. The "enc" value is a case-sensitive string 556 containing a StringOrURI value. This Header Parameter MUST be 557 present and MUST be understood and processed by implementations. 559 A list of defined "enc" values for this use can be found in the IANA 560 JSON Web Signature and Encryption Algorithms registry defined in 561 [JWA]; the initial contents of this registry are the values defined 562 in Section 5.1 of the JSON Web Algorithms (JWA) [JWA] specification. 564 4.1.3. "zip" (Compression Algorithm) Header Parameter 566 The "zip" (compression algorithm) applied to the Plaintext before 567 encryption, if any. The "zip" value defined by this specification 568 is: 570 o "DEF" - Compression with the DEFLATE [RFC1951] algorithm 572 Other values MAY be used. Compression algorithm values can be 573 registered in the IANA JSON Web Encryption Compression Algorithm 574 registry defined in [JWA]. The "zip" value is a case-sensitive 575 string. If no "zip" parameter is present, no compression is applied 576 to the Plaintext before encryption. This Header Parameter MUST be 577 integrity protected, and therefore MUST occur only within the JWE 578 Protected Header, when used. Use of this Header Parameter is 579 OPTIONAL. This Header Parameter MUST be understood and processed by 580 implementations. 582 4.1.4. "jku" (JWK Set URL) Header Parameter 584 This parameter has the same meaning, syntax, and processing rules as 585 the "jku" Header Parameter defined in Section 4.1.2 of [JWS], except 586 that the JWK Set resource contains the public key to which the JWE 587 was encrypted; this can be used to determine the private key needed 588 to decrypt the JWE. 590 4.1.5. "jwk" (JSON Web Key) Header Parameter 592 This parameter has the same meaning, syntax, and processing rules as 593 the "jwk" Header Parameter defined in Section 4.1.3 of [JWS], except 594 that the key is the public key to which the JWE was encrypted; this 595 can be used to determine the private key needed to decrypt the JWE. 597 4.1.6. "kid" (Key ID) Header Parameter 599 This parameter has the same meaning, syntax, and processing rules as 600 the "kid" Header Parameter defined in Section 4.1.4 of [JWS], except 601 that the key hint references the public key to which the JWE was 602 encrypted; this can be used to determine the private key needed to 603 decrypt the JWE. This parameter allows originators to explicitly 604 signal a change of key to JWE recipients. 606 4.1.7. "x5u" (X.509 URL) Header Parameter 608 This parameter has the same meaning, syntax, and processing rules as 609 the "x5u" Header Parameter defined in Section 4.1.5 of [JWS], except 610 that the X.509 public key certificate or certificate chain [RFC5280] 611 contains the public key to which the JWE was encrypted; this can be 612 used to determine the private key needed to decrypt the JWE. 614 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 616 This parameter has the same meaning, syntax, and processing rules as 617 the "x5c" Header Parameter defined in Section 4.1.6 of [JWS], except 618 that the X.509 public key certificate or certificate chain [RFC5280] 619 contains the public key to which the JWE was encrypted; this can be 620 used to determine the private key needed to decrypt the JWE. 622 See Appendix B of [JWS] for an example "x5c" value. 624 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 626 This parameter has the same meaning, syntax, and processing rules as 627 the "x5t" Header Parameter defined in Section 4.1.7 of [JWS], except 628 that certificate referenced by the thumbprint contains the public key 629 to which the JWE was encrypted; this can be used to determine the 630 private key needed to decrypt the JWE. 632 4.1.10. "typ" (Type) Header Parameter 634 This parameter has the same meaning, syntax, and processing rules as 635 the "typ" Header Parameter defined in Section 4.1.8 of [JWS], except 636 that the type is of this complete JWE object. 638 4.1.11. "cty" (Content Type) Header Parameter 640 This parameter has the same meaning, syntax, and processing rules as 641 the "cty" Header Parameter defined in Section 4.1.9 of [JWS], except 642 that the type is of the secured content (the plaintext). 644 4.1.12. "crit" (Critical) Header Parameter 646 This parameter has the same meaning, syntax, and processing rules as 647 the "crit" Header Parameter defined in Section 4.1.10 of [JWS], 648 except that JWE Header Parameters are being referred to, rather than 649 JWS Header Parameters. 651 4.2. Public Header Parameter Names 653 Additional Header Parameter names can be defined by those using JWEs. 654 However, in order to prevent collisions, any new Header Parameter 655 name should either be registered in the IANA JSON Web Signature and 656 Encryption Header Parameters registry defined in [JWS] or be a Public 657 Name: a value that contains a Collision-Resistant Name. In each 658 case, the definer of the name or value needs to take reasonable 659 precautions to make sure they are in control of the part of the 660 namespace they use to define the Header Parameter name. 662 New Header Parameters should be introduced sparingly, as they can 663 result in non-interoperable JWEs. 665 4.3. Private Header Parameter Names 667 A producer and consumer of a JWE may agree to use Header Parameter 668 names that are Private Names: names that are not Registered Header 669 Parameter names Section 4.1 or Public Header Parameter names 670 Section 4.2. Unlike Public Header Parameter names, Private Header 671 Parameter names are subject to collision and should be used with 672 caution. 674 5. Producing and Consuming JWEs 676 5.1. Message Encryption 678 The message encryption process is as follows. The order of the steps 679 is not significant in cases where there are no dependencies between 680 the inputs and outputs of the steps. 682 1. Determine the Key Management Mode employed by the algorithm used 683 to determine the Content Encryption Key (CEK) value. (This is 684 the algorithm recorded in the "alg" (algorithm) Header Parameter 685 of the resulting JWE.) 687 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 688 Wrapping are employed, generate a random Content Encryption Key 689 (CEK) value. See RFC 4086 [RFC4086] for considerations on 690 generating random values. The CEK MUST have a length equal to 691 that required for the content encryption algorithm. 693 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 694 employed, use the key agreement algorithm to compute the value 695 of the agreed upon key. When Direct Key Agreement is employed, 696 let the Content Encryption Key (CEK) be the agreed upon key. 697 When Key Agreement with Key Wrapping is employed, the agreed 698 upon key will be used to wrap the CEK. 700 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 701 Wrapping are employed, encrypt the CEK to the recipient and let 702 the result be the JWE Encrypted Key. 704 5. When Direct Key Agreement or Direct Encryption are employed, let 705 the JWE Encrypted Key be the empty octet sequence. 707 6. When Direct Encryption is employed, let the Content Encryption 708 Key (CEK) be the shared symmetric key. 710 7. Compute the encoded key value BASE64URL(JWE Encrypted Key). 712 8. If the JWE JSON Serialization is being used, repeat this process 713 (steps 1-7) for each recipient. 715 9. Generate a random JWE Initialization Vector of the correct size 716 for the content encryption algorithm (if required for the 717 algorithm); otherwise, let the JWE Initialization Vector be the 718 empty octet sequence. 720 10. Compute the encoded initialization vector value BASE64URL(JWE 721 Initialization Vector). 723 11. If a "zip" parameter was included, compress the Plaintext using 724 the specified compression algorithm. 726 12. Serialize the (compressed) Plaintext into an octet sequence M. 728 13. Create the JSON object(s) containing the desired set of Header 729 Parameters, which together comprise the JWE Header: the JWE 730 Protected Header, and if the JWE JSON Serialization is being 731 used, the JWE Shared Unprotected Header and the JWE Per- 732 Recipient Unprotected Header. 734 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 735 Protected Header)). If the JWE Protected Header is not present 736 (which can only happen when using the JWE JSON Serialization and 737 no "protected" member is present), let this value be the empty 738 string. 740 15. Let the Additional Authenticated Data encryption parameter be 741 ASCII(Encoded Protected Header). However if a JWE AAD value is 742 present (which can only be the case when using the JWE JSON 743 Serialization), instead let the Additional Authenticated Data 744 encryption parameter be ASCII(Encoded Protected Header || '.' || 745 BASE64URL(JWE AAD)). 747 16. Encrypt M using the CEK, the JWE Initialization Vector, and the 748 Additional Authenticated Data value using the specified content 749 encryption algorithm to create the JWE Ciphertext value and the 750 JWE Authentication Tag (which is the Authentication Tag output 751 from the encryption operation). 753 17. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext). 755 18. Compute the encoded authentication tag value BASE64URL(JWE 756 Authentication Tag). 758 19. The five encoded values are used in both the JWE Compact 759 Serialization and the JWE JSON Serialization representations. 761 20. If a JWE AAD value is present, compute the encoded AAD value 762 BASE64URL(JWE AAD). 764 21. Create the desired serialized output. The Compact Serialization 765 of this result is the string BASE64URL(UTF8(JWE Protected 766 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 767 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 768 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). The 769 JWE JSON Serialization is described in Section 7.2. 771 5.2. Message Decryption 773 The message decryption process is the reverse of the encryption 774 process. The order of the steps is not significant in cases where 775 there are no dependencies between the inputs and outputs of the 776 steps. If any of these steps fails, the encrypted content cannot be 777 validated. 779 It is an application decision which recipients' encrypted content 780 must successfully validate for the JWE to be accepted. In some 781 cases, encrypted content for all recipients must successfully 782 validate or the JWE will be rejected. In other cases, only the 783 encrypted content for a single recipient needs to be successfully 784 validated. However, in all cases, the encrypted content for at least 785 one recipient MUST successfully validate or the JWE MUST be rejected. 787 1. Parse the JWE representation to extract the serialized values 788 for the components of the JWE -- when using the JWE Compact 789 Serialization, the base64url encoded representations of the JWE 790 Protected Header, the JWE Encrypted Key, the JWE Initialization 791 Vector, the JWE Ciphertext, and the JWE Authentication Tag, and 792 when using the JWE JSON Serialization, also the base64url 793 encoded representation of the JWE AAD and the unencoded JWE 794 Shared Unprotected Header and JWE Per-Recipient Unprotected 795 Header values. When using the JWE Compact Serialization, the 796 JWE Protected Header, the JWE Encrypted Key, the JWE 797 Initialization Vector, the JWE Ciphertext, and the JWE 798 Authentication Tag are represented as base64url encoded values 799 in that order, separated by four period ('.') characters. The 800 JWE JSON Serialization is described in Section 7.2. 802 2. The encoded representations of the JWE Protected Header, the JWE 803 Encrypted Key, the JWE Initialization Vector, the JWE 804 Ciphertext, the JWE Authentication Tag, and the JWE AAD MUST be 805 successfully base64url decoded following the restriction that no 806 padding characters have been used. 808 3. The octet sequence resulting from decoding the encoded JWE 809 Protected Header MUST be a UTF-8 encoded representation of a 810 completely valid JSON object conforming to [RFC7159], which is 811 the JWE Protected Header. 813 4. If using the JWE Compact Serialization, let the JWE Header be 814 the JWE Protected Header; otherwise, when using the JWE JSON 815 Serialization, let the JWE Header be the union of the members of 816 the JWE Protected Header, the JWE Shared Unprotected Header and 817 the corresponding JWE Per-Recipient Unprotected Header, all of 818 which must be completely valid JSON objects. 820 5. The resulting JWE Header MUST NOT contain duplicate Header 821 Parameter names. When using the JWE JSON Serialization, this 822 restriction includes that the same Header Parameter name also 823 MUST NOT occur in distinct JSON object values that together 824 comprise the JWE Header. 826 6. Verify that the implementation understands and can process all 827 fields that it is required to support, whether required by this 828 specification, by the algorithms being used, or by the "crit" 829 Header Parameter value, and that the values of those parameters 830 are also understood and supported. 832 7. Determine the Key Management Mode employed by the algorithm 833 specified by the "alg" (algorithm) Header Parameter. 835 8. Verify that the JWE uses a key known to the recipient. 837 9. When Direct Key Agreement or Key Agreement with Key Wrapping are 838 employed, use the key agreement algorithm to compute the value 839 of the agreed upon key. When Direct Key Agreement is employed, 840 let the Content Encryption Key (CEK) be the agreed upon key. 841 When Key Agreement with Key Wrapping is employed, the agreed 842 upon key will be used to decrypt the JWE Encrypted Key. 844 10. When Key Wrapping, Key Encryption, or Key Agreement with Key 845 Wrapping are employed, decrypt the JWE Encrypted Key to produce 846 the Content Encryption Key (CEK). The CEK MUST have a length 847 equal to that required for the content encryption algorithm. 848 Note that when there are multiple recipients, each recipient 849 will only be able decrypt any JWE Encrypted Key values that were 850 encrypted to a key in that recipient's possession. It is 851 therefore normal to only be able to decrypt one of the per- 852 recipient JWE Encrypted Key values to obtain the CEK value. To 853 mitigate the attacks described in RFC 3218 [RFC3218], the 854 recipient MUST NOT distinguish between format, padding, and 855 length errors of encrypted keys. It is strongly recommended, in 856 the event of receiving an improperly formatted key, that the 857 receiver substitute a randomly generated CEK and proceed to the 858 next step, to mitigate timing attacks. 860 11. When Direct Key Agreement or Direct Encryption are employed, 861 verify that the JWE Encrypted Key value is empty octet sequence. 863 12. When Direct Encryption is employed, let the Content Encryption 864 Key (CEK) be the shared symmetric key. 866 13. If the JWE JSON Serialization is being used, repeat this process 867 (steps 4-12) for each recipient contained in the representation 868 until the CEK value has been determined. 870 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 871 Protected Header)). If the JWE Protected Header is not present 872 (which can only happen when using the JWE JSON Serialization and 873 no "protected" member is present), let this value be the empty 874 string. 876 15. Let the Additional Authenticated Data encryption parameter be 877 ASCII(Encoded Protected Header). However if a JWE AAD value is 878 present (which can only be the case when using the JWE JSON 879 Serialization), instead let the Additional Authenticated Data 880 encryption parameter be ASCII(Encoded Protected Header || '.' || 881 BASE64URL(JWE AAD)). 883 16. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 884 Vector, the Additional Authenticated Data value, and the JWE 885 Authentication Tag (which is the Authentication Tag input to the 886 calculation) using the specified content encryption algorithm, 887 returning the decrypted plaintext and validating the JWE 888 Authentication Tag in the manner specified for the algorithm, 889 rejecting the input without emitting any decrypted output if the 890 JWE Authentication Tag is incorrect. 892 17. If a "zip" parameter was included, uncompress the decrypted 893 plaintext using the specified compression algorithm. 895 18. If all the previous steps succeeded, output the resulting 896 Plaintext. 898 5.3. String Comparison Rules 900 The string comparison rules for this specification are the same as 901 those defined in Section 5.3 of [JWS]. 903 6. Key Identification 905 The key identification methods for this specification are the same as 906 those defined in Section 6 of [JWS], except that the key being 907 identified is the public key to which the JWE was encrypted. 909 7. Serializations 911 JWE objects use one of two serializations, the JWE Compact 912 Serialization or the JWE JSON Serialization. Applications using this 913 specification need to specify what serialization and serialization 914 features are used for that application. For instance, applications 915 might specify that only the JWE JSON Serialization is used, that only 916 JWE JSON Serialization support for a single recipient is used, or 917 that support for multiple recipients is used. JWE implementations 918 only need to implement the features needed for the applications they 919 are designed to support. 921 7.1. JWE Compact Serialization 923 The JWE Compact Serialization represents encrypted content as a 924 compact URL-safe string. This string is BASE64URL(UTF8(JWE Protected 925 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 926 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 927 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). Only one 928 recipient is supported by the JWE Compact Serialization and it 929 provides no syntax to represent JWE Shared Unprotected Header, JWE 930 Per-Recipient Unprotected Header, or JWE AAD values. 932 7.2. JWE JSON Serialization 934 The JWE JSON Serialization represents encrypted content as a JSON 935 object. Content using the JWE JSON Serialization can be encrypted to 936 more than one recipient. This representation is neither optimized 937 for compactness nor URL-safe. 939 The following members are defined for use in top-level JSON objects 940 used for the JWE JSON Serialization: 942 protected 943 The "protected" member MUST be present and contain the value 944 BASE64URL(UTF8(JWE Protected Header)) when the JWE Protected 945 Header value is non-empty; otherwise, it MUST be absent. These 946 Header Parameter values are integrity protected. 948 unprotected 949 The "unprotected" member MUST be present and contain the value JWE 950 Shared Unprotected Header when the JWE Shared Unprotected Header 951 value is non-empty; otherwise, it MUST be absent. This value is 952 represented as an unencoded JSON object, rather than as a string. 953 These Header Parameter values are not integrity protected. 955 iv 956 The "iv" member MUST be present and contain the value 957 BASE64URL(JWE Initialization Vector) when the JWE Initialization 958 Vector value is non-empty; otherwise, it MUST be absent. 960 aad 961 The "aad" member MUST be present and contain the value 962 BASE64URL(JWE AAD)) when the JWE AAD value is non-empty; 963 otherwise, it MUST be absent. A JWE AAD value can be included to 964 supply a base64url encoded value to be integrity protected but not 965 encrypted. 967 ciphertext 968 The "ciphertext" member MUST be present and contain the value 969 BASE64URL(JWE Ciphertext). 971 tag 972 The "tag" member MUST be present and contain the value 973 BASE64URL(JWE Authentication Tag) when the JWE Authentication Tag 974 value is non-empty; otherwise, it MUST be absent. 976 recipients 977 The "recipients" member value MUST be an array of JSON objects. 978 Each object contains information specific to a single recipient. 979 This member MUST be present, even if the array elements contain 980 only the empty JSON object "{}" (which can happen when all Header 981 Parameter values are shared between all recipients and when no 982 encrypted key is used, such as when doing Direct Encryption). 984 The following members are defined for use in the JSON objects that 985 are elements of the "recipients" array: 987 header 988 The "header" member MUST be present and contain the value JWE Per- 989 Recipient Unprotected Header when the JWE Per-Recipient 990 Unprotected Header value is non-empty; otherwise, it MUST be 991 absent. This value is represented as an unencoded JSON object, 992 rather than as a string. These Header Parameter values are not 993 integrity protected. 995 encrypted_key 996 The "encrypted_key" member MUST be present and contain the value 997 BASE64URL(JWE Encrypted Key) when the JWE Encrypted Key value is 998 non-empty; otherwise, it MUST be absent. 1000 At least one of the "header", "protected", and "unprotected" members 1001 MUST be present so that "alg" and "enc" Header Parameter values are 1002 conveyed for each recipient computation. 1004 Additional members can be present in both the JSON objects defined 1005 above; if not understood by implementations encountering them, they 1006 MUST be ignored. 1008 Some Header Parameters, including the "alg" parameter, can be shared 1009 among all recipient computations. Header Parameters in the JWE 1010 Protected Header and JWE Shared Unprotected Header values are shared 1011 among all recipients. 1013 The Header Parameter values used when creating or validating per- 1014 recipient Ciphertext and Authentication Tag values are the union of 1015 the three sets of Header Parameter values that may be present: (1) 1016 the JWE Protected Header represented in the "protected" member, (2) 1017 the JWE Shared Unprotected Header represented in the "unprotected" 1018 member, and (3) the JWE Per-Recipient Unprotected Header represented 1019 in the "header" member of the recipient's array element. The union 1020 of these sets of Header Parameters comprises the JWE Header. The 1021 Header Parameter names in the three locations MUST be disjoint. 1023 Each JWE Encrypted Key value is computed using the parameters of the 1024 corresponding JWE Header value in the same manner as for the JWE 1025 Compact Serialization. This has the desirable property that each JWE 1026 Encrypted Key value in the "recipients" array is identical to the 1027 value that would have been computed for the same parameter in the JWE 1028 Compact Serialization. Likewise, the JWE Ciphertext and JWE 1029 Authentication Tag values match those produced for the JWE Compact 1030 Serialization, provided that the JWE Protected Header value (which 1031 represents the integrity-protected Header Parameter values) matches 1032 that used in the JWE Compact Serialization. 1034 All recipients use the same JWE Protected Header, JWE Initialization 1035 Vector, JWE Ciphertext, and JWE Authentication Tag values, when 1036 present, resulting in potentially significant space savings if the 1037 message is large. Therefore, all Header Parameters that specify the 1038 treatment of the Plaintext value MUST be the same for all recipients. 1039 This primarily means that the "enc" (encryption algorithm) Header 1040 Parameter value in the JWE Header for each recipient and any 1041 parameters of that algorithm MUST be the same. 1043 In summary, the syntax of a JWE using the JWE JSON Serialization is 1044 as follows: 1046 {"protected":"", 1047 "unprotected":, 1048 "recipients":[ 1049 {"header":, 1050 "encrypted_key":""}, 1051 ... 1052 {"header":, 1053 "encrypted_key":""}], 1054 "aad":"", 1055 "iv":"", 1056 "ciphertext":"", 1057 "tag":"" 1058 } 1060 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1061 Serialization. 1063 8. TLS Requirements 1065 The TLS requirements for this specification are the same as those 1066 defined in Section 8 of [JWS]. 1068 9. Distinguishing between JWS and JWE Objects 1070 There are several ways of distinguishing whether an object is a JWS 1071 or JWE object. All these methods will yield the same result for all 1072 legal input values; they may yield different results for malformed 1073 inputs. 1075 o If the object is using the JWS Compact Serialization or the JWE 1076 Compact Serialization, the number of base64url encoded segments 1077 separated by period ('.') characters differs for JWSs and JWEs. 1078 JWSs have three segments separated by two period ('.') characters. 1079 JWEs have five segments separated by four period ('.') characters. 1081 o If the object is using the JWS JSON Serialization or the JWE JSON 1082 Serialization, the members used will be different. JWSs have a 1083 "signatures" member and JWEs do not. JWEs have a "recipients" 1084 member and JWSs do not. 1086 o A JWS Header can be distinguished from a JWE header by examining 1087 the "alg" (algorithm) Header Parameter value. If the value 1088 represents a digital signature or MAC algorithm, or is the value 1089 "none", it is for a JWS; if it represents a Key Encryption, Key 1090 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 1091 or Direct Encryption algorithm, it is for a JWE. (Extracting the 1092 "alg" value to examine is straightforward when using the JWS 1093 Compact Serialization or the JWE Compact Serialization and may be 1094 more difficult when using the JWS JSON Serialization or the JWE 1095 JSON Serialization.) 1097 o A JWS Header can also be distinguished from a JWE header by 1098 determining whether an "enc" (encryption algorithm) member exists. 1099 If the "enc" member exists, it is a JWE; otherwise, it is a JWS. 1101 10. IANA Considerations 1103 10.1. JSON Web Signature and Encryption Header Parameters Registration 1105 This specification registers the Header Parameter names defined in 1106 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1107 Parameters registry defined in [JWS]. 1109 10.1.1. Registry Contents 1111 o Header Parameter Name: "alg" 1112 o Header Parameter Description: Algorithm 1113 o Header Parameter Usage Location(s): JWE 1114 o Change Controller: IESG 1115 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1117 o Header Parameter Name: "enc" 1118 o Header Parameter Description: Encryption Algorithm 1119 o Header Parameter Usage Location(s): JWE 1120 o Change Controller: IESG 1121 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1123 o Header Parameter Name: "zip" 1124 o Header Parameter Description: Compression Algorithm 1125 o Header Parameter Usage Location(s): JWE 1126 o Change Controller: IESG 1127 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1129 o Header Parameter Name: "jku" 1130 o Header Parameter Description: JWK Set URL 1131 o Header Parameter Usage Location(s): JWE 1132 o Change Controller: IESG 1133 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1135 o Header Parameter Name: "jwk" 1136 o Header Parameter Description: JSON Web Key 1137 o Header Parameter Usage Location(s): JWE 1138 o Change Controller: IESG 1139 o Specification document(s): Section 4.1.5 of [[ this document ]] 1141 o Header Parameter Name: "kid" 1142 o Header Parameter Description: Key ID 1143 o Header Parameter Usage Location(s): JWE 1144 o Change Controller: IESG 1145 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1147 o Header Parameter Name: "x5u" 1148 o Header Parameter Description: X.509 URL 1149 o Header Parameter Usage Location(s): JWE 1150 o Change Controller: IESG 1151 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1153 o Header Parameter Name: "x5c" 1154 o Header Parameter Description: X.509 Certificate Chain 1155 o Header Parameter Usage Location(s): JWE 1156 o Change Controller: IESG 1157 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1159 o Header Parameter Name: "x5t" 1160 o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint 1161 o Header Parameter Usage Location(s): JWE 1162 o Change Controller: IESG 1163 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1165 o Header Parameter Name: "typ" 1166 o Header Parameter Description: Type 1167 o Header Parameter Usage Location(s): JWE 1168 o Change Controller: IESG 1169 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1171 o Header Parameter Name: "cty" 1172 o Header Parameter Description: Content Type 1173 o Header Parameter Usage Location(s): JWE 1174 o Change Controller: IESG 1175 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1177 o Header Parameter Name: "crit" 1178 o Header Parameter Description: Critical 1179 o Header Parameter Usage Location(s): JWE 1180 o Change Controller: IESG 1181 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1183 11. Security Considerations 1185 All of the security issues faced by any cryptographic application 1186 must be faced by a JWS/JWE/JWK agent. Among these issues are 1187 protecting the user's private and symmetric keys, preventing various 1188 attacks, and helping the user avoid mistakes such as inadvertently 1189 encrypting a message for the wrong recipient. The entire list of 1190 security considerations is beyond the scope of this document. 1192 All the security considerations in the JWS specification also apply 1193 to this specification. Likewise, all the security considerations in 1194 XML Encryption 1.1 [W3C.CR-xmlenc-core1-20120313] also apply, other 1195 than those that are XML specific. 1197 When decrypting, particular care must be taken not to allow the JWE 1198 recipient to be used as an oracle for decrypting messages. RFC 3218 1199 [RFC3218] should be consulted for specific countermeasures to attacks 1200 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1201 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1202 formatting error that can be detected and used to recover the CEK 1203 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1204 particularly important to report all formatting errors to the CEK, 1205 Additional Authenticated Data, or ciphertext as a single error when 1206 the encrypted content is rejected. 1208 Additionally, this type of attack can be prevented by the use of "key 1209 tainting". This method restricts the use of a key to a limited set 1210 of algorithms -- usually one. This means, for instance, that if the 1211 key is marked as being for "RSA-OAEP" only, any attempt to decrypt a 1212 message using the "RSA1_5" algorithm with that key would fail 1213 immediately due to invalid use of the key. 1215 12. References 1216 12.1. Normative References 1218 [ECMAScript] 1219 Ecma International, "ECMAScript Language Specification, 1220 5.1 Edition", ECMA 262, June 2011. 1222 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1223 draft-ietf-jose-json-web-algorithms (work in progress), 1224 March 2014. 1226 [JWK] Jones, M., "JSON Web Key (JWK)", 1227 draft-ietf-jose-json-web-key (work in progress), 1228 March 2014. 1230 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1231 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1232 in progress), March 2014. 1234 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1235 version 1.3", RFC 1951, May 1996. 1237 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1238 Requirement Levels", BCP 14, RFC 2119, March 1997. 1240 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1241 10646", STD 63, RFC 3629, November 2003. 1243 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1244 Housley, R., and W. Polk, "Internet X.509 Public Key 1245 Infrastructure Certificate and Certificate Revocation List 1246 (CRL) Profile", RFC 5280, May 2008. 1248 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1249 Interchange Format", RFC 7159, March 2014. 1251 [USASCII] American National Standards Institute, "Coded Character 1252 Set -- 7-bit American Standard Code for Information 1253 Interchange", ANSI X3.4, 1986. 1255 12.2. Informative References 1257 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1258 McGrew, D. and K. Paterson, "Authenticated Encryption with 1259 AES-CBC and HMAC-SHA", 1260 draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), 1261 October 2012. 1263 [I-D.rescorla-jsms] 1264 Rescorla, E. and J. Hildebrand, "JavaScript Message 1265 Security Format", draft-rescorla-jsms-00 (work in 1266 progress), March 2011. 1268 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1269 Encryption", September 2010. 1271 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1272 Cryptographic Message Syntax", RFC 3218, January 2002. 1274 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1275 Requirements for Security", BCP 106, RFC 4086, June 2005. 1277 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1278 RFC 5652, September 2009. 1280 [W3C.CR-xmlenc-core1-20120313] 1281 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 1282 "XML Encryption Syntax and Processing Version 1.1", World 1283 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1284 March 2012, 1285 . 1287 Appendix A. JWE Examples 1289 This section provides examples of JWE computations. 1291 A.1. Example JWE using RSAES OAEP and AES GCM 1293 This example encrypts the plaintext "The true sign of intelligence is 1294 not knowledge but imagination." to the recipient using RSAES OAEP for 1295 key encryption and AES GCM for content encryption. The 1296 representation of this plaintext is: 1298 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1299 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1300 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1301 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1302 110, 97, 116, 105, 111, 110, 46] 1304 A.1.1. JWE Header 1306 The following example JWE Protected Header declares that: 1308 o the Content Encryption Key is encrypted to the recipient using the 1309 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1311 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1312 bit key to produce the Ciphertext. 1314 {"alg":"RSA-OAEP","enc":"A256GCM"} 1316 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1317 Header)) gives this value: 1319 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1321 A.1.2. Content Encryption Key (CEK) 1323 Generate a 256 bit random Content Encryption Key (CEK). In this 1324 example, the value is: 1326 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1327 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1328 234, 64, 252] 1330 A.1.3. Key Encryption 1332 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1333 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1334 key represented in JSON Web Key [JWK] format below (with line breaks 1335 for display purposes only): 1337 {"kty":"RSA", 1338 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1339 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1340 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1341 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1342 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1343 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1344 "e":"AQAB", 1345 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1346 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1347 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1348 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1349 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1350 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ" 1351 } 1353 The resulting JWE Encrypted Key value is: 1355 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1356 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1357 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1358 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1359 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1360 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1361 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1362 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1363 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1364 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1365 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1366 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1367 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1368 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1369 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1370 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1371 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1372 117, 114, 135, 206] 1374 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1375 this value (with line breaks for display purposes only): 1377 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1378 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1379 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1380 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1381 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1382 6UklfCpIMfIjf7iGdXKHzg 1384 A.1.4. Initialization Vector 1386 Generate a random 96 bit JWE Initialization Vector. In this example, 1387 the value is: 1389 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1391 Encoding this JWE Initialization Vector as BASE64URL(JWE 1392 Initialization Vector) gives this value: 1394 48V1_ALb6US04U3b 1396 A.1.5. Additional Authenticated Data 1398 Let the Additional Authenticated Data encryption parameter be 1399 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1401 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1402 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1403 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1405 A.1.6. Content Encryption 1407 Encrypt the Plaintext with AES GCM using the CEK as the encryption 1408 key, the JWE Initialization Vector, and the Additional Authenticated 1409 Data value above, requesting a 128 bit Authentication Tag output. 1410 The resulting Ciphertext is: 1412 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1413 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1414 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1415 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1416 160, 109, 64, 63, 192] 1418 The resulting Authentication Tag value is: 1420 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1421 210, 145] 1423 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1424 value (with line breaks for display purposes only): 1426 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1427 SdiwkIr3ajwQzaBtQD_A 1429 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1430 Tag) gives this value: 1432 XFBoMYUZodetZdvTiFvSkQ 1434 A.1.7. Complete Representation 1436 Assemble the final representation: The Compact Serialization of this 1437 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1438 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1439 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1440 Authentication Tag). 1442 The final result in this example (with line breaks for display 1443 purposes only) is: 1445 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1446 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1447 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1448 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1449 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1450 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1451 6UklfCpIMfIjf7iGdXKHzg. 1452 48V1_ALb6US04U3b. 1453 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1454 SdiwkIr3ajwQzaBtQD_A. 1455 XFBoMYUZodetZdvTiFvSkQ 1457 A.1.8. Validation 1459 This example illustrates the process of creating a JWE with RSAES 1460 OAEP for key encryption and AES GCM for content encryption. These 1461 results can be used to validate JWE decryption implementations for 1462 these algorithms. Note that since the RSAES OAEP computation 1463 includes random values, the encryption results above will not be 1464 completely reproducible. However, since the AES GCM computation is 1465 deterministic, the JWE Encrypted Ciphertext values will be the same 1466 for all encryptions performed using these inputs. 1468 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1470 This example encrypts the plaintext "Live long and prosper." to the 1471 recipient using RSAES-PKCS1-V1_5 for key encryption and 1472 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1473 of this plaintext is: 1475 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1476 112, 114, 111, 115, 112, 101, 114, 46] 1478 A.2.1. JWE Header 1480 The following example JWE Protected Header declares that: 1482 o the Content Encryption Key is encrypted to the recipient using the 1483 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1485 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1486 algorithm to produce the Ciphertext. 1488 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1490 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1491 Header)) gives this value: 1493 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1495 A.2.2. Content Encryption Key (CEK) 1497 Generate a 256 bit random Content Encryption Key (CEK). In this 1498 example, the key value is: 1500 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1501 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1502 44, 207] 1504 A.2.3. Key Encryption 1506 Encrypt the CEK with the recipient's public key using the RSAES- 1507 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1508 uses the RSA key represented in JSON Web Key [JWK] format below (with 1509 line breaks for display purposes only): 1511 {"kty":"RSA", 1512 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1513 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1514 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1515 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1516 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1517 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1518 "e":"AQAB", 1519 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1520 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1521 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1522 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1523 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1524 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1525 } 1527 The resulting JWE Encrypted Key value is: 1529 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1530 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1531 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1532 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1533 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1534 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1535 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1536 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1537 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1538 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1539 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1540 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1541 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1542 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1543 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1544 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1545 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1546 146, 114, 165, 204, 71, 136, 41, 252] 1548 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1549 this value (with line breaks for display purposes only): 1551 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1552 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1553 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1554 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1555 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1556 -B3oWh2TbqmScqXMR4gp_A 1558 A.2.4. Initialization Vector 1560 Generate a random 128 bit JWE Initialization Vector. In this 1561 example, the value is: 1563 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1564 101] 1566 Encoding this JWE Initialization Vector as BASE64URL(JWE 1567 Initialization Vector) gives this value: 1569 AxY8DCtDaGlsbGljb3RoZQ 1571 A.2.5. Additional Authenticated Data 1573 Let the Additional Authenticated Data encryption parameter be 1574 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1576 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1577 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1578 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1579 50, 73, 110, 48] 1581 A.2.6. Content Encryption 1583 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1584 the encryption key, the JWE Initialization Vector, and the Additional 1585 Authenticated Data value above. The steps for doing this using the 1586 values from Appendix A.3 are detailed in Appendix B. The resulting 1587 Ciphertext is: 1589 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1590 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1591 112, 56, 102] 1593 The resulting Authentication Tag value is: 1595 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1596 191] 1598 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1599 value: 1601 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1603 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1604 Tag) gives this value: 1606 9hH0vgRfYgPnAHOd8stkvw 1608 A.2.7. Complete Representation 1610 Assemble the final representation: The Compact Serialization of this 1611 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1612 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1613 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1614 Authentication Tag). 1616 The final result in this example (with line breaks for display 1617 purposes only) is: 1619 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1620 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1621 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1622 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1623 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1624 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1625 -B3oWh2TbqmScqXMR4gp_A. 1626 AxY8DCtDaGlsbGljb3RoZQ. 1627 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1628 9hH0vgRfYgPnAHOd8stkvw 1630 A.2.8. Validation 1632 This example illustrates the process of creating a JWE with RSAES- 1633 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1634 encryption. These results can be used to validate JWE decryption 1635 implementations for these algorithms. Note that since the RSAES- 1636 PKCS1-V1_5 computation includes random values, the encryption results 1637 above will not be completely reproducible. However, since the AES 1638 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1639 will be the same for all encryptions performed using these inputs. 1641 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1643 This example encrypts the plaintext "Live long and prosper." to the 1644 recipient using AES Key Wrap for key encryption and 1645 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1646 of this plaintext is: 1648 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1649 112, 114, 111, 115, 112, 101, 114, 46] 1651 A.3.1. JWE Header 1653 The following example JWE Protected Header declares that: 1655 o the Content Encryption Key is encrypted to the recipient using the 1656 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1657 Encrypted Key and 1659 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1660 algorithm to produce the Ciphertext. 1662 {"alg":"A128KW","enc":"A128CBC-HS256"} 1664 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1665 Header)) gives this value: 1667 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1669 A.3.2. Content Encryption Key (CEK) 1671 Generate a 256 bit random Content Encryption Key (CEK). In this 1672 example, the value is: 1674 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1675 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1676 44, 207] 1678 A.3.3. Key Encryption 1680 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1681 algorithm to produce the JWE Encrypted Key. This example uses the 1682 symmetric key represented in JSON Web Key [JWK] format below: 1684 {"kty":"oct", 1685 "k":"GawgguFyGrWKav7AX4VKUg" 1686 } 1688 The resulting JWE Encrypted Key value is: 1690 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1691 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1692 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1694 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1695 this value: 1697 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1699 A.3.4. Initialization Vector 1701 Generate a random 128 bit JWE Initialization Vector. In this 1702 example, the value is: 1704 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1705 101] 1707 Encoding this JWE Initialization Vector as BASE64URL(JWE 1708 Initialization Vector) gives this value: 1710 AxY8DCtDaGlsbGljb3RoZQ 1712 A.3.5. Additional Authenticated Data 1714 Let the Additional Authenticated Data encryption parameter be 1715 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1717 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1718 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1719 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1720 110, 48] 1722 A.3.6. Content Encryption 1724 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1725 the encryption key, the JWE Initialization Vector, and the Additional 1726 Authenticated Data value above. The steps for doing this using the 1727 values from this example are detailed in Appendix B. The resulting 1728 Ciphertext is: 1730 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1731 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1732 112, 56, 102] 1734 The resulting Authentication Tag value is: 1736 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1737 194, 85] 1739 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1740 value: 1742 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1744 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1745 Tag) gives this value: 1747 U0m_YmjN04DJvceFICbCVQ 1749 A.3.7. Complete Representation 1751 Assemble the final representation: The Compact Serialization of this 1752 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1753 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1754 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1755 Authentication Tag). 1757 The final result in this example (with line breaks for display 1758 purposes only) is: 1760 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1761 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1762 AxY8DCtDaGlsbGljb3RoZQ. 1763 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1764 U0m_YmjN04DJvceFICbCVQ 1766 A.3.8. Validation 1768 This example illustrates the process of creating a JWE with AES Key 1769 Wrap for key encryption and AES GCM for content encryption. These 1770 results can be used to validate JWE decryption implementations for 1771 these algorithms. Also, since both the AES Key Wrap and AES GCM 1772 computations are deterministic, the resulting JWE value will be the 1773 same for all encryptions performed using these inputs. Since the 1774 computation is reproducible, these results can also be used to 1775 validate JWE encryption implementations for these algorithms. 1777 A.4. Example JWE using JWE JSON Serialization 1779 This section contains an example using the JWE JSON Serialization. 1780 This example demonstrates the capability for encrypting the same 1781 plaintext to multiple recipients. 1783 Two recipients are present in this example. The algorithm and key 1784 used for the first recipient are the same as that used in 1785 Appendix A.2. The algorithm and key used for the second recipient 1786 are the same as that used in Appendix A.3. The resulting JWE 1787 Encrypted Key values are therefore the same; those computations are 1788 not repeated here. 1790 The Plaintext, the Content Encryption Key (CEK), Initialization 1791 Vector, and JWE Protected Header are shared by all recipients (which 1792 must be the case, since the Ciphertext and Authentication Tag are 1793 also shared). 1795 A.4.1. JWE Per-Recipient Unprotected Headers 1797 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1798 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1799 encrypt the CEK. Key ID values are supplied for both keys. The two 1800 per-recipient header values used to represent these algorithms and 1801 Key IDs are: 1803 {"alg":"RSA1_5","kid":"2011-04-29"} 1805 and 1807 {"alg":"A128KW","kid":"7"} 1809 A.4.2. JWE Protected Header 1811 The Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1812 algorithm to produce the common JWE Ciphertext and JWE Authentication 1813 Tag values. The JWE Protected Header value representing this is: 1815 {"enc":"A128CBC-HS256"} 1817 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1818 Header)) gives this value: 1820 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1822 A.4.3. JWE Unprotected Header 1824 This JWE uses the "jku" Header Parameter to reference a JWK Set. This 1825 is represented in the following JWE Unprotected Header value as: 1827 {"jku":"https://server.example.com/keys.jwks"} 1829 A.4.4. Complete JWE Header Values 1831 Combining the per-recipient, protected, and unprotected header values 1832 supplied, the JWE Header values used for the first and second 1833 recipient respectively are: 1835 {"alg":"RSA1_5", 1836 "kid":"2011-04-29", 1837 "enc":"A128CBC-HS256", 1838 "jku":"https://server.example.com/keys.jwks"} 1840 and 1842 {"alg":"A128KW", 1843 "kid":"7", 1844 "enc":"A128CBC-HS256", 1845 "jku":"https://server.example.com/keys.jwks"} 1847 A.4.5. Additional Authenticated Data 1849 Let the Additional Authenticated Data encryption parameter be 1850 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1852 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1853 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1855 A.4.6. Content Encryption 1857 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1858 the encryption key, the JWE Initialization Vector, and the Additional 1859 Authenticated Data value above. The steps for doing this using the 1860 values from Appendix A.3 are detailed in Appendix B. The resulting 1861 Ciphertext is: 1863 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1864 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1865 112, 56, 102] 1867 The resulting Authentication Tag value is: 1869 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1870 207] 1872 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1873 value: 1875 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1877 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1878 Tag) gives this value: 1880 Mz-VPPyU4RlcuYv1IwIvzw 1882 A.4.7. Complete JWE JSON Serialization Representation 1884 The complete JSON Web Encryption JSON Serialization for these values 1885 is as follows (with line breaks for display purposes only): 1887 {"protected": 1888 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1889 "unprotected": 1890 {"jku":"https://server.example.com/keys.jwks"}, 1891 "recipients":[ 1892 {"header": 1893 {"alg":"RSA1_5","kid":"2011-04-29"}, 1894 "encrypted_key": 1895 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1896 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1897 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 1898 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 1899 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 1900 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 1901 {"header": 1902 {"alg":"A128KW","kid":"7"}, 1903 "encrypted_key": 1904 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1905 "iv": 1906 "AxY8DCtDaGlsbGljb3RoZQ", 1907 "ciphertext": 1908 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1909 "tag": 1910 "Mz-VPPyU4RlcuYv1IwIvzw" 1911 } 1913 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 1915 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 1916 authenticated encryption computation using the values from the 1917 example in Appendix A.3. As described where this algorithm is 1918 defined in Sections 5.2 and 5.2.3 of JWA, the AES_CBC_HMAC_SHA2 1919 family of algorithms are implemented using Advanced Encryption 1920 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #5 1921 padding to perform the encryption and an HMAC SHA-2 function to 1922 perform the integrity calculation - in this case, HMAC SHA-256. 1924 B.1. Extract MAC_KEY and ENC_KEY from Key 1926 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example is: 1928 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1929 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1930 44, 207] 1932 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 1933 which is: 1935 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1936 206] 1938 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 1939 is: 1941 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 1942 207] 1944 Note that the MAC key comes before the encryption key in the input 1945 key K; this is in the opposite order of the algorithm names in the 1946 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 1948 B.2. Encrypt Plaintext to Create Ciphertext 1950 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 1951 using PKCS #5 padding using the ENC_KEY above. The Plaintext in this 1952 example is: 1954 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1955 112, 114, 111, 115, 112, 101, 114, 46] 1957 The encryption result is as follows, which is the Ciphertext output: 1959 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1960 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1961 112, 56, 102] 1963 B.3. 64 Bit Big Endian Representation of AAD Length 1965 The Additional Authenticated Data (AAD) in this example is: 1967 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1968 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1969 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1970 110, 48] 1972 This AAD is 51 bytes long, which is 408 bits long. The octet string 1973 AL, which is the number of bits in AAD expressed as a big endian 64 1974 bit unsigned integer is: 1976 [0, 0, 0, 0, 0, 0, 1, 152] 1978 B.4. Initialization Vector Value 1980 The Initialization Vector value used in this example is: 1982 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1983 101] 1985 B.5. Create Input to HMAC Computation 1987 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 1988 the AL value. The result of this concatenation is: 1990 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1991 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1992 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1993 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 1994 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 1995 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 1996 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 1998 B.6. Compute HMAC Value 2000 Compute the HMAC SHA-256 of the concatenated value above. This 2001 result M is: 2003 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2004 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 2005 86, 229, 116] 2007 B.7. Truncate HMAC Value to Create Authentication Tag 2009 Use the first half (128 bits) of the HMAC output M as the 2010 Authentication Tag output T. This truncated value is: 2012 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2013 194, 85] 2015 Appendix C. Acknowledgements 2017 Solutions for encrypting JSON content were also explored by JSON 2018 Simple Encryption [JSE] and JavaScript Message Security Format 2019 [I-D.rescorla-jsms], both of which significantly influenced this 2020 draft. This draft attempts to explicitly reuse as many of the 2021 relevant concepts from XML Encryption 1.1 2022 [W3C.CR-xmlenc-core1-20120313] and RFC 5652 [RFC5652] as possible, 2023 while utilizing simple, compact JSON-based data structures. 2025 Special thanks are due to John Bradley, Eric Rescorla, and Nat 2026 Sakimura for the discussions that helped inform the content of this 2027 specification, to Eric Rescorla and Joe Hildebrand for allowing the 2028 reuse of text from [I-D.rescorla-jsms] in this document, and to Eric 2029 Rescorla for co-authoring many drafts of this specification. 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, Hideki Nara, Axel Nennker, Emmanuel Raviart, Eric Rescorla, 2042 Nat Sakimura, Jim Schaad, 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 -25 2054 o Corrected two external section number references that had changed. 2056 o Corrected a typo in an algorithm name in the prose of an example. 2058 -24 2060 o Corrected complete JSON Serialization example. 2062 o Replaced uses of the term "associated data" wherever it was used 2063 to refer to a data value with "additional authenticated data", 2064 since both terms were being used as synonyms, causing confusion. 2066 o Updated the JSON reference to RFC 7159. 2068 o Thanked Eric Rescorla for helping to author of most of the drafts 2069 of this specification and removed him from the current author 2070 list. 2072 -23 2074 o Corrected a use of the word "payload" to "plaintext". 2076 -22 2078 o Corrected RFC 2119 terminology usage. 2080 o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. 2082 -21 2084 o Changed some references from being normative to informative, 2085 addressing issue #90. 2087 o Applied review comments to the JSON Serialization section, 2088 addressing issue #178. 2090 -20 2092 o Made terminology definitions more consistent, addressing issue 2093 #165. 2095 o Restructured the JSON Serialization section to call out the 2096 parameters used in hanging lists, addressing issue #178. 2098 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 2099 addressing issue #90. 2101 -19 2103 o Reordered the key selection parameters. 2105 -18 2106 o Updated the mandatory-to-implement (MTI) language to say that 2107 applications using this specification need to specify what 2108 serialization and serialization features are used for that 2109 application, addressing issue #176. 2111 o Changes to address editorial and minor issues #89, #135, #165, 2112 #174, #175, #177, #179, and #180. 2114 o Used Header Parameter Description registry field. 2116 -17 2118 o Refined the "typ" and "cty" definitions to always be MIME Media 2119 Types, with the omission of "application/" prefixes recommended 2120 for brevity, addressing issue #50. 2122 o Updated the mandatory-to-implement (MTI) language to say that 2123 general-purpose implementations must implement the single 2124 recipient case for both serializations whereas special-purpose 2125 implementations can implement just one serialization if that meets 2126 the needs of the use cases the implementation is designed for, 2127 addressing issue #176. 2129 o Explicitly named all the logical components of a JWE and defined 2130 the processing rules and serializations in terms of those 2131 components, addressing issues #60, #61, and #62. 2133 o Replaced verbose repetitive phases such as "base64url encode the 2134 octets of the UTF-8 representation of X" with mathematical 2135 notation such as "BASE64URL(UTF8(X))". 2137 o Header Parameters and processing rules occurring in both JWS and 2138 JWE are now referenced in JWS by JWE, rather than duplicated, 2139 addressing issue #57. 2141 o Terms used in multiple documents are now defined in one place and 2142 incorporated by reference. Some lightly used or obvious terms 2143 were also removed. This addresses issue #58. 2145 -16 2147 o Changes to address editorial and minor issues #163, #168, #169, 2148 #170, #172, and #173. 2150 -15 2152 o Clarified that it is an application decision which recipients' 2153 encrypted content must successfully validate for the JWE to be 2154 accepted, addressing issue #35. 2156 o Changes to address editorial issues #34, #164, and #169. 2158 -14 2160 o Clarified that the "protected", "unprotected", "header", "iv", 2161 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2162 JSON Serialization when their values would be empty. Stated that 2163 the "recipients" array must always be present. 2165 -13 2167 o Added an "aad" (Additional Authenticated Data) member for the JWE 2168 JSON Serialization, enabling Additional Authenticated Data to be 2169 supplied that is not double base64url encoded, addressing issue 2170 #29. 2172 -12 2174 o Clarified that the "typ" and "cty" header parameters are used in 2175 an application-specific manner and have no effect upon the JWE 2176 processing. 2178 o Replaced the MIME types "application/jwe+json" and 2179 "application/jwe" with "application/jose+json" and 2180 "application/jose". 2182 o Stated that recipients MUST either reject JWEs with duplicate 2183 Header Parameter Names or use a JSON parser that returns only the 2184 lexically last duplicate member name. 2186 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2187 be with the algorithm descriptions that use them. 2189 o Added a Serializations section with parallel treatment of the JWE 2190 Compact Serialization and the JWE JSON Serialization and also 2191 moved the former Implementation Considerations content there. 2193 o Restored use of the term "AEAD". 2195 o Changed terminology from "block encryption" to "content 2196 encryption". 2198 -11 2200 o Added Key Identification section. 2202 o Removed the Encrypted Key value from the AAD computation since it 2203 is already effectively integrity protected by the encryption 2204 process. The AAD value now only contains the representation of 2205 the JWE Encrypted Header. 2207 o For the JWE JSON Serialization, enable Header Parameter values to 2208 be specified in any of three parameters: the "protected" member 2209 that is integrity protected and shared among all recipients, the 2210 "unprotected" member that is not integrity protected and shared 2211 among all recipients, and the "header" member that is not 2212 integrity protected and specific to a particular recipient. (This 2213 does not affect the JWE Compact Serialization, in which all Header 2214 Parameter values are in a single integrity protected JWE Header 2215 value.) 2217 o Shortened the names "authentication_tag" to "tag" and 2218 "initialization_vector" to "iv" in the JWE JSON Serialization, 2219 addressing issue #20. 2221 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2223 o Removed suggested compact serialization for multiple recipients. 2225 o Changed the MIME type name "application/jwe-js" to 2226 "application/jwe+json", addressing issue #22. 2228 o Tightened the description of the "crit" (critical) header 2229 parameter. 2231 -10 2233 o Changed the JWE processing rules for multiple recipients so that a 2234 single AAD value contains the header parameters and encrypted key 2235 values for all the recipients, enabling AES GCM to be safely used 2236 for multiple recipients. 2238 o Added an appendix suggesting a possible compact serialization for 2239 JWEs with multiple recipients. 2241 -09 2243 o Added JWE JSON Serialization, as specified by 2244 draft-jones-jose-jwe-json-serialization-04. 2246 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2247 parameter value. 2249 o Defined that the default action for header parameters that are not 2250 understood is to ignore them unless specifically designated as 2251 "MUST be understood" or included in the new "crit" (critical) 2252 header parameter list. This addressed issue #6. 2254 o Corrected "x5c" description. This addressed issue #12. 2256 o Changed from using the term "byte" to "octet" when referring to 8 2257 bit values. 2259 o Added Key Management Mode definitions to terminology section and 2260 used the defined terms to provide clearer key management 2261 instructions. This addressed issue #5. 2263 o Added text about preventing the recipient from behaving as an 2264 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2266 o Changed from using the term "Integrity Value" to "Authentication 2267 Tag". 2269 o Changed member name from "integrity_value" to "authentication_tag" 2270 in the JWE JSON Serialization. 2272 o Removed Initialization Vector from the AAD value since it is 2273 already integrity protected by all of the authenticated encryption 2274 algorithms specified in the JWA specification. 2276 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2277 and "A256CBC-HS512". The new algorithms perform the same 2278 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2279 but with the Initialization Vector and Authentication Tag values 2280 remaining separate from the Ciphertext value in the output 2281 representation. Also deleted the header parameters "epu" 2282 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2283 they are no longer used. 2285 -08 2287 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2288 since the term AEAD in the RFC 5116 sense implied the use of a 2289 particular data representation, rather than just referring to the 2290 class of algorithms that perform authenticated encryption with 2291 associated data. 2293 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2294 Tschofenig. Many of these simplified the terminology used. 2296 o Clarified statements of the form "This header parameter is 2297 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2299 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2300 Web Signature and Encryption Header Parameters registry. 2302 o Added seriesInfo information to Internet Draft references. 2304 -07 2306 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2308 o Updated values for example AES CBC calculations. 2310 o Made several local editorial changes to clean up loose ends left 2311 over from to the decision to only support block encryption methods 2312 providing integrity. One of these changes was to explicitly state 2313 that the "enc" (encryption method) algorithm must be an 2314 Authenticated Encryption algorithm with a specified key length. 2316 -06 2318 o Removed the "int" and "kdf" parameters and defined the new 2319 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2320 "A256CBC+HS512" to replace the former uses of AES CBC, which 2321 required the use of separate integrity and key derivation 2322 functions. 2324 o Included additional values in the Concat KDF calculation -- the 2325 desired output size and the algorithm value, and optionally 2326 PartyUInfo and PartyVInfo values. Added the optional header 2327 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2328 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2329 PartyVInfo). Updated the KDF examples accordingly. 2331 o Promoted Initialization Vector from being a header parameter to 2332 being a top-level JWE element. This saves approximately 16 bytes 2333 in the compact serialization, which is a significant savings for 2334 some use cases. Promoting the Initialization Vector out of the 2335 header also avoids repeating this shared value in the JSON 2336 serialization. 2338 o Changed "x5c" (X.509 Certificate Chain) representation from being 2339 a single string to being an array of strings, each containing a 2340 single base64 encoded DER certificate value, representing elements 2341 of the certificate chain. 2343 o Added an AES Key Wrap example. 2345 o Reordered the encryption steps so CMK creation is first, when 2346 required. 2348 o Correct statements in examples about which algorithms produce 2349 reproducible results. 2351 -05 2353 o Support both direct encryption using a shared or agreed upon 2354 symmetric key, and the use of a shared or agreed upon symmetric 2355 key to key wrap the CMK. 2357 o Added statement that "StringOrURI values are compared as case- 2358 sensitive strings with no transformations or canonicalizations 2359 applied". 2361 o Updated open issues. 2363 o Indented artwork elements to better distinguish them from the body 2364 text. 2366 -04 2368 o Refer to the registries as the primary sources of defined values 2369 and then secondarily reference the sections defining the initial 2370 contents of the registries. 2372 o Normatively reference XML Encryption 1.1 2373 [W3C.CR-xmlenc-core1-20120313] for its security considerations. 2375 o Reference draft-jones-jose-jwe-json-serialization instead of 2376 draft-jones-json-web-encryption-json-serialization. 2378 o Described additional open issues. 2380 o Applied editorial suggestions. 2382 -03 2384 o Added the "kdf" (key derivation function) header parameter to 2385 provide crypto agility for key derivation. The default KDF 2386 remains the Concat KDF with the SHA-256 digest function. 2388 o Reordered encryption steps so that the Encoded JWE Header is 2389 always created before it is needed as an input to the 2390 Authenticated Encryption "additional authenticated data" 2391 parameter. 2393 o Added the "cty" (content type) header parameter for declaring type 2394 information about the secured content, as opposed to the "typ" 2395 (type) header parameter, which declares type information about 2396 this object. 2398 o Moved description of how to determine whether a header is for a 2399 JWS or a JWE from the JWT spec to the JWE spec. 2401 o Added complete encryption examples for both Authenticated 2402 Encryption and non-Authenticated Encryption algorithms. 2404 o Added complete key derivation examples. 2406 o Added "Collision Resistant Namespace" to the terminology section. 2408 o Reference ITU.X690.1994 for DER encoding. 2410 o Added Registry Contents sections to populate registry values. 2412 o Numerous editorial improvements. 2414 -02 2416 o When using Authenticated Encryption algorithms (such as AES GCM), 2417 use the "additional authenticated data" parameter to provide 2418 integrity for the header, encrypted key, and ciphertext and use 2419 the resulting "authentication tag" value as the JWE Authentication 2420 Tag. 2422 o Defined KDF output key sizes. 2424 o Generalized text to allow key agreement to be employed as an 2425 alternative to key wrapping or key encryption. 2427 o Changed compression algorithm from gzip to DEFLATE. 2429 o Clarified that it is an error when a "kid" value is included and 2430 no matching key is found. 2432 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2433 rejected. 2435 o Clarified the relationship between "typ" header parameter values 2436 and MIME types. 2438 o Registered application/jwe MIME type and "JWE" typ header 2439 parameter value. 2441 o Simplified JWK terminology to get replace the "JWK Key Object" and 2442 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2443 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2444 between single keys and sets of keys. As part of this change, the 2445 Header Parameter Name for a public key value was changed from 2446 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2448 o Added suggestion on defining additional header parameters such as 2449 "x5t#S256" in the future for certificate thumbprints using hash 2450 algorithms other than SHA-1. 2452 o Specify RFC 2818 server identity validation, rather than RFC 6125 2453 (paralleling the same decision in the OAuth specs). 2455 o Generalized language to refer to Message Authentication Codes 2456 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2457 unless in a context specific to HMAC algorithms. 2459 o Reformatted to give each header parameter its own section heading. 2461 -01 2463 o Added an integrity check for non-Authenticated Encryption 2464 algorithms. 2466 o Added "jpk" and "x5c" header parameters for including JWK public 2467 keys and X.509 certificate chains directly in the header. 2469 o Clarified that this specification is defining the JWE Compact 2470 Serialization. Referenced the new JWE-JS spec, which defines the 2471 JWE JSON Serialization. 2473 o Added text "New header parameters should be introduced sparingly 2474 since an implementation that does not understand a parameter MUST 2475 reject the JWE". 2477 o Clarified that the order of the encryption and decryption steps is 2478 not significant in cases where there are no dependencies between 2479 the inputs and outputs of the steps. 2481 o Made other editorial improvements suggested by JOSE working group 2482 participants. 2484 -00 2485 o Created the initial IETF draft based upon 2486 draft-jones-json-web-encryption-02 with no normative changes. 2488 o Changed terminology to no longer call both digital signatures and 2489 HMACs "signatures". 2491 Authors' Addresses 2493 Michael B. Jones 2494 Microsoft 2496 Email: mbj@microsoft.com 2497 URI: http://self-issued.info/ 2499 Joe Hildebrand 2500 Cisco Systems, Inc. 2502 Email: jhildebr@cisco.com