idnits 2.17.1 draft-ietf-jose-json-web-encryption-21.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 (February 14, 2014) is 3724 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 1365 -- Looks like a reference, but probably isn't: '197' on line 1365 -- Looks like a reference, but probably isn't: '117' on line 1365 -- Looks like a reference, but probably isn't: '252' on line 1365 -- Looks like a reference, but probably isn't: '2' on line 1365 -- Looks like a reference, but probably isn't: '219' on line 1365 -- Looks like a reference, but probably isn't: '233' on line 1365 -- Looks like a reference, but probably isn't: '68' on line 1365 -- Looks like a reference, but probably isn't: '180' on line 1365 -- Looks like a reference, but probably isn't: '225' on line 1365 -- Looks like a reference, but probably isn't: '77' on line 1365 -- Looks like a reference, but probably isn't: '0' on line 1949 -- Looks like a reference, but probably isn't: '1' on line 1949 -- Looks like a reference, but probably isn't: '152' on line 1949 -- 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: August 18, 2014 RTFM 6 J. Hildebrand 7 Cisco 8 February 14, 2014 10 JSON Web Encryption (JWE) 11 draft-ietf-jose-json-web-encryption-21 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 August 18, 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 . . . . . . . . . . 13 65 4.1.2. "enc" (Encryption Algorithm) Header Parameter . . . . 13 66 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 13 67 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 14 68 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 14 69 4.1.6. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14 70 4.1.7. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 14 71 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 14 72 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 73 Parameter . . . . . . . . . . . . . . . . . . . . . . 15 74 4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 15 75 4.1.11. "cty" (Content Type) Header Parameter . . . . . . . . 15 76 4.1.12. "crit" (Critical) Header Parameter . . . . . . . . . . 15 77 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15 78 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 15 79 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 16 80 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 16 81 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 18 82 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20 83 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20 84 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 21 85 7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 21 86 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21 87 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 24 88 9. Distinguishing between JWS and JWE Objects . . . . . . . . . . 24 89 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 90 10.1. JSON Web Signature and Encryption Header Parameters 91 Registration . . . . . . . . . . . . . . . . . . . . . . . 25 92 10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25 93 11. Security Considerations . . . . . . . . . . . . . . . . . . . 27 94 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . 54 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. (Note that this can also be 250 achieved when using either serialization by including the AAD 251 value as an integrity protected Header Parameter value, but at the 252 cost of the value being double base64url encoded.) 254 JWE Ciphertext Ciphertext value resulting from authenticated 255 encryption of the plaintext with additional associated data. 257 JWE Authentication Tag Authentication Tag value resulting from 258 authenticated encryption of the plaintext with additional 259 associated data. 261 Header Parameter A name/value pair that is member of the JWE Header. 263 JWE Protected Header JSON object that contains the JWE Header 264 Parameters that are integrity protected by the authenticated 265 encryption operation. These parameters apply to all recipients of 266 the JWE. For the JWE Compact Serialization, this comprises the 267 entire JWE Header. For the JWE JSON Serialization, this is one 268 component of the JWE Header. 270 JWE Shared Unprotected Header JSON object that contains the JWE 271 Header Parameters that apply to all recipients of the JWE that are 272 not integrity protected. This can only be present when using the 273 JWE JSON Serialization. 275 JWE Per-Recipient Unprotected Header JSON object that contains JWE 276 Header Parameters that apply to a single recipient of the JWE. 277 These Header Parameter values are not integrity protected. This 278 can only be present when using the JWE JSON Serialization. 280 JWE Compact Serialization A representation of the JWE as a compact, 281 URL-safe string. 283 JWE JSON Serialization A representation of the JWE as a JSON object. 284 The JWE JSON Serialization enables the same content to be 285 encrypted to multiple parties. This representation is neither 286 optimized for compactness nor URL-safe. 288 Key Management Mode A method of determining the Content Encryption 289 Key (CEK) value to use. Each algorithm used for determining the 290 CEK value uses a specific Key Management Mode. Key Management 291 Modes employed by this specification are Key Encryption, Key 292 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 293 and Direct Encryption. 295 Key Encryption A Key Management Mode in which the Content Encryption 296 Key (CEK) value is encrypted to the intended recipient using an 297 asymmetric encryption algorithm. 299 Key Wrapping A Key Management Mode in which the Content Encryption 300 Key (CEK) value is encrypted to the intended recipient using a 301 symmetric key wrapping algorithm. 303 Direct Key Agreement A Key Management Mode in which a key agreement 304 algorithm is used to agree upon the Content Encryption Key (CEK) 305 value. 307 Key Agreement with Key Wrapping A Key Management Mode in which a key 308 agreement algorithm is used to agree upon a symmetric key used to 309 encrypt the Content Encryption Key (CEK) value to the intended 310 recipient using a symmetric key wrapping algorithm. 312 Direct Encryption A Key Management Mode in which the Content 313 Encryption Key (CEK) value used is the secret symmetric key value 314 shared between the parties. 316 3. JSON Web Encryption (JWE) Overview 318 JWE represents encrypted content using JSON data structures and 319 base64url encoding. A JWE represents these logical values: 321 JWE Header JSON object containing the parameters describing the 322 cryptographic operations and parameters employed. The JWE Header 323 members are the union of the members of the JWE Protected Header, 324 the JWE Shared Unprotected Header, and the JWE Per-Recipient 325 Unprotected Header, as described below. 327 JWE Encrypted Key Encrypted Content Encryption Key (CEK) value. 329 JWE Initialization Vector Initialization Vector value used when 330 encrypting the plaintext. 332 JWE AAD Additional value to be integrity protected by the 333 authenticated encryption operation. 335 JWE Ciphertext Ciphertext value resulting from authenticated 336 encryption of the plaintext with additional associated data. 338 JWE Authentication Tag Authentication Tag value resulting from 339 authenticated encryption of the plaintext with additional 340 associated data. 342 The JWE Header represents the combination of these logical values: 344 JWE Protected Header JSON object that contains the JWE Header 345 Parameters that are integrity protected by the authenticated 346 encryption operation. These parameters apply to all recipients of 347 the JWE. 349 JWE Shared Unprotected Header JSON object that contains the JWE 350 Header Parameters that apply to all recipients of the JWE that are 351 not integrity protected. 353 JWE Per-Recipient Unprotected Header JSON object that contains JWE 354 Header Parameters that apply to a single recipient of the JWE. 355 These Header Parameter values are not integrity protected. 357 This document defines two serializations for JWE objects: a compact, 358 URL-safe serialization called the JWE Compact Serialization and a 359 JSON serialization called the JWE JSON Serialization. In both 360 serializations, the JWE Protected Header, JWE Encrypted Key, JWE 361 Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are 362 base64url encoded for transmission, since JSON lacks a way to 363 directly represent octet sequences. When present, the JWE AAD is 364 also base64url encoded for transmission. 366 In the JWE Compact Serialization, no JWE Shared Unprotected Header or 367 JWE Per-Recipient Unprotected Header are used. In this case, the JWE 368 Header and the JWE Protected Header are the same. 370 In the JWE Compact Serialization, a JWE object is represented as the 371 combination of these five string values, 372 BASE64URL(UTF8(JWE Protected Header)), 373 BASE64URL(JWE Encrypted Key), 374 BASE64URL(JWE Initialization Vector), 375 BASE64URL(JWE Ciphertext), and 376 BASE64URL(JWE Authentication Tag), 377 concatenated in that order, with the five strings being separated by 378 four period ('.') characters. 380 In the JWE JSON Serialization, one or more of the JWE Protected 381 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 382 Unprotected Header MUST be present. In this case, the members of the 383 JWE Header are the combination of the members of the JWE Protected 384 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 385 Unprotected Header values that are present. 387 In the JWE JSON Serialization, a JWE object is represented as the 388 combination of these eight values, 389 BASE64URL(UTF8(JWE Protected Header)), 390 JWE Shared Unprotected Header, 391 JWE Per-Recipient Unprotected Header, 392 BASE64URL(JWE Encrypted Key), 393 BASE64URL(JWE Initialization Vector), 394 BASE64URL(JWE Ciphertext), 395 BASE64URL(JWE Authentication Tag), and 396 BASE64URL(JWE AAD), 397 with the six base64url encoding result strings and the two 398 unprotected JSON object values being represented as members within a 399 JSON object. The inclusion of some of these values is OPTIONAL. The 400 JWE JSON Serialization can also encrypt the plaintext to multiple 401 recipients. See Section 7.2 for more information about the JWE JSON 402 Serialization. 404 JWE utilizes authenticated encryption to ensure the confidentiality 405 and integrity of the Plaintext and the integrity of the JWE Protected 406 Header and the JWE AAD. 408 3.1. Example JWE 410 This example encrypts the plaintext "The true sign of intelligence is 411 not knowledge but imagination." to the recipient using RSAES OAEP for 412 key encryption and AES GCM for content encryption. 414 The following example JWE Protected Header declares that: 416 o the Content Encryption Key is encrypted to the recipient using the 417 RSAES OAEP algorithm to produce the JWE Encrypted Key and 419 o the Plaintext is encrypted using the AES GCM algorithm with a 256 420 bit key to produce the Ciphertext. 422 {"alg":"RSA-OAEP","enc":"A256GCM"} 424 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 425 Header)) gives this value: 427 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 429 The remaining steps to finish creating this JWE are: 431 o Generate a random Content Encryption Key (CEK). 433 o Encrypt the CEK with the recipient's public key using the RSAES 434 OAEP algorithm to produce the JWE Encrypted Key. 436 o Base64url encode the JWE Encrypted Key. 438 o Generate a random JWE Initialization Vector. 440 o Base64url encode the JWE Initialization Vector. 442 o Let the Additional Authenticated Data encryption parameter be 443 ASCII(BASE64URL(UTF8(JWE Protected Header))). 445 o Encrypt the Plaintext with AES GCM using the CEK as the encryption 446 key, the JWE Initialization Vector, and the Additional 447 Authenticated Data value, requesting a 128 bit Authentication Tag 448 output. 450 o Base64url encode the Ciphertext. 452 o Base64url encode the Authentication Tag. 454 o Assemble the final representation: The Compact Serialization of 455 this result is the string BASE64URL(UTF8(JWE Protected Header)) || 456 '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE 457 Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' 458 || BASE64URL(JWE Authentication Tag). 460 The final result in this example (with line breaks for display 461 purposes only) is: 463 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 464 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 465 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 466 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 467 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 468 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 469 6UklfCpIMfIjf7iGdXKHzg. 470 48V1_ALb6US04U3b. 471 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 472 SdiwkIr3ajwQzaBtQD_A. 473 XFBoMYUZodetZdvTiFvSkQ 475 See Appendix A.1 for the complete details of computing this JWE. See 476 other parts of Appendix A for additional examples. 478 4. JWE Header 480 The members of the JSON object(s) representing the JWE Header 481 describe the encryption applied to the Plaintext and optionally 482 additional properties of the JWE. The Header Parameter names within 483 the JWE Header MUST be unique; recipients MUST either reject JWEs 484 with duplicate Header Parameter names or use a JSON parser that 485 returns only the lexically last duplicate member name, as specified 486 in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. 488 Implementations are required to understand the specific Header 489 Parameters defined by this specification that are designated as "MUST 490 be understood" and process them in the manner defined in this 491 specification. All other Header Parameters defined by this 492 specification that are not so designated MUST be ignored when not 493 understood. Unless listed as a critical Header Parameter, per 494 Section 4.1.12, all Header Parameters not defined by this 495 specification MUST be ignored when not understood. 497 There are three classes of Header Parameter names: Registered Header 498 Parameter names, Public Header Parameter names, and Private Header 499 Parameter names. 501 4.1. Registered Header Parameter Names 503 The following Header Parameter names are registered in the IANA JSON 504 Web Signature and Encryption Header Parameters registry defined in 505 [JWS], with meanings as defined below. 507 As indicated by the common registry, JWSs and JWEs share a common 508 Header Parameter space; when a parameter is used by both 509 specifications, its usage must be compatible between the 510 specifications. 512 4.1.1. "alg" (Algorithm) Header Parameter 514 This parameter has the same meaning, syntax, and processing rules as 515 the "alg" Header Parameter defined in Section 4.1.1 of [JWS], except 516 that the Header Parameter identifies the cryptographic algorithm used 517 to encrypt or determine the value of the Content Encryption Key 518 (CEK). The encrypted content is not usable if the "alg" value does 519 not represent a supported algorithm, or if the recipient does not 520 have a key that can be used with that algorithm. 522 A list of defined "alg" values for this use can be found in the IANA 523 JSON Web Signature and Encryption Algorithms registry defined in 524 [JWA]; the initial contents of this registry are the values defined 525 in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. 527 4.1.2. "enc" (Encryption Algorithm) Header Parameter 529 The "enc" (encryption algorithm) Header Parameter identifies the 530 content encryption algorithm used to encrypt the Plaintext to produce 531 the Ciphertext. This algorithm MUST be an AEAD algorithm with a 532 specified key length. The recipient MUST reject the JWE if the "enc" 533 value does not represent a supported algorithm. "enc" values should 534 either be registered in the IANA JSON Web Signature and Encryption 535 Algorithms registry defined in [JWA] or be a value that contains a 536 Collision-Resistant Name. The "enc" value is a case-sensitive string 537 containing a StringOrURI value. This Header Parameter MUST be 538 present and MUST be understood and processed by implementations. 540 A list of defined "enc" values for this use can be found in the IANA 541 JSON Web Signature and Encryption Algorithms registry defined in 542 [JWA]; the initial contents of this registry are the values defined 543 in Section 5.1 of the JSON Web Algorithms (JWA) [JWA] specification. 545 4.1.3. "zip" (Compression Algorithm) Header Parameter 547 The "zip" (compression algorithm) applied to the Plaintext before 548 encryption, if any. The "zip" value defined by this specification 549 is: 551 o "DEF" - Compression with the DEFLATE [RFC1951] algorithm 553 Other values MAY be used. Compression algorithm values can be 554 registered in the IANA JSON Web Encryption Compression Algorithm 555 registry defined in [JWA]. The "zip" value is a case-sensitive 556 string. If no "zip" parameter is present, no compression is applied 557 to the Plaintext before encryption. This Header Parameter MUST be 558 integrity protected, and therefore MUST occur only within the JWE 559 Protected Header, when used. Use of this Header Parameter is 560 OPTIONAL. This Header Parameter MUST be understood and processed by 561 implementations. 563 4.1.4. "jku" (JWK Set URL) Header Parameter 565 This parameter has the same meaning, syntax, and processing rules as 566 the "jku" Header Parameter defined in Section 4.1.2 of [JWS], except 567 that the JWK Set resource contains the public key to which the JWE 568 was encrypted; this can be used to determine the private key needed 569 to decrypt the JWE. 571 4.1.5. "jwk" (JSON Web Key) Header Parameter 573 This parameter has the same meaning, syntax, and processing rules as 574 the "jwk" Header Parameter defined in Section 4.1.3 of [JWS], except 575 that the key is the public key to which the JWE was encrypted; this 576 can be used to determine the private key needed to decrypt the JWE. 578 4.1.6. "kid" (Key ID) Header Parameter 580 This parameter has the same meaning, syntax, and processing rules as 581 the "kid" Header Parameter defined in Section 4.1.4 of [JWS], except 582 that the key hint references the public key to which the JWE was 583 encrypted; this can be used to determine the private key needed to 584 decrypt the JWE. This parameter allows originators to explicitly 585 signal a change of key to JWE recipients. 587 4.1.7. "x5u" (X.509 URL) Header Parameter 589 This parameter has the same meaning, syntax, and processing rules as 590 the "x5u" Header Parameter defined in Section 4.1.5 of [JWS], except 591 that the X.509 public key certificate or certificate chain [RFC5280] 592 contains the public key to which the JWE was encrypted; this can be 593 used to determine the private key needed to decrypt the JWE. 595 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 597 This parameter has the same meaning, syntax, and processing rules as 598 the "x5c" Header Parameter defined in Section 4.1.6 of [JWS], except 599 that the X.509 public key certificate or certificate chain [RFC5280] 600 contains the public key to which the JWE was encrypted; this can be 601 used to determine the private key needed to decrypt the JWE. 603 See Appendix B of [JWS] for an example "x5c" value. 605 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 607 This parameter has the same meaning, syntax, and processing rules as 608 the "x5t" Header Parameter defined in Section 4.1.7 of [JWS], except 609 that certificate referenced by the thumbprint contains the public key 610 to which the JWE was encrypted; this can be used to determine the 611 private key needed to decrypt the JWE. 613 4.1.10. "typ" (Type) Header Parameter 615 This parameter has the same meaning, syntax, and processing rules as 616 the "typ" Header Parameter defined in Section 4.1.8 of [JWS], except 617 that the type is of this complete JWE object. 619 4.1.11. "cty" (Content Type) Header Parameter 621 This parameter has the same meaning, syntax, and processing rules as 622 the "cty" Header Parameter defined in Section 4.1.9 of [JWS], except 623 that the type is of the secured content (the payload). 625 4.1.12. "crit" (Critical) Header Parameter 627 This parameter has the same meaning, syntax, and processing rules as 628 the "crit" Header Parameter defined in Section 4.1.10 of [JWS], 629 except that JWE Header Parameters are being referred to, rather than 630 JWS Header Parameters. 632 4.2. Public Header Parameter Names 634 Additional Header Parameter names can be defined by those using JWEs. 635 However, in order to prevent collisions, any new Header Parameter 636 name should either be registered in the IANA JSON Web Signature and 637 Encryption Header Parameters registry defined in [JWS] or be a Public 638 Name: a value that contains a Collision-Resistant Name. In each 639 case, the definer of the name or value needs to take reasonable 640 precautions to make sure they are in control of the part of the 641 namespace they use to define the Header Parameter name. 643 New Header Parameters should be introduced sparingly, as they can 644 result in non-interoperable JWEs. 646 4.3. Private Header Parameter Names 648 A producer and consumer of a JWE may agree to use Header Parameter 649 names that are Private Names: names that are not Registered Header 650 Parameter names Section 4.1 or Public Header Parameter names 651 Section 4.2. Unlike Public Header Parameter names, Private Header 652 Parameter names are subject to collision and should be used with 653 caution. 655 5. Producing and Consuming JWEs 657 5.1. Message Encryption 659 The message encryption process is as follows. The order of the steps 660 is not significant in cases where there are no dependencies between 661 the inputs and outputs of the steps. 663 1. Determine the Key Management Mode employed by the algorithm used 664 to determine the Content Encryption Key (CEK) value. (This is 665 the algorithm recorded in the "alg" (algorithm) Header Parameter 666 of the resulting JWE.) 668 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 669 Wrapping are employed, generate a random Content Encryption Key 670 (CEK) value. See RFC 4086 [RFC4086] for considerations on 671 generating random values. The CEK MUST have a length equal to 672 that required for the content encryption algorithm. 674 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 675 employed, use the key agreement algorithm to compute the value 676 of the agreed upon key. When Direct Key Agreement is employed, 677 let the Content Encryption Key (CEK) be the agreed upon key. 678 When Key Agreement with Key Wrapping is employed, the agreed 679 upon key will be used to wrap the CEK. 681 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 682 Wrapping are employed, encrypt the CEK to the recipient and let 683 the result be the JWE Encrypted Key. 685 5. When Direct Key Agreement or Direct Encryption are employed, let 686 the JWE Encrypted Key be the empty octet sequence. 688 6. When Direct Encryption is employed, let the Content Encryption 689 Key (CEK) be the shared symmetric key. 691 7. Compute the encoded key value BASE64URL(JWE Encrypted Key). 693 8. If the JWE JSON Serialization is being used, repeat this process 694 (steps 1-7) for each recipient. 696 9. Generate a random JWE Initialization Vector of the correct size 697 for the content encryption algorithm (if required for the 698 algorithm); otherwise, let the JWE Initialization Vector be the 699 empty octet sequence. 701 10. Compute the encoded initialization vector value BASE64URL(JWE 702 Initialization Vector). 704 11. If a "zip" parameter was included, compress the Plaintext using 705 the specified compression algorithm. 707 12. Serialize the (compressed) Plaintext into an octet sequence M. 709 13. Create the JSON object(s) containing the desired set of Header 710 Parameters, which together comprise the JWE Header: the JWE 711 Protected Header, and if the JWE JSON Serialization is being 712 used, the JWE Shared Unprotected Header and the JWE Per- 713 Recipient Unprotected Header. 715 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 716 Protected Header)). If the JWE Protected Header is not present 717 (which can only happen when using the JWE JSON Serialization and 718 no "protected" member is present), let this value be the empty 719 string. 721 15. Let the Additional Authenticated Data encryption parameter be 722 ASCII(Encoded Protected Header). However if a JWE AAD value is 723 present (which can only be the case when using the JWE JSON 724 Serialization), instead let the Additional Authenticated Data 725 encryption parameter be ASCII(Encoded Protected Header || '.' || 726 BASE64URL(JWE AAD)). 728 16. Encrypt M using the CEK, the JWE Initialization Vector, and the 729 Additional Authenticated Data value using the specified content 730 encryption algorithm to create the JWE Ciphertext value and the 731 JWE Authentication Tag (which is the Authentication Tag output 732 from the encryption operation). 734 17. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext). 736 18. Compute the encoded authentication tag value BASE64URL(JWE 737 Authentication Tag). 739 19. The five encoded values are used in both the JWE Compact 740 Serialization and the JWE JSON Serialization representations. 742 20. If a JWE AAD value is present, compute the encoded AAD value 743 BASE64URL(JWE AAD). 745 21. Create the desired serialized output. The Compact Serialization 746 of this result is the string BASE64URL(UTF8(JWE Protected 747 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 748 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 749 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). The 750 JWE JSON Serialization is described in Section 7.2. 752 5.2. Message Decryption 754 The message decryption process is the reverse of the encryption 755 process. The order of the steps is not significant in cases where 756 there are no dependencies between the inputs and outputs of the 757 steps. If any of these steps fails, the encrypted content cannot be 758 validated. 760 It is an application decision which recipients' encrypted content 761 must successfully validate for the JWE to be accepted. In some 762 cases, encrypted content for all recipients must successfully 763 validate or the JWE will be rejected. In other cases, only the 764 encrypted content for a single recipient needs to be successfully 765 validated. However, in all cases, the encrypted content for at least 766 one recipient MUST successfully validate or the JWE MUST be rejected. 768 1. Parse the JWE representation to extract the serialized values 769 for the components of the JWE -- when using the JWE Compact 770 Serialization, the base64url encoded representations of the JWE 771 Protected Header, the JWE Encrypted Key, the JWE Initialization 772 Vector, the JWE Ciphertext, and the JWE Authentication Tag, and 773 when using the JWE JSON Serialization, also the base64url 774 encoded representation of the JWE AAD and the unencoded JWE 775 Shared Unprotected Header and JWE Per-Recipient Unprotected 776 Header values. When using the JWE Compact Serialization, the 777 JWE Protected Header, the JWE Encrypted Key, the JWE 778 Initialization Vector, the JWE Ciphertext, and the JWE 779 Authentication Tag are represented as base64url encoded values 780 in that order, separated by four period ('.') characters. The 781 JWE JSON Serialization is described in Section 7.2. 783 2. The encoded representations of the JWE Protected Header, the JWE 784 Encrypted Key, the JWE Initialization Vector, the JWE 785 Ciphertext, the JWE Authentication Tag, and the JWE AAD MUST be 786 successfully base64url decoded following the restriction that no 787 padding characters have been used. 789 3. The octet sequence resulting from decoding the encoded JWE 790 Protected Header MUST be a UTF-8 encoded representation of a 791 completely valid JSON object conforming to 792 [I-D.ietf-json-rfc4627bis], which is the JWE Protected Header. 794 4. If using the JWE Compact Serialization, let the JWE Header be 795 the JWE Protected Header; otherwise, when using the JWE JSON 796 Serialization, let the JWE Header be the union of the members of 797 the JWE Protected Header, the JWE Shared Unprotected Header and 798 the corresponding JWE Per-Recipient Unprotected Header, all of 799 which must be completely valid JSON objects. 801 5. The resulting JWE Header MUST NOT contain duplicate Header 802 Parameter names. When using the JWE JSON Serialization, this 803 restriction includes that the same Header Parameter name also 804 MUST NOT occur in distinct JSON object values that together 805 comprise the JWE Header. 807 6. Verify that the implementation understands and can process all 808 fields that it is required to support, whether required by this 809 specification, by the algorithms being used, or by the "crit" 810 Header Parameter value, and that the values of those parameters 811 are also understood and supported. 813 7. Determine the Key Management Mode employed by the algorithm 814 specified by the "alg" (algorithm) Header Parameter. 816 8. Verify that the JWE uses a key known to the recipient. 818 9. When Direct Key Agreement or Key Agreement with Key Wrapping are 819 employed, use the key agreement algorithm to compute the value 820 of the agreed upon key. When Direct Key Agreement is employed, 821 let the Content Encryption Key (CEK) be the agreed upon key. 822 When Key Agreement with Key Wrapping is employed, the agreed 823 upon key will be used to decrypt the JWE Encrypted Key. 825 10. When Key Wrapping, Key Encryption, or Key Agreement with Key 826 Wrapping are employed, decrypt the JWE Encrypted Key to produce 827 the Content Encryption Key (CEK). The CEK MUST have a length 828 equal to that required for the content encryption algorithm. 829 Note that when there are multiple recipients, each recipient 830 will only be able decrypt any JWE Encrypted Key values that were 831 encrypted to a key in that recipient's possession. It is 832 therefore normal to only be able to decrypt one of the per- 833 recipient JWE Encrypted Key values to obtain the CEK value. To 834 mitigate the attacks described in RFC 3218 [RFC3218], the 835 recipient MUST NOT distinguish between format, padding, and 836 length errors of encrypted keys. It is strongly recommended, in 837 the event of receiving an improperly formatted key, that the 838 receiver substitute a randomly generated CEK and proceed to the 839 next step, to mitigate timing attacks. 841 11. When Direct Key Agreement or Direct Encryption are employed, 842 verify that the JWE Encrypted Key value is empty octet sequence. 844 12. When Direct Encryption is employed, let the Content Encryption 845 Key (CEK) be the shared symmetric key. 847 13. If the JWE JSON Serialization is being used, repeat this process 848 (steps 4-12) for each recipient contained in the representation 849 until the CEK value has been determined. 851 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 852 Protected Header)). If the JWE Protected Header is not present 853 (which can only happen when using the JWE JSON Serialization and 854 no "protected" member is present), let this value be the empty 855 string. 857 15. Let the Additional Authenticated Data encryption parameter be 858 ASCII(Encoded Protected Header). However if a JWE AAD value is 859 present (which can only be the case when using the JWE JSON 860 Serialization), instead let the Additional Authenticated Data 861 encryption parameter be ASCII(Encoded Protected Header || '.' || 862 BASE64URL(JWE AAD)). 864 16. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 865 Vector, the Additional Authenticated Data value, and the JWE 866 Authentication Tag (which is the Authentication Tag input to the 867 calculation) using the specified content encryption algorithm, 868 returning the decrypted plaintext and validating the JWE 869 Authentication Tag in the manner specified for the algorithm, 870 rejecting the input without emitting any decrypted output if the 871 JWE Authentication Tag is incorrect. 873 17. If a "zip" parameter was included, uncompress the decrypted 874 plaintext using the specified compression algorithm. 876 18. If all the previous steps succeeded, output the resulting 877 Plaintext. 879 5.3. String Comparison Rules 881 The string comparison rules for this specification are the same as 882 those defined in Section 5.3 of [JWS]. 884 6. Key Identification 886 The key identification methods for this specification are the same as 887 those defined in Section 6 of [JWS], except that the key being 888 identified is the public key to which the JWE was encrypted. 890 7. Serializations 892 JWE objects use one of two serializations, the JWE Compact 893 Serialization or the JWE JSON Serialization. Applications using this 894 specification need to specify what serialization and serialization 895 features are used for that application. For instance, applications 896 might specify that only the JWE JSON Serialization is used, that only 897 JWE JSON Serialization support for a single recipient is used, or 898 that support for multiple recipients is used. JWE implementations 899 only need to implement the features needed for the applications they 900 are designed to support. 902 7.1. JWE Compact Serialization 904 The JWE Compact Serialization represents encrypted content as a 905 compact URL-safe string. This string is BASE64URL(UTF8(JWE Protected 906 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 907 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 908 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). Only one 909 recipient is supported by the JWE Compact Serialization and it 910 provides no syntax to represent JWE Shared Unprotected Header, JWE 911 Per-Recipient Unprotected Header, or JWE AAD values. 913 7.2. JWE JSON Serialization 915 The JWE JSON Serialization represents encrypted content as a JSON 916 object. Content using the JWE JSON Serialization can be encrypted to 917 more than one recipient. This representation is neither optimized 918 for compactness nor URL-safe. 920 The following members are defined for use in top-level JSON objects 921 used for the JWE JSON Serialization: 923 protected The "protected" member MUST be present and contain the 924 value BASE64URL(UTF8(JWE Protected Header)) when the JWE Protected 925 Header value is non-empty; otherwise, it MUST be absent. These 926 Header Parameter values are integrity protected. 928 unprotected The "unprotected" member MUST be present and contain the 929 value JWE Shared Unprotected Header when the JWE Shared 930 Unprotected Header value is non-empty; otherwise, it MUST be 931 absent. This value is represented as an unencoded JSON object, 932 rather than as a string. These Header Parameter values are not 933 integrity protected. 935 iv The "iv" member MUST be present and contain the value 936 BASE64URL(JWE Initialization Vector) when the JWE Initialization 937 Vector value is non-empty; otherwise, it MUST be absent. 939 aad The "aad" member MUST be present and contain the value 940 BASE64URL(JWE AAD)) when the JWE AAD value is non-empty; 941 otherwise, it MUST be absent. A JWE AAD value can be included to 942 supply a base64url encoded value to be integrity protected but not 943 encrypted. 945 ciphertext The "ciphertext" member MUST be present and contain the 946 value BASE64URL(JWE Ciphertext). 948 tag The "tag" member MUST be present and contain the value 949 BASE64URL(JWE Authentication Tag) when the JWE Authentication Tag 950 value is non-empty; otherwise, it MUST be absent. 952 recipients The "recipients" member value MUST be an array of JSON 953 objects. Each object contains information specific to a single 954 recipient. This member MUST be present, even if the array 955 elements contain only the empty JSON object "{}" (which can happen 956 when all Header Parameter values are shared between all recipients 957 and when no encrypted key is used, such as when doing Direct 958 Encryption). 960 The following members are defined for use in the JSON objects that 961 are elements of the "recipients" array: 963 header The "header" member MUST be present and contain the value JWE 964 Per-Recipient Unprotected Header when the JWE Per-Recipient 965 Unprotected Header value is non-empty; otherwise, it MUST be 966 absent. This value is represented as an unencoded JSON object, 967 rather than as a string. These Header Parameter values are not 968 integrity protected. 970 encrypted_key The "encrypted_key" member MUST be present and contain 971 the value BASE64URL(JWE Encrypted Key) when the JWE Encrypted Key 972 value is non-empty; otherwise, it MUST be absent. 974 At least one of the "header", "protected", and "unprotected" members 975 MUST be present so that "alg" and "enc" Header Parameter values are 976 conveyed for each recipient computation. 978 Additional members can be present in both the JSON objects defined 979 above; if not understood by implementations encountering them, they 980 MUST be ignored. 982 Some Header Parameters, including the "alg" parameter, can be shared 983 among all recipient computations. Header Parameters in the JWE 984 Protected Header and JWE Shared Unprotected Header values are shared 985 among all recipients. 987 The Header Parameter values used when creating or validating per- 988 recipient Ciphertext and Authentication Tag values are the union of 989 the three sets of Header Parameter values that may be present: (1) 990 the JWE Protected Header represented in the "protected" member, (2) 991 the JWE Shared Unprotected Header represented in the "unprotected" 992 member, and (3) the JWE Per-Recipient Unprotected Header represented 993 in the "header" member of the recipient's array element. The union 994 of these sets of Header Parameters comprises the JWE Header. The 995 Header Parameter names in the three locations MUST be disjoint. 997 Each JWE Encrypted Key value is computed using the parameters of the 998 corresponding JWE Header value in the same manner as for the JWE 999 Compact Serialization. This has the desirable property that each JWE 1000 Encrypted Key value in the "recipients" array is identical to the 1001 value that would have been computed for the same parameter in the JWE 1002 Compact Serialization. Likewise, the JWE Ciphertext and JWE 1003 Authentication Tag values match those produced for the JWE Compact 1004 Serialization, provided that the JWE Protected Header value (which 1005 represents the integrity-protected Header Parameter values) matches 1006 that used in the JWE Compact Serialization. 1008 All recipients use the same JWE Protected Header, JWE Initialization 1009 Vector, JWE Ciphertext, and JWE Authentication Tag values, when 1010 present, resulting in potentially significant space savings if the 1011 message is large. Therefore, all Header Parameters that specify the 1012 treatment of the Plaintext value MUST be the same for all recipients. 1013 This primarily means that the "enc" (encryption algorithm) Header 1014 Parameter value in the JWE Header for each recipient and any 1015 parameters of that algorithm MUST be the same. 1017 In summary, the syntax of a JWE using the JWE JSON Serialization is 1018 as follows: 1020 {"protected":"", 1021 "unprotected":, 1022 "recipients":[ 1023 {"header":, 1024 "encrypted_key":""}, 1025 ... 1026 {"header":, 1027 "encrypted_key":""}], 1028 "aad":"", 1029 "iv":"", 1030 "ciphertext":"", 1031 "tag":"" 1032 } 1034 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1035 Serialization. 1037 8. TLS Requirements 1039 The TLS requirements for this specification are the same as those 1040 defined in Section 8 of [JWS]. 1042 9. Distinguishing between JWS and JWE Objects 1044 There are several ways of distinguishing whether an object is a JWS 1045 or JWE object. All these methods will yield the same result for all 1046 legal input values; they may yield different results for malformed 1047 inputs. 1049 o If the object is using the JWS Compact Serialization or the JWE 1050 Compact Serialization, the number of base64url encoded segments 1051 separated by period ('.') characters differs for JWSs and JWEs. 1052 JWSs have three segments separated by two period ('.') characters. 1053 JWEs have five segments separated by four period ('.') characters. 1055 o If the object is using the JWS JSON Serialization or the JWE JSON 1056 Serialization, the members used will be different. JWSs have a 1057 "signatures" member and JWEs do not. JWEs have a "recipients" 1058 member and JWSs do not. 1060 o A JWS Header can be distinguished from a JWE header by examining 1061 the "alg" (algorithm) Header Parameter value. If the value 1062 represents a digital signature or MAC algorithm, or is the value 1063 "none", it is for a JWS; if it represents a Key Encryption, Key 1064 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 1065 or Direct Encryption algorithm, it is for a JWE. (Extracting the 1066 "alg" value to examine is straightforward when using the JWS 1067 Compact Serialization or the JWE Compact Serialization and may be 1068 more difficult when using the JWS JSON Serialization or the JWE 1069 JSON Serialization.) 1071 o A JWS Header can also be distinguished from a JWE header by 1072 determining whether an "enc" (encryption algorithm) member exists. 1073 If the "enc" member exists, it is a JWE; otherwise, it is a JWS. 1075 10. IANA Considerations 1077 10.1. JSON Web Signature and Encryption Header Parameters Registration 1079 This specification registers the Header Parameter names defined in 1080 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1081 Parameters registry defined in [JWS]. 1083 10.1.1. Registry Contents 1085 o Header Parameter Name: "alg" 1086 o Header Parameter Description: Algorithm 1087 o Header Parameter Usage Location(s): JWE 1088 o Change Controller: IESG 1089 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1091 o Header Parameter Name: "enc" 1092 o Header Parameter Description: Encryption Algorithm 1093 o Header Parameter Usage Location(s): JWE 1094 o Change Controller: IESG 1095 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1097 o Header Parameter Name: "zip" 1098 o Header Parameter Description: Compression Algorithm 1099 o Header Parameter Usage Location(s): JWE 1100 o Change Controller: IESG 1101 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1103 o Header Parameter Name: "jku" 1104 o Header Parameter Description: JWK Set URL 1105 o Header Parameter Usage Location(s): JWE 1106 o Change Controller: IESG 1107 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1108 o Header Parameter Name: "jwk" 1109 o Header Parameter Description: JSON Web Key 1110 o Header Parameter Usage Location(s): JWE 1111 o Change Controller: IESG 1112 o Specification document(s): Section 4.1.5 of [[ this document ]] 1114 o Header Parameter Name: "kid" 1115 o Header Parameter Description: Key ID 1116 o Header Parameter Usage Location(s): JWE 1117 o Change Controller: IESG 1118 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1120 o Header Parameter Name: "x5u" 1121 o Header Parameter Description: X.509 URL 1122 o Header Parameter Usage Location(s): JWE 1123 o Change Controller: IESG 1124 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1126 o Header Parameter Name: "x5c" 1127 o Header Parameter Description: X.509 Certificate Chain 1128 o Header Parameter Usage Location(s): JWE 1129 o Change Controller: IESG 1130 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1132 o Header Parameter Name: "x5t" 1133 o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint 1134 o Header Parameter Usage Location(s): JWE 1135 o Change Controller: IESG 1136 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1138 o Header Parameter Name: "typ" 1139 o Header Parameter Description: Type 1140 o Header Parameter Usage Location(s): JWE 1141 o Change Controller: IESG 1142 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1144 o Header Parameter Name: "cty" 1145 o Header Parameter Description: Content Type 1146 o Header Parameter Usage Location(s): JWE 1147 o Change Controller: IESG 1148 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1150 o Header Parameter Name: "crit" 1151 o Header Parameter Description: Critical 1152 o Header Parameter Usage Location(s): JWE 1153 o Change Controller: IESG 1154 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1156 11. Security Considerations 1158 All of the security issues faced by any cryptographic application 1159 must be faced by a JWS/JWE/JWK agent. Among these issues are 1160 protecting the user's private and symmetric keys, preventing various 1161 attacks, and helping the user avoid mistakes such as inadvertently 1162 encrypting a message for the wrong recipient. The entire list of 1163 security considerations is beyond the scope of this document. 1165 All the security considerations in the JWS specification also apply 1166 to this specification. Likewise, all the security considerations in 1167 XML Encryption 1.1 [W3C.CR-xmlenc-core1-20120313] also apply, other 1168 than those that are XML specific. 1170 When decrypting, particular care must be taken not to allow the JWE 1171 recipient to be used as an oracle for decrypting messages. RFC 3218 1172 [RFC3218] should be consulted for specific countermeasures to attacks 1173 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1174 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1175 formatting error that can be detected and used to recover the CEK 1176 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1177 particularly important to report all formatting errors to the CEK, 1178 Additional Authenticated Data, or ciphertext as a single error when 1179 the encrypted content is rejected. 1181 Additionally, this type of attack can be prevented by the use of "key 1182 tainting". This method restricts the use of a key to a limited set 1183 of algorithms -- usually one. This means, for instance, that if the 1184 key is marked as being for "RSA-OAEP" only, any attempt to decrypt a 1185 message using the "RSA1_5" algorithm with that key would fail 1186 immediately due to invalid use of the key. 1188 12. References 1190 12.1. Normative References 1192 [ECMAScript] 1193 Ecma International, "ECMAScript Language Specification, 1194 5.1 Edition", ECMA 262, June 2011. 1196 [I-D.ietf-json-rfc4627bis] 1197 Bray, T., "The JSON Data Interchange Format", 1198 draft-ietf-json-rfc4627bis-10 (work in progress), 1199 December 2013. 1201 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1202 draft-ietf-jose-json-web-algorithms (work in progress), 1203 February 2014. 1205 [JWK] Jones, M., "JSON Web Key (JWK)", 1206 draft-ietf-jose-json-web-key (work in progress), 1207 February 2014. 1209 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1210 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1211 in progress), February 2014. 1213 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1214 version 1.3", RFC 1951, May 1996. 1216 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1217 Requirement Levels", BCP 14, RFC 2119, March 1997. 1219 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1220 10646", STD 63, RFC 3629, November 2003. 1222 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1223 Housley, R., and W. Polk, "Internet X.509 Public Key 1224 Infrastructure Certificate and Certificate Revocation List 1225 (CRL) Profile", RFC 5280, May 2008. 1227 [USASCII] American National Standards Institute, "Coded Character 1228 Set -- 7-bit American Standard Code for Information 1229 Interchange", ANSI X3.4, 1986. 1231 12.2. Informative References 1233 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1234 McGrew, D. and K. Paterson, "Authenticated Encryption with 1235 AES-CBC and HMAC-SHA", 1236 draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), 1237 October 2012. 1239 [I-D.rescorla-jsms] 1240 Rescorla, E. and J. Hildebrand, "JavaScript Message 1241 Security Format", draft-rescorla-jsms-00 (work in 1242 progress), March 2011. 1244 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1245 Encryption", September 2010. 1247 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1248 Cryptographic Message Syntax", RFC 3218, January 2002. 1250 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1251 Requirements for Security", BCP 106, RFC 4086, June 2005. 1253 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1254 RFC 5652, September 2009. 1256 [W3C.CR-xmlenc-core1-20120313] 1257 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 1258 "XML Encryption Syntax and Processing Version 1.1", World 1259 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1260 March 2012, 1261 . 1263 Appendix A. JWE Examples 1265 This section provides examples of JWE computations. 1267 A.1. Example JWE using RSAES OAEP and AES GCM 1269 This example encrypts the plaintext "The true sign of intelligence is 1270 not knowledge but imagination." to the recipient using RSAES OAEP for 1271 key encryption and AES GCM for content encryption. The 1272 representation of this plaintext is: 1274 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1275 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1276 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1277 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1278 110, 97, 116, 105, 111, 110, 46] 1280 A.1.1. JWE Header 1282 The following example JWE Protected Header declares that: 1284 o the Content Encryption Key is encrypted to the recipient using the 1285 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1287 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1288 bit key to produce the Ciphertext. 1290 {"alg":"RSA-OAEP","enc":"A256GCM"} 1292 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1293 Header)) gives this value: 1295 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1297 A.1.2. Content Encryption Key (CEK) 1299 Generate a 256 bit random Content Encryption Key (CEK). In this 1300 example, the value is: 1302 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1303 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1304 234, 64, 252] 1306 A.1.3. Key Encryption 1308 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1309 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1310 key represented in JSON Web Key [JWK] format below (with line breaks 1311 for display purposes only): 1313 {"kty":"RSA", 1314 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1315 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1316 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1317 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1318 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1319 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1320 "e":"AQAB", 1321 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1322 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1323 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1324 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1325 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1326 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ" 1327 } 1329 The resulting JWE Encrypted Key value is: 1331 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1332 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1333 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1334 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1335 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1336 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1337 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1338 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1339 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1340 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1341 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1342 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1343 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1344 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1345 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1346 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1347 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1348 117, 114, 135, 206] 1350 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1351 this value (with line breaks for display purposes only): 1353 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1354 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1355 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1356 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1357 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1358 6UklfCpIMfIjf7iGdXKHzg 1360 A.1.4. Initialization Vector 1362 Generate a random 96 bit JWE Initialization Vector. In this example, 1363 the value is: 1365 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1367 Encoding this JWE Initialization Vector as BASE64URL(JWE 1368 Initialization Vector) gives this value: 1370 48V1_ALb6US04U3b 1372 A.1.5. Additional Authenticated Data 1374 Let the Additional Authenticated Data encryption parameter be 1375 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1377 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1378 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1379 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1381 A.1.6. Content Encryption 1383 Encrypt the Plaintext with AES GCM using the CEK as the encryption 1384 key, the JWE Initialization Vector, and the Additional Authenticated 1385 Data value above, requesting a 128 bit Authentication Tag output. 1386 The resulting Ciphertext is: 1388 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1389 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1390 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1391 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1392 160, 109, 64, 63, 192] 1393 The resulting Authentication Tag value is: 1395 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1396 210, 145] 1398 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1399 value (with line breaks for display purposes only): 1401 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1402 SdiwkIr3ajwQzaBtQD_A 1404 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1405 Tag) gives this value: 1407 XFBoMYUZodetZdvTiFvSkQ 1409 A.1.7. Complete Representation 1411 Assemble the final representation: The Compact Serialization of this 1412 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1413 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1414 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1415 Authentication Tag). 1417 The final result in this example (with line breaks for display 1418 purposes only) is: 1420 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1421 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1422 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1423 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1424 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1425 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1426 6UklfCpIMfIjf7iGdXKHzg. 1427 48V1_ALb6US04U3b. 1428 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1429 SdiwkIr3ajwQzaBtQD_A. 1430 XFBoMYUZodetZdvTiFvSkQ 1432 A.1.8. Validation 1434 This example illustrates the process of creating a JWE with RSAES 1435 OAEP for key encryption and AES GCM for content encryption. These 1436 results can be used to validate JWE decryption implementations for 1437 these algorithms. Note that since the RSAES OAEP computation 1438 includes random values, the encryption results above will not be 1439 completely reproducible. However, since the AES GCM computation is 1440 deterministic, the JWE Encrypted Ciphertext values will be the same 1441 for all encryptions performed using these inputs. 1443 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1445 This example encrypts the plaintext "Live long and prosper." to the 1446 recipient using RSAES-PKCS1-V1_5 for key encryption and 1447 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1448 of this plaintext is: 1450 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1451 112, 114, 111, 115, 112, 101, 114, 46] 1453 A.2.1. JWE Header 1455 The following example JWE Protected Header declares that: 1457 o the Content Encryption Key is encrypted to the recipient using the 1458 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1460 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1461 algorithm to produce the Ciphertext. 1463 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1465 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1466 Header)) gives this value: 1468 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1470 A.2.2. Content Encryption Key (CEK) 1472 Generate a 256 bit random Content Encryption Key (CEK). In this 1473 example, the key value is: 1475 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1476 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1477 44, 207] 1479 A.2.3. Key Encryption 1481 Encrypt the CEK with the recipient's public key using the RSAES- 1482 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1483 uses the RSA key represented in JSON Web Key [JWK] format below (with 1484 line breaks for display purposes only): 1486 {"kty":"RSA", 1487 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1488 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1489 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1490 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1491 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1492 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1493 "e":"AQAB", 1494 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1495 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1496 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1497 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1498 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1499 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1500 } 1502 The resulting JWE Encrypted Key value is: 1504 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1505 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1506 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1507 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1508 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1509 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1510 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1511 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1512 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1513 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1514 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1515 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1516 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1517 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1518 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1519 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1520 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1521 146, 114, 165, 204, 71, 136, 41, 252] 1523 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1524 this value (with line breaks for display purposes only): 1526 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1527 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1528 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1529 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1530 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1531 -B3oWh2TbqmScqXMR4gp_A 1533 A.2.4. Initialization Vector 1535 Generate a random 128 bit JWE Initialization Vector. In this 1536 example, the value is: 1538 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1539 101] 1541 Encoding this JWE Initialization Vector as BASE64URL(JWE 1542 Initialization Vector) gives this value: 1544 AxY8DCtDaGlsbGljb3RoZQ 1546 A.2.5. Additional Authenticated Data 1548 Let the Additional Authenticated Data encryption parameter be 1549 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1551 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1552 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1553 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1554 50, 73, 110, 48] 1556 A.2.6. Content Encryption 1558 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1559 the encryption key, the JWE Initialization Vector, and the Additional 1560 Authenticated Data value above. The steps for doing this using the 1561 values from Appendix A.3 are detailed in Appendix B. The resulting 1562 Ciphertext is: 1564 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1565 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1566 112, 56, 102] 1568 The resulting Authentication Tag value is: 1570 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1571 191] 1573 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1574 value: 1576 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1578 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1579 Tag) gives this value: 1581 9hH0vgRfYgPnAHOd8stkvw 1583 A.2.7. Complete Representation 1585 Assemble the final representation: The Compact Serialization of this 1586 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1587 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1588 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1589 Authentication Tag). 1591 The final result in this example (with line breaks for display 1592 purposes only) is: 1594 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1595 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1596 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1597 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1598 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1599 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1600 -B3oWh2TbqmScqXMR4gp_A. 1601 AxY8DCtDaGlsbGljb3RoZQ. 1602 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1603 9hH0vgRfYgPnAHOd8stkvw 1605 A.2.8. Validation 1607 This example illustrates the process of creating a JWE with RSAES- 1608 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1609 encryption. These results can be used to validate JWE decryption 1610 implementations for these algorithms. Note that since the RSAES- 1611 PKCS1-V1_5 computation includes random values, the encryption results 1612 above will not be completely reproducible. However, since the AES 1613 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1614 will be the same for all encryptions performed using these inputs. 1616 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1618 This example encrypts the plaintext "Live long and prosper." to the 1619 recipient using AES Key Wrap for key encryption and AES GCM for 1620 content encryption. The representation of this plaintext is: 1622 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1623 112, 114, 111, 115, 112, 101, 114, 46] 1625 A.3.1. JWE Header 1627 The following example JWE Protected Header declares that: 1629 o the Content Encryption Key is encrypted to the recipient using the 1630 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1631 Encrypted Key and 1633 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1634 algorithm to produce the Ciphertext. 1636 {"alg":"A128KW","enc":"A128CBC-HS256"} 1638 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1639 Header)) gives this value: 1641 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1643 A.3.2. Content Encryption Key (CEK) 1645 Generate a 256 bit random Content Encryption Key (CEK). In this 1646 example, the value is: 1648 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1649 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1650 44, 207] 1652 A.3.3. Key Encryption 1654 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1655 algorithm to produce the JWE Encrypted Key. This example uses the 1656 symmetric key represented in JSON Web Key [JWK] format below: 1658 {"kty":"oct", 1659 "k":"GawgguFyGrWKav7AX4VKUg" 1660 } 1662 The resulting JWE Encrypted Key value is: 1664 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1665 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1666 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1668 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1669 this value: 1671 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1673 A.3.4. Initialization Vector 1675 Generate a random 128 bit JWE Initialization Vector. In this 1676 example, the value is: 1678 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1679 101] 1681 Encoding this JWE Initialization Vector as BASE64URL(JWE 1682 Initialization Vector) gives this value: 1684 AxY8DCtDaGlsbGljb3RoZQ 1686 A.3.5. Additional Authenticated Data 1688 Let the Additional Authenticated Data encryption parameter be 1689 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1691 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1692 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1693 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1694 110, 48] 1696 A.3.6. Content Encryption 1698 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1699 the encryption key, the JWE Initialization Vector, and the Additional 1700 Authenticated Data value above. The steps for doing this using the 1701 values from this example are detailed in Appendix B. The resulting 1702 Ciphertext is: 1704 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1705 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1706 112, 56, 102] 1708 The resulting Authentication Tag value is: 1710 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1711 194, 85] 1713 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1714 value: 1716 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1718 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1719 Tag) gives this value: 1721 U0m_YmjN04DJvceFICbCVQ 1723 A.3.7. Complete Representation 1725 Assemble the final representation: The Compact Serialization of this 1726 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1727 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1728 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1729 Authentication Tag). 1731 The final result in this example (with line breaks for display 1732 purposes only) is: 1734 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1735 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1736 AxY8DCtDaGlsbGljb3RoZQ. 1737 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1738 U0m_YmjN04DJvceFICbCVQ 1740 A.3.8. Validation 1742 This example illustrates the process of creating a JWE with AES Key 1743 Wrap for key encryption and AES GCM for content encryption. These 1744 results can be used to validate JWE decryption implementations for 1745 these algorithms. Also, since both the AES Key Wrap and AES GCM 1746 computations are deterministic, the resulting JWE value will be the 1747 same for all encryptions performed using these inputs. Since the 1748 computation is reproducible, these results can also be used to 1749 validate JWE encryption implementations for these algorithms. 1751 A.4. Example JWE using JWE JSON Serialization 1753 This section contains an example using the JWE JSON Serialization. 1754 This example demonstrates the capability for encrypting the same 1755 plaintext to multiple recipients. 1757 Two recipients are present in this example. The algorithm and key 1758 used for the first recipient are the same as that used in 1759 Appendix A.2. The algorithm and key used for the second recipient 1760 are the same as that used in Appendix A.3. The resulting JWE 1761 Encrypted Key values are therefore the same; those computations are 1762 not repeated here. 1764 The Plaintext, the Content Encryption Key (CEK), Initialization 1765 Vector, and JWE Protected Header are shared by all recipients (which 1766 must be the case, since the Ciphertext and Authentication Tag are 1767 also shared). 1769 A.4.1. JWE Per-Recipient Unprotected Headers 1771 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1772 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1773 encrypt the CEK. Key ID values are supplied for both keys. The two 1774 per-recipient header values used to represent these algorithms and 1775 Key IDs are: 1777 {"alg":"RSA1_5","kid":"2011-04-29"} 1779 and 1781 {"alg":"A128KW","kid":"7"} 1783 A.4.2. JWE Protected Header 1785 The Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1786 algorithm to produce the common JWE Ciphertext and JWE Authentication 1787 Tag values. The JWE Protected Header value representing this is: 1789 {"enc":"A128CBC-HS256"} 1791 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1792 Header)) gives this value: 1794 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1796 A.4.3. JWE Unprotected Header 1798 This JWE uses the "jku" Header Parameter to reference a JWK Set. This 1799 is represented in the following JWE Unprotected Header value as: 1801 {"jku":"https://server.example.com/keys.jwks"} 1803 A.4.4. Complete JWE Header Values 1805 Combining the per-recipient, protected, and unprotected header values 1806 supplied, the JWE Header values used for the first and second 1807 recipient respectively are: 1809 {"alg":"RSA1_5", 1810 "kid":"2011-04-29", 1811 "enc":"A128CBC-HS256", 1812 "jku":"https://server.example.com/keys.jwks"} 1814 and 1815 {"alg":"A128KW", 1816 "kid":"7", 1817 "enc":"A128CBC-HS256", 1818 "jku":"https://server.example.com/keys.jwks"} 1820 A.4.5. Additional Authenticated Data 1822 Let the Additional Authenticated Data encryption parameter be 1823 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1825 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1826 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1828 A.4.6. Content Encryption 1830 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1831 the encryption key, the JWE Initialization Vector, and the Additional 1832 Authenticated Data value above. The steps for doing this using the 1833 values from Appendix A.3 are detailed in Appendix B. The resulting 1834 Ciphertext is: 1836 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1837 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1838 112, 56, 102] 1840 The resulting Authentication Tag value is: 1842 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1843 207] 1845 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1846 value: 1848 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1850 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1851 Tag) gives this value: 1853 Mz-VPPyU4RlcuYv1IwIvzw 1855 A.4.7. Complete JWE JSON Serialization Representation 1857 The complete JSON Web Encryption JSON Serialization for these values 1858 is as follows (with line breaks for display purposes only): 1860 {"protected": 1861 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1862 "unprotected": 1863 {"jku":"https://server.example.com/keys.jwks"}, 1864 "recipients":[ 1865 {"header": 1866 {"alg":"RSA1_5"}, 1867 "encrypted_key": 1868 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1869 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1870 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 1871 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 1872 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 1873 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 1874 {"header": 1875 {"alg":"A128KW"}, 1876 "encrypted_key": 1877 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1878 "iv": 1879 "AxY8DCtDaGlsbGljb3RoZQ", 1880 "ciphertext": 1881 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1882 "tag": 1883 "Mz-VPPyU4RlcuYv1IwIvzw" 1884 } 1886 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 1888 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 1889 authenticated encryption computation using the values from the 1890 example in Appendix A.3. As described where this algorithm is 1891 defined in Sections 4.8 and 4.8.3 of JWA, the AES_CBC_HMAC_SHA2 1892 family of algorithms are implemented using Advanced Encryption 1893 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #5 1894 padding to perform the encryption and an HMAC SHA-2 function to 1895 perform the integrity calculation - in this case, HMAC SHA-256. 1897 B.1. Extract MAC_KEY and ENC_KEY from Key 1899 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example is: 1901 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1902 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1903 44, 207] 1905 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 1906 which is: 1908 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1909 206] 1911 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 1912 is: 1914 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 1915 207] 1917 Note that the MAC key comes before the encryption key in the input 1918 key K; this is in the opposite order of the algorithm names in the 1919 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 1921 B.2. Encrypt Plaintext to Create Ciphertext 1923 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 1924 using PKCS #5 padding using the ENC_KEY above. The Plaintext in this 1925 example is: 1927 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1928 112, 114, 111, 115, 112, 101, 114, 46] 1930 The encryption result is as follows, which is the Ciphertext output: 1932 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1933 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1934 112, 56, 102] 1936 B.3. 64 Bit Big Endian Representation of AAD Length 1938 The Additional Authenticated Data (AAD) in this example is: 1940 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1941 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1942 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1943 110, 48] 1945 This AAD is 51 bytes long, which is 408 bits long. The octet string 1946 AL, which is the number of bits in AAD expressed as a big endian 64 1947 bit unsigned integer is: 1949 [0, 0, 0, 0, 0, 0, 1, 152] 1951 B.4. Initialization Vector Value 1953 The Initialization Vector value used in this example is: 1955 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1956 101] 1958 B.5. Create Input to HMAC Computation 1960 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 1961 the AL value. The result of this concatenation is: 1963 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1964 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1965 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1966 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 1967 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 1968 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 1969 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 1971 B.6. Compute HMAC Value 1973 Compute the HMAC SHA-256 of the concatenated value above. This 1974 result M is: 1976 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1977 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 1978 86, 229, 116] 1980 B.7. Truncate HMAC Value to Create Authentication Tag 1982 Use the first half (128 bits) of the HMAC output M as the 1983 Authentication Tag output T. This truncated value is: 1985 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1986 194, 85] 1988 Appendix C. Acknowledgements 1990 Solutions for encrypting JSON content were also explored by JSON 1991 Simple Encryption [JSE] and JavaScript Message Security Format 1992 [I-D.rescorla-jsms], both of which significantly influenced this 1993 draft. This draft attempts to explicitly reuse as many of the 1994 relevant concepts from XML Encryption 1.1 1995 [W3C.CR-xmlenc-core1-20120313] and RFC 5652 [RFC5652] as possible, 1996 while utilizing simple, compact JSON-based data structures. 1998 Special thanks are due to John Bradley and Nat Sakimura for the 1999 discussions that helped inform the content of this specification and 2000 to Eric Rescorla and Joe Hildebrand for allowing the reuse of text 2001 from [I-D.rescorla-jsms] in this document. 2003 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2004 Jay for validating the examples in this specification. 2006 This specification is the work of the JOSE Working Group, which 2007 includes dozens of active and dedicated participants. In particular, 2008 the following individuals contributed ideas, feedback, and wording 2009 that influenced this specification: 2011 Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick 2012 Hardt, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Tony 2013 Nadalin, Axel Nennker, Emmanuel Raviart, Nat Sakimura, Jim Schaad, 2014 Hannes Tschofenig, and Sean Turner. 2016 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2017 Sean Turner and Stephen Farrell served as Security area directors 2018 during the creation of this specification. 2020 Appendix D. Document History 2022 [[ to be removed by the RFC Editor before publication as an RFC ]] 2024 -21 2026 o Changed some references from being normative to informative, 2027 addressing issue #90. 2029 o Applied review comments to the JSON Serialization section, 2030 addressing issue #178. 2032 -20 2034 o Made terminology definitions more consistent, addressing issue 2035 #165. 2037 o Restructured the JSON Serialization section to call out the 2038 parameters used in hanging lists, addressing issue #178. 2040 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 2041 addressing issue #90. 2043 -19 2045 o Reordered the key selection parameters. 2047 -18 2048 o Updated the mandatory-to-implement (MTI) language to say that 2049 applications using this specification need to specify what 2050 serialization and serialization features are used for that 2051 application, addressing issue #176. 2053 o Changes to address editorial and minor issues #89, #135, #165, 2054 #174, #175, #177, #179, and #180. 2056 o Used Header Parameter Description registry field. 2058 -17 2060 o Refined the "typ" and "cty" definitions to always be MIME Media 2061 Types, with the omission of "application/" prefixes recommended 2062 for brevity, addressing issue #50. 2064 o Updated the mandatory-to-implement (MTI) language to say that 2065 general-purpose implementations must implement the single 2066 recipient case for both serializations whereas special-purpose 2067 implementations can implement just one serialization if that meets 2068 the needs of the use cases the implementation is designed for, 2069 addressing issue #176. 2071 o Explicitly named all the logical components of a JWE and defined 2072 the processing rules and serializations in terms of those 2073 components, addressing issues #60, #61, and #62. 2075 o Replaced verbose repetitive phases such as "base64url encode the 2076 octets of the UTF-8 representation of X" with mathematical 2077 notation such as "BASE64URL(UTF8(X))". 2079 o Header Parameters and processing rules occurring in both JWS and 2080 JWE are now referenced in JWS by JWE, rather than duplicated, 2081 addressing issue #57. 2083 o Terms used in multiple documents are now defined in one place and 2084 incorporated by reference. Some lightly used or obvious terms 2085 were also removed. This addresses issue #58. 2087 -16 2089 o Changes to address editorial and minor issues #163, #168, #169, 2090 #170, #172, and #173. 2092 -15 2094 o Clarified that it is an application decision which recipients' 2095 encrypted content must successfully validate for the JWE to be 2096 accepted, addressing issue #35. 2098 o Changes to address editorial issues #34, #164, and #169. 2100 -14 2102 o Clarified that the "protected", "unprotected", "header", "iv", 2103 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2104 JSON Serialization when their values would be empty. Stated that 2105 the "recipients" array must always be present. 2107 -13 2109 o Added an "aad" (Additional Authenticated Data) member for the JWE 2110 JSON Serialization, enabling Additional Authenticated Data to be 2111 supplied that is not double base64url encoded, addressing issue 2112 #29. 2114 -12 2116 o Clarified that the "typ" and "cty" header parameters are used in 2117 an application-specific manner and have no effect upon the JWE 2118 processing. 2120 o Replaced the MIME types "application/jwe+json" and 2121 "application/jwe" with "application/jose+json" and 2122 "application/jose". 2124 o Stated that recipients MUST either reject JWEs with duplicate 2125 Header Parameter Names or use a JSON parser that returns only the 2126 lexically last duplicate member name. 2128 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2129 be with the algorithm descriptions that use them. 2131 o Added a Serializations section with parallel treatment of the JWE 2132 Compact Serialization and the JWE JSON Serialization and also 2133 moved the former Implementation Considerations content there. 2135 o Restored use of the term "AEAD". 2137 o Changed terminology from "block encryption" to "content 2138 encryption". 2140 -11 2142 o Added Key Identification section. 2144 o Removed the Encrypted Key value from the AAD computation since it 2145 is already effectively integrity protected by the encryption 2146 process. The AAD value now only contains the representation of 2147 the JWE Encrypted Header. 2149 o For the JWE JSON Serialization, enable Header Parameter values to 2150 be specified in any of three parameters: the "protected" member 2151 that is integrity protected and shared among all recipients, the 2152 "unprotected" member that is not integrity protected and shared 2153 among all recipients, and the "header" member that is not 2154 integrity protected and specific to a particular recipient. (This 2155 does not affect the JWE Compact Serialization, in which all Header 2156 Parameter values are in a single integrity protected JWE Header 2157 value.) 2159 o Shortened the names "authentication_tag" to "tag" and 2160 "initialization_vector" to "iv" in the JWE JSON Serialization, 2161 addressing issue #20. 2163 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2165 o Removed suggested compact serialization for multiple recipients. 2167 o Changed the MIME type name "application/jwe-js" to 2168 "application/jwe+json", addressing issue #22. 2170 o Tightened the description of the "crit" (critical) header 2171 parameter. 2173 -10 2175 o Changed the JWE processing rules for multiple recipients so that a 2176 single AAD value contains the header parameters and encrypted key 2177 values for all the recipients, enabling AES GCM to be safely used 2178 for multiple recipients. 2180 o Added an appendix suggesting a possible compact serialization for 2181 JWEs with multiple recipients. 2183 -09 2185 o Added JWE JSON Serialization, as specified by 2186 draft-jones-jose-jwe-json-serialization-04. 2188 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2189 parameter value. 2191 o Defined that the default action for header parameters that are not 2192 understood is to ignore them unless specifically designated as 2193 "MUST be understood" or included in the new "crit" (critical) 2194 header parameter list. This addressed issue #6. 2196 o Corrected "x5c" description. This addressed issue #12. 2198 o Changed from using the term "byte" to "octet" when referring to 8 2199 bit values. 2201 o Added Key Management Mode definitions to terminology section and 2202 used the defined terms to provide clearer key management 2203 instructions. This addressed issue #5. 2205 o Added text about preventing the recipient from behaving as an 2206 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2208 o Changed from using the term "Integrity Value" to "Authentication 2209 Tag". 2211 o Changed member name from "integrity_value" to "authentication_tag" 2212 in the JWE JSON Serialization. 2214 o Removed Initialization Vector from the AAD value since it is 2215 already integrity protected by all of the authenticated encryption 2216 algorithms specified in the JWA specification. 2218 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2219 and "A256CBC-HS512". The new algorithms perform the same 2220 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2221 but with the Initialization Vector and Authentication Tag values 2222 remaining separate from the Ciphertext value in the output 2223 representation. Also deleted the header parameters "epu" 2224 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2225 they are no longer used. 2227 -08 2229 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2230 since the term AEAD in the RFC 5116 sense implied the use of a 2231 particular data representation, rather than just referring to the 2232 class of algorithms that perform authenticated encryption with 2233 associated data. 2235 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2236 Tschofenig. Many of these simplified the terminology used. 2238 o Clarified statements of the form "This header parameter is 2239 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2241 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2242 Web Signature and Encryption Header Parameters registry. 2244 o Added seriesInfo information to Internet Draft references. 2246 -07 2248 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2250 o Updated values for example AES CBC calculations. 2252 o Made several local editorial changes to clean up loose ends left 2253 over from to the decision to only support block encryption methods 2254 providing integrity. One of these changes was to explicitly state 2255 that the "enc" (encryption method) algorithm must be an 2256 Authenticated Encryption algorithm with a specified key length. 2258 -06 2260 o Removed the "int" and "kdf" parameters and defined the new 2261 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2262 "A256CBC+HS512" to replace the former uses of AES CBC, which 2263 required the use of separate integrity and key derivation 2264 functions. 2266 o Included additional values in the Concat KDF calculation -- the 2267 desired output size and the algorithm value, and optionally 2268 PartyUInfo and PartyVInfo values. Added the optional header 2269 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2270 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2271 PartyVInfo). Updated the KDF examples accordingly. 2273 o Promoted Initialization Vector from being a header parameter to 2274 being a top-level JWE element. This saves approximately 16 bytes 2275 in the compact serialization, which is a significant savings for 2276 some use cases. Promoting the Initialization Vector out of the 2277 header also avoids repeating this shared value in the JSON 2278 serialization. 2280 o Changed "x5c" (X.509 Certificate Chain) representation from being 2281 a single string to being an array of strings, each containing a 2282 single base64 encoded DER certificate value, representing elements 2283 of the certificate chain. 2285 o Added an AES Key Wrap example. 2287 o Reordered the encryption steps so CMK creation is first, when 2288 required. 2290 o Correct statements in examples about which algorithms produce 2291 reproducible results. 2293 -05 2295 o Support both direct encryption using a shared or agreed upon 2296 symmetric key, and the use of a shared or agreed upon symmetric 2297 key to key wrap the CMK. 2299 o Added statement that "StringOrURI values are compared as case- 2300 sensitive strings with no transformations or canonicalizations 2301 applied". 2303 o Updated open issues. 2305 o Indented artwork elements to better distinguish them from the body 2306 text. 2308 -04 2310 o Refer to the registries as the primary sources of defined values 2311 and then secondarily reference the sections defining the initial 2312 contents of the registries. 2314 o Normatively reference XML Encryption 1.1 2315 [W3C.CR-xmlenc-core1-20120313] for its security considerations. 2317 o Reference draft-jones-jose-jwe-json-serialization instead of 2318 draft-jones-json-web-encryption-json-serialization. 2320 o Described additional open issues. 2322 o Applied editorial suggestions. 2324 -03 2326 o Added the "kdf" (key derivation function) header parameter to 2327 provide crypto agility for key derivation. The default KDF 2328 remains the Concat KDF with the SHA-256 digest function. 2330 o Reordered encryption steps so that the Encoded JWE Header is 2331 always created before it is needed as an input to the 2332 Authenticated Encryption "additional authenticated data" 2333 parameter. 2335 o Added the "cty" (content type) header parameter for declaring type 2336 information about the secured content, as opposed to the "typ" 2337 (type) header parameter, which declares type information about 2338 this object. 2340 o Moved description of how to determine whether a header is for a 2341 JWS or a JWE from the JWT spec to the JWE spec. 2343 o Added complete encryption examples for both Authenticated 2344 Encryption and non-Authenticated Encryption algorithms. 2346 o Added complete key derivation examples. 2348 o Added "Collision Resistant Namespace" to the terminology section. 2350 o Reference ITU.X690.1994 for DER encoding. 2352 o Added Registry Contents sections to populate registry values. 2354 o Numerous editorial improvements. 2356 -02 2358 o When using Authenticated Encryption algorithms (such as AES GCM), 2359 use the "additional authenticated data" parameter to provide 2360 integrity for the header, encrypted key, and ciphertext and use 2361 the resulting "authentication tag" value as the JWE Authentication 2362 Tag. 2364 o Defined KDF output key sizes. 2366 o Generalized text to allow key agreement to be employed as an 2367 alternative to key wrapping or key encryption. 2369 o Changed compression algorithm from gzip to DEFLATE. 2371 o Clarified that it is an error when a "kid" value is included and 2372 no matching key is found. 2374 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2375 rejected. 2377 o Clarified the relationship between "typ" header parameter values 2378 and MIME types. 2380 o Registered application/jwe MIME type and "JWE" typ header 2381 parameter value. 2383 o Simplified JWK terminology to get replace the "JWK Key Object" and 2384 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2385 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2386 between single keys and sets of keys. As part of this change, the 2387 Header Parameter Name for a public key value was changed from 2388 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2390 o Added suggestion on defining additional header parameters such as 2391 "x5t#S256" in the future for certificate thumbprints using hash 2392 algorithms other than SHA-1. 2394 o Specify RFC 2818 server identity validation, rather than RFC 6125 2395 (paralleling the same decision in the OAuth specs). 2397 o Generalized language to refer to Message Authentication Codes 2398 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2399 unless in a context specific to HMAC algorithms. 2401 o Reformatted to give each header parameter its own section heading. 2403 -01 2405 o Added an integrity check for non-Authenticated Encryption 2406 algorithms. 2408 o Added "jpk" and "x5c" header parameters for including JWK public 2409 keys and X.509 certificate chains directly in the header. 2411 o Clarified that this specification is defining the JWE Compact 2412 Serialization. Referenced the new JWE-JS spec, which defines the 2413 JWE JSON Serialization. 2415 o Added text "New header parameters should be introduced sparingly 2416 since an implementation that does not understand a parameter MUST 2417 reject the JWE". 2419 o Clarified that the order of the encryption and decryption steps is 2420 not significant in cases where there are no dependencies between 2421 the inputs and outputs of the steps. 2423 o Made other editorial improvements suggested by JOSE working group 2424 participants. 2426 -00 2427 o Created the initial IETF draft based upon 2428 draft-jones-json-web-encryption-02 with no normative changes. 2430 o Changed terminology to no longer call both digital signatures and 2431 HMACs "signatures". 2433 Authors' Addresses 2435 Michael B. Jones 2436 Microsoft 2438 Email: mbj@microsoft.com 2439 URI: http://self-issued.info/ 2441 Eric Rescorla 2442 RTFM, Inc. 2444 Email: ekr@rtfm.com 2446 Joe Hildebrand 2447 Cisco Systems, Inc. 2449 Email: jhildebr@cisco.com