idnits 2.17.1 draft-ietf-jose-json-web-encryption-18.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 (November 12, 2013) is 3819 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 1369 -- Looks like a reference, but probably isn't: '197' on line 1369 -- Looks like a reference, but probably isn't: '117' on line 1369 -- Looks like a reference, but probably isn't: '252' on line 1369 -- Looks like a reference, but probably isn't: '2' on line 1369 -- Looks like a reference, but probably isn't: '219' on line 1369 -- Looks like a reference, but probably isn't: '233' on line 1369 -- Looks like a reference, but probably isn't: '68' on line 1369 -- Looks like a reference, but probably isn't: '180' on line 1369 -- Looks like a reference, but probably isn't: '225' on line 1369 -- Looks like a reference, but probably isn't: '77' on line 1369 -- Looks like a reference, but probably isn't: '0' on line 1954 -- Looks like a reference, but probably isn't: '1' on line 1954 -- Looks like a reference, but probably isn't: '152' on line 1954 -- 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: May 16, 2014 RTFM 6 J. Hildebrand 7 Cisco 8 November 12, 2013 10 JSON Web Encryption (JWE) 11 draft-ietf-jose-json-web-encryption-18 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 May 16, 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 . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 8 61 3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 10 62 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11 63 4.1. Registered Header Parameter Names . . . . . . . . . . . . 12 64 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 12 65 4.1.2. "enc" (Encryption Method) Header Parameter . . . . . . 12 66 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 13 67 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 13 68 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 13 69 4.1.6. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 14 70 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 71 Parameter . . . . . . . . . . . . . . . . . . . . . . 14 72 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 14 73 4.1.9. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14 74 4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 14 75 4.1.11. "cty" (Content Type) Header Parameter . . . . . . . . 14 76 4.1.12. "crit" (Critical) Header Parameter . . . . . . . . . . 15 77 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15 78 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 15 79 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 15 80 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 15 81 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 17 82 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20 83 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20 84 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 20 85 7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 20 86 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21 87 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 24 88 9. Distinguishing Between JWS and JWE Objects . . . . . . . . . . 24 89 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 90 10.1. JSON Web Signature and Encryption Header Parameters 91 Registration . . . . . . . . . . . . . . . . . . . . . . . 25 92 10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25 93 11. Security Considerations . . . . . . . . . . . . . . . . . . . 26 94 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 95 12.1. Normative References . . . . . . . . . . . . . . . . . . . 27 96 12.2. Informative References . . . . . . . . . . . . . . . . . . 28 97 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 29 98 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 29 99 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 29 100 A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 29 101 A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 30 102 A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 31 103 A.1.5. Additional Authenticated Data . . . . . . . . . . . . 31 104 A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 31 105 A.1.7. Complete Representation . . . . . . . . . . . . . . . 32 106 A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 32 107 A.2. Example JWE using RSAES-PKCS1-V1_5 and 108 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 32 109 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 33 110 A.2.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 33 111 A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 33 112 A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 35 113 A.2.5. Additional Authenticated Data . . . . . . . . . . . . 35 114 A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 35 115 A.2.7. Complete Representation . . . . . . . . . . . . . . . 36 116 A.2.8. Validation . . . . . . . . . . . . . . . . . . . . . . 36 117 A.3. Example JWE using AES Key Wrap and 118 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 36 119 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 36 120 A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 37 121 A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 37 122 A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 38 123 A.3.5. Additional Authenticated Data . . . . . . . . . . . . 38 124 A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 38 125 A.3.7. Complete Representation . . . . . . . . . . . . . . . 39 126 A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 39 127 A.4. Example JWE using JWE JSON Serialization . . . . . . . . . 39 128 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 40 129 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 40 130 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 40 131 A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 40 132 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 41 133 A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 41 134 A.4.7. Complete JWE JSON Serialization Representation . . . . 41 135 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 42 136 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 42 137 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 43 138 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 43 139 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 43 140 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 44 141 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 44 142 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 44 143 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 44 144 Appendix D. Document History . . . . . . . . . . . . . . . . . . 45 145 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 53 147 1. Introduction 149 JSON Web Encryption (JWE) represents encrypted content using 150 JavaScript Object Notation (JSON) [RFC4627] based data structures. 151 The JWE cryptographic mechanisms encrypt and provide integrity 152 protection for an arbitrary sequence of octets. 154 Two closely related serializations for JWE objects are defined. The 155 JWE Compact Serialization is a compact, URL-safe representation 156 intended for space constrained environments such as HTTP 157 Authorization headers and URI query parameters. The JWE JSON 158 Serialization represents JWE objects as JSON objects and enables the 159 same content to be encrypted to multiple parties. Both share the 160 same cryptographic underpinnings. 162 Cryptographic algorithms and identifiers for use with this 163 specification are described in the separate JSON Web Algorithms (JWA) 164 [JWA] specification and IANA registries defined by that 165 specification. Related digital signature and MAC capabilities are 166 described in the separate JSON Web Signature (JWS) [JWS] 167 specification. 169 Names defined by this specification are short because a core goal is 170 for the resulting representations to be compact. 172 1.1. Notational Conventions 174 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 175 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 176 document are to be interpreted as described in Key words for use in 177 RFCs to Indicate Requirement Levels [RFC2119]. If these words are 178 used without being spelled in uppercase then they are to be 179 interpreted with their normal natural language meanings. 181 BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per 182 Section 2. 184 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 185 of STRING. 187 ASCII(STRING) denotes the octets of the ASCII [USASCII] 188 representation of STRING. 190 The concatenation of two values A and B is denoted as A || B. 192 2. Terminology 194 These terms defined by the JSON Web Signature (JWS) [JWS] 195 specification are incorporated into this specification: "JSON Web 196 Signature (JWS)", "Base64url Encoding", "Collision-Resistant Name", 197 and "StringOrURI". 199 These terms are defined for use by this specification: 201 JSON Web Encryption (JWE) A data structure representing an encrypted 202 and integrity protected message. 204 Authenticated Encryption with Associated Data (AEAD) An AEAD 205 algorithm is one that encrypts the Plaintext, allows Additional 206 Authenticated Data to be specified, and provides an integrated 207 content integrity check over the Ciphertext and Additional 208 Authenticated Data. AEAD algorithms accept two inputs, the 209 Plaintext and the Additional Authenticated Data value, and produce 210 two outputs, the Ciphertext and the Authentication Tag value. AES 211 Galois/Counter Mode (GCM) is one such algorithm. 213 Plaintext The sequence of octets to be encrypted -- a.k.a., the 214 message. The plaintext can contain an arbitrary sequence of 215 octets. 217 Ciphertext An encrypted representation of the Plaintext. 219 Additional Authenticated Data (AAD) An input to an AEAD operation 220 that is integrity protected but not encrypted. 222 Authentication Tag An output of an AEAD operation that ensures the 223 integrity of the Ciphertext and the Additional Authenticated Data. 224 Note that some algorithms may not use an Authentication Tag, in 225 which case this value is the empty octet sequence. 227 Content Encryption Key (CEK) A symmetric key for the AEAD algorithm 228 used to encrypt the Plaintext for the recipient to produce the 229 Ciphertext and the Authentication Tag. 231 JWE Header A JSON object (or JSON objects, when using the JWE JSON 232 Serialization) that describes the encryption operations applied to 233 create the JWE Encrypted Key, the JWE Ciphertext, and the JWE 234 Authentication Tag. The members of the JWE Header object(s) are 235 Header Parameters. 237 JWE Encrypted Key The result of encrypting the Content Encryption 238 Key (CEK) with the intended recipient's key using the specified 239 algorithm. Note that for some algorithms, the JWE Encrypted Key 240 value is specified as being the empty octet sequence. 242 JWE Initialization Vector A sequence of octets containing the 243 Initialization Vector used when encrypting the Plaintext. Note 244 that some algorithms may not use an Initialization Vector, in 245 which case this value is the empty octet sequence. 247 JWE Ciphertext A sequence of octets containing the Ciphertext for a 248 JWE. 250 JWE Authentication Tag A sequence of octets containing the 251 Authentication Tag for a JWE. 253 JWE Protected Header A JSON object that contains the portion of the 254 JWE Header that is integrity protected. For the JWE Compact 255 Serialization, this comprises the entire JWE Header. For the JWE 256 JSON Serialization, this is one component of the JWE Header. 258 Header Parameter A name/value pair that is member of the JWE Header. 260 JWE Compact Serialization A representation of the JWE as a compact, 261 URL-safe string. 263 JWE JSON Serialization A representation of the JWE as a JSON object. 264 Unlike the JWE Compact Serialization, the JWE JSON Serialization 265 enables the same content to be encrypted to multiple parties. 266 This representation is neither compact nor URL-safe. 268 Key Management Mode A method of determining the Content Encryption 269 Key (CEK) value to use. Each algorithm used for determining the 270 CEK value uses a specific Key Management Mode. Key Management 271 Modes employed by this specification are Key Encryption, Key 272 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 273 and Direct Encryption. 275 Key Encryption A Key Management Mode in which the Content Encryption 276 Key (CEK) value is encrypted to the intended recipient using an 277 asymmetric encryption algorithm. 279 Key Wrapping A Key Management Mode in which the Content Encryption 280 Key (CEK) value is encrypted to the intended recipient using a 281 symmetric key wrapping algorithm. 283 Direct Key Agreement A Key Management Mode in which a key agreement 284 algorithm is used to agree upon the Content Encryption Key (CEK) 285 value. 287 Key Agreement with Key Wrapping A Key Management Mode in which a key 288 agreement algorithm is used to agree upon a symmetric key used to 289 encrypt the Content Encryption Key (CEK) value to the intended 290 recipient using a symmetric key wrapping algorithm. 292 Direct Encryption A Key Management Mode in which the Content 293 Encryption Key (CEK) value used is the secret symmetric key value 294 shared between the parties. 296 3. JSON Web Encryption (JWE) Overview 298 JWE represents encrypted content using JSON data structures and 299 base64url encoding. A JWE represents these logical values: 301 JWE Header JSON object containing the parameters describing the 302 cryptographic operations and parameters employed. The JWE Header 303 members are the union of the members of the JWE Protected Header, 304 the JWE Shared Unprotected Header, and the JWE Per-Recipient 305 Unprotected Header, as described below. 307 JWE Encrypted Key Encrypted Content Encryption Key (CEK) value. 309 JWE Initialization Vector Initialization Vector value used when 310 encrypting the plaintext. 312 JWE Ciphertext Ciphertext value resulting from authenticated 313 encryption of the plaintext. 315 JWE Authentication Tag Authentication Tag value resulting from 316 authenticated encryption of the plaintext with additional 317 associated data. 319 JWE AAD Additional value to be integrity protected by the 320 authenticated encryption operation. 322 The JWE Header represents the combination of these logical values: 324 JWE Protected Header JSON object containing some of the parameters 325 describing the cryptographic operations and parameters employed. 326 These parameters apply to all recipients of the JWE. This value 327 is integrity protected in the digital signature or MAC calculation 328 of the JWE Signature. 330 JWE Shared Unprotected Header JSON object containing some of the 331 parameters describing the cryptographic operations and parameters 332 employed. These parameters apply to all recipients of the JWE. 333 This value is not integrity protected in the authenticated 334 encryption operation. 336 JWE Per-Recipient Unprotected Header JSON object containing some of 337 the parameters describing the cryptographic operations and 338 parameters employed. These parameters apply to a single recipient 339 of the JWE. This value is not integrity protected in the 340 authenticated encryption operation. 342 This document defines two serializations for JWE objects: a compact, 343 URL-safe serialization called the JWE Compact Serialization and a 344 JSON serialization called the JWE JSON Serialization. In both 345 serializations, the JWE Protected Header, JWE Encrypted Key, JWE 346 Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are 347 base64url encoded for transmission, since JSON lacks a way to 348 directly represent octet sequences. When present, the JWE AAD is 349 also base64url encoded for transmission. 351 In the JWE Compact Serialization, no JWE Shared Unprotected Header or 352 JWE Per-Recipient Unprotected Header are used. In this case, the JWE 353 Header and the JWE Protected Header are the same. 355 In the JWE Compact Serialization, a JWE object is represented as the 356 combination of these five string values, 357 BASE64URL(UTF8(JWE Protected Header)), 358 BASE64URL(JWE Encrypted Key), 359 BASE64URL(JWE Initialization Vector), 360 BASE64URL(JWE Ciphertext), and 361 BASE64URL(JWE Authentication Tag), 362 concatenated in that order, with the five strings being separated by 363 four period ('.') characters. 365 In the JWE JSON Serialization, one or more of the JWE Protected 366 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 367 Unprotected Header MUST be present. In this case, the members of the 368 JWE Header are the combination of the members of the JWE Protected 369 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 370 Unprotected Header values that are present. 372 In the JWE JSON Serialization, a JWE object is represented as the 373 combination of these eight values, 374 BASE64URL(UTF8(JWE Protected Header)), 375 JWE Shared Unprotected Header, 376 JWE Per-Recipient Unprotected Header, 377 BASE64URL(JWE Encrypted Key), 378 BASE64URL(JWE Initialization Vector), 379 BASE64URL(JWE Ciphertext), 380 BASE64URL(JWE Authentication Tag), and 381 BASE64URL(JWE AAD), 382 with the six base64url encoding result strings and the two 383 unprotected JSON object values being represented as members within a 384 JSON object. The inclusion of some of these values is OPTIONAL. The 385 JWE JSON Serialization can also encrypt the plaintext to multiple 386 recipients. See Section 7.2 for more information about the JWE JSON 387 Serialization. 389 JWE utilizes authenticated encryption to ensure the confidentiality 390 and integrity of the Plaintext and the integrity of the JWE Protected 391 Header and the JWE AAD. 393 3.1. Example JWE 395 This example encrypts the plaintext "The true sign of intelligence is 396 not knowledge but imagination." to the recipient using RSAES OAEP for 397 key encryption and AES GCM for content encryption. 399 The following example JWE Protected Header declares that: 401 o the Content Encryption Key is encrypted to the recipient using the 402 RSAES OAEP algorithm to produce the JWE Encrypted Key and 404 o the Plaintext is encrypted using the AES GCM algorithm with a 256 405 bit key to produce the Ciphertext. 407 {"alg":"RSA-OAEP","enc":"A256GCM"} 409 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 410 Header)) gives this value: 412 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 414 The remaining steps to finish creating this JWE are: 416 o Generate a random Content Encryption Key (CEK). 418 o Encrypt the CEK with the recipient's public key using the RSAES 419 OAEP algorithm to produce the JWE Encrypted Key. 421 o Base64url encode the JWE Encrypted Key. 423 o Generate a random JWE Initialization Vector. 425 o Base64url encode the JWE Initialization Vector. 427 o Let the Additional Authenticated Data encryption parameter be 428 ASCII(BASE64URL(UTF8(JWE Protected Header))). 430 o Encrypt the Plaintext with AES GCM using the CEK as the encryption 431 key, the JWE Initialization Vector, and the Additional 432 Authenticated Data value, requesting a 128 bit Authentication Tag 433 output. 435 o Base64url encode the Ciphertext. 437 o Base64url encode the Authentication Tag. 439 o Assemble the final representation: The Compact Serialization of 440 this result is the string BASE64URL(UTF8(JWE Protected Header)) || 441 '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE 442 Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' 443 || BASE64URL(JWE Authentication Tag). 445 The final result in this example (with line breaks for display 446 purposes only) is: 448 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 449 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 450 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 451 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 452 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 453 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 454 6UklfCpIMfIjf7iGdXKHzg. 455 48V1_ALb6US04U3b. 456 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 457 SdiwkIr3ajwQzaBtQD_A. 458 XFBoMYUZodetZdvTiFvSkQ 460 See Appendix A.1 for the complete details of computing this JWE. See 461 Appendix A for additional examples. 463 4. JWE Header 465 The members of the JSON object(s) representing the JWE Header 466 describe the encryption applied to the Plaintext and optionally 467 additional properties of the JWE. The Header Parameter names within 468 the JWE Header MUST be unique; recipients MUST either reject JWEs 469 with duplicate Header Parameter names or use a JSON parser that 470 returns only the lexically last duplicate member name, as specified 471 in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. 473 Implementations are required to understand the specific Header 474 Parameters defined by this specification that are designated as "MUST 475 be understood" and process them in the manner defined in this 476 specification. All other Header Parameters defined by this 477 specification that are not so designated MUST be ignored when not 478 understood. Unless listed as a critical Header Parameter, per 479 Section 4.1.12, all Header Parameters not defined by this 480 specification MUST be ignored when not understood. 482 There are three classes of Header Parameter names: Registered Header 483 Parameter names, Public Header Parameter names, and Private Header 484 Parameter names. 486 4.1. Registered Header Parameter Names 488 The following Header Parameter names are registered in the IANA JSON 489 Web Signature and Encryption Header Parameters registry defined in 490 [JWS], with meanings as defined below. 492 As indicated by the common registry, JWSs and JWEs share a common 493 Header Parameter space; when a parameter is used by both 494 specifications, its usage must be compatible between the 495 specifications. 497 4.1.1. "alg" (Algorithm) Header Parameter 499 This parameter has the same meaning, syntax, and processing rules as 500 the "alg" Header Parameter defined in Section 4.1.1 of [JWS], except 501 that the Header Parameter identifies the cryptographic algorithm used 502 to encrypt or determine the value of the Content Encryption Key 503 (CEK). The encrypted content is not usable if the "alg" value does 504 not represent a supported algorithm, or if the recipient does not 505 have a key that can be used with that algorithm. 507 A list of defined "alg" values for this use can be found in the IANA 508 JSON Web Signature and Encryption Algorithms registry defined in 509 [JWA]; the initial contents of this registry are the values defined 510 in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. 512 4.1.2. "enc" (Encryption Method) Header Parameter 514 The "enc" (encryption method) Header Parameter identifies the content 515 encryption algorithm used to encrypt the Plaintext to produce the 516 Ciphertext. This algorithm MUST be an AEAD algorithm with a 517 specified key length. The recipient MUST reject the JWE if the "enc" 518 value does not represent a supported algorithm. "enc" values should 519 either be registered in the IANA JSON Web Signature and Encryption 520 Algorithms registry defined in [JWA] or be a value that contains a 521 Collision-Resistant Name. The "enc" value is a case-sensitive string 522 containing a StringOrURI value. This Header Parameter MUST be 523 present and MUST be understood and processed by implementations. 525 A list of defined "enc" values for this use can be found in the IANA 526 JSON Web Signature and Encryption Algorithms registry defined in 527 [JWA]; the initial contents of this registry are the values defined 528 in Section 5.1 of the JSON Web Algorithms (JWA) [JWA] specification. 530 4.1.3. "zip" (Compression Algorithm) Header Parameter 532 The "zip" (compression algorithm) applied to the Plaintext before 533 encryption, if any. The "zip" value defined by this specification 534 is: 536 o "DEF" - Compression with the DEFLATE [RFC1951] algorithm 538 Other values MAY be used. Compression algorithm values can be 539 registered in the IANA JSON Web Encryption Compression Algorithm 540 registry defined in [JWA]. The "zip" value is a case-sensitive 541 string. If no "zip" parameter is present, no compression is applied 542 to the Plaintext before encryption. This Header Parameter MUST be 543 integrity protected, and therefore MUST occur only within the JWE 544 Protected Header, when used. Use of this Header Parameter is 545 OPTIONAL. This Header Parameter MUST be understood and processed by 546 implementations. 548 4.1.4. "jku" (JWK Set URL) Header Parameter 550 This parameter has the same meaning, syntax, and processing rules as 551 the "jku" Header Parameter defined in Section 4.1.2 of [JWS], except 552 that the JWK Set resource contains the public key to which the JWE 553 was encrypted; this can be used to determine the private key needed 554 to decrypt the JWE. 556 4.1.5. "jwk" (JSON Web Key) Header Parameter 558 This parameter has the same meaning, syntax, and processing rules as 559 the "jwk" Header Parameter defined in Section 4.1.3 of [JWS], except 560 that the key is the public key to which the JWE was encrypted; this 561 can be used to determine the private key needed to decrypt the JWE. 563 4.1.6. "x5u" (X.509 URL) Header Parameter 565 This parameter has the same meaning, syntax, and processing rules as 566 the "x5u" Header Parameter defined in Section 4.1.4 of [JWS], except 567 that the X.509 public key certificate or certificate chain [RFC5280] 568 contains the public key to which the JWE was encrypted; this can be 569 used to determine the private key needed to decrypt the JWE. 571 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 573 This parameter has the same meaning, syntax, and processing rules as 574 the "x5t" Header Parameter defined in Section 4.1.5 of [JWS], except 575 that certificate referenced by the thumbprint contains the public key 576 to which the JWE was encrypted; this can be used to determine the 577 private key needed to decrypt the JWE. 579 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 581 This parameter has the same meaning, syntax, and processing rules as 582 the "x5c" Header Parameter defined in Section 4.1.6 of [JWS], except 583 that the X.509 public key certificate or certificate chain [RFC5280] 584 contains the public key to which the JWE was encrypted; this can be 585 used to determine the private key needed to decrypt the JWE. 587 See Appendix B of [JWS] for an example "x5c" value. 589 4.1.9. "kid" (Key ID) Header Parameter 591 This parameter has the same meaning, syntax, and processing rules as 592 the "kid" Header Parameter defined in Section 4.1.7 of [JWS], except 593 that the key hint references the public key to which the JWE was 594 encrypted; this can be used to determine the private key needed to 595 decrypt the JWE. This parameter allows originators to explicitly 596 signal a change of key to JWE recipients. 598 4.1.10. "typ" (Type) Header Parameter 600 This parameter has the same meaning, syntax, and processing rules as 601 the "typ" Header Parameter defined in Section 4.1.8 of [JWS], except 602 that the type is of this complete JWE object. 604 4.1.11. "cty" (Content Type) Header Parameter 606 This parameter has the same meaning, syntax, and processing rules as 607 the "cty" Header Parameter defined in Section 4.1.9 of [JWS], except 608 that the type is of the secured content (the payload). 610 4.1.12. "crit" (Critical) Header Parameter 612 This parameter has the same meaning, syntax, and processing rules as 613 the "crit" Header Parameter defined in Section 4.1.10 of [JWS], 614 except that JWE Header Parameters are being referred to, rather than 615 JWS Header Parameters. 617 4.2. Public Header Parameter Names 619 Additional Header Parameter names can be defined by those using JWEs. 620 However, in order to prevent collisions, any new Header Parameter 621 name should either be registered in the IANA JSON Web Signature and 622 Encryption Header Parameters registry defined in [JWS] or be a Public 623 Name: a value that contains a Collision-Resistant Name. In each 624 case, the definer of the name or value needs to take reasonable 625 precautions to make sure they are in control of the part of the 626 namespace they use to define the Header Parameter name. 628 New Header Parameters should be introduced sparingly, as they can 629 result in non-interoperable JWEs. 631 4.3. Private Header Parameter Names 633 A producer and consumer of a JWE may agree to use Header Parameter 634 names that are Private Names: names that are not Registered Header 635 Parameter names Section 4.1 or Public Header Parameter names 636 Section 4.2. Unlike Public Header Parameter names, Private Header 637 Parameter names are subject to collision and should be used with 638 caution. 640 5. Producing and Consuming JWEs 642 5.1. Message Encryption 644 The message encryption process is as follows. The order of the steps 645 is not significant in cases where there are no dependencies between 646 the inputs and outputs of the steps. 648 1. Determine the Key Management Mode employed by the algorithm used 649 to determine the Content Encryption Key (CEK) value. (This is 650 the algorithm recorded in the "alg" (algorithm) Header Parameter 651 of the resulting JWE.) 653 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 654 Wrapping are employed, generate a random Content Encryption Key 655 (CEK) value. See RFC 4086 [RFC4086] for considerations on 656 generating random values. The CEK MUST have a length equal to 657 that required for the content encryption algorithm. 659 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 660 employed, use the key agreement algorithm to compute the value 661 of the agreed upon key. When Direct Key Agreement is employed, 662 let the Content Encryption Key (CEK) be the agreed upon key. 663 When Key Agreement with Key Wrapping is employed, the agreed 664 upon key will be used to wrap the CEK. 666 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 667 Wrapping are employed, encrypt the CEK to the recipient and let 668 the result be the JWE Encrypted Key. 670 5. When Direct Key Agreement or Direct Encryption are employed, let 671 the JWE Encrypted Key be the empty octet sequence. 673 6. When Direct Encryption is employed, let the Content Encryption 674 Key (CEK) be the shared symmetric key. 676 7. Compute the encoded key value BASE64URL(JWE Encrypted Key). 678 8. If the JWE JSON Serialization is being used, repeat this process 679 (steps 1-7) for each recipient. 681 9. Generate a random JWE Initialization Vector of the correct size 682 for the content encryption algorithm (if required for the 683 algorithm); otherwise, let the JWE Initialization Vector be the 684 empty octet sequence. 686 10. Compute the encoded initialization vector value BASE64URL(JWE 687 Initialization Vector). 689 11. If a "zip" parameter was included, compress the Plaintext using 690 the specified compression algorithm. 692 12. Serialize the (compressed) Plaintext into an octet sequence M. 694 13. Create the JSON object(s) containing the desired set of Header 695 Parameters, which together comprise the JWE Header: the JWE 696 Protected Header, and if the JWE JSON Serialization is being 697 used, the JWE Shared Unprotected Header and the JWE Per- 698 Recipient Unprotected Header. 700 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 701 Protected Header)). If the JWE Protected Header is not present 702 (which can only happen when using the JWE JSON Serialization and 703 no "protected" member is present), let this value be the empty 704 string. 706 15. Let the Additional Authenticated Data encryption parameter be 707 ASCII(Encoded Protected Header). However if a JWE AAD value is 708 present (which can only be the case when using the JWE JSON 709 Serialization), instead let the Additional Authenticated Data 710 encryption parameter be ASCII(Encoded Protected Header || '.' || 711 BASE64URL(JWE AAD)). 713 16. Encrypt M using the CEK, the JWE Initialization Vector, and the 714 Additional Authenticated Data value using the specified content 715 encryption algorithm to create the JWE Ciphertext value and the 716 JWE Authentication Tag (which is the Authentication Tag output 717 from the encryption operation). 719 17. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext). 721 18. Compute the encoded authentication tag value BASE64URL(JWE 722 Authentication Tag). 724 19. The five encoded values are used in both the JWE Compact 725 Serialization and the JWE JSON Serialization representations. 727 20. If a JWE AAD value is present, compute the encoded AAD value 728 BASE64URL(JWE AAD). 730 21. Create the desired serialized output. The Compact Serialization 731 of this result is the string BASE64URL(UTF8(JWE Protected 732 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 733 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 734 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). The 735 JWE JSON Serialization is described in Section 7.2. 737 5.2. Message Decryption 739 The message decryption process is the reverse of the encryption 740 process. The order of the steps is not significant in cases where 741 there are no dependencies between the inputs and outputs of the 742 steps. If any of these steps fails, the encrypted content cannot be 743 validated. 745 It is an application decision which recipients' encrypted content 746 must successfully validate for the JWE to be accepted. In some 747 cases, encrypted content for all recipients must successfully 748 validate or the JWE will be rejected. In other cases, only the 749 encrypted content for a single recipient needs to be successfully 750 validated. However, in all cases, the encrypted content for at least 751 one recipient MUST successfully validate or the JWE MUST be rejected. 753 1. Parse the JWE representation to extract the serialized values 754 for the components of the JWE -- when using the JWE Compact 755 Serialization, the base64url encoded representations of the JWE 756 Protected Header, the JWE Encrypted Key, the JWE Initialization 757 Vector, the JWE Ciphertext, and the JWE Authentication Tag, and 758 when using the JWE JSON Serialization, also the base64url 759 encoded representation of the JWE AAD and the unencoded JWE 760 Shared Unprotected Header and JWE Per-Recipient Unprotected 761 Header values. When using the JWE Compact Serialization, the 762 JWE Protected Header, the JWE Encrypted Key, the JWE 763 Initialization Vector, the JWE Ciphertext, and the JWE 764 Authentication Tag are represented as base64url encoded values 765 in that order, separated by four period ('.') characters. The 766 JWE JSON Serialization is described in Section 7.2. 768 2. The encoded representations of the JWE Protected Header, the JWE 769 Encrypted Key, the JWE Initialization Vector, the JWE 770 Ciphertext, the JWE Authentication Tag, and the JWE AAD MUST be 771 successfully base64url decoded following the restriction that no 772 padding characters have been used. 774 3. The octet sequence resulting from decoding the encoded JWE 775 Protected Header MUST be a UTF-8 encoded representation of a 776 completely valid JSON object conforming to RFC 4627 [RFC4627], 777 which is the JWE Protected Header. 779 4. If using the JWE Compact Serialization, let the JWE Header be 780 the JWE Protected Header; otherwise, when using the JWE JSON 781 Serialization, let the JWE Header be the union of the members of 782 the JWE Protected Header, the JWE Shared Unprotected Header and 783 the corresponding JWE Per-Recipient Unprotected Header, all of 784 which must be completely valid JSON objects. 786 5. The resulting JWE Header MUST NOT contain duplicate Header 787 Parameter names. When using the JWE JSON Serialization, this 788 restriction includes that the same Header Parameter name also 789 MUST NOT occur in distinct JSON object values that together 790 comprise the JWE Header. 792 6. Verify that the implementation understands and can process all 793 fields that it is required to support, whether required by this 794 specification, by the algorithms being used, or by the "crit" 795 Header Parameter value, and that the values of those parameters 796 are also understood and supported. 798 7. Determine the Key Management Mode employed by the algorithm 799 specified by the "alg" (algorithm) Header Parameter. 801 8. Verify that the JWE uses a key known to the recipient. 803 9. When Direct Key Agreement or Key Agreement with Key Wrapping are 804 employed, use the key agreement algorithm to compute the value 805 of the agreed upon key. When Direct Key Agreement is employed, 806 let the Content Encryption Key (CEK) be the agreed upon key. 807 When Key Agreement with Key Wrapping is employed, the agreed 808 upon key will be used to decrypt the JWE Encrypted Key. 810 10. When Key Wrapping, Key Encryption, or Key Agreement with Key 811 Wrapping are employed, decrypt the JWE Encrypted Key to produce 812 the Content Encryption Key (CEK). The CEK MUST have a length 813 equal to that required for the content encryption algorithm. 814 Note that when there are multiple recipients, each recipient 815 will only be able decrypt any JWE Encrypted Key values that were 816 encrypted to a key in that recipient's possession. It is 817 therefore normal to only be able to decrypt one of the per- 818 recipient JWE Encrypted Key values to obtain the CEK value. To 819 mitigate the attacks described in RFC 3218 [RFC3218], the 820 recipient MUST NOT distinguish between format, padding, and 821 length errors of encrypted keys. It is strongly recommended, in 822 the event of receiving an improperly formatted key, that the 823 receiver substitute a randomly generated CEK and proceed to the 824 next step, to mitigate timing attacks. 826 11. When Direct Key Agreement or Direct Encryption are employed, 827 verify that the JWE Encrypted Key value is empty octet sequence. 829 12. When Direct Encryption is employed, let the Content Encryption 830 Key (CEK) be the shared symmetric key. 832 13. If the JWE JSON Serialization is being used, repeat this process 833 (steps 1-12) for each recipient contained in the representation 834 until the CEK value has been determined. 836 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 837 Protected Header)). If the JWE Protected Header is not present 838 (which can only happen when using the JWE JSON Serialization and 839 no "protected" member is present), let this value be the empty 840 string. 842 15. Let the Additional Authenticated Data encryption parameter be 843 ASCII(Encoded Protected Header). However if a JWE AAD value is 844 present (which can only be the case when using the JWE JSON 845 Serialization), instead let the Additional Authenticated Data 846 encryption parameter be ASCII(Encoded Protected Header || '.' || 847 BASE64URL(JWE AAD)). 849 16. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 850 Vector, the Additional Authenticated Data value, and the JWE 851 Authentication Tag (which is the Authentication Tag input to the 852 calculation) using the specified content encryption algorithm, 853 returning the decrypted plaintext and verifying the JWE 854 Authentication Tag in the manner specified for the algorithm, 855 rejecting the input without emitting any decrypted output if the 856 JWE Authentication Tag is incorrect. 858 17. If a "zip" parameter was included, uncompress the decrypted 859 plaintext using the specified compression algorithm. 861 18. If all the previous steps succeeded, output the resulting 862 Plaintext. 864 5.3. String Comparison Rules 866 The string comparison rules for this specification are the same as 867 those defined in Section 5.3 of [JWS]. 869 6. Key Identification 871 The key identification methods for this specification are the same as 872 those defined in Section 6 of [JWS], except that the key being 873 identified is the public key to which the JWE was encrypted. 875 7. Serializations 877 JWE objects use one of two serializations, the JWE Compact 878 Serialization or the JWE JSON Serialization. Applications using this 879 specification need to specify what serialization and serialization 880 features are used for that application. For instance, applications 881 might specify that only the JWE JSON Serialization is used, that only 882 JWE JSON Serialization support for a single recipient is used, or 883 that support for multiple recipients is used. JWE implementations 884 only need to implement the features needed for the applications they 885 are designed to support. 887 7.1. JWE Compact Serialization 889 The JWE Compact Serialization represents encrypted content as a 890 compact URL-safe string. This string is BASE64URL(UTF8(JWE Protected 891 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 892 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 893 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). Only one 894 recipient is supported by the JWE Compact Serialization and it 895 provides no syntax to represent JWE Shared Unprotected Header, JWE 896 Per-Recipient Unprotected Header, or JWE AAD values. 898 7.2. JWE JSON Serialization 900 The JWE JSON Serialization represents encrypted content as a JSON 901 object. Unlike the JWE Compact Serialization, content using the JWE 902 JSON Serialization can be encrypted to more than one recipient. 904 The representation is closely related to that used in the JWE Compact 905 Serialization, with the following differences for the JWE JSON 906 Serialization: 908 o Values in the JWE JSON Serialization are represented as members of 909 a JSON object, rather than as base64url encoded strings separated 910 by period ('.') characters. (However binary values and values 911 that are integrity protected are still base64url encoded.) 913 o The value BASE64URL(UTF8(JWE Protected Header)), if non-empty, is 914 stored in the "protected" member. 916 o The value BASE64URL(UTF8(JWE Shared Unprotected Header)), if non- 917 empty, is stored in the "unprotected" member. 919 o The value BASE64URL(JWE Initialization Vector), if non-empty, is 920 stored in the "iv" member. 922 o The value BASE64URL(JWE Ciphertext) is stored in the "ciphertext" 923 member. 925 o The value BASE64URL(JWE Authentication Tag), if non-empty, is 926 stored in the "tag" member. 928 o The JWE can be encrypted to multiple recipients, rather than just 929 one. A JSON array in the "recipients" member is used to hold 930 values that are specific to a particular recipient, with one array 931 element per recipient represented. These array elements are JSON 932 objects. 934 o Each value BASE64URL(JWE Encrypted Key), if non-empty, is stored 935 in the "encrypted_key" member of a JSON object that is an element 936 of the "recipients" array. 938 o Some Header Parameter values, such as the "alg" value and 939 parameters used for selecting keys, can also differ for different 940 recipient computations. JWE Per-Recipient Unprotected Header 941 values, if present, are stored in the "header" members of the same 942 JSON objects that are elements of the "recipients" array. 944 o Some Header Parameters, including the "alg" parameter, can be 945 shared among all recipient computations. Header Parameters in the 946 JWE Protected Header and JWE Shared Unprotected Header values are 947 shared among all recipients. 949 o Not all Header Parameters are integrity protected. The shared 950 Header Parameters in the JWE Protected Header value member are 951 integrity protected, and are base64url encoded for transmission. 952 The per-recipient Header Parameters in the JWE Per-Recipient 953 Unprotected Header values and the shared Header Parameters in the 954 JWE Shared Unprotected Header value are not integrity protected. 955 These JSON objects containing Header Parameters that are not 956 integrity protected are not base64url encoded. 958 o The Header Parameter values used when creating or validating per- 959 recipient Ciphertext and Authentication Tag values are the union 960 of the three sets of Header Parameter values that may be present: 961 (1) the JWE Protected Header values represented in the "protected" 962 member, (2) the JWE Shared Unprotected Header values represented 963 in the "unprotected" member, and (3) the JWE Per-Recipient 964 Unprotected Header values represented in the "header" member of 965 the recipient's array element. The union of these sets of Header 966 Parameters comprises the JWE Header. The Header Parameter names 967 in the three locations MUST be disjoint. 969 o A JWE AAD value can be included to supply a base64url encoded 970 value to be integrity protected but not encrypted. (Note that 971 this can also be achieved when using either serialization by 972 including the AAD value as a protected Header Parameter value, but 973 at the cost of the value being double base64url encoded.) If a 974 JWE AAD value is present, the value BASE64URL(JWE AAD)) is stored 975 in the "aad" member. 977 o The "recipients" array MUST always be present, even if the array 978 elements contain only the empty JSON object "{}" (which can happen 979 when all Header Parameter values are shared between all recipients 980 and when no encrypted key is used, such as when doing Direct 981 Encryption). 983 The syntax of a JWE using the JWE JSON Serialization is as follows: 985 {"protected":", 986 "unprotected":", 987 "recipients":[ 988 {"header":"", 989 "encrypted_key":""}, 990 ... 991 {"header":"", 992 "encrypted_key":""}], 993 "aad":"", 994 "iv":"", 995 "ciphertext":"", 996 "tag":"" 997 } 999 Of these members, only the "ciphertext" member MUST be present. The 1000 "iv", "tag", and "encrypted_key" members MUST be present when 1001 corresponding JWE Initialization Vector, JWE Authentication Tag, and 1002 JWE Encrypted Key values are non-empty. The "recipients" member MUST 1003 be present when any "header" or "encrypted_key" members are needed 1004 for recipients. At least one of the "header", "protected", and 1005 "unprotected" members MUST be present so that "alg" and "enc" Header 1006 Parameter values are conveyed for each recipient computation. 1008 The contents of the JWE Encrypted Key, JWE Initialization Vector, JWE 1009 Ciphertext, and JWE Authentication Tag values are exactly as defined 1010 in the rest of this specification. They are interpreted and 1011 validated in the same manner, with each corresponding JWE Encrypted 1012 Key, JWE Initialization Vector, JWE Ciphertext, JWE Authentication 1013 Tag, and set of Header Parameter values being created and validated 1014 together. The JWE Header values used are the union of the Header 1015 Parameters in the JWE Protected Header, JWE Shared Unprotected 1016 Header, and corresponding JWE Per-Recipient Unprotected Header 1017 values, as described earlier. 1019 Each JWE Encrypted Key value is computed using the parameters of the 1020 corresponding JWE Header value in the same manner as for the JWE 1021 Compact Serialization. This has the desirable property that each JWE 1022 Encrypted Key value in the "recipients" array is identical to the 1023 value that would have been computed for the same parameter in the JWE 1024 Compact Serialization. Likewise, the JWE Ciphertext and JWE 1025 Authentication Tag values match those produced for the JWE Compact 1026 Serialization, provided that the JWE Protected Header value (which 1027 represents the integrity-protected Header Parameter values) matches 1028 that used in the JWE Compact Serialization. 1030 All recipients use the same JWE Protected Header, JWE Initialization 1031 Vector, JWE Ciphertext, and JWE Authentication Tag values, resulting 1032 in potentially significant space savings if the message is large. 1033 Therefore, all Header Parameters that specify the treatment of the 1034 Plaintext value MUST be the same for all recipients. This primarily 1035 means that the "enc" (encryption method) Header Parameter value in 1036 the JWE Header for each recipient and any parameters of that 1037 algorithm MUST be the same. 1039 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1040 Serialization. 1042 8. TLS Requirements 1044 The TLS requirements for this specification are the same as those 1045 defined in Section 8 of [JWS]. 1047 9. Distinguishing Between JWS and JWE Objects 1049 There are several ways of distinguishing whether an object is a JWS 1050 or JWE object. All these methods will yield the same result for all 1051 legal input values; they may yield different results for malformed 1052 inputs. 1054 o If the object is using the JWS Compact Serialization or the JWE 1055 Compact Serialization, the number of base64url encoded segments 1056 separated by period ('.') characters differs for JWSs and JWEs. 1057 JWSs have three segments separated by two period ('.') characters. 1058 JWEs have five segments separated by four period ('.') characters. 1060 o If the object is using the JWS JSON Serialization or the JWE JSON 1061 Serialization, the members used will be different. JWSs have a 1062 "signatures" member and JWEs do not. JWEs have a "recipients" 1063 member and JWSs do not. 1065 o A JWS Header can be distinguished from a JWE header by examining 1066 the "alg" (algorithm) Header Parameter value. If the value 1067 represents a digital signature or MAC algorithm, or is the value 1068 "none", it is for a JWS; if it represents a Key Encryption, Key 1069 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 1070 or Direct Encryption algorithm, it is for a JWE. (Extracting the 1071 "alg" value to examine is straightforward when using the JWS 1072 Compact Serialization or the JWE Compact Serialization and may be 1073 more difficult when using the JWS JSON Serialization or the JWE 1074 JSON Serialization.) 1076 o A JWS Header can also be distinguished from a JWE header by 1077 determining whether an "enc" (encryption method) member exists. 1078 If the "enc" member exists, it is a JWE; otherwise, it is a JWS. 1080 10. IANA Considerations 1082 10.1. JSON Web Signature and Encryption Header Parameters Registration 1084 This specification registers the Header Parameter names defined in 1085 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1086 Parameters registry defined in [JWS]. 1088 10.1.1. Registry Contents 1090 o Header Parameter Name: "alg" 1091 o Header Parameter Description: Algorithm 1092 o Header Parameter Usage Location(s): JWE 1093 o Change Controller: IESG 1094 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1096 o Header Parameter Name: "enc" 1097 o Header Parameter Description: Encryption Method 1098 o Header Parameter Usage Location(s): JWE 1099 o Change Controller: IESG 1100 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1102 o Header Parameter Name: "zip" 1103 o Header Parameter Description: Compression Algorithm 1104 o Header Parameter Usage Location(s): JWE 1105 o Change Controller: IESG 1106 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1108 o Header Parameter Name: "jku" 1109 o Header Parameter Description: JWK Set URL 1110 o Header Parameter Usage Location(s): JWE 1111 o Change Controller: IESG 1112 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1114 o Header Parameter Name: "jwk" 1115 o Header Parameter Description: JSON Web Key 1116 o Header Parameter Usage Location(s): JWE 1117 o Change Controller: IESG 1118 o Specification document(s): Section 4.1.5 of [[ this document ]] 1120 o Header Parameter Name: "x5u" 1121 o Header Parameter Description: X.509 URL 1122 o Header Parameter Usage Location(s): JWE 1123 o Change Controller: IESG 1124 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1126 o Header Parameter Name: "x5t" 1127 o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint 1128 o Header Parameter Usage Location(s): JWE 1129 o Change Controller: IESG 1130 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1132 o Header Parameter Name: "x5c" 1133 o Header Parameter Description: X.509 Certificate Chain 1134 o Header Parameter Usage Location(s): JWE 1135 o Change Controller: IESG 1136 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1138 o Header Parameter Name: "kid" 1139 o Header Parameter Description: Key ID 1140 o Header Parameter Usage Location(s): JWE 1141 o Change Controller: IESG 1142 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1144 o Header Parameter Name: "typ" 1145 o Header Parameter Description: Type 1146 o Header Parameter Usage Location(s): JWE 1147 o Change Controller: IESG 1148 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1150 o Header Parameter Name: "cty" 1151 o Header Parameter Description: Content Type 1152 o Header Parameter Usage Location(s): JWE 1153 o Change Controller: IESG 1154 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1156 o Header Parameter Name: "crit" 1157 o Header Parameter Description: Critical 1158 o Header Parameter Usage Location(s): JWE 1159 o Change Controller: IESG 1160 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1162 11. Security Considerations 1164 All of the security issues faced by any cryptographic application 1165 must be faced by a JWS/JWE/JWK agent. Among these issues are 1166 protecting the user's private and symmetric keys, preventing various 1167 attacks, and helping the user avoid mistakes such as inadvertently 1168 encrypting a message for the wrong recipient. The entire list of 1169 security considerations is beyond the scope of this document. 1171 All the security considerations in the JWS specification also apply 1172 to this specification. Likewise, all the security considerations in 1173 XML Encryption 1.1 [W3C.CR-xmlenc-core1-20120313] also apply, other 1174 than those that are XML specific. 1176 When decrypting, particular care must be taken not to allow the JWE 1177 recipient to be used as an oracle for decrypting messages. RFC 3218 1178 [RFC3218] should be consulted for specific countermeasures to attacks 1179 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1180 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1181 formatting error that can be detected and used to recover the CEK 1182 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1183 particularly important to report all formatting errors to the CEK, 1184 Additional Authenticated Data, or ciphertext as a single error when 1185 the encrypted content is rejected. 1187 Additionally, this type of attack can be prevented by the use of "key 1188 tainting". This method restricts the use of a key to a limited set 1189 of algorithms -- usually one. This means, for instance, that if the 1190 key is marked as being for "RSA-OAEP" only, any attempt to decrypt a 1191 message using the "RSA1_5" algorithm with that key would fail 1192 immediately due to invalid use of the key. 1194 12. References 1196 12.1. Normative References 1198 [ECMAScript] 1199 Ecma International, "ECMAScript Language Specification, 1200 5.1 Edition", ECMA 262, June 2011. 1202 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1203 draft-ietf-jose-json-web-algorithms (work in progress), 1204 November 2013. 1206 [JWK] Jones, M., "JSON Web Key (JWK)", 1207 draft-ietf-jose-json-web-key (work in progress), 1208 November 2013. 1210 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1211 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1212 in progress), November 2013. 1214 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1215 version 1.3", RFC 1951, May 1996. 1217 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1218 Requirement Levels", BCP 14, RFC 2119, March 1997. 1220 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1221 10646", STD 63, RFC 3629, November 2003. 1223 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1224 Requirements for Security", BCP 106, RFC 4086, June 2005. 1226 [RFC4627] Crockford, D., "The application/json Media Type for 1227 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1229 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1230 Housley, R., and W. Polk, "Internet X.509 Public Key 1231 Infrastructure Certificate and Certificate Revocation List 1232 (CRL) Profile", RFC 5280, May 2008. 1234 [USASCII] American National Standards Institute, "Coded Character 1235 Set -- 7-bit American Standard Code for Information 1236 Interchange", ANSI X3.4, 1986. 1238 [W3C.CR-xmlenc-core1-20120313] 1239 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 1240 "XML Encryption Syntax and Processing Version 1.1", World 1241 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1242 March 2012, 1243 . 1245 12.2. Informative References 1247 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1248 McGrew, D. and K. Paterson, "Authenticated Encryption with 1249 AES-CBC and HMAC-SHA", 1250 draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), 1251 October 2012. 1253 [I-D.rescorla-jsms] 1254 Rescorla, E. and J. Hildebrand, "JavaScript Message 1255 Security Format", draft-rescorla-jsms-00 (work in 1256 progress), March 2011. 1258 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1259 Encryption", September 2010. 1261 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1262 Cryptographic Message Syntax", RFC 3218, January 2002. 1264 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1265 RFC 5652, September 2009. 1267 Appendix A. JWE Examples 1269 This section provides examples of JWE computations. 1271 A.1. Example JWE using RSAES OAEP and AES GCM 1273 This example encrypts the plaintext "The true sign of intelligence is 1274 not knowledge but imagination." to the recipient using RSAES OAEP for 1275 key encryption and AES GCM for content encryption. The 1276 representation of this plaintext is: 1278 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1279 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1280 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1281 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1282 110, 97, 116, 105, 111, 110, 46] 1284 A.1.1. JWE Header 1286 The following example JWE Protected Header declares that: 1288 o the Content Encryption Key is encrypted to the recipient using the 1289 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1291 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1292 bit key to produce the Ciphertext. 1294 {"alg":"RSA-OAEP","enc":"A256GCM"} 1296 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1297 Header)) gives this value: 1299 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1301 A.1.2. Content Encryption Key (CEK) 1303 Generate a 256 bit random Content Encryption Key (CEK). In this 1304 example, the value is: 1306 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1307 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1308 234, 64, 252] 1310 A.1.3. Key Encryption 1312 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1313 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1314 key represented in JSON Web Key [JWK] format below (with line breaks 1315 for display purposes only): 1317 {"kty":"RSA", 1318 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1319 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1320 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1321 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1322 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1323 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1324 "e":"AQAB", 1325 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1326 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1327 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1328 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1329 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1330 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ" 1331 } 1333 The resulting JWE Encrypted Key value is: 1335 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1336 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1337 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1338 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1339 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1340 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1341 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1342 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1343 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1344 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1345 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1346 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1347 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1348 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1349 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1350 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1351 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1352 117, 114, 135, 206] 1354 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1355 this value (with line breaks for display purposes only): 1357 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1358 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1359 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1360 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1361 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1362 6UklfCpIMfIjf7iGdXKHzg 1364 A.1.4. Initialization Vector 1366 Generate a random 96 bit JWE Initialization Vector. In this example, 1367 the value is: 1369 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1371 Encoding this JWE Initialization Vector as BASE64URL(JWE 1372 Initialization Vector) gives this value: 1374 48V1_ALb6US04U3b 1376 A.1.5. Additional Authenticated Data 1378 Let the Additional Authenticated Data encryption parameter be 1379 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1381 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1382 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1383 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1385 A.1.6. Content Encryption 1387 Encrypt the Plaintext with AES GCM using the CEK as the encryption 1388 key, the JWE Initialization Vector, and the Additional Authenticated 1389 Data value above, requesting a 128 bit Authentication Tag output. 1390 The resulting Ciphertext is: 1392 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1393 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1394 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1395 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1396 160, 109, 64, 63, 192] 1398 The resulting Authentication Tag value is: 1400 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1401 210, 145] 1403 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1404 value (with line breaks for display purposes only): 1406 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1407 SdiwkIr3ajwQzaBtQD_A 1409 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1410 Tag) gives this value: 1412 XFBoMYUZodetZdvTiFvSkQ 1414 A.1.7. Complete Representation 1416 Assemble the final representation: The Compact Serialization of this 1417 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1418 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1419 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1420 Authentication Tag). 1422 The final result in this example (with line breaks for display 1423 purposes only) is: 1425 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1426 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1427 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1428 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1429 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1430 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1431 6UklfCpIMfIjf7iGdXKHzg. 1432 48V1_ALb6US04U3b. 1433 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1434 SdiwkIr3ajwQzaBtQD_A. 1435 XFBoMYUZodetZdvTiFvSkQ 1437 A.1.8. Validation 1439 This example illustrates the process of creating a JWE with RSAES 1440 OAEP for key encryption and AES GCM for content encryption. These 1441 results can be used to validate JWE decryption implementations for 1442 these algorithms. Note that since the RSAES OAEP computation 1443 includes random values, the encryption results above will not be 1444 completely reproducible. However, since the AES GCM computation is 1445 deterministic, the JWE Encrypted Ciphertext values will be the same 1446 for all encryptions performed using these inputs. 1448 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1450 This example encrypts the plaintext "Live long and prosper." to the 1451 recipient using RSAES-PKCS1-V1_5 for key encryption and 1452 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1453 of this plaintext is: 1455 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1456 112, 114, 111, 115, 112, 101, 114, 46] 1458 A.2.1. JWE Header 1460 The following example JWE Protected Header declares that: 1462 o the Content Encryption Key is encrypted to the recipient using the 1463 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1465 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1466 algorithm to produce the Ciphertext. 1468 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1470 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1471 Header)) gives this value: 1473 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1475 A.2.2. Content Encryption Key (CEK) 1477 Generate a 256 bit random Content Encryption Key (CEK). In this 1478 example, the key value is: 1480 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1481 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1482 44, 207] 1484 A.2.3. Key Encryption 1486 Encrypt the CEK with the recipient's public key using the RSAES- 1487 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1488 uses the RSA key represented in JSON Web Key [JWK] format below (with 1489 line breaks for display purposes only): 1491 {"kty":"RSA", 1492 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1493 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1494 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1495 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1496 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1497 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1498 "e":"AQAB", 1499 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1500 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1501 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1502 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1503 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1504 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1505 } 1507 The resulting JWE Encrypted Key value is: 1509 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1510 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1511 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1512 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1513 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1514 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1515 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1516 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1517 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1518 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1519 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1520 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1521 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1522 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1523 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1524 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1525 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1526 146, 114, 165, 204, 71, 136, 41, 252] 1528 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1529 this value (with line breaks for display purposes only): 1531 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1532 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1533 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1534 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1535 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1536 -B3oWh2TbqmScqXMR4gp_A 1538 A.2.4. Initialization Vector 1540 Generate a random 128 bit JWE Initialization Vector. In this 1541 example, the value is: 1543 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1544 101] 1546 Encoding this JWE Initialization Vector as BASE64URL(JWE 1547 Initialization Vector) gives this value: 1549 AxY8DCtDaGlsbGljb3RoZQ 1551 A.2.5. Additional Authenticated Data 1553 Let the Additional Authenticated Data encryption parameter be 1554 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1556 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1557 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1558 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1559 50, 73, 110, 48] 1561 A.2.6. Content Encryption 1563 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1564 the encryption key, the JWE Initialization Vector, and the Additional 1565 Authenticated Data value above. The steps for doing this using the 1566 values from Appendix A.3 are detailed in Appendix B. The resulting 1567 Ciphertext is: 1569 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1570 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1571 112, 56, 102] 1573 The resulting Authentication Tag value is: 1575 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1576 191] 1578 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1579 value: 1581 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1583 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1584 Tag) gives this value: 1586 9hH0vgRfYgPnAHOd8stkvw 1588 A.2.7. Complete Representation 1590 Assemble the final representation: The Compact Serialization of this 1591 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1592 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1593 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1594 Authentication Tag). 1596 The final result in this example (with line breaks for display 1597 purposes only) is: 1599 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1600 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1601 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1602 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1603 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1604 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1605 -B3oWh2TbqmScqXMR4gp_A. 1606 AxY8DCtDaGlsbGljb3RoZQ. 1607 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1608 9hH0vgRfYgPnAHOd8stkvw 1610 A.2.8. Validation 1612 This example illustrates the process of creating a JWE with RSAES- 1613 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1614 encryption. These results can be used to validate JWE decryption 1615 implementations for these algorithms. Note that since the RSAES- 1616 PKCS1-V1_5 computation includes random values, the encryption results 1617 above will not be completely reproducible. However, since the AES 1618 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1619 will be the same for all encryptions performed using these inputs. 1621 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1623 This example encrypts the plaintext "Live long and prosper." to the 1624 recipient using AES Key Wrap for key encryption and AES GCM for 1625 content encryption. The representation of this plaintext is: 1627 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1628 112, 114, 111, 115, 112, 101, 114, 46] 1630 A.3.1. JWE Header 1632 The following example JWE Protected Header declares that: 1634 o the Content Encryption Key is encrypted to the recipient using the 1635 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1636 Encrypted Key and 1638 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1639 algorithm to produce the Ciphertext. 1641 {"alg":"A128KW","enc":"A128CBC-HS256"} 1643 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1644 Header)) gives this value: 1646 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1648 A.3.2. Content Encryption Key (CEK) 1650 Generate a 256 bit random Content Encryption Key (CEK). In this 1651 example, the value is: 1653 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1654 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1655 44, 207] 1657 A.3.3. Key Encryption 1659 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1660 algorithm to produce the JWE Encrypted Key. This example uses the 1661 symmetric key represented in JSON Web Key [JWK] format below: 1663 {"kty":"oct", 1664 "k":"GawgguFyGrWKav7AX4VKUg" 1665 } 1667 The resulting JWE Encrypted Key value is: 1669 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1670 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1671 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1673 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1674 this value: 1676 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1678 A.3.4. Initialization Vector 1680 Generate a random 128 bit JWE Initialization Vector. In this 1681 example, the value is: 1683 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1684 101] 1686 Encoding this JWE Initialization Vector as BASE64URL(JWE 1687 Initialization Vector) gives this value: 1689 AxY8DCtDaGlsbGljb3RoZQ 1691 A.3.5. Additional Authenticated Data 1693 Let the Additional Authenticated Data encryption parameter be 1694 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1696 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1697 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1698 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1699 110, 48] 1701 A.3.6. Content Encryption 1703 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1704 the encryption key, the JWE Initialization Vector, and the Additional 1705 Authenticated Data value above. The steps for doing this using the 1706 values from this example are detailed in Appendix B. The resulting 1707 Ciphertext is: 1709 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1710 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1711 112, 56, 102] 1713 The resulting Authentication Tag value is: 1715 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1716 194, 85] 1718 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1719 value: 1721 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1723 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1724 Tag) gives this value: 1726 U0m_YmjN04DJvceFICbCVQ 1728 A.3.7. Complete Representation 1730 Assemble the final representation: The Compact Serialization of this 1731 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1732 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1733 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1734 Authentication Tag). 1736 The final result in this example (with line breaks for display 1737 purposes only) is: 1739 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1740 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1741 AxY8DCtDaGlsbGljb3RoZQ. 1742 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1743 U0m_YmjN04DJvceFICbCVQ 1745 A.3.8. Validation 1747 This example illustrates the process of creating a JWE with AES Key 1748 Wrap for key encryption and AES GCM for content encryption. These 1749 results can be used to validate JWE decryption implementations for 1750 these algorithms. Also, since both the AES Key Wrap and AES GCM 1751 computations are deterministic, the resulting JWE value will be the 1752 same for all encryptions performed using these inputs. Since the 1753 computation is reproducible, these results can also be used to 1754 validate JWE encryption implementations for these algorithms. 1756 A.4. Example JWE using JWE JSON Serialization 1758 This section contains an example using the JWE JSON Serialization. 1759 This example demonstrates the capability for encrypting the same 1760 plaintext to multiple recipients. 1762 Two recipients are present in this example. The algorithm and key 1763 used for the first recipient are the same as that used in 1764 Appendix A.2. The algorithm and key used for the second recipient 1765 are the same as that used in Appendix A.3. The resulting JWE 1766 Encrypted Key values are therefore the same; those computations are 1767 not repeated here. 1769 The Plaintext, the Content Encryption Key (CEK), Initialization 1770 Vector, and JWE Protected Header are shared by all recipients (which 1771 must be the case, since the Ciphertext and Authentication Tag are 1772 also shared). 1774 A.4.1. JWE Per-Recipient Unprotected Headers 1776 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1777 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1778 encrypt the CEK. Key ID values are supplied for both keys. The two 1779 per-recipient header values used to represent these algorithms and 1780 Key IDs are: 1782 {"alg":"RSA1_5","kid":"2011-04-29"} 1784 and 1786 {"alg":"A128KW","kid":"7"} 1788 A.4.2. JWE Protected Header 1790 The Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1791 algorithm to produce the common JWE Ciphertext and JWE Authentication 1792 Tag values. The JWE Protected Header value representing this is: 1794 {"enc":"A128CBC-HS256"} 1796 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1797 Header)) gives this value: 1799 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1801 A.4.3. JWE Unprotected Header 1803 This JWE uses the "jku" Header Parameter to reference a JWK Set. This 1804 is represented in the following JWE Unprotected Header value as: 1806 {"jku":"https://server.example.com/keys.jwks"} 1808 A.4.4. Complete JWE Header Values 1810 Combining the per-recipient, protected, and unprotected header values 1811 supplied, the JWE Header values used for the first and second 1812 recipient respectively are: 1814 {"alg":"RSA1_5", 1815 "kid":"2011-04-29", 1816 "enc":"A128CBC-HS256", 1817 "jku":"https://server.example.com/keys.jwks"} 1819 and 1820 {"alg":"A128KW", 1821 "kid":"7", 1822 "enc":"A128CBC-HS256", 1823 "jku":"https://server.example.com/keys.jwks"} 1825 A.4.5. Additional Authenticated Data 1827 Let the Additional Authenticated Data encryption parameter be 1828 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1830 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1831 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1833 A.4.6. Content Encryption 1835 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1836 the encryption key, the JWE Initialization Vector, and the Additional 1837 Authenticated Data value above. The steps for doing this using the 1838 values from Appendix A.3 are detailed in Appendix B. The resulting 1839 Ciphertext is: 1841 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1842 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1843 112, 56, 102] 1845 The resulting Authentication Tag value is: 1847 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1848 207] 1850 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1851 value: 1853 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1855 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1856 Tag) gives this value: 1858 Mz-VPPyU4RlcuYv1IwIvzw 1860 A.4.7. Complete JWE JSON Serialization Representation 1862 The complete JSON Web Encryption JSON Serialization for these values 1863 is as follows (with line breaks for display purposes only): 1865 {"protected": 1866 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1867 "unprotected": 1868 {"jku":"https://server.example.com/keys.jwks"}, 1869 "recipients":[ 1870 {"header": 1871 {"alg":"RSA1_5"}, 1872 "encrypted_key": 1873 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1874 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1875 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 1876 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 1877 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 1878 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 1879 {"header": 1880 {"alg":"A128KW"}, 1881 "encrypted_key": 1882 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1883 "iv": 1884 "AxY8DCtDaGlsbGljb3RoZQ", 1885 "ciphertext": 1886 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1887 "tag": 1888 "Mz-VPPyU4RlcuYv1IwIvzw" 1889 } 1891 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 1893 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 1894 authenticated encryption computation using the values from the 1895 example in Appendix A.3. As described where this algorithm is 1896 defined in Sections 4.8 and 4.8.3 of JWA, the AES_CBC_HMAC_SHA2 1897 family of algorithms are implemented using Advanced Encryption 1898 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #5 1899 padding to perform the encryption and an HMAC SHA-2 function to 1900 perform the integrity calculation - in this case, HMAC SHA-256. 1902 B.1. Extract MAC_KEY and ENC_KEY from Key 1904 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example is: 1906 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1907 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1908 44, 207] 1910 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 1911 which is: 1913 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1914 206] 1916 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 1917 is: 1919 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 1920 207] 1922 Note that the MAC key comes before the encryption key in the input 1923 key K; this is in the opposite order of the algorithm names in the 1924 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 1926 B.2. Encrypt Plaintext to Create Ciphertext 1928 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 1929 using PKCS #5 padding using the ENC_KEY above. The Plaintext in this 1930 example is: 1932 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1933 112, 114, 111, 115, 112, 101, 114, 46] 1935 The encryption result is as follows, which is the Ciphertext output: 1937 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1938 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1939 112, 56, 102] 1941 B.3. 64 Bit Big Endian Representation of AAD Length 1943 The Additional Authenticated Data (AAD) in this example is: 1945 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1946 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1947 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1948 110, 48] 1950 This AAD is 51 bytes long, which is 408 bits long. The octet string 1951 AL, which is the number of bits in AAD expressed as a big endian 64 1952 bit unsigned integer is: 1954 [0, 0, 0, 0, 0, 0, 1, 152] 1956 B.4. Initialization Vector Value 1958 The Initialization Vector value used in this example is: 1960 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1961 101] 1963 B.5. Create Input to HMAC Computation 1965 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 1966 the AL value. The result of this concatenation is: 1968 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1969 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1970 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1971 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 1972 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 1973 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 1974 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 1976 B.6. Compute HMAC Value 1978 Compute the HMAC SHA-256 of the concatenated value above. This 1979 result M is: 1981 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1982 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 1983 86, 229, 116] 1985 B.7. Truncate HMAC Value to Create Authentication Tag 1987 Use the first half (128 bits) of the HMAC output M as the 1988 Authentication Tag output T. This truncated value is: 1990 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1991 194, 85] 1993 Appendix C. Acknowledgements 1995 Solutions for encrypting JSON content were also explored by JSON 1996 Simple Encryption [JSE] and JavaScript Message Security Format 1997 [I-D.rescorla-jsms], both of which significantly influenced this 1998 draft. This draft attempts to explicitly reuse as many of the 1999 relevant concepts from XML Encryption 1.1 2000 [W3C.CR-xmlenc-core1-20120313] and RFC 5652 [RFC5652] as possible, 2001 while utilizing simple, compact JSON-based data structures. 2003 Special thanks are due to John Bradley and Nat Sakimura for the 2004 discussions that helped inform the content of this specification and 2005 to Eric Rescorla and Joe Hildebrand for allowing the reuse of text 2006 from [I-D.rescorla-jsms] in this document. 2008 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2009 Jay for validating the examples in this specification. 2011 This specification is the work of the JOSE Working Group, which 2012 includes dozens of active and dedicated participants. In particular, 2013 the following individuals contributed ideas, feedback, and wording 2014 that influenced this specification: 2016 Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick 2017 Hardt, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Tony 2018 Nadalin, Axel Nennker, Emmanuel Raviart, Nat Sakimura, Jim Schaad, 2019 Hannes Tschofenig, and Sean Turner. 2021 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2022 Sean Turner and Stephen Farrell served as Security area directors 2023 during the creation of this specification. 2025 Appendix D. Document History 2027 [[ to be removed by the RFC Editor before publication as an RFC ]] 2029 -18 2031 o Updated the mandatory-to-implement (MTI) language to say that 2032 applications using this specification need to specify what 2033 serialization and serialization features are used for that 2034 application, addressing issue #176. 2036 o Changes to address editorial and minor issues #89, #135, #165, 2037 #174, #175, #177, #179, and #180. 2039 o Used Header Parameter Description registry field. 2041 -17 2043 o Refined the "typ" and "cty" definitions to always be MIME Media 2044 Types, with the omission of "application/" prefixes recommended 2045 for brevity, addressing issue #50. 2047 o Updated the mandatory-to-implement (MTI) language to say that 2048 general-purpose implementations must implement the single 2049 recipient case for both serializations whereas special-purpose 2050 implementations can implement just one serialization if that meets 2051 the needs of the use cases the implementation is designed for, 2052 addressing issue #176. 2054 o Explicitly named all the logical components of a JWE and defined 2055 the processing rules and serializations in terms of those 2056 components, addressing issues #60, #61, and #62. 2058 o Replaced verbose repetitive phases such as "base64url encode the 2059 octets of the UTF-8 representation of X" with mathematical 2060 notation such as "BASE64URL(UTF8(X))". 2062 o Header Parameters and processing rules occurring in both JWS and 2063 JWE are now referenced in JWS by JWE, rather than duplicated, 2064 addressing issue #57. 2066 o Terms used in multiple documents are now defined in one place and 2067 incorporated by reference. Some lightly used or obvious terms 2068 were also removed. This addresses issue #58. 2070 -16 2072 o Changes to address editorial and minor issues #163, #168, #169, 2073 #170, #172, and #173. 2075 -15 2077 o Clarified that it is an application decision which recipients' 2078 encrypted content must successfully validate for the JWE to be 2079 accepted, addressing issue #35. 2081 o Changes to address editorial issues #34, #164, and #169. 2083 -14 2085 o Clarified that the "protected", "unprotected", "header", "iv", 2086 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2087 JSON Serialization when their values would be empty. Stated that 2088 the "recipients" array must always be present. 2090 -13 2092 o Added an "aad" (Additional Authenticated Data) member for the JWE 2093 JSON Serialization, enabling Additional Authenticated Data to be 2094 supplied that is not double base64url encoded, addressing issue 2095 #29. 2097 -12 2099 o Clarified that the "typ" and "cty" header parameters are used in 2100 an application-specific manner and have no effect upon the JWE 2101 processing. 2103 o Replaced the MIME types "application/jwe+json" and 2104 "application/jwe" with "application/jose+json" and 2105 "application/jose". 2107 o Stated that recipients MUST either reject JWEs with duplicate 2108 Header Parameter Names or use a JSON parser that returns only the 2109 lexically last duplicate member name. 2111 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2112 be with the algorithm descriptions that use them. 2114 o Added a Serializations section with parallel treatment of the JWE 2115 Compact Serialization and the JWE JSON Serialization and also 2116 moved the former Implementation Considerations content there. 2118 o Restored use of the term "AEAD". 2120 o Changed terminology from "block encryption" to "content 2121 encryption". 2123 -11 2125 o Added Key Identification section. 2127 o Removed the Encrypted Key value from the AAD computation since it 2128 is already effectively integrity protected by the encryption 2129 process. The AAD value now only contains the representation of 2130 the JWE Encrypted Header. 2132 o For the JWE JSON Serialization, enable Header Parameter values to 2133 be specified in any of three parameters: the "protected" member 2134 that is integrity protected and shared among all recipients, the 2135 "unprotected" member that is not integrity protected and shared 2136 among all recipients, and the "header" member that is not 2137 integrity protected and specific to a particular recipient. (This 2138 does not affect the JWE Compact Serialization, in which all Header 2139 Parameter values are in a single integrity protected JWE Header 2140 value.) 2142 o Shortened the names "authentication_tag" to "tag" and 2143 "initialization_vector" to "iv" in the JWE JSON Serialization, 2144 addressing issue #20. 2146 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2148 o Removed suggested compact serialization for multiple recipients. 2150 o Changed the MIME type name "application/jwe-js" to 2151 "application/jwe+json", addressing issue #22. 2153 o Tightened the description of the "crit" (critical) header 2154 parameter. 2156 -10 2158 o Changed the JWE processing rules for multiple recipients so that a 2159 single AAD value contains the header parameters and encrypted key 2160 values for all the recipients, enabling AES GCM to be safely used 2161 for multiple recipients. 2163 o Added an appendix suggesting a possible compact serialization for 2164 JWEs with multiple recipients. 2166 -09 2168 o Added JWE JSON Serialization, as specified by 2169 draft-jones-jose-jwe-json-serialization-04. 2171 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2172 parameter value. 2174 o Defined that the default action for header parameters that are not 2175 understood is to ignore them unless specifically designated as 2176 "MUST be understood" or included in the new "crit" (critical) 2177 header parameter list. This addressed issue #6. 2179 o Corrected "x5c" description. This addressed issue #12. 2181 o Changed from using the term "byte" to "octet" when referring to 8 2182 bit values. 2184 o Added Key Management Mode definitions to terminology section and 2185 used the defined terms to provide clearer key management 2186 instructions. This addressed issue #5. 2188 o Added text about preventing the recipient from behaving as an 2189 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2191 o Changed from using the term "Integrity Value" to "Authentication 2192 Tag". 2194 o Changed member name from "integrity_value" to "authentication_tag" 2195 in the JWE JSON Serialization. 2197 o Removed Initialization Vector from the AAD value since it is 2198 already integrity protected by all of the authenticated encryption 2199 algorithms specified in the JWA specification. 2201 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2202 and "A256CBC-HS512". The new algorithms perform the same 2203 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2204 but with the Initialization Vector and Authentication Tag values 2205 remaining separate from the Ciphertext value in the output 2206 representation. Also deleted the header parameters "epu" 2207 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2208 they are no longer used. 2210 -08 2212 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2213 since the term AEAD in the RFC 5116 sense implied the use of a 2214 particular data representation, rather than just referring to the 2215 class of algorithms that perform authenticated encryption with 2216 associated data. 2218 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2219 Tschofenig. Many of these simplified the terminology used. 2221 o Clarified statements of the form "This header parameter is 2222 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2224 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2225 Web Signature and Encryption Header Parameters registry. 2227 o Added seriesInfo information to Internet Draft references. 2229 -07 2231 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2233 o Updated values for example AES CBC calculations. 2235 o Made several local editorial changes to clean up loose ends left 2236 over from to the decision to only support block encryption methods 2237 providing integrity. One of these changes was to explicitly state 2238 that the "enc" (encryption method) algorithm must be an 2239 Authenticated Encryption algorithm with a specified key length. 2241 -06 2243 o Removed the "int" and "kdf" parameters and defined the new 2244 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2245 "A256CBC+HS512" to replace the former uses of AES CBC, which 2246 required the use of separate integrity and key derivation 2247 functions. 2249 o Included additional values in the Concat KDF calculation -- the 2250 desired output size and the algorithm value, and optionally 2251 PartyUInfo and PartyVInfo values. Added the optional header 2252 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2253 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2254 PartyVInfo). Updated the KDF examples accordingly. 2256 o Promoted Initialization Vector from being a header parameter to 2257 being a top-level JWE element. This saves approximately 16 bytes 2258 in the compact serialization, which is a significant savings for 2259 some use cases. Promoting the Initialization Vector out of the 2260 header also avoids repeating this shared value in the JSON 2261 serialization. 2263 o Changed "x5c" (X.509 Certificate Chain) representation from being 2264 a single string to being an array of strings, each containing a 2265 single base64 encoded DER certificate value, representing elements 2266 of the certificate chain. 2268 o Added an AES Key Wrap example. 2270 o Reordered the encryption steps so CMK creation is first, when 2271 required. 2273 o Correct statements in examples about which algorithms produce 2274 reproducible results. 2276 -05 2278 o Support both direct encryption using a shared or agreed upon 2279 symmetric key, and the use of a shared or agreed upon symmetric 2280 key to key wrap the CMK. 2282 o Added statement that "StringOrURI values are compared as case- 2283 sensitive strings with no transformations or canonicalizations 2284 applied". 2286 o Updated open issues. 2288 o Indented artwork elements to better distinguish them from the body 2289 text. 2291 -04 2292 o Refer to the registries as the primary sources of defined values 2293 and then secondarily reference the sections defining the initial 2294 contents of the registries. 2296 o Normatively reference XML Encryption 1.1 2297 [W3C.CR-xmlenc-core1-20120313] for its security considerations. 2299 o Reference draft-jones-jose-jwe-json-serialization instead of 2300 draft-jones-json-web-encryption-json-serialization. 2302 o Described additional open issues. 2304 o Applied editorial suggestions. 2306 -03 2308 o Added the "kdf" (key derivation function) header parameter to 2309 provide crypto agility for key derivation. The default KDF 2310 remains the Concat KDF with the SHA-256 digest function. 2312 o Reordered encryption steps so that the Encoded JWE Header is 2313 always created before it is needed as an input to the 2314 Authenticated Encryption "additional authenticated data" 2315 parameter. 2317 o Added the "cty" (content type) header parameter for declaring type 2318 information about the secured content, as opposed to the "typ" 2319 (type) header parameter, which declares type information about 2320 this object. 2322 o Moved description of how to determine whether a header is for a 2323 JWS or a JWE from the JWT spec to the JWE spec. 2325 o Added complete encryption examples for both Authenticated 2326 Encryption and non-Authenticated Encryption algorithms. 2328 o Added complete key derivation examples. 2330 o Added "Collision Resistant Namespace" to the terminology section. 2332 o Reference ITU.X690.1994 for DER encoding. 2334 o Added Registry Contents sections to populate registry values. 2336 o Numerous editorial improvements. 2338 -02 2339 o When using Authenticated Encryption algorithms (such as AES GCM), 2340 use the "additional authenticated data" parameter to provide 2341 integrity for the header, encrypted key, and ciphertext and use 2342 the resulting "authentication tag" value as the JWE Authentication 2343 Tag. 2345 o Defined KDF output key sizes. 2347 o Generalized text to allow key agreement to be employed as an 2348 alternative to key wrapping or key encryption. 2350 o Changed compression algorithm from gzip to DEFLATE. 2352 o Clarified that it is an error when a "kid" value is included and 2353 no matching key is found. 2355 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2356 rejected. 2358 o Clarified the relationship between "typ" header parameter values 2359 and MIME types. 2361 o Registered application/jwe MIME type and "JWE" typ header 2362 parameter value. 2364 o Simplified JWK terminology to get replace the "JWK Key Object" and 2365 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2366 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2367 between single keys and sets of keys. As part of this change, the 2368 Header Parameter Name for a public key value was changed from 2369 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2371 o Added suggestion on defining additional header parameters such as 2372 "x5t#S256" in the future for certificate thumbprints using hash 2373 algorithms other than SHA-1. 2375 o Specify RFC 2818 server identity validation, rather than RFC 6125 2376 (paralleling the same decision in the OAuth specs). 2378 o Generalized language to refer to Message Authentication Codes 2379 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2380 unless in a context specific to HMAC algorithms. 2382 o Reformatted to give each header parameter its own section heading. 2384 -01 2385 o Added an integrity check for non-Authenticated Encryption 2386 algorithms. 2388 o Added "jpk" and "x5c" header parameters for including JWK public 2389 keys and X.509 certificate chains directly in the header. 2391 o Clarified that this specification is defining the JWE Compact 2392 Serialization. Referenced the new JWE-JS spec, which defines the 2393 JWE JSON Serialization. 2395 o Added text "New header parameters should be introduced sparingly 2396 since an implementation that does not understand a parameter MUST 2397 reject the JWE". 2399 o Clarified that the order of the encryption and decryption steps is 2400 not significant in cases where there are no dependencies between 2401 the inputs and outputs of the steps. 2403 o Made other editorial improvements suggested by JOSE working group 2404 participants. 2406 -00 2408 o Created the initial IETF draft based upon 2409 draft-jones-json-web-encryption-02 with no normative changes. 2411 o Changed terminology to no longer call both digital signatures and 2412 HMACs "signatures". 2414 Authors' Addresses 2416 Michael B. Jones 2417 Microsoft 2419 Email: mbj@microsoft.com 2420 URI: http://self-issued.info/ 2422 Eric Rescorla 2423 RTFM, Inc. 2425 Email: ekr@rtfm.com 2426 Joe Hildebrand 2427 Cisco Systems, Inc. 2429 Email: jhildebr@cisco.com