idnits 2.17.1 draft-ietf-jose-json-web-encryption-30.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 (July 1, 2014) is 3586 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 1411 -- Looks like a reference, but probably isn't: '197' on line 1411 -- Looks like a reference, but probably isn't: '117' on line 1411 -- Looks like a reference, but probably isn't: '252' on line 1411 -- Looks like a reference, but probably isn't: '2' on line 1411 -- Looks like a reference, but probably isn't: '219' on line 1411 -- Looks like a reference, but probably isn't: '233' on line 1411 -- Looks like a reference, but probably isn't: '68' on line 1411 -- Looks like a reference, but probably isn't: '180' on line 1411 -- Looks like a reference, but probably isn't: '225' on line 1411 -- Looks like a reference, but probably isn't: '77' on line 1411 -- Looks like a reference, but probably isn't: '0' on line 2000 -- Looks like a reference, but probably isn't: '1' on line 2000 -- Looks like a reference, but probably isn't: '152' on line 2000 == Unused Reference: 'AES' is defined on line 1264, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' == Outdated reference: A later version (-05) exists of draft-mcgrew-aead-aes-cbc-hmac-sha2-04 -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 18 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track J. Hildebrand 5 Expires: January 2, 2015 Cisco 6 July 1, 2014 8 JSON Web Encryption (JWE) 9 draft-ietf-jose-json-web-encryption-30 11 Abstract 13 JSON Web Encryption (JWE) represents encrypted content using 14 JavaScript Object Notation (JSON) based data structures. 15 Cryptographic algorithms and identifiers for use with this 16 specification are described in the separate JSON Web Algorithms (JWA) 17 specification and IANA registries defined by that specification. 18 Related digital signature and MAC capabilities are described in the 19 separate JSON Web Signature (JWS) specification. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 2, 2015. 38 Copyright Notice 40 Copyright (c) 2014 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 58 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 8 59 3.1. JWE Compact Serialization Overview . . . . . . . . . . . . 10 60 3.2. JWE JSON Serialization Overview . . . . . . . . . . . . . 10 61 3.3. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 10 62 4. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 12 63 4.1. Registered Header Parameter Names . . . . . . . . . . . . 12 64 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 12 65 4.1.2. "enc" (Encryption Algorithm) Header Parameter . . . . 12 66 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 13 67 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 13 68 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 13 69 4.1.6. "kid" (Key ID) Header Parameter . . . . . . . . . . . 13 70 4.1.7. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 14 71 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 14 72 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 73 Parameter . . . . . . . . . . . . . . . . . . . . . . 14 74 4.1.10. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) 75 Header Parameter . . . . . . . . . . . . . . . . . . . 14 76 4.1.11. "typ" (Type) Header Parameter . . . . . . . . . . . . 14 77 4.1.12. "cty" (Content Type) Header Parameter . . . . . . . . 15 78 4.1.13. "crit" (Critical) Header Parameter . . . . . . . . . . 15 79 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15 80 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 15 81 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 15 82 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 15 83 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 17 84 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20 85 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20 86 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 20 87 7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 20 88 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21 89 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 23 90 9. Distinguishing between JWS and JWE Objects . . . . . . . . . . 24 91 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 92 10.1. JSON Web Signature and Encryption Header Parameters 93 Registration . . . . . . . . . . . . . . . . . . . . . . . 24 94 10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 24 95 11. Security Considerations . . . . . . . . . . . . . . . . . . . 26 96 11.1. Using Matching Algorithm Strengths . . . . . . . . . . . . 27 97 11.2. Adaptive Chosen-Ciphertext Attacks . . . . . . . . . . . . 27 98 11.3. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 27 99 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 100 12.1. Normative References . . . . . . . . . . . . . . . . . . . 27 101 12.2. Informative References . . . . . . . . . . . . . . . . . . 28 102 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 29 103 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 29 104 A.1.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 29 105 A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 30 106 A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 30 107 A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 31 108 A.1.5. Additional Authenticated Data . . . . . . . . . . . . 31 109 A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 32 110 A.1.7. Complete Representation . . . . . . . . . . . . . . . 32 111 A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 33 112 A.2. Example JWE using RSAES-PKCS1-V1_5 and 113 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 33 114 A.2.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 33 115 A.2.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 34 116 A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 34 117 A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 35 118 A.2.5. Additional Authenticated Data . . . . . . . . . . . . 35 119 A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 35 120 A.2.7. Complete Representation . . . . . . . . . . . . . . . 36 121 A.2.8. Validation . . . . . . . . . . . . . . . . . . . . . . 36 122 A.3. Example JWE using AES Key Wrap and 123 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 37 124 A.3.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 37 125 A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 37 126 A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 37 127 A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 38 128 A.3.5. Additional Authenticated Data . . . . . . . . . . . . 38 129 A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 38 130 A.3.7. Complete Representation . . . . . . . . . . . . . . . 39 131 A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 39 132 A.4. Example JWE using JWE JSON Serialization . . . . . . . . . 40 133 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 40 134 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 40 135 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 41 136 A.4.4. Complete JOSE Header Values . . . . . . . . . . . . . 41 137 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 41 138 A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 41 139 A.4.7. Complete JWE JSON Serialization Representation . . . . 42 140 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 43 141 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 43 142 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 43 143 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 44 144 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 44 145 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 44 146 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 44 147 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 45 148 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 45 149 Appendix D. Document History . . . . . . . . . . . . . . . . . . 45 150 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 56 152 1. Introduction 154 JSON Web Encryption (JWE) represents encrypted content using 155 JavaScript Object Notation (JSON) [RFC7159] based data structures. 156 The JWE cryptographic mechanisms encrypt and provide integrity 157 protection for an arbitrary sequence of octets. 159 Two closely related serializations for JWE objects are defined. The 160 JWE Compact Serialization is a compact, URL-safe representation 161 intended for space constrained environments such as HTTP 162 Authorization headers and URI query parameters. The JWE JSON 163 Serialization represents JWE objects as JSON objects and enables the 164 same content to be encrypted to multiple parties. Both share the 165 same cryptographic underpinnings. 167 Cryptographic algorithms and identifiers for use with this 168 specification are described in the separate JSON Web Algorithms (JWA) 169 [JWA] specification and IANA registries defined by that 170 specification. Related digital signature and MAC capabilities are 171 described in the separate JSON Web Signature (JWS) [JWS] 172 specification. 174 Names defined by this specification are short because a core goal is 175 for the resulting representations to be compact. 177 1.1. Notational Conventions 179 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 180 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 181 "OPTIONAL" in this document are to be interpreted as described in Key 182 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 183 these words are used without being spelled in uppercase then they are 184 to be interpreted with their normal natural language meanings. 186 BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per 187 Section 2. 189 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 190 of STRING. 192 ASCII(STRING) denotes the octets of the ASCII [USASCII] 193 representation of STRING. 195 The concatenation of two values A and B is denoted as A || B. 197 2. Terminology 199 These terms defined by the JSON Web Signature (JWS) [JWS] 200 specification are incorporated into this specification: "JSON Web 201 Signature (JWS)", "Base64url Encoding", "Collision-Resistant Name", 202 "Header Parameter", "JOSE Header", and "StringOrURI". 204 These terms are defined by this specification: 206 JSON Web Encryption (JWE) 207 A data structure representing an encrypted and integrity protected 208 message. 210 Authenticated Encryption with Associated Data (AEAD) 211 An AEAD algorithm is one that encrypts the Plaintext, allows 212 Additional Authenticated Data to be specified, and provides an 213 integrated content integrity check over the Ciphertext and 214 Additional Authenticated Data. AEAD algorithms accept two inputs, 215 the Plaintext and the Additional Authenticated Data value, and 216 produce two outputs, the Ciphertext and the Authentication Tag 217 value. AES Galois/Counter Mode (GCM) is one such algorithm. 219 Plaintext 220 The sequence of octets to be encrypted -- a.k.a., the message. 221 The plaintext can contain an arbitrary sequence of octets. 223 Ciphertext 224 An encrypted representation of the Plaintext. 226 Additional Authenticated Data (AAD) 227 An input to an AEAD operation that is integrity protected but not 228 encrypted. 230 Authentication Tag 231 An output of an AEAD operation that ensures the integrity of the 232 Ciphertext and the Additional Authenticated Data. Note that some 233 algorithms may not use an Authentication Tag, in which case this 234 value is the empty octet sequence. 236 Content Encryption Key (CEK) 237 A symmetric key for the AEAD algorithm used to encrypt the 238 Plaintext for the recipient to produce the Ciphertext and the 239 Authentication Tag. 241 JWE Encrypted Key 242 Encrypted Content Encryption Key (CEK) value. Note that for some 243 algorithms, the JWE Encrypted Key value is specified as being the 244 empty octet sequence. 246 JWE Initialization Vector 247 Initialization vector value used when encrypting the plaintext. 248 Note that some algorithms may not use an Initialization Vector, in 249 which case this value is the empty octet sequence. 251 JWE AAD 252 Additional value to be integrity protected by the authenticated 253 encryption operation. This can only be present when using the JWE 254 JSON Serialization. (Note that this can also be achieved when 255 using either serialization by including the AAD value as an 256 integrity protected Header Parameter value, but at the cost of the 257 value being double base64url encoded.) 259 JWE Ciphertext 260 Ciphertext value resulting from authenticated encryption of the 261 plaintext with additional authenticated data. 263 JWE Authentication Tag 264 Authentication Tag value resulting from authenticated encryption 265 of the plaintext with additional authenticated data. 267 JWE Protected Header 268 JSON object that contains the Header Parameters that are integrity 269 protected by the authenticated encryption operation. These 270 parameters apply to all recipients of the JWE. For the JWE 271 Compact Serialization, this comprises the entire JOSE Header. For 272 the JWE JSON Serialization, this is one component of the JOSE 273 Header. 275 JWE Shared Unprotected Header 276 JSON object that contains the Header Parameters that apply to all 277 recipients of the JWE that are not integrity protected. This can 278 only be present when using the JWE JSON Serialization. 280 JWE Per-Recipient Unprotected Header 281 JSON object that contains Header Parameters that apply to a single 282 recipient of the JWE. These Header Parameter values are not 283 integrity protected. This can only be present when using the JWE 284 JSON Serialization. 286 JWE Compact Serialization 287 A representation of the JWE as a compact, URL-safe string. 289 JWE JSON Serialization 290 A representation of the JWE as a JSON object. The JWE JSON 291 Serialization enables the same content to be encrypted to multiple 292 parties. This representation is neither optimized for compactness 293 nor URL-safe. 295 Key Management Mode 296 A method of determining the Content Encryption Key (CEK) value to 297 use. Each algorithm used for determining the CEK value uses a 298 specific Key Management Mode. Key Management Modes employed by 299 this specification are Key Encryption, Key Wrapping, Direct Key 300 Agreement, Key Agreement with Key Wrapping, and Direct Encryption. 302 Key Encryption 303 A Key Management Mode in which the Content Encryption Key (CEK) 304 value is encrypted to the intended recipient using an asymmetric 305 encryption algorithm. 307 Key Wrapping 308 A Key Management Mode in which the Content Encryption Key (CEK) 309 value is encrypted to the intended recipient using a symmetric key 310 wrapping algorithm. 312 Direct Key Agreement 313 A Key Management Mode in which a key agreement algorithm is used 314 to agree upon the Content Encryption Key (CEK) value. 316 Key Agreement with Key Wrapping 317 A Key Management Mode in which a key agreement algorithm is used 318 to agree upon a symmetric key used to encrypt the Content 319 Encryption Key (CEK) value to the intended recipient using a 320 symmetric key wrapping algorithm. 322 Direct Encryption 323 A Key Management Mode in which the Content Encryption Key (CEK) 324 value used is the secret symmetric key value shared between the 325 parties. 327 3. JSON Web Encryption (JWE) Overview 329 JWE represents encrypted content using JSON data structures and 330 base64url encoding. A JWE represents these logical values: 332 JOSE Header 333 JSON object containing the parameters describing the cryptographic 334 operations and parameters employed. For a JWE object, the JOSE 335 Header members are the union of the members of the JWE Protected 336 Header, the JWE Shared Unprotected Header, and the JWE Per- 337 Recipient Unprotected Header, as described below. 339 JWE Encrypted Key 340 Encrypted Content Encryption Key (CEK) value. 342 JWE Initialization Vector 343 Initialization Vector value used when encrypting the plaintext. 345 JWE AAD 346 Additional value to be integrity protected by the authenticated 347 encryption operation. 349 JWE Ciphertext 350 Ciphertext value resulting from authenticated encryption of the 351 plaintext with additional authenticated data. 353 JWE Authentication Tag 354 Authentication Tag value resulting from authenticated encryption 355 of the plaintext with additional authenticated data. 357 For a JWE object, the JOSE Header represents the combination of these 358 logical values: 360 JWE Protected Header 361 JSON object that contains the Header Parameters that are integrity 362 protected by the authenticated encryption operation. These 363 parameters apply to all recipients of the JWE. 365 JWE Shared Unprotected Header 366 JSON object that contains the Header Parameters that apply to all 367 recipients of the JWE that are not integrity protected. 369 JWE Per-Recipient Unprotected Header 370 JSON object that contains Header Parameters that apply to a single 371 recipient of the JWE. These Header Parameter values are not 372 integrity protected. 374 JWE utilizes authenticated encryption to ensure the confidentiality 375 and integrity of the Plaintext and the integrity of the JWE Protected 376 Header and the JWE AAD. 378 This document defines two serializations for JWE objects: a compact, 379 URL-safe serialization called the JWE Compact Serialization and a 380 JSON serialization called the JWE JSON Serialization. In both 381 serializations, the JWE Protected Header, JWE Encrypted Key, JWE 382 Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are 383 base64url encoded for transmission, since JSON lacks a way to 384 directly represent octet sequences. When present, the JWE AAD is 385 also base64url encoded for transmission. 387 3.1. JWE Compact Serialization Overview 389 In the JWE Compact Serialization, no JWE Shared Unprotected Header or 390 JWE Per-Recipient Unprotected Header are used. In this case, the 391 JOSE Header and the JWE Protected Header are the same. 393 In the JWE Compact Serialization, a JWE object is represented as the 394 combination of these five string values, 395 BASE64URL(UTF8(JWE Protected Header)), 396 BASE64URL(JWE Encrypted Key), 397 BASE64URL(JWE Initialization Vector), 398 BASE64URL(JWE Ciphertext), and 399 BASE64URL(JWE Authentication Tag), 400 concatenated in that order, with the five strings being separated by 401 four period ('.') characters. 403 3.2. JWE JSON Serialization Overview 405 In the JWE JSON Serialization, one or more of the JWE Protected 406 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 407 Unprotected Header MUST be present. In this case, the members of the 408 JOSE Header are the combination of the members of the JWE Protected 409 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 410 Unprotected Header values that are present. 412 In the JWE JSON Serialization, a JWE object is represented as the 413 combination of these eight values, 414 BASE64URL(UTF8(JWE Protected Header)), 415 JWE Shared Unprotected Header, 416 JWE Per-Recipient Unprotected Header, 417 BASE64URL(JWE Encrypted Key), 418 BASE64URL(JWE Initialization Vector), 419 BASE64URL(JWE Ciphertext), 420 BASE64URL(JWE Authentication Tag), and 421 BASE64URL(JWE AAD), 422 with the six base64url encoded result strings and the two unprotected 423 JSON object values being represented as members within a JSON object. 424 The inclusion of some of these values is OPTIONAL. The JWE JSON 425 Serialization can also encrypt the plaintext to multiple recipients. 426 See Section 7.2 for more information about the JWE JSON 427 Serialization. 429 3.3. Example JWE 431 This example encrypts the plaintext "The true sign of intelligence is 432 not knowledge but imagination." to the recipient. 434 The following example JWE Protected Header declares that: 436 o the Content Encryption Key is encrypted to the recipient using the 437 RSAES OAEP [RFC3447] algorithm to produce the JWE Encrypted Key 438 and 439 o the Plaintext is encrypted using the AES GCM [AES, NIST.800-38D] 440 algorithm with a 256 bit key to produce the Ciphertext. 442 {"alg":"RSA-OAEP","enc":"A256GCM"} 444 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 445 Header)) gives this value: 447 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 449 The remaining steps to finish creating this JWE are: 450 o Generate a random Content Encryption Key (CEK). 451 o Encrypt the CEK with the recipient's public key using the RSAES 452 OAEP algorithm to produce the JWE Encrypted Key. 453 o Base64url encode the JWE Encrypted Key. 454 o Generate a random JWE Initialization Vector. 455 o Base64url encode the JWE Initialization Vector. 456 o Let the Additional Authenticated Data encryption parameter be 457 ASCII(BASE64URL(UTF8(JWE Protected Header))). 458 o Encrypt the Plaintext with AES GCM using the CEK as the encryption 459 key, the JWE Initialization Vector, and the Additional 460 Authenticated Data value, requesting a 128 bit Authentication Tag 461 output. 462 o Base64url encode the Ciphertext. 463 o Base64url encode the Authentication Tag. 464 o Assemble the final representation: The Compact Serialization of 465 this result is the string BASE64URL(UTF8(JWE Protected Header)) || 466 '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE 467 Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' 468 || BASE64URL(JWE Authentication Tag). 470 The final result in this example (with line breaks for display 471 purposes only) is: 473 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 474 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 475 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 476 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 477 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 478 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 479 6UklfCpIMfIjf7iGdXKHzg. 480 48V1_ALb6US04U3b. 481 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 482 SdiwkIr3ajwQzaBtQD_A. 483 XFBoMYUZodetZdvTiFvSkQ 485 See Appendix A.1 for the complete details of computing this JWE. See 486 other parts of Appendix A for additional examples. 488 4. JOSE Header 490 For a JWE object, the members of the JSON object(s) representing the 491 JOSE Header describe the encryption applied to the Plaintext and 492 optionally additional properties of the JWE. The Header Parameter 493 names within the JOSE Header MUST be unique, just as described in 494 Section 4 of [JWS]. The rules about handling Header Parameters that 495 are not understood by the implementation are also the same. The 496 classes of Header Parameter names are likewise the same. 498 4.1. Registered Header Parameter Names 500 The following Header Parameter names for use in JWE objects are 501 registered in the IANA JSON Web Signature and Encryption Header 502 Parameters registry defined in [JWS], with meanings as defined below. 504 As indicated by the common registry, JWSs and JWEs share a common 505 Header Parameter space; when a parameter is used by both 506 specifications, its usage must be compatible between the 507 specifications. 509 4.1.1. "alg" (Algorithm) Header Parameter 511 This parameter has the same meaning, syntax, and processing rules as 512 the "alg" Header Parameter defined in Section 4.1.1 of [JWS], except 513 that the Header Parameter identifies the cryptographic algorithm used 514 to encrypt or determine the value of the Content Encryption Key 515 (CEK). The encrypted content is not usable if the "alg" value does 516 not represent a supported algorithm, or if the recipient does not 517 have a key that can be used with that algorithm. 519 A list of defined "alg" values for this use can be found in the IANA 520 JSON Web Signature and Encryption Algorithms registry defined in 521 [JWA]; the initial contents of this registry are the values defined 522 in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. 524 4.1.2. "enc" (Encryption Algorithm) Header Parameter 526 The "enc" (encryption algorithm) Header Parameter identifies the 527 content encryption algorithm used to encrypt the Plaintext to produce 528 the Ciphertext. This algorithm MUST be an AEAD algorithm with a 529 specified key length. The recipient MUST reject the JWE if the "enc" 530 value does not represent a supported algorithm. "enc" values should 531 either be registered in the IANA JSON Web Signature and Encryption 532 Algorithms registry defined in [JWA] or be a value that contains a 533 Collision-Resistant Name. The "enc" value is a case-sensitive string 534 containing a StringOrURI value. This Header Parameter MUST be 535 present and MUST be understood and processed by implementations. 537 A list of defined "enc" values for this use can be found in the IANA 538 JSON Web Signature and Encryption Algorithms registry defined in 539 [JWA]; the initial contents of this registry are the values defined 540 in Section 5.1 of the JSON Web Algorithms (JWA) [JWA] specification. 542 4.1.3. "zip" (Compression Algorithm) Header Parameter 544 The "zip" (compression algorithm) applied to the Plaintext before 545 encryption, if any. The "zip" value defined by this specification 546 is: 548 o "DEF" - Compression with the DEFLATE [RFC1951] algorithm 550 Other values MAY be used. Compression algorithm values can be 551 registered in the IANA JSON Web Encryption Compression Algorithm 552 registry defined in [JWA]. The "zip" value is a case-sensitive 553 string. If no "zip" parameter is present, no compression is applied 554 to the Plaintext before encryption. This Header Parameter MUST be 555 integrity protected, and therefore MUST occur only within the JWE 556 Protected Header, when used. Use of this Header Parameter is 557 OPTIONAL. This Header Parameter MUST be understood and processed by 558 implementations. 560 4.1.4. "jku" (JWK Set URL) Header Parameter 562 This parameter has the same meaning, syntax, and processing rules as 563 the "jku" Header Parameter defined in Section 4.1.2 of [JWS], except 564 that the JWK Set resource contains the public key to which the JWE 565 was encrypted; this can be used to determine the private key needed 566 to decrypt the JWE. 568 4.1.5. "jwk" (JSON Web Key) Header Parameter 570 This parameter has the same meaning, syntax, and processing rules as 571 the "jwk" Header Parameter defined in Section 4.1.3 of [JWS], except 572 that the key is the public key to which the JWE was encrypted; this 573 can be used to determine the private key needed to decrypt the JWE. 575 4.1.6. "kid" (Key ID) Header Parameter 577 This parameter has the same meaning, syntax, and processing rules as 578 the "kid" Header Parameter defined in Section 4.1.4 of [JWS], except 579 that the key hint references the public key to which the JWE was 580 encrypted; this can be used to determine the private key needed to 581 decrypt the JWE. This parameter allows originators to explicitly 582 signal a change of key to JWE recipients. 584 4.1.7. "x5u" (X.509 URL) Header Parameter 586 This parameter has the same meaning, syntax, and processing rules as 587 the "x5u" Header Parameter defined in Section 4.1.5 of [JWS], except 588 that the X.509 public key certificate or certificate chain [RFC5280] 589 contains the public key to which the JWE was encrypted; this can be 590 used to determine the private key needed to decrypt the JWE. 592 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 594 This parameter has the same meaning, syntax, and processing rules as 595 the "x5c" Header Parameter defined in Section 4.1.6 of [JWS], except 596 that the X.509 public key certificate or certificate chain [RFC5280] 597 contains the public key to which the JWE was encrypted; this can be 598 used to determine the private key needed to decrypt the JWE. 600 See Appendix B of [JWS] for an example "x5c" value. 602 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 604 This parameter has the same meaning, syntax, and processing rules as 605 the "x5t" Header Parameter defined in Section 4.1.7 of [JWS], except 606 that the certificate referenced by the thumbprint contains the public 607 key to which the JWE was encrypted; this can be used to determine the 608 private key needed to decrypt the JWE. 610 4.1.10. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header 611 Parameter 613 This parameter has the same meaning, syntax, and processing rules as 614 the "x5t#S256" Header Parameter defined in Section 4.1.8 of [JWS], 615 except that the certificate referenced by the thumbprint contains the 616 public key to which the JWE was encrypted; this can be used to 617 determine the private key needed to decrypt the JWE. 619 4.1.11. "typ" (Type) Header Parameter 621 This parameter has the same meaning, syntax, and processing rules as 622 the "typ" Header Parameter defined in Section 4.1.9 of [JWS], except 623 that the type is that of this complete JWE object. 625 4.1.12. "cty" (Content Type) Header Parameter 627 This parameter has the same meaning, syntax, and processing rules as 628 the "cty" Header Parameter defined in Section 4.1.10 of [JWS], except 629 that the type is that of the secured content (the plaintext). 631 4.1.13. "crit" (Critical) Header Parameter 633 This parameter has the same meaning, syntax, and processing rules as 634 the "crit" Header Parameter defined in Section 4.1.11 of [JWS], 635 except that Header Parameters for a JWE object are being referred to, 636 rather than Header Parameters for a JWS object. 638 4.2. Public Header Parameter Names 640 Additional Header Parameter names can be defined by those using JWEs. 641 However, in order to prevent collisions, any new Header Parameter 642 name should either be registered in the IANA JSON Web Signature and 643 Encryption Header Parameters registry defined in [JWS] or be a Public 644 Name: a value that contains a Collision-Resistant Name. In each 645 case, the definer of the name or value needs to take reasonable 646 precautions to make sure they are in control of the part of the 647 namespace they use to define the Header Parameter name. 649 New Header Parameters should be introduced sparingly, as they can 650 result in non-interoperable JWEs. 652 4.3. Private Header Parameter Names 654 A producer and consumer of a JWE may agree to use Header Parameter 655 names that are Private Names: names that are not Registered Header 656 Parameter names Section 4.1 or Public Header Parameter names 657 Section 4.2. Unlike Public Header Parameter names, Private Header 658 Parameter names are subject to collision and should be used with 659 caution. 661 5. Producing and Consuming JWEs 663 5.1. Message Encryption 665 The message encryption process is as follows. The order of the steps 666 is not significant in cases where there are no dependencies between 667 the inputs and outputs of the steps. 669 1. Determine the Key Management Mode employed by the algorithm used 670 to determine the Content Encryption Key (CEK) value. (This is 671 the algorithm recorded in the "alg" (algorithm) Header Parameter 672 of the resulting JWE.) 674 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 675 Wrapping are employed, generate a random Content Encryption Key 676 (CEK) value. See RFC 4086 [RFC4086] for considerations on 677 generating random values. The CEK MUST have a length equal to 678 that required for the content encryption algorithm. 680 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 681 employed, use the key agreement algorithm to compute the value 682 of the agreed upon key. When Direct Key Agreement is employed, 683 let the Content Encryption Key (CEK) be the agreed upon key. 684 When Key Agreement with Key Wrapping is employed, the agreed 685 upon key will be used to wrap the CEK. 687 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 688 Wrapping are employed, encrypt the CEK to the recipient and let 689 the result be the JWE Encrypted Key. 691 5. When Direct Key Agreement or Direct Encryption are employed, let 692 the JWE Encrypted Key be the empty octet sequence. 694 6. When Direct Encryption is employed, let the Content Encryption 695 Key (CEK) be the shared symmetric key. 697 7. Compute the encoded key value BASE64URL(JWE Encrypted Key). 699 8. If the JWE JSON Serialization is being used, repeat this process 700 (steps 1-7) for each recipient. 702 9. Generate a random JWE Initialization Vector of the correct size 703 for the content encryption algorithm (if required for the 704 algorithm); otherwise, let the JWE Initialization Vector be the 705 empty octet sequence. 707 10. Compute the encoded initialization vector value BASE64URL(JWE 708 Initialization Vector). 710 11. If a "zip" parameter was included, compress the Plaintext using 711 the specified compression algorithm. 713 12. Serialize the (compressed) Plaintext into an octet sequence M. 715 13. Create the JSON object(s) containing the desired set of Header 716 Parameters, which together comprise the JOSE Header: the JWE 717 Protected Header, and if the JWE JSON Serialization is being 718 used, the JWE Shared Unprotected Header and the JWE Per- 719 Recipient Unprotected Header. 721 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 722 Protected Header)). If the JWE Protected Header is not present 723 (which can only happen when using the JWE JSON Serialization and 724 no "protected" member is present), let this value be the empty 725 string. 727 15. Let the Additional Authenticated Data encryption parameter be 728 ASCII(Encoded Protected Header). However if a JWE AAD value is 729 present (which can only be the case when using the JWE JSON 730 Serialization), instead let the Additional Authenticated Data 731 encryption parameter be ASCII(Encoded Protected Header || '.' || 732 BASE64URL(JWE AAD)). 734 16. Encrypt M using the CEK, the JWE Initialization Vector, and the 735 Additional Authenticated Data value using the specified content 736 encryption algorithm to create the JWE Ciphertext value and the 737 JWE Authentication Tag (which is the Authentication Tag output 738 from the encryption operation). 740 17. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext). 742 18. Compute the encoded authentication tag value BASE64URL(JWE 743 Authentication Tag). 745 19. The five encoded values are used in both the JWE Compact 746 Serialization and the JWE JSON Serialization representations. 748 20. If a JWE AAD value is present, compute the encoded AAD value 749 BASE64URL(JWE AAD). 751 21. Create the desired serialized output. The Compact Serialization 752 of this result is the string BASE64URL(UTF8(JWE Protected 753 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 754 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 755 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). The 756 JWE JSON Serialization is described in Section 7.2. 758 5.2. Message Decryption 760 The message decryption process is the reverse of the encryption 761 process. The order of the steps is not significant in cases where 762 there are no dependencies between the inputs and outputs of the 763 steps. If any of these steps fails, the encrypted content cannot be 764 validated. 766 It is an application decision which recipients' encrypted content 767 must successfully validate for the JWE to be accepted. In some 768 cases, encrypted content for all recipients must successfully 769 validate or the JWE will be rejected. In other cases, only the 770 encrypted content for a single recipient needs to be successfully 771 validated. However, in all cases, the encrypted content for at least 772 one recipient MUST successfully validate or the JWE MUST be rejected. 774 1. Parse the JWE representation to extract the serialized values 775 for the components of the JWE. When using the JWE Compact 776 Serialization, these components are the base64url encoded 777 representations of the JWE Protected Header, the JWE Encrypted 778 Key, the JWE Initialization Vector, the JWE Ciphertext, and the 779 JWE Authentication Tag, and when using the JWE JSON 780 Serialization, these components also include the base64url 781 encoded representation of the JWE AAD and the unencoded JWE 782 Shared Unprotected Header and JWE Per-Recipient Unprotected 783 Header values. When using the JWE Compact Serialization, the 784 JWE Protected Header, the JWE Encrypted Key, the JWE 785 Initialization Vector, the JWE Ciphertext, and the JWE 786 Authentication Tag are represented as base64url encoded values 787 in that order, separated by four period ('.') characters. The 788 JWE JSON Serialization is described in Section 7.2. 790 2. The encoded representations of the JWE Protected Header, the JWE 791 Encrypted Key, the JWE Initialization Vector, the JWE 792 Ciphertext, the JWE Authentication Tag, and the JWE AAD MUST be 793 successfully base64url decoded following the restriction that no 794 padding characters have been used. 796 3. The octet sequence resulting from decoding the encoded JWE 797 Protected Header MUST be a UTF-8 encoded representation of a 798 completely valid JSON object conforming to RFC 7159 [RFC7159], 799 which is the JWE Protected Header. 801 4. If using the JWE Compact Serialization, let the JOSE Header be 802 the JWE Protected Header. Otherwise, when using the JWE JSON 803 Serialization, let the JOSE Header be the union of the members 804 of the JWE Protected Header, the JWE Shared Unprotected Header 805 and the corresponding JWE Per-Recipient Unprotected Header, all 806 of which must be completely valid JSON objects. 808 5. The resulting JOSE Header MUST NOT contain duplicate Header 809 Parameter names. When using the JWE JSON Serialization, this 810 restriction includes that the same Header Parameter name also 811 MUST NOT occur in distinct JSON object values that together 812 comprise the JOSE Header. 814 6. Verify that the implementation understands and can process all 815 fields that it is required to support, whether required by this 816 specification, by the algorithms being used, or by the "crit" 817 Header Parameter value, and that the values of those parameters 818 are also understood and supported. 820 7. Determine the Key Management Mode employed by the algorithm 821 specified by the "alg" (algorithm) Header Parameter. 823 8. Verify that the JWE uses a key known to the recipient. 825 9. When Direct Key Agreement or Key Agreement with Key Wrapping are 826 employed, use the key agreement algorithm to compute the value 827 of the agreed upon key. When Direct Key Agreement is employed, 828 let the Content Encryption Key (CEK) be the agreed upon key. 829 When Key Agreement with Key Wrapping is employed, the agreed 830 upon key will be used to decrypt the JWE Encrypted Key. 832 10. When Key Wrapping, Key Encryption, or Key Agreement with Key 833 Wrapping are employed, decrypt the JWE Encrypted Key to produce 834 the Content Encryption Key (CEK). The CEK MUST have a length 835 equal to that required for the content encryption algorithm. 836 Note that when there are multiple recipients, each recipient 837 will only be able decrypt any JWE Encrypted Key values that were 838 encrypted to a key in that recipient's possession. It is 839 therefore normal to only be able to decrypt one of the per- 840 recipient JWE Encrypted Key values to obtain the CEK value. 841 Also, see Section 11.3 for security considerations on mitigating 842 timing attacks. 844 11. When Direct Key Agreement or Direct Encryption are employed, 845 verify that the JWE Encrypted Key value is empty octet sequence. 847 12. When Direct Encryption is employed, let the Content Encryption 848 Key (CEK) be the shared symmetric key. 850 13. If the JWE JSON Serialization is being used, repeat this process 851 (steps 4-12) for each recipient contained in the representation 852 until the CEK value has been determined. 854 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 855 Protected Header)). If the JWE Protected Header is not present 856 (which can only happen when using the JWE JSON Serialization and 857 no "protected" member is present), let this value be the empty 858 string. 860 15. Let the Additional Authenticated Data encryption parameter be 861 ASCII(Encoded Protected Header). However if a JWE AAD value is 862 present (which can only be the case when using the JWE JSON 863 Serialization), instead let the Additional Authenticated Data 864 encryption parameter be ASCII(Encoded Protected Header || '.' || 865 BASE64URL(JWE AAD)). 867 16. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 868 Vector, the Additional Authenticated Data value, and the JWE 869 Authentication Tag (which is the Authentication Tag input to the 870 calculation) using the specified content encryption algorithm, 871 returning the decrypted plaintext and validating the JWE 872 Authentication Tag in the manner specified for the algorithm, 873 rejecting the input without emitting any decrypted output if the 874 JWE Authentication Tag is incorrect. 876 17. If a "zip" parameter was included, uncompress the decrypted 877 plaintext using the specified compression algorithm. 879 18. If all the previous steps succeeded, output the resulting 880 Plaintext. 882 5.3. String Comparison Rules 884 The string comparison rules for this specification are the same as 885 those defined in Section 5.3 of [JWS]. 887 6. Key Identification 889 The key identification methods for this specification are the same as 890 those defined in Section 6 of [JWS], except that the key being 891 identified is the public key to which the JWE was encrypted. 893 7. Serializations 895 JWE objects use one of two serializations, the JWE Compact 896 Serialization or the JWE JSON Serialization. Applications using this 897 specification need to specify what serialization and serialization 898 features are used for that application. For instance, applications 899 might specify that only the JWE JSON Serialization is used, that only 900 JWE JSON Serialization support for a single recipient is used, or 901 that support for multiple recipients is used. JWE implementations 902 only need to implement the features needed for the applications they 903 are designed to support. 905 7.1. JWE Compact Serialization 907 The JWE Compact Serialization represents encrypted content as a 908 compact URL-safe string. This string is BASE64URL(UTF8(JWE Protected 909 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 910 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 911 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). Only one 912 recipient is supported by the JWE Compact Serialization and it 913 provides no syntax to represent JWE Shared Unprotected Header, JWE 914 Per-Recipient Unprotected Header, or JWE AAD values. 916 7.2. JWE JSON Serialization 918 The JWE JSON Serialization represents encrypted content as a JSON 919 object. Content using the JWE JSON Serialization can be encrypted to 920 more than one recipient. This representation is neither optimized 921 for compactness nor URL-safe. 923 The following members are defined for use in top-level JSON objects 924 used for the JWE JSON Serialization: 926 protected 927 The "protected" member MUST be present and contain the value 928 BASE64URL(UTF8(JWE Protected Header)) when the JWE Protected 929 Header value is non-empty; otherwise, it MUST be absent. These 930 Header Parameter values are integrity protected. 932 unprotected 933 The "unprotected" member MUST be present and contain the value JWE 934 Shared Unprotected Header when the JWE Shared Unprotected Header 935 value is non-empty; otherwise, it MUST be absent. This value is 936 represented as an unencoded JSON object, rather than as a string. 937 These Header Parameter values are not integrity protected. 939 iv 940 The "iv" member MUST be present and contain the value 941 BASE64URL(JWE Initialization Vector) when the JWE Initialization 942 Vector value is non-empty; otherwise, it MUST be absent. 944 aad 945 The "aad" member MUST be present and contain the value 946 BASE64URL(JWE AAD)) when the JWE AAD value is non-empty; 947 otherwise, it MUST be absent. A JWE AAD value can be included to 948 supply a base64url encoded value to be integrity protected but not 949 encrypted. 951 ciphertext 952 The "ciphertext" member MUST be present and contain the value 953 BASE64URL(JWE Ciphertext). 955 tag 956 The "tag" member MUST be present and contain the value 957 BASE64URL(JWE Authentication Tag) when the JWE Authentication Tag 958 value is non-empty; otherwise, it MUST be absent. 960 recipients 961 The "recipients" member value MUST be an array of JSON objects. 962 Each object contains information specific to a single recipient. 963 This member MUST be present, even if the array elements contain 964 only the empty JSON object "{}" (which can happen when all Header 965 Parameter values are shared between all recipients and when no 966 encrypted key is used, such as when doing Direct Encryption). 968 The following members are defined for use in the JSON objects that 969 are elements of the "recipients" array: 971 header 972 The "header" member MUST be present and contain the value JWE Per- 973 Recipient Unprotected Header when the JWE Per-Recipient 974 Unprotected Header value is non-empty; otherwise, it MUST be 975 absent. This value is represented as an unencoded JSON object, 976 rather than as a string. These Header Parameter values are not 977 integrity protected. 979 encrypted_key 980 The "encrypted_key" member MUST be present and contain the value 981 BASE64URL(JWE Encrypted Key) when the JWE Encrypted Key value is 982 non-empty; otherwise, it MUST be absent. 984 At least one of the "header", "protected", and "unprotected" members 985 MUST be present so that "alg" and "enc" Header Parameter values are 986 conveyed for each recipient computation. 988 Additional members can be present in both the JSON objects defined 989 above; if not understood by implementations encountering them, they 990 MUST be ignored. 992 Some Header Parameters, including the "alg" parameter, can be shared 993 among all recipient computations. Header Parameters in the JWE 994 Protected Header and JWE Shared Unprotected Header values are shared 995 among all recipients. 997 The Header Parameter values used when creating or validating per- 998 recipient Ciphertext and Authentication Tag values are the union of 999 the three sets of Header Parameter values that may be present: (1) 1000 the JWE Protected Header represented in the "protected" member, (2) 1001 the JWE Shared Unprotected Header represented in the "unprotected" 1002 member, and (3) the JWE Per-Recipient Unprotected Header represented 1003 in the "header" member of the recipient's array element. The union 1004 of these sets of Header Parameters comprises the JOSE Header. The 1005 Header Parameter names in the three locations MUST be disjoint. 1007 Each JWE Encrypted Key value is computed using the parameters of the 1008 corresponding JOSE Header value in the same manner as for the JWE 1009 Compact Serialization. This has the desirable property that each JWE 1010 Encrypted Key value in the "recipients" array is identical to the 1011 value that would have been computed for the same parameter in the JWE 1012 Compact Serialization. Likewise, the JWE Ciphertext and JWE 1013 Authentication Tag values match those produced for the JWE Compact 1014 Serialization, provided that the JWE Protected Header value (which 1015 represents the integrity-protected Header Parameter values) matches 1016 that used in the JWE Compact Serialization. 1018 All recipients use the same JWE Protected Header, JWE Initialization 1019 Vector, JWE Ciphertext, and JWE Authentication Tag values, when 1020 present, resulting in potentially significant space savings if the 1021 message is large. Therefore, all Header Parameters that specify the 1022 treatment of the Plaintext value MUST be the same for all recipients. 1023 This primarily means that the "enc" (encryption algorithm) Header 1024 Parameter value in the JOSE Header for each recipient and any 1025 parameters of that algorithm MUST be the same. 1027 In summary, the syntax of a JWE using the JWE JSON Serialization is 1028 as follows: 1030 {"protected":"", 1031 "unprotected":, 1032 "recipients":[ 1033 {"header":, 1034 "encrypted_key":""}, 1035 ... 1036 {"header":, 1037 "encrypted_key":""}], 1038 "aad":"", 1039 "iv":"", 1040 "ciphertext":"", 1041 "tag":"" 1042 } 1044 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1045 Serialization. 1047 8. TLS Requirements 1049 The TLS requirements for this specification are the same as those 1050 defined in Section 8 of [JWS]. 1052 9. Distinguishing between JWS and JWE Objects 1054 There are several ways of distinguishing whether an object is a JWS 1055 or JWE object. All these methods will yield the same result for all 1056 legal input values; they may yield different results for malformed 1057 inputs. 1059 o If the object is using the JWS Compact Serialization or the JWE 1060 Compact Serialization, the number of base64url encoded segments 1061 separated by period ('.') characters differs for JWSs and JWEs. 1062 JWSs have three segments separated by two period ('.') characters. 1063 JWEs have five segments separated by four period ('.') characters. 1065 o If the object is using the JWS JSON Serialization or the JWE JSON 1066 Serialization, the members used will be different. JWSs have a 1067 "signatures" member and JWEs do not. JWEs have a "recipients" 1068 member and JWSs do not. 1070 o The JOSE Header for a JWS object can be distinguished from the 1071 JOSE Header for a JWE object by examining the "alg" (algorithm) 1072 Header Parameter value. If the value represents a digital 1073 signature or MAC algorithm, or is the value "none", it is for a 1074 JWS; if it represents a Key Encryption, Key Wrapping, Direct Key 1075 Agreement, Key Agreement with Key Wrapping, or Direct Encryption 1076 algorithm, it is for a JWE. (Extracting the "alg" value to 1077 examine is straightforward when using the JWS Compact 1078 Serialization or the JWE Compact Serialization and may be more 1079 difficult when using the JWS JSON Serialization or the JWE JSON 1080 Serialization.) 1082 o The JOSE Header for a JWS object can also be distinguished from 1083 the JOSE Header for a JWE object by determining whether an "enc" 1084 (encryption algorithm) member exists. If the "enc" member exists, 1085 it is a JWE; otherwise, it is a JWS. 1087 10. IANA Considerations 1089 10.1. JSON Web Signature and Encryption Header Parameters Registration 1091 This specification registers the Header Parameter names defined in 1092 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1093 Parameters registry defined in [JWS]. 1095 10.1.1. Registry Contents 1096 o Header Parameter Name: "alg" 1097 o Header Parameter Description: Algorithm 1098 o Header Parameter Usage Location(s): JWE 1099 o Change Controller: IESG 1100 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1102 o Header Parameter Name: "enc" 1103 o Header Parameter Description: Encryption Algorithm 1104 o Header Parameter Usage Location(s): JWE 1105 o Change Controller: IESG 1106 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1108 o Header Parameter Name: "zip" 1109 o Header Parameter Description: Compression Algorithm 1110 o Header Parameter Usage Location(s): JWE 1111 o Change Controller: IESG 1112 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1114 o Header Parameter Name: "jku" 1115 o Header Parameter Description: JWK Set URL 1116 o Header Parameter Usage Location(s): JWE 1117 o Change Controller: IESG 1118 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1120 o Header Parameter Name: "jwk" 1121 o Header Parameter Description: JSON Web Key 1122 o Header Parameter Usage Location(s): JWE 1123 o Change Controller: IESG 1124 o Specification document(s): Section 4.1.5 of [[ this document ]] 1126 o Header Parameter Name: "kid" 1127 o Header Parameter Description: Key ID 1128 o Header Parameter Usage Location(s): JWE 1129 o Change Controller: IESG 1130 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1132 o Header Parameter Name: "x5u" 1133 o Header Parameter Description: X.509 URL 1134 o Header Parameter Usage Location(s): JWE 1135 o Change Controller: IESG 1136 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1138 o Header Parameter Name: "x5c" 1139 o Header Parameter Description: X.509 Certificate Chain 1140 o Header Parameter Usage Location(s): JWE 1141 o Change Controller: IESG 1142 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1144 o Header Parameter Name: "x5t" 1145 o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint 1146 o Header Parameter Usage Location(s): JWE 1147 o Change Controller: IESG 1148 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1150 o Header Parameter Name: "x5t#S256" 1151 o Header Parameter Description: X.509 Certificate SHA-256 Thumbprint 1152 o Header Parameter Usage Location(s): JWE 1153 o Change Controller: IESG 1154 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1156 o Header Parameter Name: "typ" 1157 o Header Parameter Description: Type 1158 o Header Parameter Usage Location(s): JWE 1159 o Change Controller: IESG 1160 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1162 o Header Parameter Name: "cty" 1163 o Header Parameter Description: Content Type 1164 o Header Parameter Usage Location(s): JWE 1165 o Change Controller: IESG 1166 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1168 o Header Parameter Name: "crit" 1169 o Header Parameter Description: Critical 1170 o Header Parameter Usage Location(s): JWE 1171 o Change Controller: IESG 1172 o Specification Document(s): Section 4.1.13 of [[ this document ]] 1174 11. Security Considerations 1176 All of the security issues that are pertinent to any cryptographic 1177 application must be addressed by JWS/JWE/JWK agents. Among these 1178 issues are protecting the user's asymmetric private and symmetric 1179 secret keys, preventing various attacks, and helping avoid mistakes 1180 such as inadvertently encrypting a message to the wrong recipient. 1181 The entire list of security considerations is beyond the scope of 1182 this document, but some significant considerations are listed here. 1184 All the security considerations in the JWS specification also apply 1185 to this specification. Likewise, all the security considerations in 1186 XML Encryption 1.1 [W3C.REC-xmlenc-core1-20130411] also apply, other 1187 than those that are XML specific. 1189 11.1. Using Matching Algorithm Strengths 1191 Algorithms of matching strengths should be used together whenever 1192 possible. For instance, when AES Key Wrap is used with a given key 1193 size, using the same key size is recommended when AES GCM is also 1194 used. 1196 11.2. Adaptive Chosen-Ciphertext Attacks 1198 When decrypting, particular care must be taken not to allow the JWE 1199 recipient to be used as an oracle for decrypting messages. RFC 3218 1200 [RFC3218] should be consulted for specific countermeasures to attacks 1201 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1202 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1203 formatting error that can be detected and used to recover the CEK 1204 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1205 particularly important to report all formatting errors to the CEK, 1206 Additional Authenticated Data, or ciphertext as a single error when 1207 the encrypted content is rejected. 1209 Additionally, this type of attack can be prevented by the use of "key 1210 tainting". This method restricts the use of a key to a limited set 1211 of algorithms -- usually one. This means, for instance, that if the 1212 key is marked as being for "RSA-OAEP" only, any attempt to decrypt a 1213 message using the "RSA1_5" algorithm with that key would fail 1214 immediately due to invalid use of the key. 1216 11.3. Timing Attacks 1218 To mitigate the attacks described in RFC 3218 [RFC3218], the 1219 recipient MUST NOT distinguish between format, padding, and length 1220 errors of encrypted keys. It is strongly recommended, in the event 1221 of receiving an improperly formatted key, that the receiver 1222 substitute a randomly generated CEK and proceed to the next step, to 1223 mitigate timing attacks. 1225 12. References 1227 12.1. Normative References 1229 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1230 draft-ietf-jose-json-web-algorithms (work in progress), 1231 July 2014. 1233 [JWK] Jones, M., "JSON Web Key (JWK)", 1234 draft-ietf-jose-json-web-key (work in progress), 1235 July 2014. 1237 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1238 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1239 in progress), July 2014. 1241 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1242 version 1.3", RFC 1951, May 1996. 1244 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1245 Requirement Levels", BCP 14, RFC 2119, March 1997. 1247 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1248 10646", STD 63, RFC 3629, November 2003. 1250 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1251 Housley, R., and W. Polk, "Internet X.509 Public Key 1252 Infrastructure Certificate and Certificate Revocation List 1253 (CRL) Profile", RFC 5280, May 2008. 1255 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1256 Interchange Format", RFC 7159, March 2014. 1258 [USASCII] American National Standards Institute, "Coded Character 1259 Set -- 7-bit American Standard Code for Information 1260 Interchange", ANSI X3.4, 1986. 1262 12.2. Informative References 1264 [AES] National Institute of Standards and Technology (NIST), 1265 "Advanced Encryption Standard (AES)", FIPS PUB 197, 1266 November 2001. 1268 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1269 McGrew, D., Foley, J., and K. Paterson, "Authenticated 1270 Encryption with AES-CBC and HMAC-SHA", 1271 draft-mcgrew-aead-aes-cbc-hmac-sha2-04 (work in progress), 1272 February 2014. 1274 [I-D.rescorla-jsms] 1275 Rescorla, E. and J. Hildebrand, "JavaScript Message 1276 Security Format", draft-rescorla-jsms-00 (work in 1277 progress), March 2011. 1279 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1280 Encryption", September 2010. 1282 [NIST.800-38D] 1283 National Institute of Standards and Technology (NIST), 1284 "Recommendation for Block Cipher Modes of Operation: 1286 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 1287 December 2001. 1289 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1290 Cryptographic Message Syntax", RFC 3218, January 2002. 1292 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1293 Standards (PKCS) #1: RSA Cryptography Specifications 1294 Version 2.1", RFC 3447, February 2003. 1296 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1297 Requirements for Security", BCP 106, RFC 4086, June 2005. 1299 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1300 RFC 5652, September 2009. 1302 [W3C.REC-xmlenc-core1-20130411] 1303 Eastlake, D., Reagle, J., Hirsch, F., and T. Roessler, 1304 "XML Encryption Syntax and Processing Version 1.1", World 1305 Wide Web Consortium Recommendation REC-xmlenc-core1- 1306 20130411, April 2013, 1307 . 1309 Appendix A. JWE Examples 1311 This section provides examples of JWE computations. 1313 A.1. Example JWE using RSAES OAEP and AES GCM 1315 This example encrypts the plaintext "The true sign of intelligence is 1316 not knowledge but imagination." to the recipient using RSAES OAEP for 1317 key encryption and AES GCM for content encryption. The 1318 representation of this plaintext (using JSON array notation) is: 1320 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1321 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1322 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1323 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1324 110, 97, 116, 105, 111, 110, 46] 1326 A.1.1. JOSE Header 1328 The following example JWE Protected Header declares that: 1330 o the Content Encryption Key is encrypted to the recipient using the 1331 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1333 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1334 bit key to produce the Ciphertext. 1336 {"alg":"RSA-OAEP","enc":"A256GCM"} 1338 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1339 Header)) gives this value: 1341 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1343 A.1.2. Content Encryption Key (CEK) 1345 Generate a 256 bit random Content Encryption Key (CEK). In this 1346 example, the value (using JSON array notation) is: 1348 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1349 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1350 234, 64, 252] 1352 A.1.3. Key Encryption 1354 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1355 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1356 key represented in JSON Web Key [JWK] format below (with line breaks 1357 within values for display purposes only): 1359 {"kty":"RSA", 1360 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1361 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1362 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1363 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1364 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1365 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1366 "e":"AQAB", 1367 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1368 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1369 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1370 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1371 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1372 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ" 1373 } 1375 The resulting JWE Encrypted Key value is: 1377 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1378 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1379 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1380 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1381 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1382 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1383 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1384 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1385 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1386 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1387 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1388 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1389 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1390 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1391 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1392 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1393 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1394 117, 114, 135, 206] 1396 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1397 this value (with line breaks for display purposes only): 1399 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1400 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1401 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1402 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1403 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1404 6UklfCpIMfIjf7iGdXKHzg 1406 A.1.4. Initialization Vector 1408 Generate a random 96 bit JWE Initialization Vector. In this example, 1409 the value is: 1411 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1413 Encoding this JWE Initialization Vector as BASE64URL(JWE 1414 Initialization Vector) gives this value: 1416 48V1_ALb6US04U3b 1418 A.1.5. Additional Authenticated Data 1420 Let the Additional Authenticated Data encryption parameter be 1421 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1423 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1424 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1425 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1427 A.1.6. Content Encryption 1429 Encrypt the Plaintext with AES GCM using the CEK as the encryption 1430 key, the JWE Initialization Vector, and the Additional Authenticated 1431 Data value above, requesting a 128 bit Authentication Tag output. 1432 The resulting Ciphertext is: 1434 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1435 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1436 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1437 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1438 160, 109, 64, 63, 192] 1440 The resulting Authentication Tag value is: 1442 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1443 210, 145] 1445 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1446 value (with line breaks for display purposes only): 1448 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1449 SdiwkIr3ajwQzaBtQD_A 1451 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1452 Tag) gives this value: 1454 XFBoMYUZodetZdvTiFvSkQ 1456 A.1.7. Complete Representation 1458 Assemble the final representation: The Compact Serialization of this 1459 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1460 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1461 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1462 Authentication Tag). 1464 The final result in this example (with line breaks for display 1465 purposes only) is: 1467 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1468 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1469 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1470 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1471 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1472 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1473 6UklfCpIMfIjf7iGdXKHzg. 1474 48V1_ALb6US04U3b. 1475 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1476 SdiwkIr3ajwQzaBtQD_A. 1477 XFBoMYUZodetZdvTiFvSkQ 1479 A.1.8. Validation 1481 This example illustrates the process of creating a JWE with RSAES 1482 OAEP for key encryption and AES GCM for content encryption. These 1483 results can be used to validate JWE decryption implementations for 1484 these algorithms. Note that since the RSAES OAEP computation 1485 includes random values, the encryption results above will not be 1486 completely reproducible. However, since the AES GCM computation is 1487 deterministic, the JWE Encrypted Ciphertext values will be the same 1488 for all encryptions performed using these inputs. 1490 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1492 This example encrypts the plaintext "Live long and prosper." to the 1493 recipient using RSAES-PKCS1-V1_5 for key encryption and 1494 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1495 of this plaintext (using JSON array notation) is: 1497 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1498 112, 114, 111, 115, 112, 101, 114, 46] 1500 A.2.1. JOSE Header 1502 The following example JWE Protected Header declares that: 1504 o the Content Encryption Key is encrypted to the recipient using the 1505 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1507 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1508 algorithm to produce the Ciphertext. 1510 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1512 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1513 Header)) gives this value: 1515 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1517 A.2.2. Content Encryption Key (CEK) 1519 Generate a 256 bit random Content Encryption Key (CEK). In this 1520 example, the key value is: 1522 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1523 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1524 44, 207] 1526 A.2.3. Key Encryption 1528 Encrypt the CEK with the recipient's public key using the RSAES- 1529 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1530 uses the RSA key represented in JSON Web Key [JWK] format below (with 1531 line breaks within values for display purposes only): 1533 {"kty":"RSA", 1534 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1535 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1536 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1537 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1538 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1539 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1540 "e":"AQAB", 1541 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1542 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1543 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1544 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1545 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1546 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1547 } 1549 The resulting JWE Encrypted Key value is: 1551 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1552 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1553 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1554 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1555 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1556 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1557 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1558 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1559 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1560 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1561 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1562 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1563 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1564 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1565 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1566 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1567 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1568 146, 114, 165, 204, 71, 136, 41, 252] 1570 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1571 this value (with line breaks for display purposes only): 1573 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1574 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1575 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1576 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1577 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1578 -B3oWh2TbqmScqXMR4gp_A 1580 A.2.4. Initialization Vector 1582 Generate a random 128 bit JWE Initialization Vector. In this 1583 example, the value is: 1585 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1586 101] 1588 Encoding this JWE Initialization Vector as BASE64URL(JWE 1589 Initialization Vector) gives this value: 1591 AxY8DCtDaGlsbGljb3RoZQ 1593 A.2.5. Additional Authenticated Data 1595 Let the Additional Authenticated Data encryption parameter be 1596 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1598 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1599 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1600 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1601 50, 73, 110, 48] 1603 A.2.6. Content Encryption 1605 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1606 the encryption key, the JWE Initialization Vector, and the Additional 1607 Authenticated Data value above. The steps for doing this using the 1608 values from Appendix A.3 are detailed in Appendix B. The resulting 1609 Ciphertext is: 1611 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1612 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1613 112, 56, 102] 1615 The resulting Authentication Tag value is: 1617 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1618 191] 1620 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1621 value: 1623 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1625 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1626 Tag) gives this value: 1628 9hH0vgRfYgPnAHOd8stkvw 1630 A.2.7. Complete Representation 1632 Assemble the final representation: The Compact Serialization of this 1633 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1634 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1635 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1636 Authentication Tag). 1638 The final result in this example (with line breaks for display 1639 purposes only) is: 1641 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1642 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1643 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1644 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1645 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1646 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1647 -B3oWh2TbqmScqXMR4gp_A. 1648 AxY8DCtDaGlsbGljb3RoZQ. 1649 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1650 9hH0vgRfYgPnAHOd8stkvw 1652 A.2.8. Validation 1654 This example illustrates the process of creating a JWE with RSAES- 1655 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1656 encryption. These results can be used to validate JWE decryption 1657 implementations for these algorithms. Note that since the RSAES- 1658 PKCS1-V1_5 computation includes random values, the encryption results 1659 above will not be completely reproducible. However, since the AES 1660 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1661 will be the same for all encryptions performed using these inputs. 1663 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1665 This example encrypts the plaintext "Live long and prosper." to the 1666 recipient using AES Key Wrap for key encryption and 1667 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1668 of this plaintext (using JSON array notation) is: 1670 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1671 112, 114, 111, 115, 112, 101, 114, 46] 1673 A.3.1. JOSE Header 1675 The following example JWE Protected Header declares that: 1677 o the Content Encryption Key is encrypted to the recipient using the 1678 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1679 Encrypted Key and 1681 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1682 algorithm to produce the Ciphertext. 1684 {"alg":"A128KW","enc":"A128CBC-HS256"} 1686 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1687 Header)) gives this value: 1689 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1691 A.3.2. Content Encryption Key (CEK) 1693 Generate a 256 bit random Content Encryption Key (CEK). In this 1694 example, the value is: 1696 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1697 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1698 44, 207] 1700 A.3.3. Key Encryption 1702 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1703 algorithm to produce the JWE Encrypted Key. This example uses the 1704 symmetric key represented in JSON Web Key [JWK] format below: 1706 {"kty":"oct", 1707 "k":"GawgguFyGrWKav7AX4VKUg" 1708 } 1710 The resulting JWE Encrypted Key value is: 1712 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1713 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1714 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1716 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1717 this value: 1719 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1721 A.3.4. Initialization Vector 1723 Generate a random 128 bit JWE Initialization Vector. In this 1724 example, the value is: 1726 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1727 101] 1729 Encoding this JWE Initialization Vector as BASE64URL(JWE 1730 Initialization Vector) gives this value: 1732 AxY8DCtDaGlsbGljb3RoZQ 1734 A.3.5. Additional Authenticated Data 1736 Let the Additional Authenticated Data encryption parameter be 1737 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1739 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1740 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1741 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1742 110, 48] 1744 A.3.6. Content Encryption 1746 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1747 the encryption key, the JWE Initialization Vector, and the Additional 1748 Authenticated Data value above. The steps for doing this using the 1749 values from this example are detailed in Appendix B. The resulting 1750 Ciphertext is: 1752 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1753 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1754 112, 56, 102] 1756 The resulting Authentication Tag value is: 1758 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1759 194, 85] 1761 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1762 value: 1764 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1766 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1767 Tag) gives this value: 1769 U0m_YmjN04DJvceFICbCVQ 1771 A.3.7. Complete Representation 1773 Assemble the final representation: The Compact Serialization of this 1774 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1775 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1776 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1777 Authentication Tag). 1779 The final result in this example (with line breaks for display 1780 purposes only) is: 1782 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1783 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1784 AxY8DCtDaGlsbGljb3RoZQ. 1785 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1786 U0m_YmjN04DJvceFICbCVQ 1788 A.3.8. Validation 1790 This example illustrates the process of creating a JWE with AES Key 1791 Wrap for key encryption and AES GCM for content encryption. These 1792 results can be used to validate JWE decryption implementations for 1793 these algorithms. Also, since both the AES Key Wrap and AES GCM 1794 computations are deterministic, the resulting JWE value will be the 1795 same for all encryptions performed using these inputs. Since the 1796 computation is reproducible, these results can also be used to 1797 validate JWE encryption implementations for these algorithms. 1799 A.4. Example JWE using JWE JSON Serialization 1801 This section contains an example using the JWE JSON Serialization. 1802 This example demonstrates the capability for encrypting the same 1803 plaintext to multiple recipients. 1805 Two recipients are present in this example. The algorithm and key 1806 used for the first recipient are the same as that used in 1807 Appendix A.2. The algorithm and key used for the second recipient 1808 are the same as that used in Appendix A.3. The resulting JWE 1809 Encrypted Key values are therefore the same; those computations are 1810 not repeated here. 1812 The Plaintext, the Content Encryption Key (CEK), JWE Initialization 1813 Vector, and JWE Protected Header are shared by all recipients (which 1814 must be the case, since the Ciphertext and Authentication Tag are 1815 also shared). 1817 A.4.1. JWE Per-Recipient Unprotected Headers 1819 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1820 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1821 encrypt the CEK. Key ID values are supplied for both keys. The two 1822 per-recipient header values used to represent these algorithms and 1823 Key IDs are: 1825 {"alg":"RSA1_5","kid":"2011-04-29"} 1827 and 1829 {"alg":"A128KW","kid":"7"} 1831 A.4.2. JWE Protected Header 1833 The Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1834 algorithm to produce the common JWE Ciphertext and JWE Authentication 1835 Tag values. The JWE Protected Header value representing this is: 1837 {"enc":"A128CBC-HS256"} 1839 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1840 Header)) gives this value: 1842 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1844 A.4.3. JWE Unprotected Header 1846 This JWE uses the "jku" Header Parameter to reference a JWK Set. This 1847 is represented in the following JWE Unprotected Header value as: 1849 {"jku":"https://server.example.com/keys.jwks"} 1851 A.4.4. Complete JOSE Header Values 1853 Combining the per-recipient, protected, and unprotected header values 1854 supplied, the JOSE Header values used for the first and second 1855 recipient respectively are: 1857 {"alg":"RSA1_5", 1858 "kid":"2011-04-29", 1859 "enc":"A128CBC-HS256", 1860 "jku":"https://server.example.com/keys.jwks"} 1862 and 1864 {"alg":"A128KW", 1865 "kid":"7", 1866 "enc":"A128CBC-HS256", 1867 "jku":"https://server.example.com/keys.jwks"} 1869 A.4.5. Additional Authenticated Data 1871 Let the Additional Authenticated Data encryption parameter be 1872 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1874 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1875 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1877 A.4.6. Content Encryption 1879 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1880 the encryption key, the JWE Initialization Vector, and the Additional 1881 Authenticated Data value above. The steps for doing this using the 1882 values from Appendix A.3 are detailed in Appendix B. The resulting 1883 Ciphertext is: 1885 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1886 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1887 112, 56, 102] 1889 The resulting Authentication Tag value is: 1891 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1892 207] 1894 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1895 value: 1897 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1899 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1900 Tag) gives this value: 1902 Mz-VPPyU4RlcuYv1IwIvzw 1904 A.4.7. Complete JWE JSON Serialization Representation 1906 The complete JSON Web Encryption JSON Serialization for these values 1907 is as follows (with line breaks within values for display purposes 1908 only): 1910 {"protected": 1911 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1912 "unprotected": 1913 {"jku":"https://server.example.com/keys.jwks"}, 1914 "recipients":[ 1915 {"header": 1916 {"alg":"RSA1_5","kid":"2011-04-29"}, 1917 "encrypted_key": 1918 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1919 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1920 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 1921 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 1922 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 1923 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 1924 {"header": 1925 {"alg":"A128KW","kid":"7"}, 1926 "encrypted_key": 1927 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1928 "iv": 1929 "AxY8DCtDaGlsbGljb3RoZQ", 1930 "ciphertext": 1931 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1932 "tag": 1933 "Mz-VPPyU4RlcuYv1IwIvzw" 1934 } 1936 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 1938 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 1939 authenticated encryption computation using the values from the 1940 example in Appendix A.3. As described where this algorithm is 1941 defined in Sections 5.2 and 5.2.3 of JWA, the AES_CBC_HMAC_SHA2 1942 family of algorithms are implemented using Advanced Encryption 1943 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #7 1944 padding to perform the encryption and an HMAC SHA-2 function to 1945 perform the integrity calculation - in this case, HMAC SHA-256. 1947 B.1. Extract MAC_KEY and ENC_KEY from Key 1949 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example 1950 (using JSON array notation) is: 1952 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1953 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1954 44, 207] 1956 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 1957 which is: 1959 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1960 206] 1962 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 1963 is: 1965 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 1966 207] 1968 Note that the MAC key comes before the encryption key in the input 1969 key K; this is in the opposite order of the algorithm names in the 1970 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 1972 B.2. Encrypt Plaintext to Create Ciphertext 1974 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 1975 using PKCS #7 padding using the ENC_KEY above. The Plaintext in this 1976 example is: 1978 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1979 112, 114, 111, 115, 112, 101, 114, 46] 1981 The encryption result is as follows, which is the Ciphertext output: 1983 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1984 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1985 112, 56, 102] 1987 B.3. 64 Bit Big Endian Representation of AAD Length 1989 The Additional Authenticated Data (AAD) in this example is: 1991 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1992 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1993 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1994 110, 48] 1996 This AAD is 51 bytes long, which is 408 bits long. The octet string 1997 AL, which is the number of bits in AAD expressed as a big endian 64 1998 bit unsigned integer is: 2000 [0, 0, 0, 0, 0, 0, 1, 152] 2002 B.4. Initialization Vector Value 2004 The Initialization Vector value used in this example is: 2006 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 2007 101] 2009 B.5. Create Input to HMAC Computation 2011 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 2012 the AL value. The result of this concatenation is: 2014 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2015 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2016 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2017 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 2018 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 2019 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 2020 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 2022 B.6. Compute HMAC Value 2024 Compute the HMAC SHA-256 of the concatenated value above. This 2025 result M is: 2027 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2028 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 2029 86, 229, 116] 2031 B.7. Truncate HMAC Value to Create Authentication Tag 2033 Use the first half (128 bits) of the HMAC output M as the 2034 Authentication Tag output T. This truncated value is: 2036 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2037 194, 85] 2039 Appendix C. Acknowledgements 2041 Solutions for encrypting JSON content were also explored by JSON 2042 Simple Encryption [JSE] and JavaScript Message Security Format 2043 [I-D.rescorla-jsms], both of which significantly influenced this 2044 draft. This draft attempts to explicitly reuse as many of the 2045 relevant concepts from XML Encryption 1.1 2046 [W3C.REC-xmlenc-core1-20130411] and RFC 5652 [RFC5652] as possible, 2047 while utilizing simple, compact JSON-based data structures. 2049 Special thanks are due to John Bradley, Eric Rescorla, and Nat 2050 Sakimura for the discussions that helped inform the content of this 2051 specification, to Eric Rescorla and Joe Hildebrand for allowing the 2052 reuse of text from [I-D.rescorla-jsms] in this document, and to Eric 2053 Rescorla for co-authoring many drafts of this specification. 2055 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2056 Jay for validating the examples in this specification. 2058 This specification is the work of the JOSE Working Group, which 2059 includes dozens of active and dedicated participants. In particular, 2060 the following individuals contributed ideas, feedback, and wording 2061 that influenced this specification: 2063 Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick 2064 Hardt, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Kathleen 2065 Moriarty, Tony Nadalin, Hideki Nara, Axel Nennker, Emmanuel Raviart, 2066 Eric Rescorla, Nat Sakimura, Jim Schaad, Hannes Tschofenig, and Sean 2067 Turner. 2069 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2070 Sean Turner, Stephen Farrell, and Kathleen Moriarty served as 2071 Security area directors during the creation of this specification. 2073 Appendix D. Document History 2075 [[ to be removed by the RFC Editor before publication as an RFC ]] 2076 -30 2078 o Added subsection headings within the Overview section for the two 2079 serializations. 2081 o Added references and cleaned up the reference syntax in a few 2082 places. 2084 o Applied minor wording changes to the Security Considerations 2085 section and made other local editorial improvements. 2087 -29 2089 o Replaced the terms JWS Header, JWE Header, and JWT Header with a 2090 single JOSE Header term defined in the JWS specification. This 2091 also enabled a single Header Parameter definition to be used and 2092 reduced other areas of duplication between specifications. 2094 -28 2096 o Specified the use of PKCS #7 padding with AES CBC, rather than 2097 PKCS #5. (PKCS #7 is a superset of PKCS #5, and is appropriate 2098 for the 16 octet blocks used by AES CBC.) 2100 o Revised the introduction to the Security Considerations section. 2101 Also moved a security consideration item here from the JWA draft. 2103 -27 2105 o Described additional security considerations. 2107 o Added the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) header 2108 parameter. 2110 -26 2112 o Noted that octet sequences are depicted using JSON array notation. 2114 o Updated references, including to W3C specifications. 2116 -25 2118 o Corrected two external section number references that had changed. 2120 o Corrected a typo in an algorithm name in the prose of an example. 2122 -24 2123 o Corrected complete JSON Serialization example. 2125 o Replaced uses of the term "associated data" wherever it was used 2126 to refer to a data value with "additional authenticated data", 2127 since both terms were being used as synonyms, causing confusion. 2129 o Updated the JSON reference to RFC 7159. 2131 o Thanked Eric Rescorla for helping to author of most of the drafts 2132 of this specification and removed him from the current author 2133 list. 2135 -23 2137 o Corrected a use of the word "payload" to "plaintext". 2139 -22 2141 o Corrected RFC 2119 terminology usage. 2143 o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. 2145 -21 2147 o Changed some references from being normative to informative, 2148 addressing issue #90. 2150 o Applied review comments to the JSON Serialization section, 2151 addressing issue #178. 2153 -20 2155 o Made terminology definitions more consistent, addressing issue 2156 #165. 2158 o Restructured the JSON Serialization section to call out the 2159 parameters used in hanging lists, addressing issue #178. 2161 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 2162 addressing issue #90. 2164 -19 2166 o Reordered the key selection parameters. 2168 -18 2169 o Updated the mandatory-to-implement (MTI) language to say that 2170 applications using this specification need to specify what 2171 serialization and serialization features are used for that 2172 application, addressing issue #176. 2174 o Changes to address editorial and minor issues #89, #135, #165, 2175 #174, #175, #177, #179, and #180. 2177 o Used Header Parameter Description registry field. 2179 -17 2181 o Refined the "typ" and "cty" definitions to always be MIME Media 2182 Types, with the omission of "application/" prefixes recommended 2183 for brevity, addressing issue #50. 2185 o Updated the mandatory-to-implement (MTI) language to say that 2186 general-purpose implementations must implement the single 2187 recipient case for both serializations whereas special-purpose 2188 implementations can implement just one serialization if that meets 2189 the needs of the use cases the implementation is designed for, 2190 addressing issue #176. 2192 o Explicitly named all the logical components of a JWE and defined 2193 the processing rules and serializations in terms of those 2194 components, addressing issues #60, #61, and #62. 2196 o Replaced verbose repetitive phases such as "base64url encode the 2197 octets of the UTF-8 representation of X" with mathematical 2198 notation such as "BASE64URL(UTF8(X))". 2200 o Header Parameters and processing rules occurring in both JWS and 2201 JWE are now referenced in JWS by JWE, rather than duplicated, 2202 addressing issue #57. 2204 o Terms used in multiple documents are now defined in one place and 2205 incorporated by reference. Some lightly used or obvious terms 2206 were also removed. This addresses issue #58. 2208 -16 2210 o Changes to address editorial and minor issues #163, #168, #169, 2211 #170, #172, and #173. 2213 -15 2215 o Clarified that it is an application decision which recipients' 2216 encrypted content must successfully validate for the JWE to be 2217 accepted, addressing issue #35. 2219 o Changes to address editorial issues #34, #164, and #169. 2221 -14 2223 o Clarified that the "protected", "unprotected", "header", "iv", 2224 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2225 JSON Serialization when their values would be empty. Stated that 2226 the "recipients" array must always be present. 2228 -13 2230 o Added an "aad" (Additional Authenticated Data) member for the JWE 2231 JSON Serialization, enabling Additional Authenticated Data to be 2232 supplied that is not double base64url encoded, addressing issue 2233 #29. 2235 -12 2237 o Clarified that the "typ" and "cty" header parameters are used in 2238 an application-specific manner and have no effect upon the JWE 2239 processing. 2241 o Replaced the MIME types "application/jwe+json" and 2242 "application/jwe" with "application/jose+json" and 2243 "application/jose". 2245 o Stated that recipients MUST either reject JWEs with duplicate 2246 Header Parameter Names or use a JSON parser that returns only the 2247 lexically last duplicate member name. 2249 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2250 be with the algorithm descriptions that use them. 2252 o Added a Serializations section with parallel treatment of the JWE 2253 Compact Serialization and the JWE JSON Serialization and also 2254 moved the former Implementation Considerations content there. 2256 o Restored use of the term "AEAD". 2258 o Changed terminology from "block encryption" to "content 2259 encryption". 2261 -11 2263 o Added Key Identification section. 2265 o Removed the Encrypted Key value from the AAD computation since it 2266 is already effectively integrity protected by the encryption 2267 process. The AAD value now only contains the representation of 2268 the JWE Encrypted Header. 2270 o For the JWE JSON Serialization, enable Header Parameter values to 2271 be specified in any of three parameters: the "protected" member 2272 that is integrity protected and shared among all recipients, the 2273 "unprotected" member that is not integrity protected and shared 2274 among all recipients, and the "header" member that is not 2275 integrity protected and specific to a particular recipient. (This 2276 does not affect the JWE Compact Serialization, in which all Header 2277 Parameter values are in a single integrity protected JWE Header 2278 value.) 2280 o Shortened the names "authentication_tag" to "tag" and 2281 "initialization_vector" to "iv" in the JWE JSON Serialization, 2282 addressing issue #20. 2284 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2286 o Removed suggested compact serialization for multiple recipients. 2288 o Changed the MIME type name "application/jwe-js" to 2289 "application/jwe+json", addressing issue #22. 2291 o Tightened the description of the "crit" (critical) header 2292 parameter. 2294 -10 2296 o Changed the JWE processing rules for multiple recipients so that a 2297 single AAD value contains the header parameters and encrypted key 2298 values for all the recipients, enabling AES GCM to be safely used 2299 for multiple recipients. 2301 o Added an appendix suggesting a possible compact serialization for 2302 JWEs with multiple recipients. 2304 -09 2306 o Added JWE JSON Serialization, as specified by 2307 draft-jones-jose-jwe-json-serialization-04. 2309 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2310 parameter value. 2312 o Defined that the default action for header parameters that are not 2313 understood is to ignore them unless specifically designated as 2314 "MUST be understood" or included in the new "crit" (critical) 2315 header parameter list. This addressed issue #6. 2317 o Corrected "x5c" description. This addressed issue #12. 2319 o Changed from using the term "byte" to "octet" when referring to 8 2320 bit values. 2322 o Added Key Management Mode definitions to terminology section and 2323 used the defined terms to provide clearer key management 2324 instructions. This addressed issue #5. 2326 o Added text about preventing the recipient from behaving as an 2327 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2329 o Changed from using the term "Integrity Value" to "Authentication 2330 Tag". 2332 o Changed member name from "integrity_value" to "authentication_tag" 2333 in the JWE JSON Serialization. 2335 o Removed Initialization Vector from the AAD value since it is 2336 already integrity protected by all of the authenticated encryption 2337 algorithms specified in the JWA specification. 2339 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2340 and "A256CBC-HS512". The new algorithms perform the same 2341 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2342 but with the Initialization Vector and Authentication Tag values 2343 remaining separate from the Ciphertext value in the output 2344 representation. Also deleted the header parameters "epu" 2345 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2346 they are no longer used. 2348 -08 2350 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2351 since the term AEAD in the RFC 5116 sense implied the use of a 2352 particular data representation, rather than just referring to the 2353 class of algorithms that perform authenticated encryption with 2354 associated data. 2356 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2357 Tschofenig. Many of these simplified the terminology used. 2359 o Clarified statements of the form "This header parameter is 2360 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2362 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2363 Web Signature and Encryption Header Parameters registry. 2365 o Added seriesInfo information to Internet Draft references. 2367 -07 2369 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2371 o Updated values for example AES CBC calculations. 2373 o Made several local editorial changes to clean up loose ends left 2374 over from to the decision to only support block encryption methods 2375 providing integrity. One of these changes was to explicitly state 2376 that the "enc" (encryption method) algorithm must be an 2377 Authenticated Encryption algorithm with a specified key length. 2379 -06 2381 o Removed the "int" and "kdf" parameters and defined the new 2382 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2383 "A256CBC+HS512" to replace the former uses of AES CBC, which 2384 required the use of separate integrity and key derivation 2385 functions. 2387 o Included additional values in the Concat KDF calculation -- the 2388 desired output size and the algorithm value, and optionally 2389 PartyUInfo and PartyVInfo values. Added the optional header 2390 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2391 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2392 PartyVInfo). Updated the KDF examples accordingly. 2394 o Promoted Initialization Vector from being a header parameter to 2395 being a top-level JWE element. This saves approximately 16 bytes 2396 in the compact serialization, which is a significant savings for 2397 some use cases. Promoting the Initialization Vector out of the 2398 header also avoids repeating this shared value in the JSON 2399 serialization. 2401 o Changed "x5c" (X.509 Certificate Chain) representation from being 2402 a single string to being an array of strings, each containing a 2403 single base64 encoded DER certificate value, representing elements 2404 of the certificate chain. 2406 o Added an AES Key Wrap example. 2408 o Reordered the encryption steps so CMK creation is first, when 2409 required. 2411 o Correct statements in examples about which algorithms produce 2412 reproducible results. 2414 -05 2416 o Support both direct encryption using a shared or agreed upon 2417 symmetric key, and the use of a shared or agreed upon symmetric 2418 key to key wrap the CMK. 2420 o Added statement that "StringOrURI values are compared as case- 2421 sensitive strings with no transformations or canonicalizations 2422 applied". 2424 o Updated open issues. 2426 o Indented artwork elements to better distinguish them from the body 2427 text. 2429 -04 2431 o Refer to the registries as the primary sources of defined values 2432 and then secondarily reference the sections defining the initial 2433 contents of the registries. 2435 o Normatively reference XML Encryption 1.1 for its security 2436 considerations. 2438 o Reference draft-jones-jose-jwe-json-serialization instead of 2439 draft-jones-json-web-encryption-json-serialization. 2441 o Described additional open issues. 2443 o Applied editorial suggestions. 2445 -03 2447 o Added the "kdf" (key derivation function) header parameter to 2448 provide crypto agility for key derivation. The default KDF 2449 remains the Concat KDF with the SHA-256 digest function. 2451 o Reordered encryption steps so that the Encoded JWE Header is 2452 always created before it is needed as an input to the 2453 Authenticated Encryption "additional authenticated data" 2454 parameter. 2456 o Added the "cty" (content type) header parameter for declaring type 2457 information about the secured content, as opposed to the "typ" 2458 (type) header parameter, which declares type information about 2459 this object. 2461 o Moved description of how to determine whether a header is for a 2462 JWS or a JWE from the JWT spec to the JWE spec. 2464 o Added complete encryption examples for both Authenticated 2465 Encryption and non-Authenticated Encryption algorithms. 2467 o Added complete key derivation examples. 2469 o Added "Collision Resistant Namespace" to the terminology section. 2471 o Reference ITU.X690.1994 for DER encoding. 2473 o Added Registry Contents sections to populate registry values. 2475 o Numerous editorial improvements. 2477 -02 2479 o When using Authenticated Encryption algorithms (such as AES GCM), 2480 use the "additional authenticated data" parameter to provide 2481 integrity for the header, encrypted key, and ciphertext and use 2482 the resulting "authentication tag" value as the JWE Authentication 2483 Tag. 2485 o Defined KDF output key sizes. 2487 o Generalized text to allow key agreement to be employed as an 2488 alternative to key wrapping or key encryption. 2490 o Changed compression algorithm from gzip to DEFLATE. 2492 o Clarified that it is an error when a "kid" value is included and 2493 no matching key is found. 2495 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2496 rejected. 2498 o Clarified the relationship between "typ" header parameter values 2499 and MIME types. 2501 o Registered application/jwe MIME type and "JWE" typ header 2502 parameter value. 2504 o Simplified JWK terminology to get replace the "JWK Key Object" and 2505 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2506 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2507 between single keys and sets of keys. As part of this change, the 2508 Header Parameter Name for a public key value was changed from 2509 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2511 o Added suggestion on defining additional header parameters such as 2512 "x5t#S256" in the future for certificate thumbprints using hash 2513 algorithms other than SHA-1. 2515 o Specify RFC 2818 server identity validation, rather than RFC 6125 2516 (paralleling the same decision in the OAuth specs). 2518 o Generalized language to refer to Message Authentication Codes 2519 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2520 unless in a context specific to HMAC algorithms. 2522 o Reformatted to give each header parameter its own section heading. 2524 -01 2526 o Added an integrity check for non-Authenticated Encryption 2527 algorithms. 2529 o Added "jpk" and "x5c" header parameters for including JWK public 2530 keys and X.509 certificate chains directly in the header. 2532 o Clarified that this specification is defining the JWE Compact 2533 Serialization. Referenced the new JWE-JS spec, which defines the 2534 JWE JSON Serialization. 2536 o Added text "New header parameters should be introduced sparingly 2537 since an implementation that does not understand a parameter MUST 2538 reject the JWE". 2540 o Clarified that the order of the encryption and decryption steps is 2541 not significant in cases where there are no dependencies between 2542 the inputs and outputs of the steps. 2544 o Made other editorial improvements suggested by JOSE working group 2545 participants. 2547 -00 2548 o Created the initial IETF draft based upon 2549 draft-jones-json-web-encryption-02 with no normative changes. 2551 o Changed terminology to no longer call both digital signatures and 2552 HMACs "signatures". 2554 Authors' Addresses 2556 Michael B. Jones 2557 Microsoft 2559 Email: mbj@microsoft.com 2560 URI: http://self-issued.info/ 2562 Joe Hildebrand 2563 Cisco Systems, Inc. 2565 Email: jhildebr@cisco.com