idnits 2.17.1 draft-ietf-jose-json-web-encryption-20.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 (January 20, 2014) is 3743 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 1384 -- Looks like a reference, but probably isn't: '197' on line 1384 -- Looks like a reference, but probably isn't: '117' on line 1384 -- Looks like a reference, but probably isn't: '252' on line 1384 -- Looks like a reference, but probably isn't: '2' on line 1384 -- Looks like a reference, but probably isn't: '219' on line 1384 -- Looks like a reference, but probably isn't: '233' on line 1384 -- Looks like a reference, but probably isn't: '68' on line 1384 -- Looks like a reference, but probably isn't: '180' on line 1384 -- Looks like a reference, but probably isn't: '225' on line 1384 -- Looks like a reference, but probably isn't: '77' on line 1384 -- Looks like a reference, but probably isn't: '0' on line 1969 -- Looks like a reference, but probably isn't: '1' on line 1969 -- Looks like a reference, but probably isn't: '152' on line 1969 -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMAScript' ** Downref: Normative reference to an Informational RFC: RFC 1951 -- 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: 1 error (**), 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: July 24, 2014 RTFM 6 J. Hildebrand 7 Cisco 8 January 20, 2014 10 JSON Web Encryption (JWE) 11 draft-ietf-jose-json-web-encryption-20 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 July 24, 2014. 40 Copyright Notice 42 Copyright (c) 2014 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 8 61 3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 10 62 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 12 63 4.1. Registered Header Parameter Names . . . . . . . . . . . . 12 64 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 12 65 4.1.2. "enc" (Encryption Algorithm) Header Parameter . . . . 13 66 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 13 67 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 13 68 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 14 69 4.1.6. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14 70 4.1.7. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 14 71 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 14 72 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 73 Parameter . . . . . . . . . . . . . . . . . . . . . . 14 74 4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 14 75 4.1.11. "cty" (Content Type) Header Parameter . . . . . . . . 15 76 4.1.12. "crit" (Critical) Header Parameter . . . . . . . . . . 15 77 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15 78 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . 21 86 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21 87 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 24 88 9. Distinguishing between JWS and JWE Objects . . . . . . . . . . 24 89 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 90 10.1. JSON Web Signature and Encryption Header Parameters 91 Registration . . . . . . . . . . . . . . . . . . . . . . . 25 92 10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25 93 11. Security Considerations . . . . . . . . . . . . . . . . . . . 27 94 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 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) . . . . . . . . . . . . . 30 101 A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 30 102 A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 31 103 A.1.5. Additional Authenticated Data . . . . . . . . . . . . 31 104 A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . 33 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) [I-D.ietf-json-rfc4627bis] based 151 data structures. The JWE cryptographic mechanisms encrypt and 152 provide integrity 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 JSON object containing the parameters describing the 232 cryptographic operations and parameters employed. The JWE Header 233 members are the union of the members of the JWE Protected Header, 234 the JWE Shared Unprotected Header, and the JWE Per-Recipient 235 Unprotected Header. The members of the JWE Header are Header 236 Parameters. 238 JWE Encrypted Key Encrypted Content Encryption Key (CEK) value. 239 Note that for some algorithms, the JWE Encrypted Key value is 240 specified as being the empty octet sequence. 242 JWE Initialization Vector Initialization Vector value used when 243 encrypting the plaintext. Note that some algorithms may not use 244 an Initialization Vector, in which case this value is the empty 245 octet sequence. 247 JWE AAD Additional value to be integrity protected by the 248 authenticated encryption operation. This can only be present when 249 using the JWE JSON Serialization. 251 JWE Ciphertext Ciphertext value resulting from authenticated 252 encryption of the plaintext with additional associated data. 254 JWE Authentication Tag Authentication Tag value resulting from 255 authenticated encryption of the plaintext with additional 256 associated data. 258 Header Parameter A name/value pair that is member of the JWE Header. 260 JWE Protected Header JSON object that contains the JWE Header 261 Parameters that are integrity protected by the authenticated 262 encryption operation. These parameters apply to all recipients of 263 the JWE. For the JWE Compact Serialization, this comprises the 264 entire JWE Header. For the JWE JSON Serialization, this is one 265 component of the JWE Header. 267 JWE Shared Unprotected Header JSON object that contains the JWE 268 Header Parameters that apply to all recipients of the JWE that are 269 not integrity protected. This can only be present when using the 270 JWE JSON Serialization. 272 JWE Per-Recipient Unprotected Header JSON object that contains JWE 273 Header Parameters that apply to a single recipient of the JWE. 274 This value is not integrity protected. This can only be present 275 when using the JWE JSON Serialization. 277 JWE Compact Serialization A representation of the JWE as a compact, 278 URL-safe string. 280 JWE JSON Serialization A representation of the JWE as a JSON object. 281 The JWE JSON Serialization enables the same content to be 282 encrypted to multiple parties. This representation is neither 283 optimized for compactness nor URL-safe. 285 Key Management Mode A method of determining the Content Encryption 286 Key (CEK) value to use. Each algorithm used for determining the 287 CEK value uses a specific Key Management Mode. Key Management 288 Modes employed by this specification are Key Encryption, Key 289 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 290 and Direct Encryption. 292 Key Encryption A Key Management Mode in which the Content Encryption 293 Key (CEK) value is encrypted to the intended recipient using an 294 asymmetric encryption algorithm. 296 Key Wrapping A Key Management Mode in which the Content Encryption 297 Key (CEK) value is encrypted to the intended recipient using a 298 symmetric key wrapping algorithm. 300 Direct Key Agreement A Key Management Mode in which a key agreement 301 algorithm is used to agree upon the Content Encryption Key (CEK) 302 value. 304 Key Agreement with Key Wrapping A Key Management Mode in which a key 305 agreement algorithm is used to agree upon a symmetric key used to 306 encrypt the Content Encryption Key (CEK) value to the intended 307 recipient using a symmetric key wrapping algorithm. 309 Direct Encryption A Key Management Mode in which the Content 310 Encryption Key (CEK) value used is the secret symmetric key value 311 shared between the parties. 313 3. JSON Web Encryption (JWE) Overview 315 JWE represents encrypted content using JSON data structures and 316 base64url encoding. A JWE represents these logical values: 318 JWE Header JSON object containing the parameters describing the 319 cryptographic operations and parameters employed. The JWE Header 320 members are the union of the members of the JWE Protected Header, 321 the JWE Shared Unprotected Header, and the JWE Per-Recipient 322 Unprotected Header, as described below. 324 JWE Encrypted Key Encrypted Content Encryption Key (CEK) value. 326 JWE Initialization Vector Initialization Vector value used when 327 encrypting the plaintext. 329 JWE AAD Additional value to be integrity protected by the 330 authenticated encryption operation. 332 JWE Ciphertext Ciphertext value resulting from authenticated 333 encryption of the plaintext with additional associated data. 335 JWE Authentication Tag Authentication Tag value resulting from 336 authenticated encryption of the plaintext with additional 337 associated data. 339 The JWE Header represents the combination of these logical values: 341 JWE Protected Header JSON object that contains the JWE Header 342 Parameters that are integrity protected by the authenticated 343 encryption operation. These parameters apply to all recipients of 344 the JWE. 346 JWE Shared Unprotected Header JSON object that contains the JWE 347 Header Parameters that apply to all recipients of the JWE that are 348 not integrity protected. 350 JWE Per-Recipient Unprotected Header JSON object that contains JWE 351 Header Parameters that apply to a single recipient of the JWE. 352 This value is not integrity protected. 354 This document defines two serializations for JWE objects: a compact, 355 URL-safe serialization called the JWE Compact Serialization and a 356 JSON serialization called the JWE JSON Serialization. In both 357 serializations, the JWE Protected Header, JWE Encrypted Key, JWE 358 Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are 359 base64url encoded for transmission, since JSON lacks a way to 360 directly represent octet sequences. When present, the JWE AAD is 361 also base64url encoded for transmission. 363 In the JWE Compact Serialization, no JWE Shared Unprotected Header or 364 JWE Per-Recipient Unprotected Header are used. In this case, the JWE 365 Header and the JWE Protected Header are the same. 367 In the JWE Compact Serialization, a JWE object is represented as the 368 combination of these five string values, 369 BASE64URL(UTF8(JWE Protected Header)), 370 BASE64URL(JWE Encrypted Key), 371 BASE64URL(JWE Initialization Vector), 372 BASE64URL(JWE Ciphertext), and 373 BASE64URL(JWE Authentication Tag), 374 concatenated in that order, with the five strings being separated by 375 four period ('.') characters. 377 In the JWE JSON Serialization, one or more of the JWE Protected 378 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 379 Unprotected Header MUST be present. In this case, the members of the 380 JWE Header are the combination of the members of the JWE Protected 381 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 382 Unprotected Header values that are present. 384 In the JWE JSON Serialization, a JWE object is represented as the 385 combination of these eight values, 386 BASE64URL(UTF8(JWE Protected Header)), 387 JWE Shared Unprotected Header, 388 JWE Per-Recipient Unprotected Header, 389 BASE64URL(JWE Encrypted Key), 390 BASE64URL(JWE Initialization Vector), 391 BASE64URL(JWE Ciphertext), 392 BASE64URL(JWE Authentication Tag), and 393 BASE64URL(JWE AAD), 394 with the six base64url encoding result strings and the two 395 unprotected JSON object values being represented as members within a 396 JSON object. The inclusion of some of these values is OPTIONAL. The 397 JWE JSON Serialization can also encrypt the plaintext to multiple 398 recipients. See Section 7.2 for more information about the JWE JSON 399 Serialization. 401 JWE utilizes authenticated encryption to ensure the confidentiality 402 and integrity of the Plaintext and the integrity of the JWE Protected 403 Header and the JWE AAD. 405 3.1. Example JWE 407 This example encrypts the plaintext "The true sign of intelligence is 408 not knowledge but imagination." to the recipient using RSAES OAEP for 409 key encryption and AES GCM for content encryption. 411 The following example JWE Protected Header declares that: 413 o the Content Encryption Key is encrypted to the recipient using the 414 RSAES OAEP algorithm to produce the JWE Encrypted Key and 416 o the Plaintext is encrypted using the AES GCM algorithm with a 256 417 bit key to produce the Ciphertext. 419 {"alg":"RSA-OAEP","enc":"A256GCM"} 421 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 422 Header)) gives this value: 424 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 426 The remaining steps to finish creating this JWE are: 428 o Generate a random Content Encryption Key (CEK). 430 o Encrypt the CEK with the recipient's public key using the RSAES 431 OAEP algorithm to produce the JWE Encrypted Key. 433 o Base64url encode the JWE Encrypted Key. 435 o Generate a random JWE Initialization Vector. 437 o Base64url encode the JWE Initialization Vector. 439 o Let the Additional Authenticated Data encryption parameter be 440 ASCII(BASE64URL(UTF8(JWE Protected Header))). 442 o Encrypt the Plaintext with AES GCM using the CEK as the encryption 443 key, the JWE Initialization Vector, and the Additional 444 Authenticated Data value, requesting a 128 bit Authentication Tag 445 output. 447 o Base64url encode the Ciphertext. 449 o Base64url encode the Authentication Tag. 451 o Assemble the final representation: The Compact Serialization of 452 this result is the string BASE64URL(UTF8(JWE Protected Header)) || 453 '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE 454 Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' 455 || BASE64URL(JWE Authentication Tag). 457 The final result in this example (with line breaks for display 458 purposes only) is: 460 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 461 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 462 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 463 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 464 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 465 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 466 6UklfCpIMfIjf7iGdXKHzg. 467 48V1_ALb6US04U3b. 468 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 469 SdiwkIr3ajwQzaBtQD_A. 470 XFBoMYUZodetZdvTiFvSkQ 472 See Appendix A.1 for the complete details of computing this JWE. See 473 other parts of Appendix A for additional examples. 475 4. JWE Header 477 The members of the JSON object(s) representing the JWE Header 478 describe the encryption applied to the Plaintext and optionally 479 additional properties of the JWE. The Header Parameter names within 480 the JWE Header MUST be unique; recipients MUST either reject JWEs 481 with duplicate Header Parameter names or use a JSON parser that 482 returns only the lexically last duplicate member name, as specified 483 in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. 485 Implementations are required to understand the specific Header 486 Parameters defined by this specification that are designated as "MUST 487 be understood" and process them in the manner defined in this 488 specification. All other Header Parameters defined by this 489 specification that are not so designated MUST be ignored when not 490 understood. Unless listed as a critical Header Parameter, per 491 Section 4.1.12, all Header Parameters not defined by this 492 specification MUST be ignored when not understood. 494 There are three classes of Header Parameter names: Registered Header 495 Parameter names, Public Header Parameter names, and Private Header 496 Parameter names. 498 4.1. Registered Header Parameter Names 500 The following Header Parameter names are registered in the IANA JSON 501 Web Signature and Encryption Header Parameters registry defined in 502 [JWS], with meanings as defined below. 504 As indicated by the common registry, JWSs and JWEs share a common 505 Header Parameter space; when a parameter is used by both 506 specifications, its usage must be compatible between the 507 specifications. 509 4.1.1. "alg" (Algorithm) Header Parameter 511 This parameter has the same meaning, syntax, and processing rules as 512 the "alg" Header Parameter defined in Section 4.1.1 of [JWS], except 513 that the Header Parameter identifies the cryptographic algorithm used 514 to encrypt or determine the value of the Content Encryption Key 515 (CEK). The encrypted content is not usable if the "alg" value does 516 not represent a supported algorithm, or if the recipient does not 517 have a key that can be used with that algorithm. 519 A list of defined "alg" values for this use can be found in the IANA 520 JSON Web Signature and Encryption Algorithms registry defined in 521 [JWA]; the initial contents of this registry are the values defined 522 in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. 524 4.1.2. "enc" (Encryption Algorithm) Header Parameter 526 The "enc" (encryption algorithm) Header Parameter identifies the 527 content encryption algorithm used to encrypt the Plaintext to produce 528 the Ciphertext. This algorithm MUST be an AEAD algorithm with a 529 specified key length. The recipient MUST reject the JWE if the "enc" 530 value does not represent a supported algorithm. "enc" values should 531 either be registered in the IANA JSON Web Signature and Encryption 532 Algorithms registry defined in [JWA] or be a value that contains a 533 Collision-Resistant Name. The "enc" value is a case-sensitive string 534 containing a StringOrURI value. This Header Parameter MUST be 535 present and MUST be understood and processed by implementations. 537 A list of defined "enc" values for this use can be found in the IANA 538 JSON Web Signature and Encryption Algorithms registry defined in 539 [JWA]; the initial contents of this registry are the values defined 540 in Section 5.1 of the JSON Web Algorithms (JWA) [JWA] specification. 542 4.1.3. "zip" (Compression Algorithm) Header Parameter 544 The "zip" (compression algorithm) applied to the Plaintext before 545 encryption, if any. The "zip" value defined by this specification 546 is: 548 o "DEF" - Compression with the DEFLATE [RFC1951] algorithm 550 Other values MAY be used. Compression algorithm values can be 551 registered in the IANA JSON Web Encryption Compression Algorithm 552 registry defined in [JWA]. The "zip" value is a case-sensitive 553 string. If no "zip" parameter is present, no compression is applied 554 to the Plaintext before encryption. This Header Parameter MUST be 555 integrity protected, and therefore MUST occur only within the JWE 556 Protected Header, when used. Use of this Header Parameter is 557 OPTIONAL. This Header Parameter MUST be understood and processed by 558 implementations. 560 4.1.4. "jku" (JWK Set URL) Header Parameter 562 This parameter has the same meaning, syntax, and processing rules as 563 the "jku" Header Parameter defined in Section 4.1.2 of [JWS], except 564 that the JWK Set resource contains the public key to which the JWE 565 was encrypted; this can be used to determine the private key needed 566 to decrypt the JWE. 568 4.1.5. "jwk" (JSON Web Key) Header Parameter 570 This parameter has the same meaning, syntax, and processing rules as 571 the "jwk" Header Parameter defined in Section 4.1.3 of [JWS], except 572 that the key is the public key to which the JWE was encrypted; this 573 can be used to determine the private key needed to decrypt the JWE. 575 4.1.6. "kid" (Key ID) Header Parameter 577 This parameter has the same meaning, syntax, and processing rules as 578 the "kid" Header Parameter defined in Section 4.1.4 of [JWS], except 579 that the key hint references the public key to which the JWE was 580 encrypted; this can be used to determine the private key needed to 581 decrypt the JWE. This parameter allows originators to explicitly 582 signal a change of key to JWE recipients. 584 4.1.7. "x5u" (X.509 URL) Header Parameter 586 This parameter has the same meaning, syntax, and processing rules as 587 the "x5u" Header Parameter defined in Section 4.1.5 of [JWS], except 588 that the X.509 public key certificate or certificate chain [RFC5280] 589 contains the public key to which the JWE was encrypted; this can be 590 used to determine the private key needed to decrypt the JWE. 592 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 594 This parameter has the same meaning, syntax, and processing rules as 595 the "x5c" Header Parameter defined in Section 4.1.6 of [JWS], except 596 that the X.509 public key certificate or certificate chain [RFC5280] 597 contains the public key to which the JWE was encrypted; this can be 598 used to determine the private key needed to decrypt the JWE. 600 See Appendix B of [JWS] for an example "x5c" value. 602 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 604 This parameter has the same meaning, syntax, and processing rules as 605 the "x5t" Header Parameter defined in Section 4.1.7 of [JWS], except 606 that certificate referenced by the thumbprint contains the public key 607 to which the JWE was encrypted; this can be used to determine the 608 private key needed to decrypt the JWE. 610 4.1.10. "typ" (Type) Header Parameter 612 This parameter has the same meaning, syntax, and processing rules as 613 the "typ" Header Parameter defined in Section 4.1.8 of [JWS], except 614 that the type is of this complete JWE object. 616 4.1.11. "cty" (Content Type) Header Parameter 618 This parameter has the same meaning, syntax, and processing rules as 619 the "cty" Header Parameter defined in Section 4.1.9 of [JWS], except 620 that the type is of the secured content (the payload). 622 4.1.12. "crit" (Critical) Header Parameter 624 This parameter has the same meaning, syntax, and processing rules as 625 the "crit" Header Parameter defined in Section 4.1.10 of [JWS], 626 except that JWE Header Parameters are being referred to, rather than 627 JWS Header Parameters. 629 4.2. Public Header Parameter Names 631 Additional Header Parameter names can be defined by those using JWEs. 632 However, in order to prevent collisions, any new Header Parameter 633 name should either be registered in the IANA JSON Web Signature and 634 Encryption Header Parameters registry defined in [JWS] or be a Public 635 Name: a value that contains a Collision-Resistant Name. In each 636 case, the definer of the name or value needs to take reasonable 637 precautions to make sure they are in control of the part of the 638 namespace they use to define the Header Parameter name. 640 New Header Parameters should be introduced sparingly, as they can 641 result in non-interoperable JWEs. 643 4.3. Private Header Parameter Names 645 A producer and consumer of a JWE may agree to use Header Parameter 646 names that are Private Names: names that are not Registered Header 647 Parameter names Section 4.1 or Public Header Parameter names 648 Section 4.2. Unlike Public Header Parameter names, Private Header 649 Parameter names are subject to collision and should be used with 650 caution. 652 5. Producing and Consuming JWEs 654 5.1. Message Encryption 656 The message encryption process is as follows. The order of the steps 657 is not significant in cases where there are no dependencies between 658 the inputs and outputs of the steps. 660 1. Determine the Key Management Mode employed by the algorithm used 661 to determine the Content Encryption Key (CEK) value. (This is 662 the algorithm recorded in the "alg" (algorithm) Header Parameter 663 of the resulting JWE.) 665 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 666 Wrapping are employed, generate a random Content Encryption Key 667 (CEK) value. See RFC 4086 [RFC4086] for considerations on 668 generating random values. The CEK MUST have a length equal to 669 that required for the content encryption algorithm. 671 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 672 employed, use the key agreement algorithm to compute the value 673 of the agreed upon key. When Direct Key Agreement is employed, 674 let the Content Encryption Key (CEK) be the agreed upon key. 675 When Key Agreement with Key Wrapping is employed, the agreed 676 upon key will be used to wrap the CEK. 678 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 679 Wrapping are employed, encrypt the CEK to the recipient and let 680 the result be the JWE Encrypted Key. 682 5. When Direct Key Agreement or Direct Encryption are employed, let 683 the JWE Encrypted Key be the empty octet sequence. 685 6. When Direct Encryption is employed, let the Content Encryption 686 Key (CEK) be the shared symmetric key. 688 7. Compute the encoded key value BASE64URL(JWE Encrypted Key). 690 8. If the JWE JSON Serialization is being used, repeat this process 691 (steps 1-7) for each recipient. 693 9. Generate a random JWE Initialization Vector of the correct size 694 for the content encryption algorithm (if required for the 695 algorithm); otherwise, let the JWE Initialization Vector be the 696 empty octet sequence. 698 10. Compute the encoded initialization vector value BASE64URL(JWE 699 Initialization Vector). 701 11. If a "zip" parameter was included, compress the Plaintext using 702 the specified compression algorithm. 704 12. Serialize the (compressed) Plaintext into an octet sequence M. 706 13. Create the JSON object(s) containing the desired set of Header 707 Parameters, which together comprise the JWE Header: the JWE 708 Protected Header, and if the JWE JSON Serialization is being 709 used, the JWE Shared Unprotected Header and the JWE Per- 710 Recipient Unprotected Header. 712 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 713 Protected Header)). If the JWE Protected Header is not present 714 (which can only happen when using the JWE JSON Serialization and 715 no "protected" member is present), let this value be the empty 716 string. 718 15. Let the Additional Authenticated Data encryption parameter be 719 ASCII(Encoded Protected Header). However if a JWE AAD value is 720 present (which can only be the case when using the JWE JSON 721 Serialization), instead let the Additional Authenticated Data 722 encryption parameter be ASCII(Encoded Protected Header || '.' || 723 BASE64URL(JWE AAD)). 725 16. Encrypt M using the CEK, the JWE Initialization Vector, and the 726 Additional Authenticated Data value using the specified content 727 encryption algorithm to create the JWE Ciphertext value and the 728 JWE Authentication Tag (which is the Authentication Tag output 729 from the encryption operation). 731 17. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext). 733 18. Compute the encoded authentication tag value BASE64URL(JWE 734 Authentication Tag). 736 19. The five encoded values are used in both the JWE Compact 737 Serialization and the JWE JSON Serialization representations. 739 20. If a JWE AAD value is present, compute the encoded AAD value 740 BASE64URL(JWE AAD). 742 21. Create the desired serialized output. The Compact Serialization 743 of this result is the string BASE64URL(UTF8(JWE Protected 744 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 745 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 746 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). The 747 JWE JSON Serialization is described in Section 7.2. 749 5.2. Message Decryption 751 The message decryption process is the reverse of the encryption 752 process. The order of the steps is not significant in cases where 753 there are no dependencies between the inputs and outputs of the 754 steps. If any of these steps fails, the encrypted content cannot be 755 validated. 757 It is an application decision which recipients' encrypted content 758 must successfully validate for the JWE to be accepted. In some 759 cases, encrypted content for all recipients must successfully 760 validate or the JWE will be rejected. In other cases, only the 761 encrypted content for a single recipient needs to be successfully 762 validated. However, in all cases, the encrypted content for at least 763 one recipient MUST successfully validate or the JWE MUST be rejected. 765 1. Parse the JWE representation to extract the serialized values 766 for the components of the JWE -- when using the JWE Compact 767 Serialization, the base64url encoded representations of the JWE 768 Protected Header, the JWE Encrypted Key, the JWE Initialization 769 Vector, the JWE Ciphertext, and the JWE Authentication Tag, and 770 when using the JWE JSON Serialization, also the base64url 771 encoded representation of the JWE AAD and the unencoded JWE 772 Shared Unprotected Header and JWE Per-Recipient Unprotected 773 Header values. When using the JWE Compact Serialization, the 774 JWE Protected Header, the JWE Encrypted Key, the JWE 775 Initialization Vector, the JWE Ciphertext, and the JWE 776 Authentication Tag are represented as base64url encoded values 777 in that order, separated by four period ('.') characters. The 778 JWE JSON Serialization is described in Section 7.2. 780 2. The encoded representations of the JWE Protected Header, the JWE 781 Encrypted Key, the JWE Initialization Vector, the JWE 782 Ciphertext, the JWE Authentication Tag, and the JWE AAD MUST be 783 successfully base64url decoded following the restriction that no 784 padding characters have been used. 786 3. The octet sequence resulting from decoding the encoded JWE 787 Protected Header MUST be a UTF-8 encoded representation of a 788 completely valid JSON object conforming to 789 [I-D.ietf-json-rfc4627bis], which is the JWE Protected Header. 791 4. If using the JWE Compact Serialization, let the JWE Header be 792 the JWE Protected Header; otherwise, when using the JWE JSON 793 Serialization, let the JWE Header be the union of the members of 794 the JWE Protected Header, the JWE Shared Unprotected Header and 795 the corresponding JWE Per-Recipient Unprotected Header, all of 796 which must be completely valid JSON objects. 798 5. The resulting JWE Header MUST NOT contain duplicate Header 799 Parameter names. When using the JWE JSON Serialization, this 800 restriction includes that the same Header Parameter name also 801 MUST NOT occur in distinct JSON object values that together 802 comprise the JWE Header. 804 6. Verify that the implementation understands and can process all 805 fields that it is required to support, whether required by this 806 specification, by the algorithms being used, or by the "crit" 807 Header Parameter value, and that the values of those parameters 808 are also understood and supported. 810 7. Determine the Key Management Mode employed by the algorithm 811 specified by the "alg" (algorithm) Header Parameter. 813 8. Verify that the JWE uses a key known to the recipient. 815 9. When Direct Key Agreement or Key Agreement with Key Wrapping are 816 employed, use the key agreement algorithm to compute the value 817 of the agreed upon key. When Direct Key Agreement is employed, 818 let the Content Encryption Key (CEK) be the agreed upon key. 819 When Key Agreement with Key Wrapping is employed, the agreed 820 upon key will be used to decrypt the JWE Encrypted Key. 822 10. When Key Wrapping, Key Encryption, or Key Agreement with Key 823 Wrapping are employed, decrypt the JWE Encrypted Key to produce 824 the Content Encryption Key (CEK). The CEK MUST have a length 825 equal to that required for the content encryption algorithm. 826 Note that when there are multiple recipients, each recipient 827 will only be able decrypt any JWE Encrypted Key values that were 828 encrypted to a key in that recipient's possession. It is 829 therefore normal to only be able to decrypt one of the per- 830 recipient JWE Encrypted Key values to obtain the CEK value. To 831 mitigate the attacks described in RFC 3218 [RFC3218], the 832 recipient MUST NOT distinguish between format, padding, and 833 length errors of encrypted keys. It is strongly recommended, in 834 the event of receiving an improperly formatted key, that the 835 receiver substitute a randomly generated CEK and proceed to the 836 next step, to mitigate timing attacks. 838 11. When Direct Key Agreement or Direct Encryption are employed, 839 verify that the JWE Encrypted Key value is empty octet sequence. 841 12. When Direct Encryption is employed, let the Content Encryption 842 Key (CEK) be the shared symmetric key. 844 13. If the JWE JSON Serialization is being used, repeat this process 845 (steps 4-12) for each recipient contained in the representation 846 until the CEK value has been determined. 848 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 849 Protected Header)). If the JWE Protected Header is not present 850 (which can only happen when using the JWE JSON Serialization and 851 no "protected" member is present), let this value be the empty 852 string. 854 15. Let the Additional Authenticated Data encryption parameter be 855 ASCII(Encoded Protected Header). However if a JWE AAD value is 856 present (which can only be the case when using the JWE JSON 857 Serialization), instead let the Additional Authenticated Data 858 encryption parameter be ASCII(Encoded Protected Header || '.' || 859 BASE64URL(JWE AAD)). 861 16. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 862 Vector, the Additional Authenticated Data value, and the JWE 863 Authentication Tag (which is the Authentication Tag input to the 864 calculation) using the specified content encryption algorithm, 865 returning the decrypted plaintext and validating the JWE 866 Authentication Tag in the manner specified for the algorithm, 867 rejecting the input without emitting any decrypted output if the 868 JWE Authentication Tag is incorrect. 870 17. If a "zip" parameter was included, uncompress the decrypted 871 plaintext using the specified compression algorithm. 873 18. If all the previous steps succeeded, output the resulting 874 Plaintext. 876 5.3. String Comparison Rules 878 The string comparison rules for this specification are the same as 879 those defined in Section 5.3 of [JWS]. 881 6. Key Identification 883 The key identification methods for this specification are the same as 884 those defined in Section 6 of [JWS], except that the key being 885 identified is the public key to which the JWE was encrypted. 887 7. Serializations 889 JWE objects use one of two serializations, the JWE Compact 890 Serialization or the JWE JSON Serialization. Applications using this 891 specification need to specify what serialization and serialization 892 features are used for that application. For instance, applications 893 might specify that only the JWE JSON Serialization is used, that only 894 JWE JSON Serialization support for a single recipient is used, or 895 that support for multiple recipients is used. JWE implementations 896 only need to implement the features needed for the applications they 897 are designed to support. 899 7.1. JWE Compact Serialization 901 The JWE Compact Serialization represents encrypted content as a 902 compact URL-safe string. This string is BASE64URL(UTF8(JWE Protected 903 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 904 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 905 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). Only one 906 recipient is supported by the JWE Compact Serialization and it 907 provides no syntax to represent JWE Shared Unprotected Header, JWE 908 Per-Recipient Unprotected Header, or JWE AAD values. 910 7.2. JWE JSON Serialization 912 The JWE JSON Serialization represents encrypted content as a JSON 913 object. Content using the JWE JSON Serialization can be encrypted to 914 more than one recipient. This representation is neither optimized 915 for compactness nor URL-safe. 917 The following members are defined for use in top-level JSON objects 918 used for the JWE JSON Serialization: 920 protected The value BASE64URL(UTF8(JWE Protected Header)), if non- 921 empty, is stored in the "protected" member. 923 unprotected The value BASE64URL(UTF8(JWE Shared Unprotected 924 Header)), if non-empty, is stored in the "unprotected" member. If 925 present, a JWE Shared Unprotected Header value is represented as 926 an unencoded JSON object, rather than as a string. 928 iv The value BASE64URL(JWE Initialization Vector), if non-empty, is 929 stored in the "iv" member. 931 aad A JWE AAD value can be included to supply a base64url encoded 932 value to be integrity protected but not encrypted. (Note that 933 this can also be achieved when using either serialization by 934 including the AAD value as a protected Header Parameter value, but 935 at the cost of the value being double base64url encoded.) If a 936 JWE AAD value is present, the value BASE64URL(JWE AAD)) is stored 937 in the "aad" member. 939 ciphertext The value BASE64URL(JWE Ciphertext) is stored in the 940 "ciphertext" member. 942 tag The value BASE64URL(JWE Authentication Tag), if non-empty, is 943 stored in the "tag" member. 945 recipients A JSON array in the "recipients" member is used to hold 946 values that are specific to a particular recipient, with one array 947 element per recipient represented. These array elements are JSON 948 objects, as specified below. 950 The following members are defined for use in the JSON objects that 951 are elements of the "recipients" array: 953 header Each JWE Per-Recipient Unprotected Header value, if non- 954 empty, is stored in the "header" member. If present, a JWE Per- 955 Recipient Unprotected Header value is represented as an unencoded 956 JSON object, rather than as a string. 958 encrypted_key Each value BASE64URL(JWE Encrypted Key), if non-empty, 959 is stored in the "encrypted_key" member. 961 Of these members of the two JSON objects defined above, only the 962 "ciphertext" and "recipients" members MUST be present. The 963 "recipients" array MUST always be present, even if the array elements 964 contain only the empty JSON object "{}" (which can happen when all 965 Header Parameter values are shared between all recipients and when no 966 encrypted key is used, such as when doing Direct Encryption). 968 The "iv", "tag", and "encrypted_key" members MUST be present when 969 corresponding JWE Initialization Vector, JWE Authentication Tag, and 970 JWE Encrypted Key values are non-empty. The "recipients" member MUST 971 be present when any "header" or "encrypted_key" members are needed 972 for recipients. At least one of the "header", "protected", and 973 "unprotected" members MUST be present so that "alg" and "enc" Header 974 Parameter values are conveyed for each recipient computation. 976 Additional members can be present in both the JSON objects defined 977 above; if not understood by implementations encountering them, they 978 MUST be ignored. 980 Some Header Parameters, including the "alg" parameter, can be shared 981 among all recipient computations. Header Parameters in the JWE 982 Protected Header and JWE Shared Unprotected Header values are shared 983 among all recipients. 985 Not all Header Parameters are integrity protected. The shared Header 986 Parameters in the JWE Protected Header value member are integrity 987 protected, and are base64url encoded for transmission. The per- 988 recipient Header Parameters in the JWE Per-Recipient Unprotected 989 Header values and the shared Header Parameters in the JWE Shared 990 Unprotected Header value are not integrity protected. These JSON 991 objects containing Header Parameters that are not integrity protected 992 are not base64url encoded. 994 The Header Parameter values used when creating or validating per- 995 recipient Ciphertext and Authentication Tag values are the union of 996 the three sets of Header Parameter values that may be present: (1) 997 the JWE Protected Header values represented in the "protected" 998 member, (2) the JWE Shared Unprotected Header values represented in 999 the "unprotected" member, and (3) the JWE Per-Recipient Unprotected 1000 Header values represented in the "header" member of the recipient's 1001 array element. The union of these sets of Header Parameters 1002 comprises the JWE Header. The Header Parameter names in the three 1003 locations MUST be disjoint. 1005 The contents of the JWE Encrypted Key, JWE Initialization Vector, JWE 1006 Ciphertext, and JWE Authentication Tag values are exactly as defined 1007 in the rest of this specification. They are interpreted and 1008 validated in the same manner, with each corresponding JWE Encrypted 1009 Key, JWE Initialization Vector, JWE Ciphertext, JWE Authentication 1010 Tag, and set of Header Parameter values being created and validated 1011 together. The JWE Header values used are the union of the Header 1012 Parameters in the JWE Protected Header, JWE Shared Unprotected 1013 Header, and corresponding JWE Per-Recipient Unprotected Header 1014 values, as described earlier. 1016 Each JWE Encrypted Key value is computed using the parameters of the 1017 corresponding JWE Header value in the same manner as for the JWE 1018 Compact Serialization. This has the desirable property that each JWE 1019 Encrypted Key value in the "recipients" array is identical to the 1020 value that would have been computed for the same parameter in the JWE 1021 Compact Serialization. Likewise, the JWE Ciphertext and JWE 1022 Authentication Tag values match those produced for the JWE Compact 1023 Serialization, provided that the JWE Protected Header value (which 1024 represents the integrity-protected Header Parameter values) matches 1025 that used in the JWE Compact Serialization. 1027 All recipients use the same JWE Protected Header, JWE Initialization 1028 Vector, JWE Ciphertext, and JWE Authentication Tag values, when 1029 present, resulting in potentially significant space savings if the 1030 message is large. Therefore, all Header Parameters that specify the 1031 treatment of the Plaintext value MUST be the same for all recipients. 1032 This primarily means that the "enc" (encryption algorithm) Header 1033 Parameter value in the JWE Header for each recipient and any 1034 parameters of that algorithm MUST be the same. 1036 In summary, the syntax of a JWE using the JWE JSON Serialization is 1037 as follows: 1039 {"protected":"", 1040 "unprotected":, 1041 "recipients":[ 1042 {"header":, 1043 "encrypted_key":""}, 1044 ... 1045 {"header":, 1046 "encrypted_key":""}], 1047 "aad":"", 1048 "iv":"", 1049 "ciphertext":"", 1050 "tag":"" 1051 } 1053 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1054 Serialization. 1056 8. TLS Requirements 1058 The TLS requirements for this specification are the same as those 1059 defined in Section 8 of [JWS]. 1061 9. Distinguishing between JWS and JWE Objects 1063 There are several ways of distinguishing whether an object is a JWS 1064 or JWE object. All these methods will yield the same result for all 1065 legal input values; they may yield different results for malformed 1066 inputs. 1068 o If the object is using the JWS Compact Serialization or the JWE 1069 Compact Serialization, the number of base64url encoded segments 1070 separated by period ('.') characters differs for JWSs and JWEs. 1071 JWSs have three segments separated by two period ('.') characters. 1072 JWEs have five segments separated by four period ('.') characters. 1074 o If the object is using the JWS JSON Serialization or the JWE JSON 1075 Serialization, the members used will be different. JWSs have a 1076 "signatures" member and JWEs do not. JWEs have a "recipients" 1077 member and JWSs do not. 1079 o A JWS Header can be distinguished from a JWE header by examining 1080 the "alg" (algorithm) Header Parameter value. If the value 1081 represents a digital signature or MAC algorithm, or is the value 1082 "none", it is for a JWS; if it represents a Key Encryption, Key 1083 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 1084 or Direct Encryption algorithm, it is for a JWE. (Extracting the 1085 "alg" value to examine is straightforward when using the JWS 1086 Compact Serialization or the JWE Compact Serialization and may be 1087 more difficult when using the JWS JSON Serialization or the JWE 1088 JSON Serialization.) 1090 o A JWS Header can also be distinguished from a JWE header by 1091 determining whether an "enc" (encryption algorithm) member exists. 1092 If the "enc" member exists, it is a JWE; otherwise, it is a JWS. 1094 10. IANA Considerations 1096 10.1. JSON Web Signature and Encryption Header Parameters Registration 1098 This specification registers the Header Parameter names defined in 1099 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1100 Parameters registry defined in [JWS]. 1102 10.1.1. Registry Contents 1104 o Header Parameter Name: "alg" 1105 o Header Parameter Description: Algorithm 1106 o Header Parameter Usage Location(s): JWE 1107 o Change Controller: IESG 1108 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1110 o Header Parameter Name: "enc" 1111 o Header Parameter Description: Encryption Algorithm 1112 o Header Parameter Usage Location(s): JWE 1113 o Change Controller: IESG 1114 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1116 o Header Parameter Name: "zip" 1117 o Header Parameter Description: Compression Algorithm 1118 o Header Parameter Usage Location(s): JWE 1119 o Change Controller: IESG 1120 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1122 o Header Parameter Name: "jku" 1123 o Header Parameter Description: JWK Set URL 1124 o Header Parameter Usage Location(s): JWE 1125 o Change Controller: IESG 1126 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1127 o Header Parameter Name: "jwk" 1128 o Header Parameter Description: JSON Web Key 1129 o Header Parameter Usage Location(s): JWE 1130 o Change Controller: IESG 1131 o Specification document(s): Section 4.1.5 of [[ this document ]] 1133 o Header Parameter Name: "kid" 1134 o Header Parameter Description: Key ID 1135 o Header Parameter Usage Location(s): JWE 1136 o Change Controller: IESG 1137 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1139 o Header Parameter Name: "x5u" 1140 o Header Parameter Description: X.509 URL 1141 o Header Parameter Usage Location(s): JWE 1142 o Change Controller: IESG 1143 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1145 o Header Parameter Name: "x5c" 1146 o Header Parameter Description: X.509 Certificate Chain 1147 o Header Parameter Usage Location(s): JWE 1148 o Change Controller: IESG 1149 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1151 o Header Parameter Name: "x5t" 1152 o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint 1153 o Header Parameter Usage Location(s): JWE 1154 o Change Controller: IESG 1155 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1157 o Header Parameter Name: "typ" 1158 o Header Parameter Description: Type 1159 o Header Parameter Usage Location(s): JWE 1160 o Change Controller: IESG 1161 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1163 o Header Parameter Name: "cty" 1164 o Header Parameter Description: Content Type 1165 o Header Parameter Usage Location(s): JWE 1166 o Change Controller: IESG 1167 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1169 o Header Parameter Name: "crit" 1170 o Header Parameter Description: Critical 1171 o Header Parameter Usage Location(s): JWE 1172 o Change Controller: IESG 1173 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1175 11. Security Considerations 1177 All of the security issues faced by any cryptographic application 1178 must be faced by a JWS/JWE/JWK agent. Among these issues are 1179 protecting the user's private and symmetric keys, preventing various 1180 attacks, and helping the user avoid mistakes such as inadvertently 1181 encrypting a message for the wrong recipient. The entire list of 1182 security considerations is beyond the scope of this document. 1184 All the security considerations in the JWS specification also apply 1185 to this specification. Likewise, all the security considerations in 1186 XML Encryption 1.1 [W3C.CR-xmlenc-core1-20120313] also apply, other 1187 than those that are XML specific. 1189 When decrypting, particular care must be taken not to allow the JWE 1190 recipient to be used as an oracle for decrypting messages. RFC 3218 1191 [RFC3218] should be consulted for specific countermeasures to attacks 1192 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1193 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1194 formatting error that can be detected and used to recover the CEK 1195 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1196 particularly important to report all formatting errors to the CEK, 1197 Additional Authenticated Data, or ciphertext as a single error when 1198 the encrypted content is rejected. 1200 Additionally, this type of attack can be prevented by the use of "key 1201 tainting". This method restricts the use of a key to a limited set 1202 of algorithms -- usually one. This means, for instance, that if the 1203 key is marked as being for "RSA-OAEP" only, any attempt to decrypt a 1204 message using the "RSA1_5" algorithm with that key would fail 1205 immediately due to invalid use of the key. 1207 12. References 1209 12.1. Normative References 1211 [ECMAScript] 1212 Ecma International, "ECMAScript Language Specification, 1213 5.1 Edition", ECMA 262, June 2011. 1215 [I-D.ietf-json-rfc4627bis] 1216 Bray, T., "The JSON Data Interchange Format", 1217 draft-ietf-json-rfc4627bis-10 (work in progress), 1218 December 2013. 1220 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1221 draft-ietf-jose-json-web-algorithms (work in progress), 1222 January 2014. 1224 [JWK] Jones, M., "JSON Web Key (JWK)", 1225 draft-ietf-jose-json-web-key (work in progress), 1226 January 2014. 1228 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1229 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1230 in progress), January 2014. 1232 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1233 version 1.3", RFC 1951, May 1996. 1235 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1236 Requirement Levels", BCP 14, RFC 2119, March 1997. 1238 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1239 10646", STD 63, RFC 3629, November 2003. 1241 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1242 Requirements for Security", BCP 106, RFC 4086, June 2005. 1244 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1245 Housley, R., and W. Polk, "Internet X.509 Public Key 1246 Infrastructure Certificate and Certificate Revocation List 1247 (CRL) Profile", RFC 5280, May 2008. 1249 [USASCII] American National Standards Institute, "Coded Character 1250 Set -- 7-bit American Standard Code for Information 1251 Interchange", ANSI X3.4, 1986. 1253 [W3C.CR-xmlenc-core1-20120313] 1254 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 1255 "XML Encryption Syntax and Processing Version 1.1", World 1256 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1257 March 2012, 1258 . 1260 12.2. Informative References 1262 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1263 McGrew, D. and K. Paterson, "Authenticated Encryption with 1264 AES-CBC and HMAC-SHA", 1265 draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), 1266 October 2012. 1268 [I-D.rescorla-jsms] 1269 Rescorla, E. and J. Hildebrand, "JavaScript Message 1270 Security Format", draft-rescorla-jsms-00 (work in 1271 progress), March 2011. 1273 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1274 Encryption", September 2010. 1276 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1277 Cryptographic Message Syntax", RFC 3218, January 2002. 1279 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1280 RFC 5652, September 2009. 1282 Appendix A. JWE Examples 1284 This section provides examples of JWE computations. 1286 A.1. Example JWE using RSAES OAEP and AES GCM 1288 This example encrypts the plaintext "The true sign of intelligence is 1289 not knowledge but imagination." to the recipient using RSAES OAEP for 1290 key encryption and AES GCM for content encryption. The 1291 representation of this plaintext is: 1293 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1294 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1295 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1296 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1297 110, 97, 116, 105, 111, 110, 46] 1299 A.1.1. JWE Header 1301 The following example JWE Protected Header declares that: 1303 o the Content Encryption Key is encrypted to the recipient using the 1304 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1306 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1307 bit key to produce the Ciphertext. 1309 {"alg":"RSA-OAEP","enc":"A256GCM"} 1311 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1312 Header)) gives this value: 1314 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1316 A.1.2. Content Encryption Key (CEK) 1318 Generate a 256 bit random Content Encryption Key (CEK). In this 1319 example, the value is: 1321 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1322 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1323 234, 64, 252] 1325 A.1.3. Key Encryption 1327 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1328 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1329 key represented in JSON Web Key [JWK] format below (with line breaks 1330 for display purposes only): 1332 {"kty":"RSA", 1333 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1334 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1335 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1336 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1337 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1338 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1339 "e":"AQAB", 1340 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1341 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1342 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1343 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1344 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1345 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ" 1346 } 1348 The resulting JWE Encrypted Key value is: 1350 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1351 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1352 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1353 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1354 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1355 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1356 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1357 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1358 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1359 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1360 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1361 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1362 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1363 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1364 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1365 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1366 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1367 117, 114, 135, 206] 1369 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1370 this value (with line breaks for display purposes only): 1372 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1373 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1374 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1375 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1376 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1377 6UklfCpIMfIjf7iGdXKHzg 1379 A.1.4. Initialization Vector 1381 Generate a random 96 bit JWE Initialization Vector. In this example, 1382 the value is: 1384 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1386 Encoding this JWE Initialization Vector as BASE64URL(JWE 1387 Initialization Vector) gives this value: 1389 48V1_ALb6US04U3b 1391 A.1.5. Additional Authenticated Data 1393 Let the Additional Authenticated Data encryption parameter be 1394 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1396 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1397 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1398 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1400 A.1.6. Content Encryption 1402 Encrypt the Plaintext with AES GCM using the CEK as the encryption 1403 key, the JWE Initialization Vector, and the Additional Authenticated 1404 Data value above, requesting a 128 bit Authentication Tag output. 1405 The resulting Ciphertext is: 1407 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1408 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1409 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1410 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1411 160, 109, 64, 63, 192] 1413 The resulting Authentication Tag value is: 1415 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1416 210, 145] 1418 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1419 value (with line breaks for display purposes only): 1421 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1422 SdiwkIr3ajwQzaBtQD_A 1424 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1425 Tag) gives this value: 1427 XFBoMYUZodetZdvTiFvSkQ 1429 A.1.7. Complete Representation 1431 Assemble the final representation: The Compact Serialization of this 1432 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1433 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1434 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1435 Authentication Tag). 1437 The final result in this example (with line breaks for display 1438 purposes only) is: 1440 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1441 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1442 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1443 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1444 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1445 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1446 6UklfCpIMfIjf7iGdXKHzg. 1447 48V1_ALb6US04U3b. 1448 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1449 SdiwkIr3ajwQzaBtQD_A. 1450 XFBoMYUZodetZdvTiFvSkQ 1452 A.1.8. Validation 1454 This example illustrates the process of creating a JWE with RSAES 1455 OAEP for key encryption and AES GCM for content encryption. These 1456 results can be used to validate JWE decryption implementations for 1457 these algorithms. Note that since the RSAES OAEP computation 1458 includes random values, the encryption results above will not be 1459 completely reproducible. However, since the AES GCM computation is 1460 deterministic, the JWE Encrypted Ciphertext values will be the same 1461 for all encryptions performed using these inputs. 1463 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1465 This example encrypts the plaintext "Live long and prosper." to the 1466 recipient using RSAES-PKCS1-V1_5 for key encryption and 1467 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1468 of this plaintext is: 1470 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1471 112, 114, 111, 115, 112, 101, 114, 46] 1473 A.2.1. JWE Header 1475 The following example JWE Protected Header declares that: 1477 o the Content Encryption Key is encrypted to the recipient using the 1478 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1480 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1481 algorithm to produce the Ciphertext. 1483 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1485 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1486 Header)) gives this value: 1488 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1490 A.2.2. Content Encryption Key (CEK) 1492 Generate a 256 bit random Content Encryption Key (CEK). In this 1493 example, the key value is: 1495 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1496 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1497 44, 207] 1499 A.2.3. Key Encryption 1501 Encrypt the CEK with the recipient's public key using the RSAES- 1502 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1503 uses the RSA key represented in JSON Web Key [JWK] format below (with 1504 line breaks for display purposes only): 1506 {"kty":"RSA", 1507 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1508 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1509 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1510 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1511 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1512 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1513 "e":"AQAB", 1514 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1515 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1516 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1517 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1518 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1519 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1520 } 1522 The resulting JWE Encrypted Key value is: 1524 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1525 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1526 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1527 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1528 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1529 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1530 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1531 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1532 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1533 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1534 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1535 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1536 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1537 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1538 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1539 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1540 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1541 146, 114, 165, 204, 71, 136, 41, 252] 1543 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1544 this value (with line breaks for display purposes only): 1546 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1547 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1548 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1549 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1550 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1551 -B3oWh2TbqmScqXMR4gp_A 1553 A.2.4. Initialization Vector 1555 Generate a random 128 bit JWE Initialization Vector. In this 1556 example, the value is: 1558 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1559 101] 1561 Encoding this JWE Initialization Vector as BASE64URL(JWE 1562 Initialization Vector) gives this value: 1564 AxY8DCtDaGlsbGljb3RoZQ 1566 A.2.5. Additional Authenticated Data 1568 Let the Additional Authenticated Data encryption parameter be 1569 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1571 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1572 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1573 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1574 50, 73, 110, 48] 1576 A.2.6. Content Encryption 1578 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1579 the encryption key, the JWE Initialization Vector, and the Additional 1580 Authenticated Data value above. The steps for doing this using the 1581 values from Appendix A.3 are detailed in Appendix B. The resulting 1582 Ciphertext is: 1584 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1585 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1586 112, 56, 102] 1588 The resulting Authentication Tag value is: 1590 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1591 191] 1593 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1594 value: 1596 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1598 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1599 Tag) gives this value: 1601 9hH0vgRfYgPnAHOd8stkvw 1603 A.2.7. Complete Representation 1605 Assemble the final representation: The Compact Serialization of this 1606 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1607 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1608 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1609 Authentication Tag). 1611 The final result in this example (with line breaks for display 1612 purposes only) is: 1614 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1615 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1616 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1617 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1618 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1619 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1620 -B3oWh2TbqmScqXMR4gp_A. 1621 AxY8DCtDaGlsbGljb3RoZQ. 1622 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1623 9hH0vgRfYgPnAHOd8stkvw 1625 A.2.8. Validation 1627 This example illustrates the process of creating a JWE with RSAES- 1628 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1629 encryption. These results can be used to validate JWE decryption 1630 implementations for these algorithms. Note that since the RSAES- 1631 PKCS1-V1_5 computation includes random values, the encryption results 1632 above will not be completely reproducible. However, since the AES 1633 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1634 will be the same for all encryptions performed using these inputs. 1636 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1638 This example encrypts the plaintext "Live long and prosper." to the 1639 recipient using AES Key Wrap for key encryption and AES GCM for 1640 content encryption. The representation of this plaintext is: 1642 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1643 112, 114, 111, 115, 112, 101, 114, 46] 1645 A.3.1. JWE Header 1647 The following example JWE Protected Header declares that: 1649 o the Content Encryption Key is encrypted to the recipient using the 1650 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1651 Encrypted Key and 1653 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1654 algorithm to produce the Ciphertext. 1656 {"alg":"A128KW","enc":"A128CBC-HS256"} 1658 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1659 Header)) gives this value: 1661 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1663 A.3.2. Content Encryption Key (CEK) 1665 Generate a 256 bit random Content Encryption Key (CEK). In this 1666 example, the value is: 1668 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1669 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1670 44, 207] 1672 A.3.3. Key Encryption 1674 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1675 algorithm to produce the JWE Encrypted Key. This example uses the 1676 symmetric key represented in JSON Web Key [JWK] format below: 1678 {"kty":"oct", 1679 "k":"GawgguFyGrWKav7AX4VKUg" 1680 } 1682 The resulting JWE Encrypted Key value is: 1684 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1685 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1686 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1688 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1689 this value: 1691 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1693 A.3.4. Initialization Vector 1695 Generate a random 128 bit JWE Initialization Vector. In this 1696 example, the value is: 1698 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1699 101] 1701 Encoding this JWE Initialization Vector as BASE64URL(JWE 1702 Initialization Vector) gives this value: 1704 AxY8DCtDaGlsbGljb3RoZQ 1706 A.3.5. Additional Authenticated Data 1708 Let the Additional Authenticated Data encryption parameter be 1709 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1711 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1712 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1713 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1714 110, 48] 1716 A.3.6. Content Encryption 1718 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1719 the encryption key, the JWE Initialization Vector, and the Additional 1720 Authenticated Data value above. The steps for doing this using the 1721 values from this example are detailed in Appendix B. The resulting 1722 Ciphertext is: 1724 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1725 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1726 112, 56, 102] 1728 The resulting Authentication Tag value is: 1730 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1731 194, 85] 1733 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1734 value: 1736 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1738 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1739 Tag) gives this value: 1741 U0m_YmjN04DJvceFICbCVQ 1743 A.3.7. Complete Representation 1745 Assemble the final representation: The Compact Serialization of this 1746 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1747 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1748 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1749 Authentication Tag). 1751 The final result in this example (with line breaks for display 1752 purposes only) is: 1754 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1755 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1756 AxY8DCtDaGlsbGljb3RoZQ. 1757 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1758 U0m_YmjN04DJvceFICbCVQ 1760 A.3.8. Validation 1762 This example illustrates the process of creating a JWE with AES Key 1763 Wrap for key encryption and AES GCM for content encryption. These 1764 results can be used to validate JWE decryption implementations for 1765 these algorithms. Also, since both the AES Key Wrap and AES GCM 1766 computations are deterministic, the resulting JWE value will be the 1767 same for all encryptions performed using these inputs. Since the 1768 computation is reproducible, these results can also be used to 1769 validate JWE encryption implementations for these algorithms. 1771 A.4. Example JWE using JWE JSON Serialization 1773 This section contains an example using the JWE JSON Serialization. 1774 This example demonstrates the capability for encrypting the same 1775 plaintext to multiple recipients. 1777 Two recipients are present in this example. The algorithm and key 1778 used for the first recipient are the same as that used in 1779 Appendix A.2. The algorithm and key used for the second recipient 1780 are the same as that used in Appendix A.3. The resulting JWE 1781 Encrypted Key values are therefore the same; those computations are 1782 not repeated here. 1784 The Plaintext, the Content Encryption Key (CEK), Initialization 1785 Vector, and JWE Protected Header are shared by all recipients (which 1786 must be the case, since the Ciphertext and Authentication Tag are 1787 also shared). 1789 A.4.1. JWE Per-Recipient Unprotected Headers 1791 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1792 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1793 encrypt the CEK. Key ID values are supplied for both keys. The two 1794 per-recipient header values used to represent these algorithms and 1795 Key IDs are: 1797 {"alg":"RSA1_5","kid":"2011-04-29"} 1799 and 1801 {"alg":"A128KW","kid":"7"} 1803 A.4.2. JWE Protected Header 1805 The Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1806 algorithm to produce the common JWE Ciphertext and JWE Authentication 1807 Tag values. The JWE Protected Header value representing this is: 1809 {"enc":"A128CBC-HS256"} 1811 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1812 Header)) gives this value: 1814 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1816 A.4.3. JWE Unprotected Header 1818 This JWE uses the "jku" Header Parameter to reference a JWK Set. This 1819 is represented in the following JWE Unprotected Header value as: 1821 {"jku":"https://server.example.com/keys.jwks"} 1823 A.4.4. Complete JWE Header Values 1825 Combining the per-recipient, protected, and unprotected header values 1826 supplied, the JWE Header values used for the first and second 1827 recipient respectively are: 1829 {"alg":"RSA1_5", 1830 "kid":"2011-04-29", 1831 "enc":"A128CBC-HS256", 1832 "jku":"https://server.example.com/keys.jwks"} 1834 and 1835 {"alg":"A128KW", 1836 "kid":"7", 1837 "enc":"A128CBC-HS256", 1838 "jku":"https://server.example.com/keys.jwks"} 1840 A.4.5. Additional Authenticated Data 1842 Let the Additional Authenticated Data encryption parameter be 1843 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1845 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1846 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1848 A.4.6. Content Encryption 1850 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1851 the encryption key, the JWE Initialization Vector, and the Additional 1852 Authenticated Data value above. The steps for doing this using the 1853 values from Appendix A.3 are detailed in Appendix B. The resulting 1854 Ciphertext is: 1856 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1857 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1858 112, 56, 102] 1860 The resulting Authentication Tag value is: 1862 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1863 207] 1865 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1866 value: 1868 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1870 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1871 Tag) gives this value: 1873 Mz-VPPyU4RlcuYv1IwIvzw 1875 A.4.7. Complete JWE JSON Serialization Representation 1877 The complete JSON Web Encryption JSON Serialization for these values 1878 is as follows (with line breaks for display purposes only): 1880 {"protected": 1881 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1882 "unprotected": 1883 {"jku":"https://server.example.com/keys.jwks"}, 1884 "recipients":[ 1885 {"header": 1886 {"alg":"RSA1_5"}, 1887 "encrypted_key": 1888 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1889 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1890 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 1891 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 1892 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 1893 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 1894 {"header": 1895 {"alg":"A128KW"}, 1896 "encrypted_key": 1897 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1898 "iv": 1899 "AxY8DCtDaGlsbGljb3RoZQ", 1900 "ciphertext": 1901 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1902 "tag": 1903 "Mz-VPPyU4RlcuYv1IwIvzw" 1904 } 1906 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 1908 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 1909 authenticated encryption computation using the values from the 1910 example in Appendix A.3. As described where this algorithm is 1911 defined in Sections 4.8 and 4.8.3 of JWA, the AES_CBC_HMAC_SHA2 1912 family of algorithms are implemented using Advanced Encryption 1913 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #5 1914 padding to perform the encryption and an HMAC SHA-2 function to 1915 perform the integrity calculation - in this case, HMAC SHA-256. 1917 B.1. Extract MAC_KEY and ENC_KEY from Key 1919 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example is: 1921 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1922 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1923 44, 207] 1925 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 1926 which is: 1928 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1929 206] 1931 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 1932 is: 1934 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 1935 207] 1937 Note that the MAC key comes before the encryption key in the input 1938 key K; this is in the opposite order of the algorithm names in the 1939 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 1941 B.2. Encrypt Plaintext to Create Ciphertext 1943 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 1944 using PKCS #5 padding using the ENC_KEY above. The Plaintext in this 1945 example is: 1947 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1948 112, 114, 111, 115, 112, 101, 114, 46] 1950 The encryption result is as follows, which is the Ciphertext output: 1952 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1953 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1954 112, 56, 102] 1956 B.3. 64 Bit Big Endian Representation of AAD Length 1958 The Additional Authenticated Data (AAD) in this example is: 1960 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1961 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1962 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1963 110, 48] 1965 This AAD is 51 bytes long, which is 408 bits long. The octet string 1966 AL, which is the number of bits in AAD expressed as a big endian 64 1967 bit unsigned integer is: 1969 [0, 0, 0, 0, 0, 0, 1, 152] 1971 B.4. Initialization Vector Value 1973 The Initialization Vector value used in this example is: 1975 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1976 101] 1978 B.5. Create Input to HMAC Computation 1980 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 1981 the AL value. The result of this concatenation is: 1983 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1984 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1985 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1986 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 1987 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 1988 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 1989 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 1991 B.6. Compute HMAC Value 1993 Compute the HMAC SHA-256 of the concatenated value above. This 1994 result M is: 1996 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1997 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 1998 86, 229, 116] 2000 B.7. Truncate HMAC Value to Create Authentication Tag 2002 Use the first half (128 bits) of the HMAC output M as the 2003 Authentication Tag output T. This truncated value is: 2005 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2006 194, 85] 2008 Appendix C. Acknowledgements 2010 Solutions for encrypting JSON content were also explored by JSON 2011 Simple Encryption [JSE] and JavaScript Message Security Format 2012 [I-D.rescorla-jsms], both of which significantly influenced this 2013 draft. This draft attempts to explicitly reuse as many of the 2014 relevant concepts from XML Encryption 1.1 2015 [W3C.CR-xmlenc-core1-20120313] and RFC 5652 [RFC5652] as possible, 2016 while utilizing simple, compact JSON-based data structures. 2018 Special thanks are due to John Bradley and Nat Sakimura for the 2019 discussions that helped inform the content of this specification and 2020 to Eric Rescorla and Joe Hildebrand for allowing the reuse of text 2021 from [I-D.rescorla-jsms] in this document. 2023 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2024 Jay for validating the examples in this specification. 2026 This specification is the work of the JOSE Working Group, which 2027 includes dozens of active and dedicated participants. In particular, 2028 the following individuals contributed ideas, feedback, and wording 2029 that influenced this specification: 2031 Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick 2032 Hardt, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Tony 2033 Nadalin, Axel Nennker, Emmanuel Raviart, Nat Sakimura, Jim Schaad, 2034 Hannes Tschofenig, and Sean Turner. 2036 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2037 Sean Turner and Stephen Farrell served as Security area directors 2038 during the creation of this specification. 2040 Appendix D. Document History 2042 [[ to be removed by the RFC Editor before publication as an RFC ]] 2044 -20 2046 o Made terminology definitions more consistent, addressing issue 2047 #165. 2049 o Restructured the JSON Serialization section to call out the 2050 parameters used in hanging lists, addressing issue #178. 2052 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 2053 addressing issue #90. 2055 -19 2057 o Reordered the key selection parameters. 2059 -18 2061 o Updated the mandatory-to-implement (MTI) language to say that 2062 applications using this specification need to specify what 2063 serialization and serialization features are used for that 2064 application, addressing issue #176. 2066 o Changes to address editorial and minor issues #89, #135, #165, 2067 #174, #175, #177, #179, and #180. 2069 o Used Header Parameter Description registry field. 2071 -17 2073 o Refined the "typ" and "cty" definitions to always be MIME Media 2074 Types, with the omission of "application/" prefixes recommended 2075 for brevity, addressing issue #50. 2077 o Updated the mandatory-to-implement (MTI) language to say that 2078 general-purpose implementations must implement the single 2079 recipient case for both serializations whereas special-purpose 2080 implementations can implement just one serialization if that meets 2081 the needs of the use cases the implementation is designed for, 2082 addressing issue #176. 2084 o Explicitly named all the logical components of a JWE and defined 2085 the processing rules and serializations in terms of those 2086 components, addressing issues #60, #61, and #62. 2088 o Replaced verbose repetitive phases such as "base64url encode the 2089 octets of the UTF-8 representation of X" with mathematical 2090 notation such as "BASE64URL(UTF8(X))". 2092 o Header Parameters and processing rules occurring in both JWS and 2093 JWE are now referenced in JWS by JWE, rather than duplicated, 2094 addressing issue #57. 2096 o Terms used in multiple documents are now defined in one place and 2097 incorporated by reference. Some lightly used or obvious terms 2098 were also removed. This addresses issue #58. 2100 -16 2102 o Changes to address editorial and minor issues #163, #168, #169, 2103 #170, #172, and #173. 2105 -15 2107 o Clarified that it is an application decision which recipients' 2108 encrypted content must successfully validate for the JWE to be 2109 accepted, addressing issue #35. 2111 o Changes to address editorial issues #34, #164, and #169. 2113 -14 2115 o Clarified that the "protected", "unprotected", "header", "iv", 2116 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2117 JSON Serialization when their values would be empty. Stated that 2118 the "recipients" array must always be present. 2120 -13 2122 o Added an "aad" (Additional Authenticated Data) member for the JWE 2123 JSON Serialization, enabling Additional Authenticated Data to be 2124 supplied that is not double base64url encoded, addressing issue 2125 #29. 2127 -12 2129 o Clarified that the "typ" and "cty" header parameters are used in 2130 an application-specific manner and have no effect upon the JWE 2131 processing. 2133 o Replaced the MIME types "application/jwe+json" and 2134 "application/jwe" with "application/jose+json" and 2135 "application/jose". 2137 o Stated that recipients MUST either reject JWEs with duplicate 2138 Header Parameter Names or use a JSON parser that returns only the 2139 lexically last duplicate member name. 2141 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2142 be with the algorithm descriptions that use them. 2144 o Added a Serializations section with parallel treatment of the JWE 2145 Compact Serialization and the JWE JSON Serialization and also 2146 moved the former Implementation Considerations content there. 2148 o Restored use of the term "AEAD". 2150 o Changed terminology from "block encryption" to "content 2151 encryption". 2153 -11 2155 o Added Key Identification section. 2157 o Removed the Encrypted Key value from the AAD computation since it 2158 is already effectively integrity protected by the encryption 2159 process. The AAD value now only contains the representation of 2160 the JWE Encrypted Header. 2162 o For the JWE JSON Serialization, enable Header Parameter values to 2163 be specified in any of three parameters: the "protected" member 2164 that is integrity protected and shared among all recipients, the 2165 "unprotected" member that is not integrity protected and shared 2166 among all recipients, and the "header" member that is not 2167 integrity protected and specific to a particular recipient. (This 2168 does not affect the JWE Compact Serialization, in which all Header 2169 Parameter values are in a single integrity protected JWE Header 2170 value.) 2172 o Shortened the names "authentication_tag" to "tag" and 2173 "initialization_vector" to "iv" in the JWE JSON Serialization, 2174 addressing issue #20. 2176 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2178 o Removed suggested compact serialization for multiple recipients. 2180 o Changed the MIME type name "application/jwe-js" to 2181 "application/jwe+json", addressing issue #22. 2183 o Tightened the description of the "crit" (critical) header 2184 parameter. 2186 -10 2188 o Changed the JWE processing rules for multiple recipients so that a 2189 single AAD value contains the header parameters and encrypted key 2190 values for all the recipients, enabling AES GCM to be safely used 2191 for multiple recipients. 2193 o Added an appendix suggesting a possible compact serialization for 2194 JWEs with multiple recipients. 2196 -09 2198 o Added JWE JSON Serialization, as specified by 2199 draft-jones-jose-jwe-json-serialization-04. 2201 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2202 parameter value. 2204 o Defined that the default action for header parameters that are not 2205 understood is to ignore them unless specifically designated as 2206 "MUST be understood" or included in the new "crit" (critical) 2207 header parameter list. This addressed issue #6. 2209 o Corrected "x5c" description. This addressed issue #12. 2211 o Changed from using the term "byte" to "octet" when referring to 8 2212 bit values. 2214 o Added Key Management Mode definitions to terminology section and 2215 used the defined terms to provide clearer key management 2216 instructions. This addressed issue #5. 2218 o Added text about preventing the recipient from behaving as an 2219 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2221 o Changed from using the term "Integrity Value" to "Authentication 2222 Tag". 2224 o Changed member name from "integrity_value" to "authentication_tag" 2225 in the JWE JSON Serialization. 2227 o Removed Initialization Vector from the AAD value since it is 2228 already integrity protected by all of the authenticated encryption 2229 algorithms specified in the JWA specification. 2231 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2232 and "A256CBC-HS512". The new algorithms perform the same 2233 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2234 but with the Initialization Vector and Authentication Tag values 2235 remaining separate from the Ciphertext value in the output 2236 representation. Also deleted the header parameters "epu" 2237 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2238 they are no longer used. 2240 -08 2242 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2243 since the term AEAD in the RFC 5116 sense implied the use of a 2244 particular data representation, rather than just referring to the 2245 class of algorithms that perform authenticated encryption with 2246 associated data. 2248 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2249 Tschofenig. Many of these simplified the terminology used. 2251 o Clarified statements of the form "This header parameter is 2252 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2254 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2255 Web Signature and Encryption Header Parameters registry. 2257 o Added seriesInfo information to Internet Draft references. 2259 -07 2260 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2262 o Updated values for example AES CBC calculations. 2264 o Made several local editorial changes to clean up loose ends left 2265 over from to the decision to only support block encryption methods 2266 providing integrity. One of these changes was to explicitly state 2267 that the "enc" (encryption method) algorithm must be an 2268 Authenticated Encryption algorithm with a specified key length. 2270 -06 2272 o Removed the "int" and "kdf" parameters and defined the new 2273 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2274 "A256CBC+HS512" to replace the former uses of AES CBC, which 2275 required the use of separate integrity and key derivation 2276 functions. 2278 o Included additional values in the Concat KDF calculation -- the 2279 desired output size and the algorithm value, and optionally 2280 PartyUInfo and PartyVInfo values. Added the optional header 2281 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2282 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2283 PartyVInfo). Updated the KDF examples accordingly. 2285 o Promoted Initialization Vector from being a header parameter to 2286 being a top-level JWE element. This saves approximately 16 bytes 2287 in the compact serialization, which is a significant savings for 2288 some use cases. Promoting the Initialization Vector out of the 2289 header also avoids repeating this shared value in the JSON 2290 serialization. 2292 o Changed "x5c" (X.509 Certificate Chain) representation from being 2293 a single string to being an array of strings, each containing a 2294 single base64 encoded DER certificate value, representing elements 2295 of the certificate chain. 2297 o Added an AES Key Wrap example. 2299 o Reordered the encryption steps so CMK creation is first, when 2300 required. 2302 o Correct statements in examples about which algorithms produce 2303 reproducible results. 2305 -05 2306 o Support both direct encryption using a shared or agreed upon 2307 symmetric key, and the use of a shared or agreed upon symmetric 2308 key to key wrap the CMK. 2310 o Added statement that "StringOrURI values are compared as case- 2311 sensitive strings with no transformations or canonicalizations 2312 applied". 2314 o Updated open issues. 2316 o Indented artwork elements to better distinguish them from the body 2317 text. 2319 -04 2321 o Refer to the registries as the primary sources of defined values 2322 and then secondarily reference the sections defining the initial 2323 contents of the registries. 2325 o Normatively reference XML Encryption 1.1 2326 [W3C.CR-xmlenc-core1-20120313] for its security considerations. 2328 o Reference draft-jones-jose-jwe-json-serialization instead of 2329 draft-jones-json-web-encryption-json-serialization. 2331 o Described additional open issues. 2333 o Applied editorial suggestions. 2335 -03 2337 o Added the "kdf" (key derivation function) header parameter to 2338 provide crypto agility for key derivation. The default KDF 2339 remains the Concat KDF with the SHA-256 digest function. 2341 o Reordered encryption steps so that the Encoded JWE Header is 2342 always created before it is needed as an input to the 2343 Authenticated Encryption "additional authenticated data" 2344 parameter. 2346 o Added the "cty" (content type) header parameter for declaring type 2347 information about the secured content, as opposed to the "typ" 2348 (type) header parameter, which declares type information about 2349 this object. 2351 o Moved description of how to determine whether a header is for a 2352 JWS or a JWE from the JWT spec to the JWE spec. 2354 o Added complete encryption examples for both Authenticated 2355 Encryption and non-Authenticated Encryption algorithms. 2357 o Added complete key derivation examples. 2359 o Added "Collision Resistant Namespace" to the terminology section. 2361 o Reference ITU.X690.1994 for DER encoding. 2363 o Added Registry Contents sections to populate registry values. 2365 o Numerous editorial improvements. 2367 -02 2369 o When using Authenticated Encryption algorithms (such as AES GCM), 2370 use the "additional authenticated data" parameter to provide 2371 integrity for the header, encrypted key, and ciphertext and use 2372 the resulting "authentication tag" value as the JWE Authentication 2373 Tag. 2375 o Defined KDF output key sizes. 2377 o Generalized text to allow key agreement to be employed as an 2378 alternative to key wrapping or key encryption. 2380 o Changed compression algorithm from gzip to DEFLATE. 2382 o Clarified that it is an error when a "kid" value is included and 2383 no matching key is found. 2385 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2386 rejected. 2388 o Clarified the relationship between "typ" header parameter values 2389 and MIME types. 2391 o Registered application/jwe MIME type and "JWE" typ header 2392 parameter value. 2394 o Simplified JWK terminology to get replace the "JWK Key Object" and 2395 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2396 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2397 between single keys and sets of keys. As part of this change, the 2398 Header Parameter Name for a public key value was changed from 2399 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2401 o Added suggestion on defining additional header parameters such as 2402 "x5t#S256" in the future for certificate thumbprints using hash 2403 algorithms other than SHA-1. 2405 o Specify RFC 2818 server identity validation, rather than RFC 6125 2406 (paralleling the same decision in the OAuth specs). 2408 o Generalized language to refer to Message Authentication Codes 2409 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2410 unless in a context specific to HMAC algorithms. 2412 o Reformatted to give each header parameter its own section heading. 2414 -01 2416 o Added an integrity check for non-Authenticated Encryption 2417 algorithms. 2419 o Added "jpk" and "x5c" header parameters for including JWK public 2420 keys and X.509 certificate chains directly in the header. 2422 o Clarified that this specification is defining the JWE Compact 2423 Serialization. Referenced the new JWE-JS spec, which defines the 2424 JWE JSON Serialization. 2426 o Added text "New header parameters should be introduced sparingly 2427 since an implementation that does not understand a parameter MUST 2428 reject the JWE". 2430 o Clarified that the order of the encryption and decryption steps is 2431 not significant in cases where there are no dependencies between 2432 the inputs and outputs of the steps. 2434 o Made other editorial improvements suggested by JOSE working group 2435 participants. 2437 -00 2439 o Created the initial IETF draft based upon 2440 draft-jones-json-web-encryption-02 with no normative changes. 2442 o Changed terminology to no longer call both digital signatures and 2443 HMACs "signatures". 2445 Authors' Addresses 2447 Michael B. Jones 2448 Microsoft 2450 Email: mbj@microsoft.com 2451 URI: http://self-issued.info/ 2453 Eric Rescorla 2454 RTFM, Inc. 2456 Email: ekr@rtfm.com 2458 Joe Hildebrand 2459 Cisco Systems, Inc. 2461 Email: jhildebr@cisco.com