idnits 2.17.1 draft-ietf-jose-json-web-encryption-17.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 7, 2013) is 3847 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 1326 -- Looks like a reference, but probably isn't: '197' on line 1326 -- Looks like a reference, but probably isn't: '117' on line 1326 -- Looks like a reference, but probably isn't: '252' on line 1326 -- Looks like a reference, but probably isn't: '2' on line 1326 -- Looks like a reference, but probably isn't: '219' on line 1326 -- Looks like a reference, but probably isn't: '233' on line 1326 -- Looks like a reference, but probably isn't: '68' on line 1326 -- Looks like a reference, but probably isn't: '180' on line 1326 -- Looks like a reference, but probably isn't: '225' on line 1326 -- Looks like a reference, but probably isn't: '77' on line 1326 -- Looks like a reference, but probably isn't: '0' on line 1911 -- Looks like a reference, but probably isn't: '1' on line 1911 -- Looks like a reference, but probably isn't: '152' on line 1911 -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMAScript' ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' == Outdated reference: A later version (-05) exists of draft-mcgrew-aead-aes-cbc-hmac-sha2-01 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 18 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track E. Rescorla 5 Expires: April 10, 2014 RTFM 6 J. Hildebrand 7 Cisco 8 October 7, 2013 10 JSON Web Encryption (JWE) 11 draft-ietf-jose-json-web-encryption-17 13 Abstract 15 JSON Web Encryption (JWE) represents encrypted content using 16 JavaScript Object Notation (JSON) based data structures. 17 Cryptographic algorithms and identifiers for use with this 18 specification are described in the separate JSON Web Algorithms (JWA) 19 specification and IANA registries defined by that specification. 20 Related digital signature and MAC capabilities are described in the 21 separate JSON Web Signature (JWS) specification. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on April 10, 2014. 40 Copyright Notice 42 Copyright (c) 2013 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 7 61 3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 9 62 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11 63 4.1. Registered Header Parameter Names . . . . . . . . . . . . 11 64 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 11 65 4.1.2. "enc" (Encryption Method) Header Parameter . . . . . . 12 66 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 12 67 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 12 68 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 13 69 4.1.6. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 13 70 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 71 Parameter . . . . . . . . . . . . . . . . . . . . . . 13 72 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 13 73 4.1.9. "kid" (Key ID) Header Parameter . . . . . . . . . . . 13 74 4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 13 75 4.1.11. "cty" (Content Type) Header Parameter . . . . . . . . 14 76 4.1.12. "crit" (Critical) Header Parameter . . . . . . . . . . 14 77 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 14 78 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 14 79 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 14 80 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 14 81 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 16 82 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 19 83 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 19 84 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 19 85 7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 19 86 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 19 87 8. Distinguishing Between JWS and JWE Objects . . . . . . . . . . 22 88 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 89 9.1. JWE Header Parameter Names Registration . . . . . . . . . 23 90 9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 23 91 10. Security Considerations . . . . . . . . . . . . . . . . . . . 25 92 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 93 11.1. Normative References . . . . . . . . . . . . . . . . . . . 25 94 11.2. Informative References . . . . . . . . . . . . . . . . . . 26 95 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 27 96 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 27 97 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 27 98 A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 27 99 A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 28 100 A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 29 101 A.1.5. Additional Authenticated Data . . . . . . . . . . . . 29 102 A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 29 103 A.1.7. Complete Representation . . . . . . . . . . . . . . . 30 104 A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 30 105 A.2. Example JWE using RSAES-PKCS1-V1_5 and 106 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 30 107 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 31 108 A.2.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 31 109 A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 31 110 A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 33 111 A.2.5. Additional Authenticated Data . . . . . . . . . . . . 33 112 A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 33 113 A.2.7. Complete Representation . . . . . . . . . . . . . . . 34 114 A.2.8. Validation . . . . . . . . . . . . . . . . . . . . . . 34 115 A.3. Example JWE using AES Key Wrap and 116 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 34 117 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 34 118 A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 35 119 A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 35 120 A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 36 121 A.3.5. Additional Authenticated Data . . . . . . . . . . . . 36 122 A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 36 123 A.3.7. Complete Representation . . . . . . . . . . . . . . . 37 124 A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 37 125 A.4. Example JWE using JWE JSON Serialization . . . . . . . . . 37 126 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 38 127 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 38 128 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 38 129 A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 38 130 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 39 131 A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 39 132 A.4.7. Complete JWE JSON Serialization Representation . . . . 39 133 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 40 134 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 40 135 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 41 136 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 41 137 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 41 138 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 42 139 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 42 140 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 42 141 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 42 142 Appendix D. Document History . . . . . . . . . . . . . . . . . . 43 143 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 51 145 1. Introduction 147 JSON Web Encryption (JWE) represents encrypted content using 148 JavaScript Object Notation (JSON) [RFC4627] 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", "MAY", and "OPTIONAL" in this 174 document are to be interpreted as described in Key words for use in 175 RFCs to Indicate Requirement Levels [RFC2119]. If these words are 176 used without being spelled in uppercase then they are to be 177 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)", "JSON Text Object", "Base64url Encoding", 195 "Collision Resistant Name", and "StringOrURI". 197 These terms are defined for use by this specification: 199 JSON Web Encryption (JWE) A data structure representing an encrypted 200 and integrity protected message. 202 Authenticated Encryption with Associated Data (AEAD) An AEAD 203 algorithm is one that encrypts the Plaintext, allows Additional 204 Authenticated Data to be specified, and provides an integrated 205 content integrity check over the Ciphertext and Additional 206 Authenticated Data. AEAD algorithms accept two inputs, the 207 Plaintext and the Additional Authenticated Data value, and produce 208 two outputs, the Ciphertext and the Authentication Tag value. AES 209 Galois/Counter Mode (GCM) is one such algorithm. 211 Plaintext The sequence of octets to be encrypted -- a.k.a., the 212 message. The plaintext can contain an arbitrary sequence of 213 octets. 215 Ciphertext An encrypted representation of the Plaintext. 217 Additional Authenticated Data (AAD) An input to an AEAD operation 218 that is integrity protected but not encrypted. 220 Authentication Tag An output of an AEAD operation that ensures the 221 integrity of the Ciphertext and the Additional Authenticated Data. 222 Note that some algorithms may not use an Authentication Tag, in 223 which case this value is the empty octet sequence. 225 Content Encryption Key (CEK) A symmetric key for the AEAD algorithm 226 used to encrypt the Plaintext for the recipient to produce the 227 Ciphertext and the Authentication Tag. 229 JWE Header A JSON Text Object (or JSON Text Objects, when using the 230 JWE JSON Serialization) that describes the encryption operations 231 applied to create the JWE Encrypted Key, the JWE Ciphertext, and 232 the JWE Authentication Tag. The members of the JWE Header 233 object(s) are Header Parameters. 235 JWE Encrypted Key The result of encrypting the Content Encryption 236 Key (CEK) with the intended recipient's key using the specified 237 algorithm. Note that for some algorithms, the JWE Encrypted Key 238 value is specified as being the empty octet sequence. 240 JWE Initialization Vector A sequence of octets containing the 241 Initialization Vector used when encrypting the Plaintext. Note 242 that some algorithms may not use an Initialization Vector, in 243 which case this value is the empty octet sequence. 245 JWE Ciphertext A sequence of octets containing the Ciphertext for a 246 JWE. 248 JWE Authentication Tag A sequence of octets containing the 249 Authentication Tag for a JWE. 251 JWE Protected Header A JSON Text Object that contains the portion of 252 the JWE Header that is integrity protected. For the JWE Compact 253 Serialization, this comprises the entire JWE Header. For the JWE 254 JSON Serialization, this is one component of the JWE Header. 256 Header Parameter A name/value pair that is member of the JWE Header. 258 JWE Compact Serialization A representation of the JWE as the string 259 BASE64URL(UTF8(JWE Protected Header)) || '.' || BASE64URL(JWE 260 Encrypted Key) || '.' || BASE64URL(JWE Initialization Vector) || 261 '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 262 Authentication Tag). This representation is compact and URL-safe. 264 JWE JSON Serialization A representation of the JWE as a JSON 265 structure. Unlike the JWE Compact Serialization, the JWE JSON 266 Serialization enables the same content to be encrypted to multiple 267 parties. This representation is neither compact nor URL-safe. 269 Key Management Mode A method of determining the Content Encryption 270 Key (CEK) value to use. Each algorithm used for determining the 271 CEK value uses a specific Key Management Mode. Key Management 272 Modes employed by this specification are Key Encryption, Key 273 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 274 and Direct Encryption. 276 Key Encryption A Key Management Mode in which the Content Encryption 277 Key (CEK) value is encrypted to the intended recipient using an 278 asymmetric encryption algorithm. 280 Key Wrapping A Key Management Mode in which the Content Encryption 281 Key (CEK) value is encrypted to the intended recipient using a 282 symmetric key wrapping algorithm. 284 Direct Key Agreement A Key Management Mode in which a key agreement 285 algorithm is used to agree upon the Content Encryption Key (CEK) 286 value. 288 Key Agreement with Key Wrapping A Key Management Mode in which a key 289 agreement algorithm is used to agree upon a symmetric key used to 290 encrypt the Content Encryption Key (CEK) value to the intended 291 recipient using a symmetric key wrapping algorithm. 293 Direct Encryption A Key Management Mode in which the Content 294 Encryption Key (CEK) value used is the secret symmetric key value 295 shared between the parties. 297 3. JSON Web Encryption (JWE) Overview 299 JWE represents encrypted content using JSON data structures and 300 base64url encoding. A JWE represents these logical values: 302 JWE Header JSON object containing the parameters describing the 303 cryptographic operations and parameters employed. The JWE Header 304 members are the union of the members of the JWE Protected Header, 305 the JWE Shared Unprotected Header, and the JWE Per-Recipient 306 Unprotected Header, as described below. 308 JWE Encrypted Key Encrypted Content Encryption Key (CEK) value. 310 JWE Initialization Vector Initialization Vector value used when 311 encrypting the plaintext. 313 JWE Ciphertext Ciphertext value resulting from authenticated 314 encryption of the plaintext. 316 JWE Authentication Tag Authentication Tag value resulting from 317 authenticated encryption of the plaintext with additional 318 associated data. 320 JWE AAD Additional value to be integrity protected by the 321 authenticated encryption operation. 323 The JWE Header represents the combination of these logical values: 325 JWE Protected Header JSON object containing some of the parameters 326 describing the cryptographic operations and parameters employed. 327 These parameters apply to all recipients of the JWE. This value 328 is integrity protected in the digital signature or MAC calculation 329 of the JWE Signature. 331 JWE Shared Unprotected Header JSON object containing some of the 332 parameters describing the cryptographic operations and parameters 333 employed. These parameters apply to all recipients of the JWE. 334 This value is not integrity protected in the authenticated 335 encryption operation. 337 JWE Per-Recipient Unprotected Header JSON object containing some of 338 the parameters describing the cryptographic operations and 339 parameters employed. These parameters apply to a single recipient 340 of the JWE. This value is not integrity protected in the 341 authenticated encryption operation. 343 This document defines two serializations for JWE objects: a compact, 344 URL-safe serialization called the JWE Compact Serialization and a 345 JSON serialization called the JWE JSON Serialization. In both 346 serializations, the JWE Protected Header, JWE Encrypted Key, JWE 347 Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are 348 base64url encoded for transmission, since JSON lacks a way to 349 directly represent octet sequences. When present, the JWE AAD is 350 also base64url encoded for transmission. 352 In the JWE Compact Serialization, no JWE Shared Unprotected Header or 353 JWE Per-Recipient Unprotected Header are used. In this case, the JWE 354 Header and the JWE Protected Header are the same. 356 In the JWE Compact Serialization, a JWE object is represented as the 357 combination of these five string values, 358 BASE64URL(UTF8(JWE Protected Header)), 359 BASE64URL(JWE Encrypted Key), 360 BASE64URL(JWE Initialization Vector), 361 BASE64URL(JWE Ciphertext), and 362 BASE64URL(JWE Authentication Tag), 363 concatenated in that order, with the five strings being separated by 364 four period ('.') characters. 366 In the JWE JSON Serialization, one or more of the JWE Protected 367 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 368 Unprotected Header MUST be present. In this case, the members of the 369 JWE Header are the combination of the members of the JWE Protected 370 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 371 Unprotected Header values that are present. 373 In the JWE JSON Serialization, a JWE object is represented as the 374 combination of these eight values, 375 BASE64URL(UTF8(JWE Protected Header)), 376 JWE Shared Unprotected Header, 377 JWE Per-Recipient Unprotected Header, 378 BASE64URL(JWE Encrypted Key), 379 BASE64URL(JWE Initialization Vector), 380 BASE64URL(JWE Ciphertext), 381 BASE64URL(JWE Authentication Tag), and 382 BASE64URL(JWE AAD), 383 with the six base64url encoding result strings and the two 384 unprotected JSON object values being represented as members within a 385 JSON object. The inclusion of some of these values is OPTIONAL. The 386 JWE JSON Serialization can also encrypt the plaintext to multiple 387 recipients. See Section 7.2 for more information about the JWE JSON 388 Serialization. 390 JWE utilizes authenticated encryption to ensure the confidentiality 391 and integrity of the Plaintext and the integrity of the JWE Protected 392 Header and the JWE AAD. 394 3.1. Example JWE 396 This example encrypts the plaintext "The true sign of intelligence is 397 not knowledge but imagination." to the recipient using RSAES OAEP for 398 key encryption and AES GCM for content encryption. 400 The following example JWE Protected Header declares that: 402 o the Content Encryption Key is encrypted to the recipient using the 403 RSAES OAEP algorithm to produce the JWE Encrypted Key and 405 o the Plaintext is encrypted using the AES GCM algorithm with a 256 406 bit key to produce the Ciphertext. 408 {"alg":"RSA-OAEP","enc":"A256GCM"} 410 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 411 Header)) gives this value: 413 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 415 The remaining steps to finish creating this JWE are: 417 o Generate a random Content Encryption Key (CEK). 419 o Encrypt the CEK with the recipient's public key using the RSAES 420 OAEP algorithm to produce the JWE Encrypted Key. 422 o Base64url encode the JWE Encrypted Key. 424 o Generate a random JWE Initialization Vector. 426 o Base64url encode the JWE Initialization Vector. 428 o Let the Additional Authenticated Data encryption parameter be 429 ASCII(BASE64URL(UTF8(JWE Protected Header))). 431 o Encrypt the Plaintext with AES GCM using the CEK as the encryption 432 key, the JWE Initialization Vector, and the Additional 433 Authenticated Data value, requesting a 128 bit Authentication Tag 434 output. 436 o Base64url encode the Ciphertext. 438 o Base64url encode the Authentication Tag. 440 o Assemble the final representation: The Compact Serialization of 441 this result is the string BASE64URL(UTF8(JWE Protected Header)) || 442 '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE 443 Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' 444 || BASE64URL(JWE Authentication Tag). 446 The final result in this example (with line breaks for display 447 purposes only) is: 449 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 450 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 451 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 452 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 453 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 454 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 455 6UklfCpIMfIjf7iGdXKHzg. 456 48V1_ALb6US04U3b. 457 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 458 SdiwkIr3ajwQzaBtQD_A. 459 XFBoMYUZodetZdvTiFvSkQ 461 See Appendix A.1 for the complete details of computing this JWE. See 462 Appendix A for additional examples. 464 4. JWE Header 466 The members of the JSON object(s) representing the JWE Header 467 describe the encryption applied to the Plaintext and optionally 468 additional properties of the JWE. The Header Parameter names within 469 the JWE Header MUST be unique; recipients MUST either reject JWEs 470 with duplicate Header Parameter names or use a JSON parser that 471 returns only the lexically last duplicate member name, as specified 472 in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. 474 Implementations are required to understand the specific Header 475 Parameters defined by this specification that are designated as "MUST 476 be understood" and process them in the manner defined in this 477 specification. All other Header Parameters defined by this 478 specification that are not so designated MUST be ignored when not 479 understood. Unless listed as a critical Header Parameter, per 480 Section 4.1.12, all Header Parameters not defined by this 481 specification MUST be ignored when not understood. 483 There are three classes of Header Parameter names: Registered Header 484 Parameter names, Public Header Parameter names, and Private Header 485 Parameter names. 487 4.1. Registered Header Parameter Names 489 The following Header Parameter names are registered in the IANA JSON 490 Web Signature and Encryption Header Parameters registry defined in 491 [JWS], with meanings as defined below. 493 As indicated by the common registry, JWSs and JWEs share a common 494 Header Parameter space; when a parameter is used by both 495 specifications, its usage must be compatible between the 496 specifications. 498 4.1.1. "alg" (Algorithm) Header Parameter 500 This parameter has the same meaning, syntax, and processing rules as 501 the "alg" Header Parameter defined in Section 4.1.1 of [JWS], except 502 that the Header Parameter identifies the cryptographic algorithm used 503 to encrypt or determine the value of the Content Encryption Key 504 (CEK). The encrypted content is not usable if the "alg" value does 505 not represent a supported algorithm, or if the recipient does not 506 have a key that can be used with that algorithm. 508 A list of defined "alg" values for this use can be found in the IANA 509 JSON Web Signature and Encryption Algorithms registry defined in 510 [JWA]; the initial contents of this registry are the values defined 511 in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. 513 4.1.2. "enc" (Encryption Method) Header Parameter 515 The "enc" (encryption method) Header Parameter identifies the content 516 encryption algorithm used to encrypt the Plaintext to produce the 517 Ciphertext. This algorithm MUST be an AEAD algorithm with a 518 specified key length. The recipient MUST reject the JWE if the "enc" 519 value does not represent a supported algorithm. "enc" values SHOULD 520 either be registered in the IANA JSON Web Signature and Encryption 521 Algorithms registry defined in [JWA] or be a value that contains a 522 Collision Resistant Name. The "enc" value is a case sensitive string 523 containing a StringOrURI value. Use of this Header Parameter is 524 REQUIRED. This Header Parameter MUST be understood and processed by 525 implementations. 527 A list of defined "enc" values for this use can be found in the IANA 528 JSON Web Signature and Encryption Algorithms registry defined in 529 [JWA]; the initial contents of this registry are the values defined 530 in Section 4.2 of the JSON Web Algorithms (JWA) [JWA] specification. 532 4.1.3. "zip" (Compression Algorithm) Header Parameter 534 The "zip" (compression algorithm) applied to the Plaintext before 535 encryption, if any. The "zip" value defined by this specification 536 is: 538 o "DEF" - Compression with the DEFLATE [RFC1951] algorithm 540 Other values MAY be used. Compression algorithm values can be 541 registered in the IANA JSON Web Encryption Compression Algorithm 542 registry defined in [JWA]. The "zip" value is a case sensitive 543 string. If no "zip" parameter is present, no compression is applied 544 to the Plaintext before encryption. This Header Parameter MUST be 545 integrity protected, and therefore MUST occur only within the JWE 546 Protected Header, when used. Use of this Header Parameter is 547 OPTIONAL. This Header Parameter MUST be understood and processed by 548 implementations. 550 4.1.4. "jku" (JWK Set URL) Header Parameter 552 This parameter has the same meaning, syntax, and processing rules as 553 the "jku" Header Parameter defined in Section 4.1.2 of [JWS], except 554 that the JWK Set resource contains the public key to which the JWE 555 was encrypted; this can be used to determine the private key needed 556 to decrypt the JWE. 558 4.1.5. "jwk" (JSON Web Key) Header Parameter 560 This parameter has the same meaning, syntax, and processing rules as 561 the "jwk" Header Parameter defined in Section 4.1.3 of [JWS], except 562 that the key is the public key to which the JWE was encrypted; this 563 can be used to determine the private key needed to decrypt the JWE. 565 4.1.6. "x5u" (X.509 URL) Header Parameter 567 This parameter has the same meaning, syntax, and processing rules as 568 the "x5u" Header Parameter defined in Section 4.1.4 of [JWS], except 569 that the X.509 public key certificate or certificate chain [RFC5280] 570 contains the public key to which the JWE was encrypted; this can be 571 used to determine the private key needed to decrypt the JWE. 573 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 575 This parameter has the same meaning, syntax, and processing rules as 576 the "x5t" Header Parameter defined in Section 4.1.5 of [JWS], except 577 that certificate referenced by the thumbprint contains the public key 578 to which the JWE was encrypted; this can be used to determine the 579 private key needed to decrypt the JWE. 581 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 583 This parameter has the same meaning, syntax, and processing rules as 584 the "x5c" Header Parameter defined in Section 4.1.6 of [JWS], except 585 that the X.509 public key certificate or certificate chain [RFC5280] 586 contains the public key to which the JWE was encrypted; this can be 587 used to determine the private key needed to decrypt the JWE. 589 See Appendix B of [JWS] for an example "x5c" value. 591 4.1.9. "kid" (Key ID) Header Parameter 593 This parameter has the same meaning, syntax, and processing rules as 594 the "kid" Header Parameter defined in Section 4.1.7 of [JWS], except 595 that the key hint references the public key to which the JWE was 596 encrypted; this can be used to determine the private key needed to 597 decrypt the JWE. This parameter allows originators to explicitly 598 signal a change of key to JWE recipients. 600 4.1.10. "typ" (Type) Header Parameter 602 This parameter has the same meaning, syntax, and processing rules as 603 the "typ" Header Parameter defined in Section 4.1.8 of [JWS], except 604 that the type is of this complete JWE object. 606 4.1.11. "cty" (Content Type) Header Parameter 608 This parameter has the same meaning, syntax, and processing rules as 609 the "cty" Header Parameter defined in Section 4.1.9 of [JWS], except 610 that the type is of the secured content (the payload). 612 4.1.12. "crit" (Critical) Header Parameter 614 This parameter has the same meaning, syntax, and processing rules as 615 the "typ" Header Parameter defined in Section 4.1.8 of [JWS], except 616 that the Header Parameters referenced are the JWE Header Parameters. 618 4.2. Public Header Parameter Names 620 Additional Header Parameter names can be defined by those using JWEs. 621 However, in order to prevent collisions, any new Header Parameter 622 name SHOULD either be registered in the IANA JSON Web Signature and 623 Encryption Header Parameters registry defined in [JWS] or be a Public 624 Name: a value that contains a Collision Resistant Name. In each 625 case, the definer of the name or value needs to take reasonable 626 precautions to make sure they are in control of the part of the 627 namespace they use to define the Header Parameter name. 629 New Header Parameters should be introduced sparingly, as they can 630 result in non-interoperable JWEs. 632 4.3. Private Header Parameter Names 634 A producer and consumer of a JWE may agree to use Header Parameter 635 names that are Private Names: names that are not Registered Header 636 Parameter names Section 4.1 or Public Header Parameter names 637 Section 4.2. Unlike Public Header Parameter names, Private Header 638 Parameter names are subject to collision and should be used with 639 caution. 641 5. Producing and Consuming JWEs 643 5.1. Message Encryption 645 The message encryption process is as follows. The order of the steps 646 is not significant in cases where there are no dependencies between 647 the inputs and outputs of the steps. 649 1. Determine the Key Management Mode employed by the algorithm used 650 to determine the Content Encryption Key (CEK) value. (This is 651 the algorithm recorded in the "alg" (algorithm) Header Parameter 652 of the resulting JWE.) 654 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 655 Wrapping are employed, generate a random Content Encryption Key 656 (CEK) value. See RFC 4086 [RFC4086] for considerations on 657 generating random values. The CEK MUST have a length equal to 658 that required for the content encryption algorithm. 660 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 661 employed, use the key agreement algorithm to compute the value 662 of the agreed upon key. When Direct Key Agreement is employed, 663 let the Content Encryption Key (CEK) be the agreed upon key. 664 When Key Agreement with Key Wrapping is employed, the agreed 665 upon key will be used to wrap the CEK. 667 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 668 Wrapping are employed, encrypt the CEK to the recipient and let 669 the result be the JWE Encrypted Key. 671 5. Otherwise, when Direct Key Agreement or Direct Encryption are 672 employed, let the JWE Encrypted Key be the empty octet sequence. 674 6. When Direct Encryption is employed, let the Content Encryption 675 Key (CEK) be the shared symmetric key. 677 7. Compute the encoded key value BASE64URL(JWE Encrypted Key). 679 8. If the JWE JSON Serialization is being used, repeat this process 680 for each recipient. 682 9. Generate a random JWE Initialization Vector of the correct size 683 for the content encryption algorithm (if required for the 684 algorithm); otherwise, let the JWE Initialization Vector be the 685 empty octet sequence. 687 10. Compute the encoded initialization vector value BASE64URL(JWE 688 Initialization Vector). 690 11. Compress the Plaintext if a "zip" parameter was included. 692 12. Serialize the (compressed) Plaintext into an octet sequence M. 694 13. Create a JWE Header containing the encryption parameters used. 695 Note that white space is explicitly allowed in the 696 representation and no canonicalization need be performed before 697 encoding. 699 14. Compute the encoded header value BASE64URL(UTF8(JWE Protected 700 Header)). If the JWE Protected Header is not present (which can 701 only happen when using the JWE JSON Serialization and no 702 "protected" member is present), let this value be the empty 703 string. 705 15. Let the Additional Authenticated Data encryption parameter be 706 ASCII(BASE64URL(UTF8(JWE Protected Header))). However if a JWE 707 AAD value is present when using the JWE JSON Serialization, 708 instead let the Additional Authenticated Data encryption 709 parameter be ASCII(BASE64URL(UTF8(JWE Protected Header)) || '.' 710 || BASE64URL(JWE AAD)). 712 16. Encrypt M using the CEK, the JWE Initialization Vector, and the 713 Additional Authenticated Data value using the specified content 714 encryption algorithm to create the JWE Ciphertext value and the 715 JWE Authentication Tag (which is the Authentication Tag output 716 from the encryption operation). 718 17. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext). 720 18. Compute the encoded authentication tag value BASE64URL(JWE 721 Authentication Tag). 723 19. The five encoded values are used in both the JWE Compact 724 Serialization and the JWE JSON Serialization representations. 726 20. If a JWE AAD value is present, compute the encoded AAD value 727 BASE64URL(JWE AAD). 729 21. Create the desired serialized output. The Compact Serialization 730 of this result is the string BASE64URL(UTF8(JWE Protected 731 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 732 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 733 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). The 734 JWE JSON Serialization is described in Section 7.2. 736 5.2. Message Decryption 738 The message decryption process is the reverse of the encryption 739 process. The order of the steps is not significant in cases where 740 there are no dependencies between the inputs and outputs of the 741 steps. If any of these steps fails, the encrypted content cannot be 742 validated. 744 It is an application decision which recipients' encrypted content 745 must successfully validate for the JWE to be accepted. In some 746 cases, encrypted content for all recipients must successfully 747 validate or the JWE will be rejected. In other cases, only the 748 encrypted content for a single recipient needs to be successfully 749 validated. However, in all cases, the encrypted content for at least 750 one recipient MUST successfully validate or the JWE MUST be rejected. 752 1. Parse the JWE representation to extract the serialized values 753 for the components of the JWE -- when using the JWE Compact 754 Serialization, the base64url encoded representations of the JWE 755 Protected Header, the JWE Encrypted Key, the JWE Initialization 756 Vector, the JWE Ciphertext, and the JWE Authentication Tag, and 757 when using the JWE JSON Serialization, also the base64url 758 encoded representation of the JWE AAD and the unencoded JWE 759 Shared Unprotected Header and JWE Per-Recipient Unprotected 760 Header values. When using the JWE Compact Serialization, the 761 JWE Protected Header, the JWE Encrypted Key, the JWE 762 Initialization Vector, the JWE Ciphertext, and the JWE 763 Authentication Tag are represented as base64url encoded values 764 in that order, separated by four period ('.') characters. The 765 JWE JSON Serialization is described in Section 7.2. 767 2. The encoded representations of the JWE Protected Header, the JWE 768 Encrypted Key, the JWE Initialization Vector, the JWE 769 Ciphertext, the JWE Authentication Tag, and the JWE AAD MUST be 770 successfully base64url decoded following the restriction that no 771 padding characters have been used. 773 3. The resulting UTF8 encoded JWE Protected Header MUST be a 774 completely valid JSON object conforming to RFC 4627 [RFC4627]. 776 4. If using the JWE Compact Serialization, let the JWE Header be 777 the JWE Protected Header; otherwise, when using the JWE JSON 778 Serialization, let the JWE Header be the union of the members of 779 the JWE Protected Header, the JWE Shared Unprotected Header and 780 the corresponding JWE Per-Recipient Unprotected Header, all of 781 which must be completely valid JSON objects. 783 5. The resulting JWE Header MUST NOT contain duplicate Header 784 Parameter names. When using the JWE JSON Serialization, this 785 restriction includes that the same Header Parameter name also 786 MUST NOT occur in distinct JSON Text Object values that together 787 comprise the JWE Header. 789 6. The resulting JWE Header MUST be validated to only include 790 parameters and values whose syntax and semantics are both 791 understood and supported or that are specified as being ignored 792 when not understood. 794 7. Determine the Key Management Mode employed by the algorithm 795 specified by the "alg" (algorithm) Header Parameter. 797 8. Verify that the JWE uses a key known to the recipient. 799 9. When Direct Key Agreement or Key Agreement with Key Wrapping are 800 employed, use the key agreement algorithm to compute the value 801 of the agreed upon key. When Direct Key Agreement is employed, 802 let the Content Encryption Key (CEK) be the agreed upon key. 803 When Key Agreement with Key Wrapping is employed, the agreed 804 upon key will be used to decrypt the JWE Encrypted Key. 806 10. When Key Wrapping, Key Encryption, or Key Agreement with Key 807 Wrapping are employed, decrypt the JWE Encrypted Key to produce 808 the Content Encryption Key (CEK). The CEK MUST have a length 809 equal to that required for the content encryption algorithm. 810 Note that when there are multiple recipients, each recipient 811 will only be able decrypt any JWE Encrypted Key values that were 812 encrypted to a key in that recipient's possession. It is 813 therefore normal to only be able to decrypt one of the per- 814 recipient JWE Encrypted Key values to obtain the CEK value. To 815 mitigate the attacks described in RFC 3218 [RFC3218], the 816 recipient MUST NOT distinguish between format, padding, and 817 length errors of encrypted keys. It is strongly recommended, in 818 the event of receiving an improperly formatted key, that the 819 receiver substitute a randomly generated CEK and proceed to the 820 next step, to mitigate timing attacks. 822 11. Otherwise, when Direct Key Agreement or Direct Encryption are 823 employed, verify that the JWE Encrypted Key value is empty octet 824 sequence. 826 12. When Direct Encryption is employed, let the Content Encryption 827 Key (CEK) be the shared symmetric key. 829 13. If the JWE JSON Serialization is being used, repeat this process 830 for each recipient contained in the representation until the CEK 831 value has been determined. 833 14. Let the Additional Authenticated Data encryption parameter be 834 ASCII(BASE64URL(UTF8(JWE Protected Header))). However if a JWE 835 AAD value is present when using the JWE JSON Serialization, 836 instead let the Additional Authenticated Data encryption 837 parameter be ASCII(BASE64URL(UTF8(JWE Protected Header)) || '.' 838 || BASE64URL(JWE AAD)). 840 15. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 841 Vector, the Additional Authenticated Data value, and the JWE 842 Authentication Tag (which is the Authentication Tag input to the 843 calculation) using the specified content encryption algorithm, 844 returning the decrypted plaintext and verifying the JWE 845 Authentication Tag in the manner specified for the algorithm, 846 rejecting the input without emitting any decrypted output if the 847 JWE Authentication Tag is incorrect. 849 16. Uncompress the decrypted plaintext if a "zip" parameter was 850 included. 852 17. Output the resulting Plaintext. 854 5.3. String Comparison Rules 856 The string comparison rules for this specification are the same as 857 those defined in Section 5.3 of [JWS]. 859 6. Key Identification 861 The key identification methods for this specification are the same as 862 those defined in Section 6 of [JWS], except that the key being 863 identified is the public key to which the JWE was encrypted. 865 7. Serializations 867 JWE objects use one of two serializations, the JWE Compact 868 Serialization or the JWE JSON Serialization. For general-purpose 869 implementations, both the JWE Compact Serialization and JWE JSON 870 Serialization support for the single recipient case are mandatory to 871 implement; support for multiple recipients is OPTIONAL. Special- 872 purpose implementations are permitted to implement only a single 873 serialization, if that meets the needs of the targeted use cases. 875 7.1. JWE Compact Serialization 877 The JWE Compact Serialization represents encrypted content as a 878 compact URL-safe string. This string is BASE64URL(UTF8(JWE Protected 879 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 880 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 881 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). Only one 882 recipient is supported by the JWE Compact Serialization. 884 7.2. JWE JSON Serialization 886 The JWE JSON Serialization represents encrypted content as a JSON 887 object. Unlike the JWE Compact Serialization, content using the JWE 888 JSON Serialization can be encrypted to more than one recipient. 890 The representation is closely related to that used in the JWE Compact 891 Serialization, with the following differences for the JWE JSON 892 Serialization: 894 o Values in the JWE JSON Serialization are represented as members of 895 a JSON object, rather than as base64url encoded strings separated 896 by period ('.') characters. (However binary values and values 897 that are integrity protected are still base64url encoded.) 899 o The value BASE64URL(UTF8(JWE Protected Header)), if non-empty, is 900 stored in the "protected" member. 902 o The value BASE64URL(UTF8(JWE Shared Unprotected Header)), if non- 903 empty, is stored in the "unprotected" member. 905 o The value BASE64URL(JWE Initialization Vector), if non-empty, is 906 stored in the "iv" member. 908 o The value BASE64URL(JWE Ciphertext)is stored in the "ciphertext" 909 member. 911 o The value BASE64URL(JWE Authentication Tag), if non-empty, is 912 stored in the "tag" member. 914 o The JWE can be encrypted to multiple recipients, rather than just 915 one. A JSON array in the "recipients" member is used to hold 916 values that are specific to a particular recipient, with one array 917 element per recipient represented. These array elements are JSON 918 objects. 920 o Each value BASE64URL(JWE Encrypted Key), if non-empty, is stored 921 in the "encrypted_key" member of a JSON object that is an element 922 of the "recipients" array. 924 o Some Header Parameter values, such as the "alg" value and 925 parameters used for selecting keys, can also differ for different 926 recipient computations. JWE Per-Recipient Unprotected Header 927 values, if present, are stored in the "header" members of the same 928 JSON objects that are elements of the "recipients" array. 930 o Some Header Parameters, including the "alg" parameter, can be 931 shared among all recipient computations. Header Parameters in the 932 JWE Protected Header and JWE Shared Unprotected Header values are 933 shared among all recipients. 935 o Not all Header Parameters are integrity protected. The shared 936 Header Parameters in the JWE Protected Header value member are 937 integrity protected, and are base64url encoded for transmission. 938 The per-recipient Header Parameters in the JWE Per-Recipient 939 Unprotected Header values and the shared Header Parameters in the 940 JWE Shared Unprotected Header value are not integrity protected. 941 These JSON Text Objects containing Header Parameters that are not 942 integrity protected are not base64url encoded. 944 o The Header Parameter values used when creating or validating per- 945 recipient Ciphertext and Authentication Tag values are the union 946 of the three sets of Header Parameter values that may be present: 947 (1) the JWE Protected Header values represented in the "protected" 948 member, (2) the JWE Shared Unprotected Header values represented 949 in the "unprotected" member, and (3) the JWE Per-Recipient 950 Unprotected Header values represented in the "header" member of 951 the recipient's array element. The union of these sets of Header 952 Parameters comprises the JWE Header. The Header Parameter names 953 in the three locations MUST be disjoint. 955 o A JWE AAD value can be included to supply a base64url encoded 956 value to be integrity protected but not encrypted. (Note that 957 this can also be achieved when using either serialization by 958 including the AAD value as a protected Header Parameter value, but 959 at the cost of the value being double base64url encoded.) If a 960 JWE AAD value is present, the value BASE64URL(JWE AAD)) is stored 961 in the "aad" member. 963 o The "recipients" array MUST always be present, even if the array 964 elements contain only the empty JSON object "{}" (which can happen 965 when all Header Parameter values are shared between all recipients 966 and when no encrypted key is used, such as when doing Direct 967 Encryption). 969 The syntax of a JWE using the JWE JSON Serialization is as follows: 971 {"protected":", 972 "unprotected":", 973 "recipients":[ 974 {"header":"", 975 "encrypted_key":""}, 976 ... 977 {"header":"", 978 "encrypted_key":""}], 979 "aad":"", 980 "iv":"", 981 "ciphertext":"", 982 "tag":"" 983 } 985 Of these members, only the "ciphertext" member MUST be present. The 986 "iv", "tag", and "encrypted_key" members MUST be present when 987 corresponding JWE Initialization Vector, JWE Authentication Tag, and 988 JWE Encrypted Key values are non-empty. The "recipients" member MUST 989 be present when any "header" or "encrypted_key" members are needed 990 for recipients. At least one of the "header", "protected", and 991 "unprotected" members MUST be present so that "alg" and "enc" Header 992 Parameter values are conveyed for each recipient computation. 994 The contents of the JWE Encrypted Key, JWE Initialization Vector, JWE 995 Ciphertext, and JWE Authentication Tag values are exactly as defined 996 in the rest of this specification. They are interpreted and 997 validated in the same manner, with each corresponding JWE Encrypted 998 Key, JWE Initialization Vector, JWE Ciphertext, JWE Authentication 999 Tag, and set of Header Parameter values being created and validated 1000 together. The JWE Header values used are the union of the Header 1001 Parameters in the JWE Protected Header, JWE Shared Unprotected 1002 Header, and corresponding JWE Per-Recipient Unprotected Header 1003 values, as described earlier. 1005 Each JWE Encrypted Key value is computed using the parameters of the 1006 corresponding JWE Header value in the same manner as for the JWE 1007 Compact Serialization. This has the desirable property that each JWE 1008 Encrypted Key value in the "recipients" array is identical to the 1009 value that would have been computed for the same parameter in the JWE 1010 Compact Serialization. Likewise, the JWE Ciphertext and JWE 1011 Authentication Tag values match those produced for the JWE Compact 1012 Serialization, provided that the JWE Protected Header value (which 1013 represents the integrity-protected Header Parameter values) matches 1014 that used in the JWE Compact Serialization. 1016 All recipients use the same JWE Protected Header, JWE Initialization 1017 Vector, JWE Ciphertext, and JWE Authentication Tag values, resulting 1018 in potentially significant space savings if the message is large. 1019 Therefore, all Header Parameters that specify the treatment of the 1020 Plaintext value MUST be the same for all recipients. This primarily 1021 means that the "enc" (encryption method) Header Parameter value in 1022 the JWE Header for each recipient and any parameters of that 1023 algorithm MUST be the same. 1025 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1026 Serialization. 1028 8. Distinguishing Between JWS and JWE Objects 1030 There are several ways of distinguishing whether an object is a JWS 1031 or JWE object. All these methods will yield the same result for all 1032 legal input values. 1034 o If the object is using the JWS Compact Serialization or the JWE 1035 Compact Serialization, the number of base64url encoded segments 1036 separated by period ('.') characters differs for JWSs and JWEs. 1037 JWSs have three segments separated by two period ('.') characters. 1038 JWEs have five segments separated by four period ('.') characters. 1040 o If the object is using the JWS JSON Serialization or the JWE JSON 1041 Serialization, the members used will be different. JWSs have a 1042 "signatures" member and JWEs do not. JWEs have a "recipients" 1043 member and JWSs do not. 1045 o A JWS Header can be distinguished from a JWE header by examining 1046 the "alg" (algorithm) Header Parameter value. If the value 1047 represents a digital signature or MAC algorithm, or is the value 1048 "none", it is for a JWS; if it represents a Key Encryption, Key 1049 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 1050 or Direct Encryption algorithm, it is for a JWE. 1052 o A JWS Header can also be distinguished from a JWE header by 1053 determining whether an "enc" (encryption method) member exists. 1054 If the "enc" member exists, it is a JWE; otherwise, it is a JWS. 1056 9. IANA Considerations 1058 9.1. JWE Header Parameter Names Registration 1060 This specification registers the Header Parameter names defined in 1061 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1062 Parameters registry defined in [JWS]. 1064 9.1.1. Registry Contents 1066 o Header Parameter Name: "alg" 1067 o Header Parameter Usage Location(s): JWE 1068 o Change Controller: IESG 1069 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1071 o Header Parameter Name: "enc" 1072 o Header Parameter Usage Location(s): JWE 1073 o Change Controller: IESG 1074 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1076 o Header Parameter Name: "zip" 1077 o Header Parameter Usage Location(s): JWE 1078 o Change Controller: IESG 1079 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1081 o Header Parameter Name: "jku" 1082 o Header Parameter Usage Location(s): JWE 1083 o Change Controller: IESG 1084 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1086 o Header Parameter Name: "jwk" 1087 o Header Parameter Usage Location(s): JWE 1088 o Change Controller: IESG 1089 o Specification document(s): Section 4.1.5 of [[ this document ]] 1091 o Header Parameter Name: "x5u" 1092 o Header Parameter Usage Location(s): JWE 1093 o Change Controller: IESG 1094 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1096 o Header Parameter Name: "x5t" 1097 o Header Parameter Usage Location(s): JWE 1098 o Change Controller: IESG 1099 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1101 o Header Parameter Name: "x5c" 1102 o Header Parameter Usage Location(s): JWE 1103 o Change Controller: IESG 1104 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1106 o Header Parameter Name: "kid" 1107 o Header Parameter Usage Location(s): JWE 1108 o Change Controller: IESG 1109 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1111 o Header Parameter Name: "typ" 1112 o Header Parameter Usage Location(s): JWE 1113 o Change Controller: IESG 1114 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1116 o Header Parameter Name: "cty" 1117 o Header Parameter Usage Location(s): JWE 1118 o Change Controller: IESG 1119 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1121 o Header Parameter Name: "crit" 1122 o Header Parameter Usage Location(s): JWE 1123 o Change Controller: IESG 1124 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1126 10. Security Considerations 1128 All of the security issues faced by any cryptographic application 1129 must be faced by a JWS/JWE/JWK agent. Among these issues are 1130 protecting the user's private and symmetric keys, preventing various 1131 attacks, and helping the user avoid mistakes such as inadvertently 1132 encrypting a message for the wrong recipient. The entire list of 1133 security considerations is beyond the scope of this document. 1135 All the security considerations in the JWS specification also apply 1136 to this specification. Likewise, all the security considerations in 1137 XML Encryption 1.1 [W3C.CR-xmlenc-core1-20120313] also apply, other 1138 than those that are XML specific. 1140 When decrypting, particular care must be taken not to allow the JWE 1141 recipient to be used as an oracle for decrypting messages. RFC 3218 1142 [RFC3218] should be consulted for specific countermeasures to attacks 1143 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1144 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1145 formatting error that can be detected and used to recover the CEK 1146 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1147 particularly important to report all formatting errors to the CEK, 1148 Additional Authenticated Data, or ciphertext as a single error when 1149 the encrypted content is rejected. 1151 11. References 1153 11.1. Normative References 1155 [ECMAScript] 1156 Ecma International, "ECMAScript Language Specification, 1157 5.1 Edition", ECMA 262, June 2011. 1159 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1160 draft-ietf-jose-json-web-algorithms (work in progress), 1161 October 2013. 1163 [JWK] Jones, M., "JSON Web Key (JWK)", 1164 draft-ietf-jose-json-web-key (work in progress), 1165 October 2013. 1167 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1168 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1169 in progress), October 2013. 1171 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1172 version 1.3", RFC 1951, May 1996. 1174 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1175 Requirement Levels", BCP 14, RFC 2119, March 1997. 1177 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1178 10646", STD 63, RFC 3629, November 2003. 1180 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1181 Requirements for Security", BCP 106, RFC 4086, June 2005. 1183 [RFC4627] Crockford, D., "The application/json Media Type for 1184 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1186 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1187 Housley, R., and W. Polk, "Internet X.509 Public Key 1188 Infrastructure Certificate and Certificate Revocation List 1189 (CRL) Profile", RFC 5280, May 2008. 1191 [USASCII] American National Standards Institute, "Coded Character 1192 Set -- 7-bit American Standard Code for Information 1193 Interchange", ANSI X3.4, 1986. 1195 [W3C.CR-xmlenc-core1-20120313] 1196 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 1197 "XML Encryption Syntax and Processing Version 1.1", World 1198 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1199 March 2012, 1200 . 1202 11.2. Informative References 1204 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1205 McGrew, D. and K. Paterson, "Authenticated Encryption with 1206 AES-CBC and HMAC-SHA", 1207 draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), 1208 October 2012. 1210 [I-D.rescorla-jsms] 1211 Rescorla, E. and J. Hildebrand, "JavaScript Message 1212 Security Format", draft-rescorla-jsms-00 (work in 1213 progress), March 2011. 1215 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1216 Encryption", September 2010. 1218 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1219 Cryptographic Message Syntax", RFC 3218, January 2002. 1221 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1222 RFC 5652, September 2009. 1224 Appendix A. JWE Examples 1226 This section provides examples of JWE computations. 1228 A.1. Example JWE using RSAES OAEP and AES GCM 1230 This example encrypts the plaintext "The true sign of intelligence is 1231 not knowledge but imagination." to the recipient using RSAES OAEP for 1232 key encryption and AES GCM for content encryption. The 1233 representation of this plaintext is: 1235 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1236 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1237 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1238 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1239 110, 97, 116, 105, 111, 110, 46] 1241 A.1.1. JWE Header 1243 The following example JWE Protected Header declares that: 1245 o the Content Encryption Key is encrypted to the recipient using the 1246 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1248 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1249 bit key to produce the Ciphertext. 1251 {"alg":"RSA-OAEP","enc":"A256GCM"} 1253 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1254 Header)) gives this value: 1256 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1258 A.1.2. Content Encryption Key (CEK) 1260 Generate a 256 bit random Content Encryption Key (CEK). In this 1261 example, the value is: 1263 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1264 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1265 234, 64, 252] 1267 A.1.3. Key Encryption 1269 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1270 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1271 key represented in JSON Web Key [JWK] format below (with line breaks 1272 for display purposes only): 1274 {"kty":"RSA", 1275 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1276 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1277 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1278 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1279 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1280 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1281 "e":"AQAB", 1282 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1283 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1284 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1285 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1286 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1287 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ" 1288 } 1290 The resulting JWE Encrypted Key value is: 1292 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1293 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1294 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1295 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1296 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1297 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1298 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1299 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1300 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1301 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1302 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1303 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1304 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1305 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1306 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1307 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1308 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1309 117, 114, 135, 206] 1311 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1312 this value (with line breaks for display purposes only): 1314 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1315 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1316 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1317 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1318 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1319 6UklfCpIMfIjf7iGdXKHzg 1321 A.1.4. Initialization Vector 1323 Generate a random 96 bit JWE Initialization Vector. In this example, 1324 the value is: 1326 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1328 Encoding this JWE Initialization Vector as BASE64URL(JWE 1329 Initialization Vector) gives this value: 1331 48V1_ALb6US04U3b 1333 A.1.5. Additional Authenticated Data 1335 Let the Additional Authenticated Data encryption parameter be 1336 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1338 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1339 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1340 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1342 A.1.6. Content Encryption 1344 Encrypt the Plaintext with AES GCM using the CEK as the encryption 1345 key, the JWE Initialization Vector, and the Additional Authenticated 1346 Data value above, requesting a 128 bit Authentication Tag output. 1347 The resulting Ciphertext is: 1349 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1350 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1351 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1352 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1353 160, 109, 64, 63, 192] 1355 The resulting Authentication Tag value is: 1357 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1358 210, 145] 1360 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1361 value (with line breaks for display purposes only): 1363 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1364 SdiwkIr3ajwQzaBtQD_A 1366 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1367 Tag) gives this value: 1369 XFBoMYUZodetZdvTiFvSkQ 1371 A.1.7. Complete Representation 1373 Assemble the final representation: The Compact Serialization of this 1374 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1375 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1376 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1377 Authentication Tag). 1379 The final result in this example (with line breaks for display 1380 purposes only) is: 1382 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1383 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1384 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1385 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1386 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1387 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1388 6UklfCpIMfIjf7iGdXKHzg. 1389 48V1_ALb6US04U3b. 1390 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1391 SdiwkIr3ajwQzaBtQD_A. 1392 XFBoMYUZodetZdvTiFvSkQ 1394 A.1.8. Validation 1396 This example illustrates the process of creating a JWE with RSAES 1397 OAEP for key encryption and AES GCM for content encryption. These 1398 results can be used to validate JWE decryption implementations for 1399 these algorithms. Note that since the RSAES OAEP computation 1400 includes random values, the encryption results above will not be 1401 completely reproducible. However, since the AES GCM computation is 1402 deterministic, the JWE Encrypted Ciphertext values will be the same 1403 for all encryptions performed using these inputs. 1405 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1407 This example encrypts the plaintext "Live long and prosper." to the 1408 recipient using RSAES-PKCS1-V1_5 for key encryption and 1409 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1410 of this plaintext is: 1412 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1413 112, 114, 111, 115, 112, 101, 114, 46] 1415 A.2.1. JWE Header 1417 The following example JWE Protected Header declares that: 1419 o the Content Encryption Key is encrypted to the recipient using the 1420 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1422 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1423 algorithm to produce the Ciphertext. 1425 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1427 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1428 Header)) gives this value: 1430 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1432 A.2.2. Content Encryption Key (CEK) 1434 Generate a 256 bit random Content Encryption Key (CEK). In this 1435 example, the key value is: 1437 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1438 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1439 44, 207] 1441 A.2.3. Key Encryption 1443 Encrypt the CEK with the recipient's public key using the RSAES- 1444 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1445 uses the RSA key represented in JSON Web Key [JWK] format below (with 1446 line breaks for display purposes only): 1448 {"kty":"RSA", 1449 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1450 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1451 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1452 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1453 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1454 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1455 "e":"AQAB", 1456 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1457 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1458 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1459 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1460 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1461 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1462 } 1464 The resulting JWE Encrypted Key value is: 1466 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1467 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1468 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1469 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1470 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1471 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1472 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1473 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1474 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1475 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1476 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1477 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1478 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1479 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1480 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1481 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1482 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1483 146, 114, 165, 204, 71, 136, 41, 252] 1485 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1486 this value (with line breaks for display purposes only): 1488 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1489 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1490 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1491 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1492 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1493 -B3oWh2TbqmScqXMR4gp_A 1495 A.2.4. Initialization Vector 1497 Generate a random 128 bit JWE Initialization Vector. In this 1498 example, the value is: 1500 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1501 101] 1503 Encoding this JWE Initialization Vector as BASE64URL(JWE 1504 Initialization Vector) gives this value: 1506 AxY8DCtDaGlsbGljb3RoZQ 1508 A.2.5. Additional Authenticated Data 1510 Let the Additional Authenticated Data encryption parameter be 1511 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1513 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1514 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1515 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1516 50, 73, 110, 48] 1518 A.2.6. Content Encryption 1520 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1521 the encryption key, the JWE Initialization Vector, and the Additional 1522 Authenticated Data value above. The steps for doing this using the 1523 values from Appendix A.3 are detailed in Appendix B. The resulting 1524 Ciphertext is: 1526 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1527 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1528 112, 56, 102] 1530 The resulting Authentication Tag value is: 1532 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1533 191] 1535 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1536 value: 1538 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1540 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1541 Tag) gives this value: 1543 9hH0vgRfYgPnAHOd8stkvw 1545 A.2.7. Complete Representation 1547 Assemble the final representation: The Compact Serialization of this 1548 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1549 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1550 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1551 Authentication Tag). 1553 The final result in this example (with line breaks for display 1554 purposes only) is: 1556 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1557 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1558 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1559 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1560 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1561 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1562 -B3oWh2TbqmScqXMR4gp_A. 1563 AxY8DCtDaGlsbGljb3RoZQ. 1564 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1565 9hH0vgRfYgPnAHOd8stkvw 1567 A.2.8. Validation 1569 This example illustrates the process of creating a JWE with RSAES- 1570 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1571 encryption. These results can be used to validate JWE decryption 1572 implementations for these algorithms. Note that since the RSAES- 1573 PKCS1-V1_5 computation includes random values, the encryption results 1574 above will not be completely reproducible. However, since the AES 1575 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1576 will be the same for all encryptions performed using these inputs. 1578 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1580 This example encrypts the plaintext "Live long and prosper." to the 1581 recipient using AES Key Wrap for key encryption and AES GCM for 1582 content encryption. The representation of this plaintext is: 1584 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1585 112, 114, 111, 115, 112, 101, 114, 46] 1587 A.3.1. JWE Header 1589 The following example JWE Protected Header declares that: 1591 o the Content Encryption Key is encrypted to the recipient using the 1592 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1593 Encrypted Key and 1595 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1596 algorithm to produce the Ciphertext. 1598 {"alg":"A128KW","enc":"A128CBC-HS256"} 1600 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1601 Header)) gives this value: 1603 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1605 A.3.2. Content Encryption Key (CEK) 1607 Generate a 256 bit random Content Encryption Key (CEK). In this 1608 example, the value is: 1610 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1611 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1612 44, 207] 1614 A.3.3. Key Encryption 1616 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1617 algorithm to produce the JWE Encrypted Key. This example uses the 1618 symmetric key represented in JSON Web Key [JWK] format below: 1620 {"kty":"oct", 1621 "k":"GawgguFyGrWKav7AX4VKUg" 1622 } 1624 The resulting JWE Encrypted Key value is: 1626 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1627 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1628 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1630 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1631 this value: 1633 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1635 A.3.4. Initialization Vector 1637 Generate a random 128 bit JWE Initialization Vector. In this 1638 example, the value is: 1640 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1641 101] 1643 Encoding this JWE Initialization Vector as BASE64URL(JWE 1644 Initialization Vector) gives this value: 1646 AxY8DCtDaGlsbGljb3RoZQ 1648 A.3.5. Additional Authenticated Data 1650 Let the Additional Authenticated Data encryption parameter be 1651 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1653 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1654 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1655 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1656 110, 48] 1658 A.3.6. Content Encryption 1660 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1661 the encryption key, the JWE Initialization Vector, and the Additional 1662 Authenticated Data value above. The steps for doing this using the 1663 values from this example are detailed in Appendix B. The resulting 1664 Ciphertext is: 1666 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1667 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1668 112, 56, 102] 1670 The resulting Authentication Tag value is: 1672 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1673 194, 85] 1675 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1676 value: 1678 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1680 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1681 Tag) gives this value: 1683 U0m_YmjN04DJvceFICbCVQ 1685 A.3.7. Complete Representation 1687 Assemble the final representation: The Compact Serialization of this 1688 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1689 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1690 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1691 Authentication Tag). 1693 The final result in this example (with line breaks for display 1694 purposes only) is: 1696 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1697 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1698 AxY8DCtDaGlsbGljb3RoZQ. 1699 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1700 U0m_YmjN04DJvceFICbCVQ 1702 A.3.8. Validation 1704 This example illustrates the process of creating a JWE with AES Key 1705 Wrap for key encryption and AES GCM for content encryption. These 1706 results can be used to validate JWE decryption implementations for 1707 these algorithms. Also, since both the AES Key Wrap and AES GCM 1708 computations are deterministic, the resulting JWE value will be the 1709 same for all encryptions performed using these inputs. Since the 1710 computation is reproducible, these results can also be used to 1711 validate JWE encryption implementations for these algorithms. 1713 A.4. Example JWE using JWE JSON Serialization 1715 This section contains an example using the JWE JSON Serialization. 1716 This example demonstrates the capability for encrypting the same 1717 plaintext to multiple recipients. 1719 Two recipients are present in this example. The algorithm and key 1720 used for the first recipient are the same as that used in 1721 Appendix A.2. The algorithm and key used for the second recipient 1722 are the same as that used in Appendix A.3. The resulting JWE 1723 Encrypted Key values are therefore the same; those computations are 1724 not repeated here. 1726 The Plaintext, the Content Encryption Key (CEK), Initialization 1727 Vector, and JWE Protected Header are shared by all recipients (which 1728 must be the case, since the Ciphertext and Authentication Tag are 1729 also shared). 1731 A.4.1. JWE Per-Recipient Unprotected Headers 1733 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1734 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1735 encrypt the CEK. Key ID values are supplied for both keys. The two 1736 per-recipient header values used to represent these algorithms and 1737 Key IDs are: 1739 {"alg":"RSA1_5","kid":"2011-04-29"} 1741 and 1743 {"alg":"A128KW","kid":"7"} 1745 A.4.2. JWE Protected Header 1747 The Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1748 algorithm to produce the common JWE Ciphertext and JWE Authentication 1749 Tag values. The JWE Protected Header value representing this is: 1751 {"enc":"A128CBC-HS256"} 1753 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1754 Header)) gives this value: 1756 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1758 A.4.3. JWE Unprotected Header 1760 This JWE uses the "jku" Header Parameter to reference a JWK Set. This 1761 is represented in the following JWE Unprotected Header value as: 1763 {"jku":"https://server.example.com/keys.jwks"} 1765 A.4.4. Complete JWE Header Values 1767 Combining the per-recipient, protected, and unprotected header values 1768 supplied, the JWE Header values used for the first and second 1769 recipient respectively are: 1771 {"alg":"RSA1_5", 1772 "kid":"2011-04-29", 1773 "enc":"A128CBC-HS256", 1774 "jku":"https://server.example.com/keys.jwks"} 1776 and 1777 {"alg":"A128KW", 1778 "kid":"7", 1779 "enc":"A128CBC-HS256", 1780 "jku":"https://server.example.com/keys.jwks"} 1782 A.4.5. Additional Authenticated Data 1784 Let the Additional Authenticated Data encryption parameter be 1785 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1787 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1788 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1790 A.4.6. Content Encryption 1792 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1793 the encryption key, the JWE Initialization Vector, and the Additional 1794 Authenticated Data value above. The steps for doing this using the 1795 values from Appendix A.3 are detailed in Appendix B. The resulting 1796 Ciphertext is: 1798 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1799 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1800 112, 56, 102] 1802 The resulting Authentication Tag value is: 1804 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1805 207] 1807 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1808 value: 1810 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1812 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1813 Tag) gives this value: 1815 Mz-VPPyU4RlcuYv1IwIvzw 1817 A.4.7. Complete JWE JSON Serialization Representation 1819 The complete JSON Web Encryption JSON Serialization for these values 1820 is as follows (with line breaks for display purposes only): 1822 {"protected": 1823 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1824 "unprotected": 1825 {"jku":"https://server.example.com/keys.jwks"}, 1826 "recipients":[ 1827 {"header": 1828 {"alg":"RSA1_5"}, 1829 "encrypted_key": 1830 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1831 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1832 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 1833 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 1834 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 1835 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 1836 {"header": 1837 {"alg":"A128KW"}, 1838 "encrypted_key": 1839 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1840 "iv": 1841 "AxY8DCtDaGlsbGljb3RoZQ", 1842 "ciphertext": 1843 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1844 "tag": 1845 "Mz-VPPyU4RlcuYv1IwIvzw" 1846 } 1848 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 1850 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 1851 authenticated encryption computation using the values from the 1852 example in Appendix A.3. As described where this algorithm is 1853 defined in Sections 4.8 and 4.8.3 of JWA, the AES_CBC_HMAC_SHA2 1854 family of algorithms are implemented using Advanced Encryption 1855 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #5 1856 padding to perform the encryption and an HMAC SHA-2 function to 1857 perform the integrity calculation - in this case, HMAC SHA-256. 1859 B.1. Extract MAC_KEY and ENC_KEY from Key 1861 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example is: 1863 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1864 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1865 44, 207] 1867 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 1868 which is: 1870 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1871 206] 1873 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 1874 is: 1876 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 1877 207] 1879 Note that the MAC key comes before the encryption key in the input 1880 key K; this is in the opposite order of the algorithm names in the 1881 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 1883 B.2. Encrypt Plaintext to Create Ciphertext 1885 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 1886 using PKCS #5 padding using the ENC_KEY above. The Plaintext in this 1887 example is: 1889 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1890 112, 114, 111, 115, 112, 101, 114, 46] 1892 The encryption result is as follows, which is the Ciphertext output: 1894 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1895 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1896 112, 56, 102] 1898 B.3. 64 Bit Big Endian Representation of AAD Length 1900 The Additional Authenticated Data (AAD) in this example is: 1902 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1903 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1904 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1905 110, 48] 1907 This AAD is 51 bytes long, which is 408 bits long. The octet string 1908 AL, which is the number of bits in AAD expressed as a big endian 64 1909 bit unsigned integer is: 1911 [0, 0, 0, 0, 0, 0, 1, 152] 1913 B.4. Initialization Vector Value 1915 The Initialization Vector value used in this example is: 1917 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1918 101] 1920 B.5. Create Input to HMAC Computation 1922 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 1923 the AL value. The result of this concatenation is: 1925 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1926 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1927 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1928 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 1929 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 1930 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 1931 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 1933 B.6. Compute HMAC Value 1935 Compute the HMAC SHA-256 of the concatenated value above. This 1936 result M is: 1938 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1939 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 1940 86, 229, 116] 1942 B.7. Truncate HMAC Value to Create Authentication Tag 1944 Use the first half (128 bits) of the HMAC output M as the 1945 Authentication Tag output T. This truncated value is: 1947 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1948 194, 85] 1950 Appendix C. Acknowledgements 1952 Solutions for encrypting JSON content were also explored by JSON 1953 Simple Encryption [JSE] and JavaScript Message Security Format 1954 [I-D.rescorla-jsms], both of which significantly influenced this 1955 draft. This draft attempts to explicitly reuse as many of the 1956 relevant concepts from XML Encryption 1.1 1957 [W3C.CR-xmlenc-core1-20120313] and RFC 5652 [RFC5652] as possible, 1958 while utilizing simple, compact JSON-based data structures. 1960 Special thanks are due to John Bradley and Nat Sakimura for the 1961 discussions that helped inform the content of this specification and 1962 to Eric Rescorla and Joe Hildebrand for allowing the reuse of text 1963 from [I-D.rescorla-jsms] in this document. 1965 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 1966 Jay for validating the examples in this specification. 1968 This specification is the work of the JOSE Working Group, which 1969 includes dozens of active and dedicated participants. In particular, 1970 the following individuals contributed ideas, feedback, and wording 1971 that influenced this specification: 1973 Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick 1974 Hardt, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Tony 1975 Nadalin, Axel Nennker, Emmanuel Raviart, Nat Sakimura, Jim Schaad, 1976 Hannes Tschofenig, and Sean Turner. 1978 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 1979 Sean Turner and Stephen Farrell served as Security area directors 1980 during the creation of this specification. 1982 Appendix D. Document History 1984 [[ to be removed by the RFC Editor before publication as an RFC ]] 1986 -17 1988 o Refined the "typ" and "cty" definitions to always be MIME Media 1989 Types, with the omission of "application/" prefixes recommended 1990 for brevity, addressing issue #50. 1992 o Updated the mandatory-to-implement (MTI) language to say that 1993 general-purpose implementations must implement the single 1994 recipient case for both serializations whereas special-purpose 1995 implementations can implement just one serialization if that meets 1996 the needs of the use cases the implementation is designed for, 1997 addressing issue #176. 1999 o Explicitly named all the logical components of a JWE and defined 2000 the processing rules and serializations in terms of those 2001 components, addressing issues #60, #61, and #62. 2003 o Replaced verbose repetitive phases such as "base64url encode the 2004 octets of the UTF-8 representation of X" with mathematical 2005 notation such as "BASE64URL(UTF8(X))". 2007 o Header Parameters and processing rules occurring in both JWS and 2008 JWE are now referenced in JWS by JWE, rather than duplicated, 2009 addressing issue #57. 2011 o Terms used in multiple documents are now defined in one place and 2012 incorporated by reference. Some lightly used or obvious terms 2013 were also removed. This addresses issue #58. 2015 -16 2017 o Changes to address editorial and minor issues #163, #168, #169, 2018 #170, #172, and #173. 2020 -15 2022 o Clarified that it is an application decision which recipients' 2023 encrypted content must successfully validate for the JWE to be 2024 accepted, addressing issue #35. 2026 o Changes to address editorial issues #34, #164, and #169. 2028 -14 2030 o Clarified that the "protected", "unprotected", "header", "iv", 2031 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2032 JSON Serialization when their values would be empty. Stated that 2033 the "recipients" array must always be present. 2035 -13 2037 o Added an "aad" (Additional Authenticated Data) member for the JWE 2038 JSON Serialization, enabling Additional Authenticated Data to be 2039 supplied that is not double base64url encoded, addressing issue 2040 #29. 2042 -12 2044 o Clarified that the "typ" and "cty" header parameters are used in 2045 an application-specific manner and have no effect upon the JWE 2046 processing. 2048 o Replaced the MIME types "application/jwe+json" and 2049 "application/jwe" with "application/jose+json" and 2050 "application/jose". 2052 o Stated that recipients MUST either reject JWEs with duplicate 2053 Header Parameter Names or use a JSON parser that returns only the 2054 lexically last duplicate member name. 2056 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2057 be with the algorithm descriptions that use them. 2059 o Added a Serializations section with parallel treatment of the JWE 2060 Compact Serialization and the JWE JSON Serialization and also 2061 moved the former Implementation Considerations content there. 2063 o Restored use of the term "AEAD". 2065 o Changed terminology from "block encryption" to "content 2066 encryption". 2068 -11 2070 o Added Key Identification section. 2072 o Removed the Encrypted Key value from the AAD computation since it 2073 is already effectively integrity protected by the encryption 2074 process. The AAD value now only contains the representation of 2075 the JWE Encrypted Header. 2077 o For the JWE JSON Serialization, enable Header Parameter values to 2078 be specified in any of three parameters: the "protected" member 2079 that is integrity protected and shared among all recipients, the 2080 "unprotected" member that is not integrity protected and shared 2081 among all recipients, and the "header" member that is not 2082 integrity protected and specific to a particular recipient. (This 2083 does not affect the JWE Compact Serialization, in which all Header 2084 Parameter values are in a single integrity protected JWE Header 2085 value.) 2087 o Shortened the names "authentication_tag" to "tag" and 2088 "initialization_vector" to "iv" in the JWE JSON Serialization, 2089 addressing issue #20. 2091 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2093 o Removed suggested compact serialization for multiple recipients. 2095 o Changed the MIME type name "application/jwe-js" to 2096 "application/jwe+json", addressing issue #22. 2098 o Tightened the description of the "crit" (critical) header 2099 parameter. 2101 -10 2103 o Changed the JWE processing rules for multiple recipients so that a 2104 single AAD value contains the header parameters and encrypted key 2105 values for all the recipients, enabling AES GCM to be safely used 2106 for multiple recipients. 2108 o Added an appendix suggesting a possible compact serialization for 2109 JWEs with multiple recipients. 2111 -09 2113 o Added JWE JSON Serialization, as specified by 2114 draft-jones-jose-jwe-json-serialization-04. 2116 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2117 parameter value. 2119 o Defined that the default action for header parameters that are not 2120 understood is to ignore them unless specifically designated as 2121 "MUST be understood" or included in the new "crit" (critical) 2122 header parameter list. This addressed issue #6. 2124 o Corrected "x5c" description. This addressed issue #12. 2126 o Changed from using the term "byte" to "octet" when referring to 8 2127 bit values. 2129 o Added Key Management Mode definitions to terminology section and 2130 used the defined terms to provide clearer key management 2131 instructions. This addressed issue #5. 2133 o Added text about preventing the recipient from behaving as an 2134 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2136 o Changed from using the term "Integrity Value" to "Authentication 2137 Tag". 2139 o Changed member name from "integrity_value" to "authentication_tag" 2140 in the JWE JSON Serialization. 2142 o Removed Initialization Vector from the AAD value since it is 2143 already integrity protected by all of the authenticated encryption 2144 algorithms specified in the JWA specification. 2146 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2147 and "A256CBC-HS512". The new algorithms perform the same 2148 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2149 but with the Initialization Vector and Authentication Tag values 2150 remaining separate from the Ciphertext value in the output 2151 representation. Also deleted the header parameters "epu" 2152 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2153 they are no longer used. 2155 -08 2156 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2157 since the term AEAD in the RFC 5116 sense implied the use of a 2158 particular data representation, rather than just referring to the 2159 class of algorithms that perform authenticated encryption with 2160 associated data. 2162 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2163 Tschofenig. Many of these simplified the terminology used. 2165 o Clarified statements of the form "This header parameter is 2166 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2168 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2169 Web Signature and Encryption Header Parameters registry. 2171 o Added seriesInfo information to Internet Draft references. 2173 -07 2175 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2177 o Updated values for example AES CBC calculations. 2179 o Made several local editorial changes to clean up loose ends left 2180 over from to the decision to only support block encryption methods 2181 providing integrity. One of these changes was to explicitly state 2182 that the "enc" (encryption method) algorithm must be an 2183 Authenticated Encryption algorithm with a specified key length. 2185 -06 2187 o Removed the "int" and "kdf" parameters and defined the new 2188 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2189 "A256CBC+HS512" to replace the former uses of AES CBC, which 2190 required the use of separate integrity and key derivation 2191 functions. 2193 o Included additional values in the Concat KDF calculation -- the 2194 desired output size and the algorithm value, and optionally 2195 PartyUInfo and PartyVInfo values. Added the optional header 2196 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2197 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2198 PartyVInfo). Updated the KDF examples accordingly. 2200 o Promoted Initialization Vector from being a header parameter to 2201 being a top-level JWE element. This saves approximately 16 bytes 2202 in the compact serialization, which is a significant savings for 2203 some use cases. Promoting the Initialization Vector out of the 2204 header also avoids repeating this shared value in the JSON 2205 serialization. 2207 o Changed "x5c" (X.509 Certificate Chain) representation from being 2208 a single string to being an array of strings, each containing a 2209 single base64 encoded DER certificate value, representing elements 2210 of the certificate chain. 2212 o Added an AES Key Wrap example. 2214 o Reordered the encryption steps so CMK creation is first, when 2215 required. 2217 o Correct statements in examples about which algorithms produce 2218 reproducible results. 2220 -05 2222 o Support both direct encryption using a shared or agreed upon 2223 symmetric key, and the use of a shared or agreed upon symmetric 2224 key to key wrap the CMK. 2226 o Added statement that "StringOrURI values are compared as case- 2227 sensitive strings with no transformations or canonicalizations 2228 applied". 2230 o Updated open issues. 2232 o Indented artwork elements to better distinguish them from the body 2233 text. 2235 -04 2237 o Refer to the registries as the primary sources of defined values 2238 and then secondarily reference the sections defining the initial 2239 contents of the registries. 2241 o Normatively reference XML Encryption 1.1 2242 [W3C.CR-xmlenc-core1-20120313] for its security considerations. 2244 o Reference draft-jones-jose-jwe-json-serialization instead of 2245 draft-jones-json-web-encryption-json-serialization. 2247 o Described additional open issues. 2249 o Applied editorial suggestions. 2251 -03 2252 o Added the "kdf" (key derivation function) header parameter to 2253 provide crypto agility for key derivation. The default KDF 2254 remains the Concat KDF with the SHA-256 digest function. 2256 o Reordered encryption steps so that the Encoded JWE Header is 2257 always created before it is needed as an input to the 2258 Authenticated Encryption "additional authenticated data" 2259 parameter. 2261 o Added the "cty" (content type) header parameter for declaring type 2262 information about the secured content, as opposed to the "typ" 2263 (type) header parameter, which declares type information about 2264 this object. 2266 o Moved description of how to determine whether a header is for a 2267 JWS or a JWE from the JWT spec to the JWE spec. 2269 o Added complete encryption examples for both Authenticated 2270 Encryption and non-Authenticated Encryption algorithms. 2272 o Added complete key derivation examples. 2274 o Added "Collision Resistant Namespace" to the terminology section. 2276 o Reference ITU.X690.1994 for DER encoding. 2278 o Added Registry Contents sections to populate registry values. 2280 o Numerous editorial improvements. 2282 -02 2284 o When using Authenticated Encryption algorithms (such as AES GCM), 2285 use the "additional authenticated data" parameter to provide 2286 integrity for the header, encrypted key, and ciphertext and use 2287 the resulting "authentication tag" value as the JWE Authentication 2288 Tag. 2290 o Defined KDF output key sizes. 2292 o Generalized text to allow key agreement to be employed as an 2293 alternative to key wrapping or key encryption. 2295 o Changed compression algorithm from gzip to DEFLATE. 2297 o Clarified that it is an error when a "kid" value is included and 2298 no matching key is found. 2300 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2301 rejected. 2303 o Clarified the relationship between "typ" header parameter values 2304 and MIME types. 2306 o Registered application/jwe MIME type and "JWE" typ header 2307 parameter value. 2309 o Simplified JWK terminology to get replace the "JWK Key Object" and 2310 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2311 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2312 between single keys and sets of keys. As part of this change, the 2313 Header Parameter Name for a public key value was changed from 2314 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2316 o Added suggestion on defining additional header parameters such as 2317 "x5t#S256" in the future for certificate thumbprints using hash 2318 algorithms other than SHA-1. 2320 o Specify RFC 2818 server identity validation, rather than RFC 6125 2321 (paralleling the same decision in the OAuth specs). 2323 o Generalized language to refer to Message Authentication Codes 2324 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2325 unless in a context specific to HMAC algorithms. 2327 o Reformatted to give each header parameter its own section heading. 2329 -01 2331 o Added an integrity check for non-Authenticated Encryption 2332 algorithms. 2334 o Added "jpk" and "x5c" header parameters for including JWK public 2335 keys and X.509 certificate chains directly in the header. 2337 o Clarified that this specification is defining the JWE Compact 2338 Serialization. Referenced the new JWE-JS spec, which defines the 2339 JWE JSON Serialization. 2341 o Added text "New header parameters should be introduced sparingly 2342 since an implementation that does not understand a parameter MUST 2343 reject the JWE". 2345 o Clarified that the order of the encryption and decryption steps is 2346 not significant in cases where there are no dependencies between 2347 the inputs and outputs of the steps. 2349 o Made other editorial improvements suggested by JOSE working group 2350 participants. 2352 -00 2354 o Created the initial IETF draft based upon 2355 draft-jones-json-web-encryption-02 with no normative changes. 2357 o Changed terminology to no longer call both digital signatures and 2358 HMACs "signatures". 2360 Authors' Addresses 2362 Michael B. Jones 2363 Microsoft 2365 Email: mbj@microsoft.com 2366 URI: http://self-issued.info/ 2368 Eric Rescorla 2369 RTFM, Inc. 2371 Email: ekr@rtfm.com 2373 Joe Hildebrand 2374 Cisco Systems, Inc. 2376 Email: jhildebr@cisco.com