idnits 2.17.1 draft-ietf-jose-json-web-encryption-32.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 (September 23, 2014) is 3503 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 1425 -- Looks like a reference, but probably isn't: '197' on line 1425 -- Looks like a reference, but probably isn't: '117' on line 1425 -- Looks like a reference, but probably isn't: '252' on line 1425 -- Looks like a reference, but probably isn't: '2' on line 1425 -- Looks like a reference, but probably isn't: '219' on line 1425 -- Looks like a reference, but probably isn't: '233' on line 1425 -- Looks like a reference, but probably isn't: '68' on line 1425 -- Looks like a reference, but probably isn't: '180' on line 1425 -- Looks like a reference, but probably isn't: '225' on line 1425 -- Looks like a reference, but probably isn't: '77' on line 1425 -- Looks like a reference, but probably isn't: '0' on line 2015 -- Looks like a reference, but probably isn't: '1' on line 2015 -- Looks like a reference, but probably isn't: '152' on line 2015 == Unused Reference: 'AES' is defined on line 1275, 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' -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 18 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track J. Hildebrand 5 Expires: March 27, 2015 Cisco 6 September 23, 2014 8 JSON Web Encryption (JWE) 9 draft-ietf-jose-json-web-encryption-32 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 March 27, 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 . . . . . . . . . . . . 9 60 3.2. JWE JSON Serialization Overview . . . . . . . . . . . . . 9 61 3.3. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 10 62 4. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 11 63 4.1. Registered Header Parameter Names . . . . . . . . . . . . 11 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 . . . . 12 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 . . . . . . . . . . 13 71 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 13 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 . . . . . . . . 14 78 4.1.13. "crit" (Critical) Header Parameter . . . . . . . . . . 14 79 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 14 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 . . . . . . . . . . . . . . . . . . 20 89 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 23 90 9. Distinguishing between JWS and JWE Objects . . . . . . . . . . 23 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. Key Entropy and Random Values . . . . . . . . . . . . . . 26 97 11.2. Key Protection . . . . . . . . . . . . . . . . . . . . . . 26 98 11.3. Using Matching Algorithm Strengths . . . . . . . . . . . . 27 99 11.4. Adaptive Chosen-Ciphertext Attacks . . . . . . . . . . . . 27 100 11.5. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 27 101 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 102 12.1. Normative References . . . . . . . . . . . . . . . . . . . 28 103 12.2. Informative References . . . . . . . . . . . . . . . . . . 28 104 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 29 105 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 29 106 A.1.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 30 107 A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 30 108 A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 30 109 A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 32 110 A.1.5. Additional Authenticated Data . . . . . . . . . . . . 32 111 A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 32 112 A.1.7. Complete Representation . . . . . . . . . . . . . . . 33 113 A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 33 114 A.2. Example JWE using RSAES-PKCS1-V1_5 and 115 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 33 116 A.2.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 34 117 A.2.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 34 118 A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 34 119 A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 35 120 A.2.5. Additional Authenticated Data . . . . . . . . . . . . 36 121 A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 36 122 A.2.7. Complete Representation . . . . . . . . . . . . . . . 36 123 A.2.8. Validation . . . . . . . . . . . . . . . . . . . . . . 37 124 A.3. Example JWE using AES Key Wrap and 125 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 37 126 A.3.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 37 127 A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 38 128 A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 38 129 A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 38 130 A.3.5. Additional Authenticated Data . . . . . . . . . . . . 39 131 A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 39 132 A.3.7. Complete Representation . . . . . . . . . . . . . . . 39 133 A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 40 134 A.4. Example JWE using JWE JSON Serialization . . . . . . . . . 40 135 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 40 136 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 41 137 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 41 138 A.4.4. Complete JOSE Header Values . . . . . . . . . . . . . 41 139 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 41 140 A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 42 141 A.4.7. Complete JWE JSON Serialization Representation . . . . 42 142 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 43 143 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 43 144 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 44 145 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 44 146 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 45 147 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 45 148 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 45 149 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 45 150 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 45 151 Appendix D. Document History . . . . . . . . . . . . . . . . . . 46 152 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 56 154 1. Introduction 156 JSON Web Encryption (JWE) represents encrypted content using 157 JavaScript Object Notation (JSON) [RFC7159] based data structures. 158 The JWE cryptographic mechanisms encrypt and provide integrity 159 protection for an arbitrary sequence of octets. 161 Two closely related serializations for JWE objects are defined. The 162 JWE Compact Serialization is a compact, URL-safe representation 163 intended for space constrained environments such as HTTP 164 Authorization headers and URI query parameters. The JWE JSON 165 Serialization represents JWE objects as JSON objects and enables the 166 same content to be encrypted to multiple parties. Both share the 167 same cryptographic underpinnings. 169 Cryptographic algorithms and identifiers for use with this 170 specification are described in the separate JSON Web Algorithms (JWA) 171 [JWA] specification and IANA registries defined by that 172 specification. Related digital signature and MAC capabilities are 173 described in the separate JSON Web Signature (JWS) [JWS] 174 specification. 176 Names defined by this specification are short because a core goal is 177 for the resulting representations to be compact. 179 1.1. Notational Conventions 181 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 182 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 183 "OPTIONAL" in this document are to be interpreted as described in Key 184 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 185 these words are used without being spelled in uppercase then they are 186 to be interpreted with their normal natural language meanings. 188 BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per 189 Section 2. 191 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 192 of STRING. 194 ASCII(STRING) denotes the octets of the ASCII [USASCII] 195 representation of STRING. 197 The concatenation of two values A and B is denoted as A || B. 199 2. Terminology 201 These terms defined by the JSON Web Signature (JWS) [JWS] 202 specification are incorporated into this specification: "JSON Web 203 Signature (JWS)", "Base64url Encoding", "Collision-Resistant Name", 204 "Header Parameter", "JOSE Header", and "StringOrURI". 206 These terms are defined by this specification: 208 JSON Web Encryption (JWE) 209 A data structure representing an encrypted and integrity protected 210 message. 212 Authenticated Encryption with Associated Data (AEAD) 213 An AEAD algorithm is one that encrypts the Plaintext, allows 214 Additional Authenticated Data to be specified, and provides an 215 integrated content integrity check over the Ciphertext and 216 Additional Authenticated Data. AEAD algorithms accept two inputs, 217 the Plaintext and the Additional Authenticated Data value, and 218 produce two outputs, the Ciphertext and the Authentication Tag 219 value. AES Galois/Counter Mode (GCM) is one such algorithm. 221 Plaintext 222 The sequence of octets to be encrypted -- a.k.a., the message. 223 The plaintext can contain an arbitrary sequence of octets. 225 Ciphertext 226 An encrypted representation of the Plaintext. 228 Additional Authenticated Data (AAD) 229 An input to an AEAD operation that is integrity protected but not 230 encrypted. 232 Authentication Tag 233 An output of an AEAD operation that ensures the integrity of the 234 Ciphertext and the Additional Authenticated Data. Note that some 235 algorithms may not use an Authentication Tag, in which case this 236 value is the empty octet sequence. 238 Content Encryption Key (CEK) 239 A symmetric key for the AEAD algorithm used to encrypt the 240 Plaintext for the recipient to produce the Ciphertext and the 241 Authentication Tag. 243 JWE Encrypted Key 244 Encrypted Content Encryption Key (CEK) value. Note that for some 245 algorithms, the JWE Encrypted Key value is specified as being the 246 empty octet sequence. 248 JWE Initialization Vector 249 Initialization vector value used when encrypting the plaintext. 250 Note that some algorithms may not use an Initialization Vector, in 251 which case this value is the empty octet sequence. 253 JWE AAD 254 Additional value to be integrity protected by the authenticated 255 encryption operation. This can only be present when using the JWE 256 JSON Serialization. (Note that this can also be achieved when 257 using either serialization by including the AAD value as an 258 integrity protected Header Parameter value, but at the cost of the 259 value being double base64url encoded.) 261 JWE Ciphertext 262 Ciphertext value resulting from authenticated encryption of the 263 plaintext with additional authenticated data. 265 JWE Authentication Tag 266 Authentication Tag value resulting from authenticated encryption 267 of the plaintext with additional authenticated data. 269 JWE Protected Header 270 JSON object that contains the Header Parameters that are integrity 271 protected by the authenticated encryption operation. These 272 parameters apply to all recipients of the JWE. For the JWE 273 Compact Serialization, this comprises the entire JOSE Header. For 274 the JWE JSON Serialization, this is one component of the JOSE 275 Header. 277 JWE Shared Unprotected Header 278 JSON object that contains the Header Parameters that apply to all 279 recipients of the JWE that are not integrity protected. This can 280 only be present when using the JWE JSON Serialization. 282 JWE Per-Recipient Unprotected Header 283 JSON object that contains Header Parameters that apply to a single 284 recipient of the JWE. These Header Parameter values are not 285 integrity protected. This can only be present when using the JWE 286 JSON Serialization. 288 JWE Compact Serialization 289 A representation of the JWE as a compact, URL-safe string. 291 JWE JSON Serialization 292 A representation of the JWE as a JSON object. The JWE JSON 293 Serialization enables the same content to be encrypted to multiple 294 parties. This representation is neither optimized for compactness 295 nor URL-safe. 297 Key Management Mode 298 A method of determining the Content Encryption Key (CEK) value to 299 use. Each algorithm used for determining the CEK value uses a 300 specific Key Management Mode. Key Management Modes employed by 301 this specification are Key Encryption, Key Wrapping, Direct Key 302 Agreement, Key Agreement with Key Wrapping, and Direct Encryption. 304 Key Encryption 305 A Key Management Mode in which the Content Encryption Key (CEK) 306 value is encrypted to the intended recipient using an asymmetric 307 encryption algorithm. 309 Key Wrapping 310 A Key Management Mode in which the Content Encryption Key (CEK) 311 value is encrypted to the intended recipient using a symmetric key 312 wrapping algorithm. 314 Direct Key Agreement 315 A Key Management Mode in which a key agreement algorithm is used 316 to agree upon the Content Encryption Key (CEK) value. 318 Key Agreement with Key Wrapping 319 A Key Management Mode in which a key agreement algorithm is used 320 to agree upon a symmetric key used to encrypt the Content 321 Encryption Key (CEK) value to the intended recipient using a 322 symmetric key wrapping algorithm. 324 Direct Encryption 325 A Key Management Mode in which the Content Encryption Key (CEK) 326 value used is the secret symmetric key value shared between the 327 parties. 329 3. JSON Web Encryption (JWE) Overview 331 JWE represents encrypted content using JSON data structures and 332 base64url encoding. These JSON data structures MAY contain white 333 space and/or line breaks. A JWE represents these logical values 334 (each of which is defined in Section 2): 336 o JOSE Header 337 o JWE Encrypted Key 338 o JWE Initialization Vector 339 o JWE AAD 340 o JWE Ciphertext 341 o JWE Authentication Tag 343 For a JWE object, the JOSE Header members are the union of the 344 members of these values (each of which is defined in Section 2): 346 o JWE Protected Header 347 o JWE Shared Unprotected Header 348 o JWE Per-Recipient Unprotected Header 350 JWE utilizes authenticated encryption to ensure the confidentiality 351 and integrity of the Plaintext and the integrity of the JWE Protected 352 Header and the JWE AAD. 354 This document defines two serializations for JWE objects: a compact, 355 URL-safe serialization called the JWE Compact Serialization and a 356 JSON serialization called the JWE JSON Serialization. In both 357 serializations, the JWE Protected Header, JWE Encrypted Key, JWE 358 Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are 359 base64url encoded for transmission, since JSON lacks a way to 360 directly represent arbitrary octet sequences. When present, the JWE 361 AAD is also base64url encoded for transmission. 363 3.1. JWE Compact Serialization Overview 365 In the JWE Compact Serialization, no JWE Shared Unprotected Header or 366 JWE Per-Recipient Unprotected Header are used. In this case, the 367 JOSE Header and the JWE Protected Header are the same. 369 In the JWE Compact Serialization, a JWE object is represented as the 370 concatenation: 372 BASE64URL(UTF8(JWE Protected Header)) || '.' || 373 BASE64URL(JWE Encrypted Key) || '.' || 374 BASE64URL(JWE Initialization Vector) || '.' || 375 BASE64URL(JWE Ciphertext) || '.' || 376 BASE64URL(JWE Authentication Tag) 378 3.2. JWE JSON Serialization Overview 380 In the JWE JSON Serialization, one or more of the JWE Protected 381 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 382 Unprotected Header MUST be present. In this case, the members of the 383 JOSE Header are the combination of the members of the JWE Protected 384 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 385 Unprotected Header values that are present. 387 In the JWE JSON Serialization, a JWE object is represented as the 388 combination of these eight values, 389 BASE64URL(UTF8(JWE Protected Header)), 390 JWE Shared Unprotected Header, 391 JWE Per-Recipient Unprotected Header, 392 BASE64URL(JWE Encrypted Key), 393 BASE64URL(JWE Initialization Vector), 394 BASE64URL(JWE Ciphertext), 395 BASE64URL(JWE Authentication Tag), and 396 BASE64URL(JWE AAD), 397 with the six base64url encoded result strings and the two unprotected 398 JSON object values being represented as members within a JSON object. 399 The inclusion of some of these values is OPTIONAL. The JWE JSON 400 Serialization can also encrypt the plaintext to multiple recipients. 401 See Section 7.2 for more information about the JWE JSON 402 Serialization. 404 3.3. Example JWE 406 This example encrypts the plaintext "The true sign of intelligence is 407 not knowledge but imagination." to the recipient. 409 The following example JWE Protected Header declares that: 410 o the Content Encryption Key is encrypted to the recipient using the 411 RSAES OAEP [RFC3447] algorithm to produce the JWE Encrypted Key 412 and 413 o the Plaintext is encrypted using the AES GCM [AES, NIST.800-38D] 414 algorithm with a 256 bit key to produce the Ciphertext. 416 {"alg":"RSA-OAEP","enc":"A256GCM"} 418 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 419 Header)) gives this value: 421 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 423 The remaining steps to finish creating this JWE are: 424 o Generate a random Content Encryption Key (CEK). 425 o Encrypt the CEK with the recipient's public key using the RSAES 426 OAEP algorithm to produce the JWE Encrypted Key. 427 o Base64url encode the JWE Encrypted Key. 428 o Generate a random JWE Initialization Vector. 429 o Base64url encode the JWE Initialization Vector. 430 o Let the Additional Authenticated Data encryption parameter be 431 ASCII(BASE64URL(UTF8(JWE Protected Header))). 432 o Encrypt the Plaintext with AES GCM using the CEK as the encryption 433 key, the JWE Initialization Vector, and the Additional 434 Authenticated Data value, requesting a 128 bit Authentication Tag 435 output. 437 o Base64url encode the Ciphertext. 438 o Base64url encode the Authentication Tag. 439 o Assemble the final representation: The Compact Serialization of 440 this result is the string BASE64URL(UTF8(JWE Protected Header)) || 441 '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE 442 Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' 443 || BASE64URL(JWE Authentication Tag). 445 The final result in this example (with line breaks for display 446 purposes only) is: 448 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 449 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 450 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 451 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 452 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 453 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 454 6UklfCpIMfIjf7iGdXKHzg. 455 48V1_ALb6US04U3b. 456 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 457 SdiwkIr3ajwQzaBtQD_A. 458 XFBoMYUZodetZdvTiFvSkQ 460 See Appendix A.1 for the complete details of computing this JWE. See 461 other parts of Appendix A for additional examples. 463 4. JOSE Header 465 For a JWE object, the members of the JSON object(s) representing the 466 JOSE Header describe the encryption applied to the Plaintext and 467 optionally additional properties of the JWE. The Header Parameter 468 names within the JOSE Header MUST be unique, just as described in 469 Section 4 of [JWS]. The rules about handling Header Parameters that 470 are not understood by the implementation are also the same. The 471 classes of Header Parameter names are likewise the same. 473 4.1. Registered Header Parameter Names 475 The following Header Parameter names for use in JWE objects are 476 registered in the IANA JSON Web Signature and Encryption Header 477 Parameters registry defined in [JWS], with meanings as defined below. 479 As indicated by the common registry, JWSs and JWEs share a common 480 Header Parameter space; when a parameter is used by both 481 specifications, its usage must be compatible between the 482 specifications. 484 4.1.1. "alg" (Algorithm) Header Parameter 486 This parameter has the same meaning, syntax, and processing rules as 487 the "alg" Header Parameter defined in Section 4.1.1 of [JWS], except 488 that the Header Parameter identifies the cryptographic algorithm used 489 to encrypt or determine the value of the Content Encryption Key 490 (CEK). The encrypted content is not usable if the "alg" value does 491 not represent a supported algorithm, or if the recipient does not 492 have a key that can be used with that algorithm. 494 A list of defined "alg" values for this use can be found in the IANA 495 JSON Web Signature and Encryption Algorithms registry defined in 496 [JWA]; the initial contents of this registry are the values defined 497 in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. 499 4.1.2. "enc" (Encryption Algorithm) Header Parameter 501 The "enc" (encryption algorithm) Header Parameter identifies the 502 content encryption algorithm used to encrypt the Plaintext to produce 503 the Ciphertext. This algorithm MUST be an AEAD algorithm with a 504 specified key length. The recipient MUST reject the JWE if the "enc" 505 value does not represent a supported algorithm. "enc" values should 506 either be registered in the IANA JSON Web Signature and Encryption 507 Algorithms registry defined in [JWA] or be a value that contains a 508 Collision-Resistant Name. The "enc" value is a case-sensitive string 509 containing a StringOrURI value. This Header Parameter MUST be 510 present and MUST be understood and processed by implementations. 512 A list of defined "enc" values for this use can be found in the IANA 513 JSON Web Signature and Encryption Algorithms registry defined in 514 [JWA]; the initial contents of this registry are the values defined 515 in Section 5.1 of the JSON Web Algorithms (JWA) [JWA] specification. 517 4.1.3. "zip" (Compression Algorithm) Header Parameter 519 The "zip" (compression algorithm) applied to the Plaintext before 520 encryption, if any. The "zip" value defined by this specification 521 is: 523 o "DEF" - Compression with the DEFLATE [RFC1951] algorithm 525 Other values MAY be used. Compression algorithm values can be 526 registered in the IANA JSON Web Encryption Compression Algorithm 527 registry defined in [JWA]. The "zip" value is a case-sensitive 528 string. If no "zip" parameter is present, no compression is applied 529 to the Plaintext before encryption. This Header Parameter MUST be 530 integrity protected, and therefore MUST occur only within the JWE 531 Protected Header, when used. Use of this Header Parameter is 532 OPTIONAL. This Header Parameter MUST be understood and processed by 533 implementations. 535 4.1.4. "jku" (JWK Set URL) Header Parameter 537 This parameter has the same meaning, syntax, and processing rules as 538 the "jku" Header Parameter defined in Section 4.1.2 of [JWS], except 539 that the JWK Set resource contains the public key to which the JWE 540 was encrypted; this can be used to determine the private key needed 541 to decrypt the JWE. 543 4.1.5. "jwk" (JSON Web Key) Header Parameter 545 This parameter has the same meaning, syntax, and processing rules as 546 the "jwk" Header Parameter defined in Section 4.1.3 of [JWS], except 547 that the key is the public key to which the JWE was encrypted; this 548 can be used to determine the private key needed to decrypt the JWE. 550 4.1.6. "kid" (Key ID) Header Parameter 552 This parameter has the same meaning, syntax, and processing rules as 553 the "kid" Header Parameter defined in Section 4.1.4 of [JWS], except 554 that the key hint references the public key to which the JWE was 555 encrypted; this can be used to determine the private key needed to 556 decrypt the JWE. This parameter allows originators to explicitly 557 signal a change of key to JWE recipients. 559 4.1.7. "x5u" (X.509 URL) Header Parameter 561 This parameter has the same meaning, syntax, and processing rules as 562 the "x5u" Header Parameter defined in Section 4.1.5 of [JWS], except 563 that the X.509 public key certificate or certificate chain [RFC5280] 564 contains the public key to which the JWE was encrypted; this can be 565 used to determine the private key needed to decrypt the JWE. 567 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 569 This parameter has the same meaning, syntax, and processing rules as 570 the "x5c" Header Parameter defined in Section 4.1.6 of [JWS], except 571 that the X.509 public key certificate or certificate chain [RFC5280] 572 contains the public key to which the JWE was encrypted; this can be 573 used to determine the private key needed to decrypt the JWE. 575 See Appendix B of [JWS] for an example "x5c" value. 577 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 579 This parameter has the same meaning, syntax, and processing rules as 580 the "x5t" Header Parameter defined in Section 4.1.7 of [JWS], except 581 that the certificate referenced by the thumbprint contains the public 582 key to which the JWE was encrypted; this can be used to determine the 583 private key needed to decrypt the JWE. 585 4.1.10. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header 586 Parameter 588 This parameter has the same meaning, syntax, and processing rules as 589 the "x5t#S256" Header Parameter defined in Section 4.1.8 of [JWS], 590 except that the certificate referenced by the thumbprint contains the 591 public key to which the JWE was encrypted; this can be used to 592 determine the private key needed to decrypt the JWE. 594 4.1.11. "typ" (Type) Header Parameter 596 This parameter has the same meaning, syntax, and processing rules as 597 the "typ" Header Parameter defined in Section 4.1.9 of [JWS], except 598 that the type is that of this complete JWE object. 600 4.1.12. "cty" (Content Type) Header Parameter 602 This parameter has the same meaning, syntax, and processing rules as 603 the "cty" Header Parameter defined in Section 4.1.10 of [JWS], except 604 that the type is that of the secured content (the plaintext). 606 4.1.13. "crit" (Critical) Header Parameter 608 This parameter has the same meaning, syntax, and processing rules as 609 the "crit" Header Parameter defined in Section 4.1.11 of [JWS], 610 except that Header Parameters for a JWE object are being referred to, 611 rather than Header Parameters for a JWS object. 613 4.2. Public Header Parameter Names 615 Additional Header Parameter names can be defined by those using JWEs. 616 However, in order to prevent collisions, any new Header Parameter 617 name should either be registered in the IANA JSON Web Signature and 618 Encryption Header Parameters registry defined in [JWS] or be a Public 619 Name: a value that contains a Collision-Resistant Name. In each 620 case, the definer of the name or value needs to take reasonable 621 precautions to make sure they are in control of the part of the 622 namespace they use to define the Header Parameter name. 624 New Header Parameters should be introduced sparingly, as they can 625 result in non-interoperable JWEs. 627 4.3. Private Header Parameter Names 629 A producer and consumer of a JWE may agree to use Header Parameter 630 names that are Private Names: names that are not Registered Header 631 Parameter names Section 4.1 or Public Header Parameter names 632 Section 4.2. Unlike Public Header Parameter names, Private Header 633 Parameter names are subject to collision and should be used with 634 caution. 636 5. Producing and Consuming JWEs 638 5.1. Message Encryption 640 The message encryption process is as follows. The order of the steps 641 is not significant in cases where there are no dependencies between 642 the inputs and outputs of the steps. 644 1. Determine the Key Management Mode employed by the algorithm used 645 to determine the Content Encryption Key (CEK) value. (This is 646 the algorithm recorded in the "alg" (algorithm) Header Parameter 647 of the resulting JWE.) 649 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 650 Wrapping are employed, generate a random Content Encryption Key 651 (CEK) value. See RFC 4086 [RFC4086] for considerations on 652 generating random values. The CEK MUST have a length equal to 653 that required for the content encryption algorithm. 655 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 656 employed, use the key agreement algorithm to compute the value 657 of the agreed upon key. When Direct Key Agreement is employed, 658 let the Content Encryption Key (CEK) be the agreed upon key. 659 When Key Agreement with Key Wrapping is employed, the agreed 660 upon key will be used to wrap the CEK. 662 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 663 Wrapping are employed, encrypt the CEK to the recipient and let 664 the result be the JWE Encrypted Key. 666 5. When Direct Key Agreement or Direct Encryption are employed, let 667 the JWE Encrypted Key be the empty octet sequence. 669 6. When Direct Encryption is employed, let the Content Encryption 670 Key (CEK) be the shared symmetric key. 672 7. Compute the encoded key value BASE64URL(JWE Encrypted Key). 674 8. If the JWE JSON Serialization is being used, repeat this process 675 (steps 1-7) for each recipient. 677 9. Generate a random JWE Initialization Vector of the correct size 678 for the content encryption algorithm (if required for the 679 algorithm); otherwise, let the JWE Initialization Vector be the 680 empty octet sequence. 682 10. Compute the encoded initialization vector value BASE64URL(JWE 683 Initialization Vector). 685 11. If a "zip" parameter was included, compress the Plaintext using 686 the specified compression algorithm and let M be the octet 687 sequence representing the compressed Plaintext; otherwise, let M 688 be the octet sequence representing the Plaintext. 690 12. Create the JSON object(s) containing the desired set of Header 691 Parameters, which together comprise the JOSE Header: the JWE 692 Protected Header, and if the JWE JSON Serialization is being 693 used, the JWE Shared Unprotected Header and the JWE Per- 694 Recipient Unprotected Header. 696 13. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 697 Protected Header)). If the JWE Protected Header is not present 698 (which can only happen when using the JWE JSON Serialization and 699 no "protected" member is present), let this value be the empty 700 string. 702 14. Let the Additional Authenticated Data encryption parameter be 703 ASCII(Encoded Protected Header). However if a JWE AAD value is 704 present (which can only be the case when using the JWE JSON 705 Serialization), instead let the Additional Authenticated Data 706 encryption parameter be ASCII(Encoded Protected Header || '.' || 707 BASE64URL(JWE AAD)). 709 15. Encrypt M using the CEK, the JWE Initialization Vector, and the 710 Additional Authenticated Data value using the specified content 711 encryption algorithm to create the JWE Ciphertext value and the 712 JWE Authentication Tag (which is the Authentication Tag output 713 from the encryption operation). 715 16. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext). 717 17. Compute the encoded authentication tag value BASE64URL(JWE 718 Authentication Tag). 720 18. The five encoded values are used in both the JWE Compact 721 Serialization and the JWE JSON Serialization representations. 723 19. If a JWE AAD value is present, compute the encoded AAD value 724 BASE64URL(JWE AAD). 726 20. Create the desired serialized output. The Compact Serialization 727 of this result is the string BASE64URL(UTF8(JWE Protected 728 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 729 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 730 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). The 731 JWE JSON Serialization is described in Section 7.2. 733 5.2. Message Decryption 735 The message decryption process is the reverse of the encryption 736 process. The order of the steps is not significant in cases where 737 there are no dependencies between the inputs and outputs of the 738 steps. If any of these steps fails, the encrypted content cannot be 739 validated. 741 When there are multiple recipients, it is an application decision 742 which of the recipients' encrypted content must successfully validate 743 for the JWE to be accepted. In some cases, encrypted content for all 744 recipients must successfully validate or the JWE will be rejected. 745 In other cases, only the encrypted content for a single recipient 746 needs to be successfully validated. However, in all cases, the 747 encrypted content for at least one recipient MUST successfully 748 validate or the JWE MUST be rejected. 750 1. Parse the JWE representation to extract the serialized values 751 for the components of the JWE. When using the JWE Compact 752 Serialization, these components are the base64url encoded 753 representations of the JWE Protected Header, the JWE Encrypted 754 Key, the JWE Initialization Vector, the JWE Ciphertext, and the 755 JWE Authentication Tag, and when using the JWE JSON 756 Serialization, these components also include the base64url 757 encoded representation of the JWE AAD and the unencoded JWE 758 Shared Unprotected Header and JWE Per-Recipient Unprotected 759 Header values. When using the JWE Compact Serialization, the 760 JWE Protected Header, the JWE Encrypted Key, the JWE 761 Initialization Vector, the JWE Ciphertext, and the JWE 762 Authentication Tag are represented as base64url encoded values 763 in that order, separated by four period ('.') characters. The 764 JWE JSON Serialization is described in Section 7.2. 766 2. The encoded representations of the JWE Protected Header, the JWE 767 Encrypted Key, the JWE Initialization Vector, the JWE 768 Ciphertext, the JWE Authentication Tag, and the JWE AAD MUST be 769 successfully base64url decoded following the restriction that no 770 padding characters have been used. 772 3. The octet sequence resulting from decoding the encoded JWE 773 Protected Header MUST be a UTF-8 encoded representation of a 774 completely valid JSON object conforming to RFC 7159 [RFC7159], 775 which is the JWE Protected Header. 777 4. If using the JWE Compact Serialization, let the JOSE Header be 778 the JWE Protected Header. Otherwise, when using the JWE JSON 779 Serialization, let the JOSE Header be the union of the members 780 of the JWE Protected Header, the JWE Shared Unprotected Header 781 and the corresponding JWE Per-Recipient Unprotected Header, all 782 of which must be completely valid JSON objects. 784 5. The resulting JOSE Header MUST NOT contain duplicate Header 785 Parameter names. When using the JWE JSON Serialization, this 786 restriction includes that the same Header Parameter name also 787 MUST NOT occur in distinct JSON object values that together 788 comprise the JOSE Header. 790 6. Verify that the implementation understands and can process all 791 fields that it is required to support, whether required by this 792 specification, by the algorithms being used, or by the "crit" 793 Header Parameter value, and that the values of those parameters 794 are also understood and supported. 796 7. Determine the Key Management Mode employed by the algorithm 797 specified by the "alg" (algorithm) Header Parameter. 799 8. Verify that the JWE uses a key known to the recipient. 801 9. When Direct Key Agreement or Key Agreement with Key Wrapping are 802 employed, use the key agreement algorithm to compute the value 803 of the agreed upon key. When Direct Key Agreement is employed, 804 let the Content Encryption Key (CEK) be the agreed upon key. 805 When Key Agreement with Key Wrapping is employed, the agreed 806 upon key will be used to decrypt the JWE Encrypted Key. 808 10. When Key Wrapping, Key Encryption, or Key Agreement with Key 809 Wrapping are employed, decrypt the JWE Encrypted Key to produce 810 the Content Encryption Key (CEK). The CEK MUST have a length 811 equal to that required for the content encryption algorithm. 812 Note that when there are multiple recipients, each recipient 813 will only be able decrypt any JWE Encrypted Key values that were 814 encrypted to a key in that recipient's possession. It is 815 therefore normal to only be able to decrypt one of the per- 816 recipient JWE Encrypted Key values to obtain the CEK value. 817 Also, see Section 11.5 for security considerations on mitigating 818 timing attacks. 820 11. When Direct Key Agreement or Direct Encryption are employed, 821 verify that the JWE Encrypted Key value is empty octet sequence. 823 12. When Direct Encryption is employed, let the Content Encryption 824 Key (CEK) be the shared symmetric key. 826 13. Record whether the CEK could be successfully determined for this 827 recipient or not. 829 14. If the JWE JSON Serialization is being used, repeat this process 830 (steps 4-13) for each recipient contained in the representation. 832 15. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 833 Protected Header)). If the JWE Protected Header is not present 834 (which can only happen when using the JWE JSON Serialization and 835 no "protected" member is present), let this value be the empty 836 string. 838 16. Let the Additional Authenticated Data encryption parameter be 839 ASCII(Encoded Protected Header). However if a JWE AAD value is 840 present (which can only be the case when using the JWE JSON 841 Serialization), instead let the Additional Authenticated Data 842 encryption parameter be ASCII(Encoded Protected Header || '.' || 843 BASE64URL(JWE AAD)). 845 17. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 846 Vector, the Additional Authenticated Data value, and the JWE 847 Authentication Tag (which is the Authentication Tag input to the 848 calculation) using the specified content encryption algorithm, 849 returning the decrypted plaintext and validating the JWE 850 Authentication Tag in the manner specified for the algorithm, 851 rejecting the input without emitting any decrypted output if the 852 JWE Authentication Tag is incorrect. 854 18. If a "zip" parameter was included, uncompress the decrypted 855 plaintext using the specified compression algorithm. 857 19. If there was no recipient for which all of the decryption steps 858 succeeded, then the JWE MUST be rejected. Otherwise, output the 859 Plaintext. In the JWE JSON Serialization case, also return a 860 result to the application indicating for which of the recipients 861 the decryption succeeded and failed. 863 Finally, note that it is an application decision which algorithms are 864 acceptable in a given context. Even if a JWE can be successfully 865 decrypted, unless the algorithms used in the JWE are acceptable to 866 the application, it SHOULD reject the JWE. 868 5.3. String Comparison Rules 870 The string comparison rules for this specification are the same as 871 those defined in Section 5.3 of [JWS]. 873 6. Key Identification 875 The key identification methods for this specification are the same as 876 those defined in Section 6 of [JWS], except that the key being 877 identified is the public key to which the JWE was encrypted. 879 7. Serializations 881 JWE objects use one of two serializations, the JWE Compact 882 Serialization or the JWE JSON Serialization. Applications using this 883 specification need to specify what serialization and serialization 884 features are used for that application. For instance, applications 885 might specify that only the JWE JSON Serialization is used, that only 886 JWE JSON Serialization support for a single recipient is used, or 887 that support for multiple recipients is used. JWE implementations 888 only need to implement the features needed for the applications they 889 are designed to support. 891 7.1. JWE Compact Serialization 893 The JWE Compact Serialization represents encrypted content as a 894 compact, URL-safe string. This string is: 896 BASE64URL(UTF8(JWE Protected Header)) || '.' || 897 BASE64URL(JWE Encrypted Key) || '.' || 898 BASE64URL(JWE Initialization Vector) || '.' || 899 BASE64URL(JWE Ciphertext) || '.' || 900 BASE64URL(JWE Authentication Tag) 902 Only one recipient is supported by the JWE Compact Serialization and 903 it provides no syntax to represent JWE Shared Unprotected Header, JWE 904 Per-Recipient Unprotected Header, or JWE AAD values. 906 7.2. JWE JSON Serialization 908 The JWE JSON Serialization represents encrypted content as a JSON 909 object. Content using the JWE JSON Serialization can be encrypted to 910 more than one recipient. This representation is neither optimized 911 for compactness nor URL-safe. 913 The following members are defined for use in top-level JSON objects 914 used for the JWE JSON Serialization: 916 protected 917 The "protected" member MUST be present and contain the value 918 BASE64URL(UTF8(JWE Protected Header)) when the JWE Protected 919 Header value is non-empty; otherwise, it MUST be absent. These 920 Header Parameter values are integrity protected. 922 unprotected 923 The "unprotected" member MUST be present and contain the value JWE 924 Shared Unprotected Header when the JWE Shared Unprotected Header 925 value is non-empty; otherwise, it MUST be absent. This value is 926 represented as an unencoded JSON object, rather than as a string. 927 These Header Parameter values are not integrity protected. 929 iv 930 The "iv" member MUST be present and contain the value 931 BASE64URL(JWE Initialization Vector) when the JWE Initialization 932 Vector value is non-empty; otherwise, it MUST be absent. 934 aad 935 The "aad" member MUST be present and contain the value 936 BASE64URL(JWE AAD)) when the JWE AAD value is non-empty; 937 otherwise, it MUST be absent. A JWE AAD value can be included to 938 supply a base64url encoded value to be integrity protected but not 939 encrypted. 941 ciphertext 942 The "ciphertext" member MUST be present and contain the value 943 BASE64URL(JWE Ciphertext). 945 tag 946 The "tag" member MUST be present and contain the value 947 BASE64URL(JWE Authentication Tag) when the JWE Authentication Tag 948 value is non-empty; otherwise, it MUST be absent. 950 recipients 951 The "recipients" member value MUST be an array of JSON objects. 952 Each object contains information specific to a single recipient. 953 This member MUST be present, even if the array elements contain 954 only the empty JSON object "{}" (which can happen when all Header 955 Parameter values are shared between all recipients and when no 956 encrypted key is used, such as when doing Direct Encryption). 958 The following members are defined for use in the JSON objects that 959 are elements of the "recipients" array: 961 header 962 The "header" member MUST be present and contain the value JWE Per- 963 Recipient Unprotected Header when the JWE Per-Recipient 964 Unprotected Header value is non-empty; otherwise, it MUST be 965 absent. This value is represented as an unencoded JSON object, 966 rather than as a string. These Header Parameter values are not 967 integrity protected. 969 encrypted_key 970 The "encrypted_key" member MUST be present and contain the value 971 BASE64URL(JWE Encrypted Key) when the JWE Encrypted Key value is 972 non-empty; otherwise, it MUST be absent. 974 At least one of the "header", "protected", and "unprotected" members 975 MUST be present so that "alg" and "enc" Header Parameter values are 976 conveyed for each recipient computation. 978 Additional members can be present in both the JSON objects defined 979 above; if not understood by implementations encountering them, they 980 MUST be ignored. 982 Some Header Parameters, including the "alg" parameter, can be shared 983 among all recipient computations. Header Parameters in the JWE 984 Protected Header and JWE Shared Unprotected Header values are shared 985 among all recipients. 987 The Header Parameter values used when creating or validating per- 988 recipient Ciphertext and Authentication Tag values are the union of 989 the three sets of Header Parameter values that may be present: (1) 990 the JWE Protected Header represented in the "protected" member, (2) 991 the JWE Shared Unprotected Header represented in the "unprotected" 992 member, and (3) the JWE Per-Recipient Unprotected Header represented 993 in the "header" member of the recipient's array element. The union 994 of these sets of Header Parameters comprises the JOSE Header. The 995 Header Parameter names in the three locations MUST be disjoint. 997 Each JWE Encrypted Key value is computed using the parameters of the 998 corresponding JOSE Header value in the same manner as for the JWE 999 Compact Serialization. This has the desirable property that each JWE 1000 Encrypted Key value in the "recipients" array is identical to the 1001 value that would have been computed for the same parameter in the JWE 1002 Compact Serialization. Likewise, the JWE Ciphertext and JWE 1003 Authentication Tag values match those produced for the JWE Compact 1004 Serialization, provided that the JWE Protected Header value (which 1005 represents the integrity-protected Header Parameter values) matches 1006 that used in the JWE Compact Serialization. 1008 All recipients use the same JWE Protected Header, JWE Initialization 1009 Vector, JWE Ciphertext, and JWE Authentication Tag values, when 1010 present, resulting in potentially significant space savings if the 1011 message is large. Therefore, all Header Parameters that specify the 1012 treatment of the Plaintext value MUST be the same for all recipients. 1013 This primarily means that the "enc" (encryption algorithm) Header 1014 Parameter value in the JOSE Header for each recipient and any 1015 parameters of that algorithm MUST be the same. 1017 In summary, the syntax of a JWE using the JWE JSON Serialization is 1018 as follows: 1020 {"protected":"", 1021 "unprotected":, 1022 "recipients":[ 1023 {"header":, 1024 "encrypted_key":""}, 1025 ... 1026 {"header":, 1027 "encrypted_key":""}], 1028 "aad":"", 1029 "iv":"", 1030 "ciphertext":"", 1031 "tag":"" 1032 } 1034 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1035 Serialization. 1037 8. TLS Requirements 1039 The TLS requirements for this specification are the same as those 1040 defined in Section 8 of [JWS]. 1042 9. Distinguishing between JWS and JWE Objects 1044 There are several ways of distinguishing whether an object is a JWS 1045 or JWE object. All these methods will yield the same result for all 1046 legal input values; they may yield different results for malformed 1047 inputs. 1049 o If the object is using the JWS Compact Serialization or the JWE 1050 Compact Serialization, the number of base64url encoded segments 1051 separated by period ('.') characters differs for JWSs and JWEs. 1053 JWSs have three segments separated by two period ('.') characters. 1054 JWEs have five segments separated by four period ('.') characters. 1056 o If the object is using the JWS JSON Serialization or the JWE JSON 1057 Serialization, the members used will be different. JWSs have a 1058 "signatures" member and JWEs do not. JWEs have a "recipients" 1059 member and JWSs do not. 1061 o The JOSE Header for a JWS object can be distinguished from the 1062 JOSE Header for a JWE object by examining the "alg" (algorithm) 1063 Header Parameter value. If the value represents a digital 1064 signature or MAC algorithm, or is the value "none", it is for a 1065 JWS; if it represents a Key Encryption, Key Wrapping, Direct Key 1066 Agreement, Key Agreement with Key Wrapping, or Direct Encryption 1067 algorithm, it is for a JWE. (Extracting the "alg" value to 1068 examine is straightforward when using the JWS Compact 1069 Serialization or the JWE Compact Serialization and may be more 1070 difficult when using the JWS JSON Serialization or the JWE JSON 1071 Serialization.) 1073 o The JOSE Header for a JWS object can also be distinguished from 1074 the JOSE Header for a JWE object by determining whether an "enc" 1075 (encryption algorithm) member exists. If the "enc" member exists, 1076 it is a JWE; otherwise, it is a JWS. 1078 10. IANA Considerations 1080 10.1. JSON Web Signature and Encryption Header Parameters Registration 1082 This specification registers the Header Parameter names defined in 1083 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1084 Parameters registry defined in [JWS]. 1086 10.1.1. Registry Contents 1088 o Header Parameter Name: "alg" 1089 o Header Parameter Description: Algorithm 1090 o Header Parameter Usage Location(s): JWE 1091 o Change Controller: IESG 1092 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1094 o Header Parameter Name: "enc" 1095 o Header Parameter Description: Encryption Algorithm 1096 o Header Parameter Usage Location(s): JWE 1097 o Change Controller: IESG 1098 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1100 o Header Parameter Name: "zip" 1101 o Header Parameter Description: Compression Algorithm 1102 o Header Parameter Usage Location(s): JWE 1103 o Change Controller: IESG 1104 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1106 o Header Parameter Name: "jku" 1107 o Header Parameter Description: JWK Set URL 1108 o Header Parameter Usage Location(s): JWE 1109 o Change Controller: IESG 1110 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1112 o Header Parameter Name: "jwk" 1113 o Header Parameter Description: JSON Web Key 1114 o Header Parameter Usage Location(s): JWE 1115 o Change Controller: IESG 1116 o Specification document(s): Section 4.1.5 of [[ this document ]] 1118 o Header Parameter Name: "kid" 1119 o Header Parameter Description: Key ID 1120 o Header Parameter Usage Location(s): JWE 1121 o Change Controller: IESG 1122 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1124 o Header Parameter Name: "x5u" 1125 o Header Parameter Description: X.509 URL 1126 o Header Parameter Usage Location(s): JWE 1127 o Change Controller: IESG 1128 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1130 o Header Parameter Name: "x5c" 1131 o Header Parameter Description: X.509 Certificate Chain 1132 o Header Parameter Usage Location(s): JWE 1133 o Change Controller: IESG 1134 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1136 o Header Parameter Name: "x5t" 1137 o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint 1138 o Header Parameter Usage Location(s): JWE 1139 o Change Controller: IESG 1140 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1142 o Header Parameter Name: "x5t#S256" 1143 o Header Parameter Description: X.509 Certificate SHA-256 Thumbprint 1144 o Header Parameter Usage Location(s): JWE 1145 o Change Controller: IESG 1146 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1148 o Header Parameter Name: "typ" 1149 o Header Parameter Description: Type 1150 o Header Parameter Usage Location(s): JWE 1151 o Change Controller: IESG 1152 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1154 o Header Parameter Name: "cty" 1155 o Header Parameter Description: Content Type 1156 o Header Parameter Usage Location(s): JWE 1157 o Change Controller: IESG 1158 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1160 o Header Parameter Name: "crit" 1161 o Header Parameter Description: Critical 1162 o Header Parameter Usage Location(s): JWE 1163 o Change Controller: IESG 1164 o Specification Document(s): Section 4.1.13 of [[ this document ]] 1166 11. Security Considerations 1168 All of the security issues that are pertinent to any cryptographic 1169 application must be addressed by JWS/JWE/JWK agents. Among these 1170 issues are protecting the user's asymmetric private and symmetric 1171 secret keys and employing countermeasures to various attacks. 1173 All the security considerations in the JWS specification also apply 1174 to this specification. Likewise, all the security considerations in 1175 XML Encryption 1.1 [W3C.REC-xmlenc-core1-20130411] also apply, other 1176 than those that are XML specific. 1178 11.1. Key Entropy and Random Values 1180 See Section 10.1 of [JWS] for security considerations on key entropy 1181 and random values. In addition to the uses of random values listed 1182 there, note that random values are also used for content encryption 1183 keys (CEKs) and initialization vectors (IVs) when performing 1184 encryption. 1186 11.2. Key Protection 1188 See Section 10.2 of [JWS] for security considerations on key 1189 protection. In addition to the keys listed there that must be 1190 protected, implementations performing encryption must protect the key 1191 encryption key and the content encryption key. Compromise of the key 1192 encryption key may result in the disclosure of all contents protected 1193 with that key. Similarly, compromise of the content encryption key 1194 may result in disclosure of the associated encrypted content. 1196 11.3. Using Matching Algorithm Strengths 1198 Algorithms of matching strengths should be used together whenever 1199 possible. For instance, when AES Key Wrap is used with a given key 1200 size, using the same key size is recommended when AES GCM is also 1201 used. If the key encryption and content encryption algorithms are 1202 different, the effective security is determined by the weaker of the 1203 two algorithms. 1205 Also, see RFC 3766 [RFC3766] for information on determining strengths 1206 for public keys used for exchanging symmetric keys. 1208 11.4. Adaptive Chosen-Ciphertext Attacks 1210 When decrypting, particular care must be taken not to allow the JWE 1211 recipient to be used as an oracle for decrypting messages. RFC 3218 1212 [RFC3218] should be consulted for specific countermeasures to attacks 1213 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1214 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1215 formatting error that can be detected and used to recover the CEK 1216 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1217 particularly important to report all formatting errors to the CEK, 1218 Additional Authenticated Data, or ciphertext as a single error when 1219 the encrypted content is rejected. 1221 Additionally, this type of attack can be prevented by restricting the 1222 use of a key to a limited set of algorithms -- usually one. This 1223 means, for instance, that if the key is marked as being for 1224 "RSA-OAEP" only, any attempt to decrypt a message using the "RSA1_5" 1225 algorithm with that key should fail immediately due to invalid use of 1226 the key. 1228 11.5. Timing Attacks 1230 To mitigate the attacks described in RFC 3218 [RFC3218], the 1231 recipient MUST NOT distinguish between format, padding, and length 1232 errors of encrypted keys. It is strongly recommended, in the event 1233 of receiving an improperly formatted key, that the receiver 1234 substitute a randomly generated CEK and proceed to the next step, to 1235 mitigate timing attacks. 1237 12. References 1238 12.1. Normative References 1240 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1241 draft-ietf-jose-json-web-algorithms (work in progress), 1242 September 2014. 1244 [JWK] Jones, M., "JSON Web Key (JWK)", 1245 draft-ietf-jose-json-web-key (work in progress), 1246 September 2014. 1248 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1249 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1250 in progress), September 2014. 1252 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1253 version 1.3", RFC 1951, May 1996. 1255 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1256 Requirement Levels", BCP 14, RFC 2119, March 1997. 1258 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1259 10646", STD 63, RFC 3629, November 2003. 1261 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1262 Housley, R., and W. Polk, "Internet X.509 Public Key 1263 Infrastructure Certificate and Certificate Revocation List 1264 (CRL) Profile", RFC 5280, May 2008. 1266 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1267 Interchange Format", RFC 7159, March 2014. 1269 [USASCII] American National Standards Institute, "Coded Character 1270 Set -- 7-bit American Standard Code for Information 1271 Interchange", ANSI X3.4, 1986. 1273 12.2. Informative References 1275 [AES] National Institute of Standards and Technology (NIST), 1276 "Advanced Encryption Standard (AES)", FIPS PUB 197, 1277 November 2001. 1279 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1280 McGrew, D., Foley, J., and K. Paterson, "Authenticated 1281 Encryption with AES-CBC and HMAC-SHA", 1282 draft-mcgrew-aead-aes-cbc-hmac-sha2-05 (work in progress), 1283 July 2014. 1285 [I-D.rescorla-jsms] 1286 Rescorla, E. and J. Hildebrand, "JavaScript Message 1287 Security Format", draft-rescorla-jsms-00 (work in 1288 progress), March 2011. 1290 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1291 Encryption", September 2010. 1293 [NIST.800-38D] 1294 National Institute of Standards and Technology (NIST), 1295 "Recommendation for Block Cipher Modes of Operation: 1296 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 1297 December 2001. 1299 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1300 Cryptographic Message Syntax", RFC 3218, January 2002. 1302 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1303 Standards (PKCS) #1: RSA Cryptography Specifications 1304 Version 2.1", RFC 3447, February 2003. 1306 [RFC3766] Orman, H. and P. Hoffman, "Determining Strengths For 1307 Public Keys Used For Exchanging Symmetric Keys", BCP 86, 1308 RFC 3766, April 2004. 1310 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1311 Requirements for Security", BCP 106, RFC 4086, June 2005. 1313 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1314 RFC 5652, September 2009. 1316 [W3C.REC-xmlenc-core1-20130411] 1317 Eastlake, D., Reagle, J., Hirsch, F., and T. Roessler, 1318 "XML Encryption Syntax and Processing Version 1.1", World 1319 Wide Web Consortium Recommendation REC-xmlenc-core1- 1320 20130411, April 2013, 1321 . 1323 Appendix A. JWE Examples 1325 This section provides examples of JWE computations. 1327 A.1. Example JWE using RSAES OAEP and AES GCM 1329 This example encrypts the plaintext "The true sign of intelligence is 1330 not knowledge but imagination." to the recipient using RSAES OAEP for 1331 key encryption and AES GCM for content encryption. The 1332 representation of this plaintext (using JSON array notation) is: 1334 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1335 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1336 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1337 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1338 110, 97, 116, 105, 111, 110, 46] 1340 A.1.1. JOSE Header 1342 The following example JWE Protected Header declares that: 1344 o the Content Encryption Key is encrypted to the recipient using the 1345 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1347 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1348 bit key to produce the Ciphertext. 1350 {"alg":"RSA-OAEP","enc":"A256GCM"} 1352 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1353 Header)) gives this value: 1355 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1357 A.1.2. Content Encryption Key (CEK) 1359 Generate a 256 bit random Content Encryption Key (CEK). In this 1360 example, the value (using JSON array notation) is: 1362 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1363 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1364 234, 64, 252] 1366 A.1.3. Key Encryption 1368 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1369 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1370 key represented in JSON Web Key [JWK] format below (with line breaks 1371 within values for display purposes only): 1373 {"kty":"RSA", 1374 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1375 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1376 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1377 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1378 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1379 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1380 "e":"AQAB", 1381 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1382 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1383 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1384 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1385 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1386 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ" 1387 } 1389 The resulting JWE Encrypted Key value is: 1391 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1392 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1393 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1394 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1395 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1396 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1397 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1398 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1399 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1400 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1401 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1402 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1403 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1404 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1405 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1406 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1407 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1408 117, 114, 135, 206] 1410 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1411 this value (with line breaks for display purposes only): 1413 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1414 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1415 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1416 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1417 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1418 6UklfCpIMfIjf7iGdXKHzg 1420 A.1.4. Initialization Vector 1422 Generate a random 96 bit JWE Initialization Vector. In this example, 1423 the value is: 1425 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1427 Encoding this JWE Initialization Vector as BASE64URL(JWE 1428 Initialization Vector) gives this value: 1430 48V1_ALb6US04U3b 1432 A.1.5. Additional Authenticated Data 1434 Let the Additional Authenticated Data encryption parameter be 1435 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1437 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1438 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1439 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1441 A.1.6. Content Encryption 1443 Encrypt the Plaintext with AES GCM using the CEK as the encryption 1444 key, the JWE Initialization Vector, and the Additional Authenticated 1445 Data value above, requesting a 128 bit Authentication Tag output. 1446 The resulting Ciphertext is: 1448 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1449 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1450 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1451 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1452 160, 109, 64, 63, 192] 1454 The resulting Authentication Tag value is: 1456 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1457 210, 145] 1459 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1460 value (with line breaks for display purposes only): 1462 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1463 SdiwkIr3ajwQzaBtQD_A 1465 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1466 Tag) gives this value: 1468 XFBoMYUZodetZdvTiFvSkQ 1470 A.1.7. Complete Representation 1472 Assemble the final representation: The Compact Serialization of this 1473 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1474 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1475 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1476 Authentication Tag). 1478 The final result in this example (with line breaks for display 1479 purposes only) is: 1481 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1482 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1483 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1484 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1485 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1486 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1487 6UklfCpIMfIjf7iGdXKHzg. 1488 48V1_ALb6US04U3b. 1489 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1490 SdiwkIr3ajwQzaBtQD_A. 1491 XFBoMYUZodetZdvTiFvSkQ 1493 A.1.8. Validation 1495 This example illustrates the process of creating a JWE with RSAES 1496 OAEP for key encryption and AES GCM for content encryption. These 1497 results can be used to validate JWE decryption implementations for 1498 these algorithms. Note that since the RSAES OAEP computation 1499 includes random values, the encryption results above will not be 1500 completely reproducible. However, since the AES GCM computation is 1501 deterministic, the JWE Encrypted Ciphertext values will be the same 1502 for all encryptions performed using these inputs. 1504 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1506 This example encrypts the plaintext "Live long and prosper." to the 1507 recipient using RSAES-PKCS1-V1_5 for key encryption and 1508 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1509 of this plaintext (using JSON array notation) is: 1511 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1512 112, 114, 111, 115, 112, 101, 114, 46] 1514 A.2.1. JOSE Header 1516 The following example JWE Protected Header declares that: 1518 o the Content Encryption Key is encrypted to the recipient using the 1519 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1521 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1522 algorithm to produce the Ciphertext. 1524 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1526 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1527 Header)) gives this value: 1529 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1531 A.2.2. Content Encryption Key (CEK) 1533 Generate a 256 bit random Content Encryption Key (CEK). In this 1534 example, the key value is: 1536 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1537 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1538 44, 207] 1540 A.2.3. Key Encryption 1542 Encrypt the CEK with the recipient's public key using the RSAES- 1543 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1544 uses the RSA key represented in JSON Web Key [JWK] format below (with 1545 line breaks within values for display purposes only): 1547 {"kty":"RSA", 1548 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1549 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1550 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1551 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1552 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1553 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1554 "e":"AQAB", 1555 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1556 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1557 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1558 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1559 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1560 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1562 } 1564 The resulting JWE Encrypted Key value is: 1566 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1567 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1568 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1569 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1570 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1571 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1572 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1573 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1574 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1575 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1576 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1577 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1578 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1579 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1580 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1581 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1582 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1583 146, 114, 165, 204, 71, 136, 41, 252] 1585 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1586 this value (with line breaks for display purposes only): 1588 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1589 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1590 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1591 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1592 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1593 -B3oWh2TbqmScqXMR4gp_A 1595 A.2.4. Initialization Vector 1597 Generate a random 128 bit JWE Initialization Vector. In this 1598 example, the value is: 1600 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1601 101] 1603 Encoding this JWE Initialization Vector as BASE64URL(JWE 1604 Initialization Vector) gives this value: 1606 AxY8DCtDaGlsbGljb3RoZQ 1608 A.2.5. Additional Authenticated Data 1610 Let the Additional Authenticated Data encryption parameter be 1611 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1613 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1614 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1615 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1616 50, 73, 110, 48] 1618 A.2.6. Content Encryption 1620 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1621 the encryption key, the JWE Initialization Vector, and the Additional 1622 Authenticated Data value above. The steps for doing this using the 1623 values from Appendix A.3 are detailed in Appendix B. The resulting 1624 Ciphertext is: 1626 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1627 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1628 112, 56, 102] 1630 The resulting Authentication Tag value is: 1632 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1633 191] 1635 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1636 value: 1638 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1640 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1641 Tag) gives this value: 1643 9hH0vgRfYgPnAHOd8stkvw 1645 A.2.7. Complete Representation 1647 Assemble the final representation: The Compact Serialization of this 1648 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1649 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1650 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1651 Authentication Tag). 1653 The final result in this example (with line breaks for display 1654 purposes only) is: 1656 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1657 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1658 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1659 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1660 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1661 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1662 -B3oWh2TbqmScqXMR4gp_A. 1663 AxY8DCtDaGlsbGljb3RoZQ. 1664 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1665 9hH0vgRfYgPnAHOd8stkvw 1667 A.2.8. Validation 1669 This example illustrates the process of creating a JWE with RSAES- 1670 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1671 encryption. These results can be used to validate JWE decryption 1672 implementations for these algorithms. Note that since the RSAES- 1673 PKCS1-V1_5 computation includes random values, the encryption results 1674 above will not be completely reproducible. However, since the AES 1675 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1676 will be the same for all encryptions performed using these inputs. 1678 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1680 This example encrypts the plaintext "Live long and prosper." to the 1681 recipient using AES Key Wrap for key encryption and 1682 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1683 of this plaintext (using JSON array notation) is: 1685 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1686 112, 114, 111, 115, 112, 101, 114, 46] 1688 A.3.1. JOSE Header 1690 The following example JWE Protected Header declares that: 1692 o the Content Encryption Key is encrypted to the recipient using the 1693 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1694 Encrypted Key and 1696 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1697 algorithm to produce the Ciphertext. 1699 {"alg":"A128KW","enc":"A128CBC-HS256"} 1701 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1702 Header)) gives this value: 1704 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1706 A.3.2. Content Encryption Key (CEK) 1708 Generate a 256 bit random Content Encryption Key (CEK). In this 1709 example, the value is: 1711 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1712 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1713 44, 207] 1715 A.3.3. Key Encryption 1717 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1718 algorithm to produce the JWE Encrypted Key. This example uses the 1719 symmetric key represented in JSON Web Key [JWK] format below: 1721 {"kty":"oct", 1722 "k":"GawgguFyGrWKav7AX4VKUg" 1723 } 1725 The resulting JWE Encrypted Key value is: 1727 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1728 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1729 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1731 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1732 this value: 1734 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1736 A.3.4. Initialization Vector 1738 Generate a random 128 bit JWE Initialization Vector. In this 1739 example, the value is: 1741 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1742 101] 1744 Encoding this JWE Initialization Vector as BASE64URL(JWE 1745 Initialization Vector) gives this value: 1747 AxY8DCtDaGlsbGljb3RoZQ 1749 A.3.5. Additional Authenticated Data 1751 Let the Additional Authenticated Data encryption parameter be 1752 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1754 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1755 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1756 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1757 110, 48] 1759 A.3.6. Content Encryption 1761 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1762 the encryption key, the JWE Initialization Vector, and the Additional 1763 Authenticated Data value above. The steps for doing this using the 1764 values from this example are detailed in Appendix B. The resulting 1765 Ciphertext is: 1767 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1768 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1769 112, 56, 102] 1771 The resulting Authentication Tag value is: 1773 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1774 194, 85] 1776 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1777 value: 1779 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1781 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1782 Tag) gives this value: 1784 U0m_YmjN04DJvceFICbCVQ 1786 A.3.7. Complete Representation 1788 Assemble the final representation: The Compact Serialization of this 1789 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1790 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1791 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1792 Authentication Tag). 1794 The final result in this example (with line breaks for display 1795 purposes only) is: 1797 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1798 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1799 AxY8DCtDaGlsbGljb3RoZQ. 1800 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1801 U0m_YmjN04DJvceFICbCVQ 1803 A.3.8. Validation 1805 This example illustrates the process of creating a JWE with AES Key 1806 Wrap for key encryption and AES GCM for content encryption. These 1807 results can be used to validate JWE decryption implementations for 1808 these algorithms. Also, since both the AES Key Wrap and AES GCM 1809 computations are deterministic, the resulting JWE value will be the 1810 same for all encryptions performed using these inputs. Since the 1811 computation is reproducible, these results can also be used to 1812 validate JWE encryption implementations for these algorithms. 1814 A.4. Example JWE using JWE JSON Serialization 1816 This section contains an example using the JWE JSON Serialization. 1817 This example demonstrates the capability for encrypting the same 1818 plaintext to multiple recipients. 1820 Two recipients are present in this example. The algorithm and key 1821 used for the first recipient are the same as that used in 1822 Appendix A.2. The algorithm and key used for the second recipient 1823 are the same as that used in Appendix A.3. The resulting JWE 1824 Encrypted Key values are therefore the same; those computations are 1825 not repeated here. 1827 The Plaintext, the Content Encryption Key (CEK), JWE Initialization 1828 Vector, and JWE Protected Header are shared by all recipients (which 1829 must be the case, since the Ciphertext and Authentication Tag are 1830 also shared). 1832 A.4.1. JWE Per-Recipient Unprotected Headers 1834 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1835 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1836 encrypt the CEK. Key ID values are supplied for both keys. The two 1837 per-recipient header values used to represent these algorithms and 1838 Key IDs are: 1840 {"alg":"RSA1_5","kid":"2011-04-29"} 1842 and 1844 {"alg":"A128KW","kid":"7"} 1846 A.4.2. JWE Protected Header 1848 The Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1849 algorithm to produce the common JWE Ciphertext and JWE Authentication 1850 Tag values. The JWE Protected Header value representing this is: 1852 {"enc":"A128CBC-HS256"} 1854 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1855 Header)) gives this value: 1857 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1859 A.4.3. JWE Unprotected Header 1861 This JWE uses the "jku" Header Parameter to reference a JWK Set. This 1862 is represented in the following JWE Unprotected Header value as: 1864 {"jku":"https://server.example.com/keys.jwks"} 1866 A.4.4. Complete JOSE Header Values 1868 Combining the per-recipient, protected, and unprotected header values 1869 supplied, the JOSE Header values used for the first and second 1870 recipient respectively are: 1872 {"alg":"RSA1_5", 1873 "kid":"2011-04-29", 1874 "enc":"A128CBC-HS256", 1875 "jku":"https://server.example.com/keys.jwks"} 1877 and 1879 {"alg":"A128KW", 1880 "kid":"7", 1881 "enc":"A128CBC-HS256", 1882 "jku":"https://server.example.com/keys.jwks"} 1884 A.4.5. Additional Authenticated Data 1886 Let the Additional Authenticated Data encryption parameter be 1887 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1889 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1890 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1892 A.4.6. Content Encryption 1894 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1895 the encryption key, the JWE Initialization Vector, and the Additional 1896 Authenticated Data value above. The steps for doing this using the 1897 values from Appendix A.3 are detailed in Appendix B. The resulting 1898 Ciphertext is: 1900 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1901 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1902 112, 56, 102] 1904 The resulting Authentication Tag value is: 1906 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1907 207] 1909 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1910 value: 1912 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1914 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1915 Tag) gives this value: 1917 Mz-VPPyU4RlcuYv1IwIvzw 1919 A.4.7. Complete JWE JSON Serialization Representation 1921 The complete JSON Web Encryption JSON Serialization for these values 1922 is as follows (with line breaks within values for display purposes 1923 only): 1925 {"protected": 1926 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1927 "unprotected": 1928 {"jku":"https://server.example.com/keys.jwks"}, 1929 "recipients":[ 1930 {"header": 1931 {"alg":"RSA1_5","kid":"2011-04-29"}, 1932 "encrypted_key": 1933 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1934 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1935 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 1936 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 1937 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 1938 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 1939 {"header": 1940 {"alg":"A128KW","kid":"7"}, 1941 "encrypted_key": 1942 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1943 "iv": 1944 "AxY8DCtDaGlsbGljb3RoZQ", 1945 "ciphertext": 1946 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1947 "tag": 1948 "Mz-VPPyU4RlcuYv1IwIvzw" 1949 } 1951 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 1953 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 1954 authenticated encryption computation using the values from the 1955 example in Appendix A.3. As described where this algorithm is 1956 defined in Sections 5.2 and 5.2.3 of JWA, the AES_CBC_HMAC_SHA2 1957 family of algorithms are implemented using Advanced Encryption 1958 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #7 1959 padding to perform the encryption and an HMAC SHA-2 function to 1960 perform the integrity calculation - in this case, HMAC SHA-256. 1962 B.1. Extract MAC_KEY and ENC_KEY from Key 1964 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example 1965 (using JSON array notation) is: 1967 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1968 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1969 44, 207] 1971 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 1972 which is: 1974 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1975 206] 1977 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 1978 is: 1980 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 1981 207] 1983 Note that the MAC key comes before the encryption key in the input 1984 key K; this is in the opposite order of the algorithm names in the 1985 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 1987 B.2. Encrypt Plaintext to Create Ciphertext 1989 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 1990 using PKCS #7 padding using the ENC_KEY above. The Plaintext in this 1991 example is: 1993 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1994 112, 114, 111, 115, 112, 101, 114, 46] 1996 The encryption result is as follows, which is the Ciphertext output: 1998 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1999 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 2000 112, 56, 102] 2002 B.3. 64 Bit Big Endian Representation of AAD Length 2004 The Additional Authenticated Data (AAD) in this example is: 2006 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2007 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2008 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2009 110, 48] 2011 This AAD is 51 bytes long, which is 408 bits long. The octet string 2012 AL, which is the number of bits in AAD expressed as a big endian 64 2013 bit unsigned integer is: 2015 [0, 0, 0, 0, 0, 0, 1, 152] 2017 B.4. Initialization Vector Value 2019 The Initialization Vector value used in this example is: 2021 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 2022 101] 2024 B.5. Create Input to HMAC Computation 2026 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 2027 the AL value. The result of this concatenation is: 2029 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2030 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2031 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2032 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 2033 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 2034 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 2035 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 2037 B.6. Compute HMAC Value 2039 Compute the HMAC SHA-256 of the concatenated value above. This 2040 result M is: 2042 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2043 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 2044 86, 229, 116] 2046 B.7. Truncate HMAC Value to Create Authentication Tag 2048 Use the first half (128 bits) of the HMAC output M as the 2049 Authentication Tag output T. This truncated value is: 2051 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2052 194, 85] 2054 Appendix C. Acknowledgements 2056 Solutions for encrypting JSON content were also explored by JSON 2057 Simple Encryption [JSE] and JavaScript Message Security Format 2058 [I-D.rescorla-jsms], both of which significantly influenced this 2059 draft. This draft attempts to explicitly reuse as many of the 2060 relevant concepts from XML Encryption 1.1 2061 [W3C.REC-xmlenc-core1-20130411] and RFC 5652 [RFC5652] as possible, 2062 while utilizing simple, compact JSON-based data structures. 2064 Special thanks are due to John Bradley, Eric Rescorla, and Nat 2065 Sakimura for the discussions that helped inform the content of this 2066 specification, to Eric Rescorla and Joe Hildebrand for allowing the 2067 reuse of text from [I-D.rescorla-jsms] in this document, and to Eric 2068 Rescorla for co-authoring many drafts of this specification. 2070 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2071 Jay for validating the examples in this specification. 2073 This specification is the work of the JOSE Working Group, which 2074 includes dozens of active and dedicated participants. In particular, 2075 the following individuals contributed ideas, feedback, and wording 2076 that influenced this specification: 2078 Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick 2079 Hardt, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Kathleen 2080 Moriarty, Tony Nadalin, Hideki Nara, Axel Nennker, Emmanuel Raviart, 2081 Eric Rescorla, Nat Sakimura, Jim Schaad, Hannes Tschofenig, and Sean 2082 Turner. 2084 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2085 Sean Turner, Stephen Farrell, and Kathleen Moriarty served as 2086 Security area directors during the creation of this specification. 2088 Appendix D. Document History 2090 [[ to be removed by the RFC Editor before publication as an RFC ]] 2092 -32 2094 o Addressed Gen-ART review comments by Russ Housley. 2096 o Addressed secdir review comments by Scott Kelly, Tero Kivinen, and 2097 Stephen Kent. 2099 -31 2101 o Updated the reference to draft-mcgrew-aead-aes-cbc-hmac-sha2. 2103 -30 2105 o Added subsection headings within the Overview section for the two 2106 serializations. 2108 o Added references and cleaned up the reference syntax in a few 2109 places. 2111 o Applied minor wording changes to the Security Considerations 2112 section and made other local editorial improvements. 2114 -29 2116 o Replaced the terms JWS Header, JWE Header, and JWT Header with a 2117 single JOSE Header term defined in the JWS specification. This 2118 also enabled a single Header Parameter definition to be used and 2119 reduced other areas of duplication between specifications. 2121 -28 2123 o Specified the use of PKCS #7 padding with AES CBC, rather than 2124 PKCS #5. (PKCS #7 is a superset of PKCS #5, and is appropriate 2125 for the 16 octet blocks used by AES CBC.) 2127 o Revised the introduction to the Security Considerations section. 2128 Also moved a security consideration item here from the JWA draft. 2130 -27 2132 o Described additional security considerations. 2134 o Added the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) header 2135 parameter. 2137 -26 2139 o Noted that octet sequences are depicted using JSON array notation. 2141 o Updated references, including to W3C specifications. 2143 -25 2145 o Corrected two external section number references that had changed. 2147 o Corrected a typo in an algorithm name in the prose of an example. 2149 -24 2151 o Corrected complete JSON Serialization example. 2153 o Replaced uses of the term "associated data" wherever it was used 2154 to refer to a data value with "additional authenticated data", 2155 since both terms were being used as synonyms, causing confusion. 2157 o Updated the JSON reference to RFC 7159. 2159 o Thanked Eric Rescorla for helping to author of most of the drafts 2160 of this specification and removed him from the current author 2161 list. 2163 -23 2165 o Corrected a use of the word "payload" to "plaintext". 2167 -22 2169 o Corrected RFC 2119 terminology usage. 2171 o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. 2173 -21 2175 o Changed some references from being normative to informative, 2176 addressing issue #90. 2178 o Applied review comments to the JSON Serialization section, 2179 addressing issue #178. 2181 -20 2183 o Made terminology definitions more consistent, addressing issue 2184 #165. 2186 o Restructured the JSON Serialization section to call out the 2187 parameters used in hanging lists, addressing issue #178. 2189 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 2190 addressing issue #90. 2192 -19 2194 o Reordered the key selection parameters. 2196 -18 2198 o Updated the mandatory-to-implement (MTI) language to say that 2199 applications using this specification need to specify what 2200 serialization and serialization features are used for that 2201 application, addressing issue #176. 2203 o Changes to address editorial and minor issues #89, #135, #165, 2204 #174, #175, #177, #179, and #180. 2206 o Used Header Parameter Description registry field. 2208 -17 2210 o Refined the "typ" and "cty" definitions to always be MIME Media 2211 Types, with the omission of "application/" prefixes recommended 2212 for brevity, addressing issue #50. 2214 o Updated the mandatory-to-implement (MTI) language to say that 2215 general-purpose implementations must implement the single 2216 recipient case for both serializations whereas special-purpose 2217 implementations can implement just one serialization if that meets 2218 the needs of the use cases the implementation is designed for, 2219 addressing issue #176. 2221 o Explicitly named all the logical components of a JWE and defined 2222 the processing rules and serializations in terms of those 2223 components, addressing issues #60, #61, and #62. 2225 o Replaced verbose repetitive phases such as "base64url encode the 2226 octets of the UTF-8 representation of X" with mathematical 2227 notation such as "BASE64URL(UTF8(X))". 2229 o Header Parameters and processing rules occurring in both JWS and 2230 JWE are now referenced in JWS by JWE, rather than duplicated, 2231 addressing issue #57. 2233 o Terms used in multiple documents are now defined in one place and 2234 incorporated by reference. Some lightly used or obvious terms 2235 were also removed. This addresses issue #58. 2237 -16 2239 o Changes to address editorial and minor issues #163, #168, #169, 2240 #170, #172, and #173. 2242 -15 2244 o Clarified that it is an application decision which recipients' 2245 encrypted content must successfully validate for the JWE to be 2246 accepted, addressing issue #35. 2248 o Changes to address editorial issues #34, #164, and #169. 2250 -14 2252 o Clarified that the "protected", "unprotected", "header", "iv", 2253 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2254 JSON Serialization when their values would be empty. Stated that 2255 the "recipients" array must always be present. 2257 -13 2259 o Added an "aad" (Additional Authenticated Data) member for the JWE 2260 JSON Serialization, enabling Additional Authenticated Data to be 2261 supplied that is not double base64url encoded, addressing issue 2262 #29. 2264 -12 2266 o Clarified that the "typ" and "cty" header parameters are used in 2267 an application-specific manner and have no effect upon the JWE 2268 processing. 2270 o Replaced the MIME types "application/jwe+json" and 2271 "application/jwe" with "application/jose+json" and 2272 "application/jose". 2274 o Stated that recipients MUST either reject JWEs with duplicate 2275 Header Parameter Names or use a JSON parser that returns only the 2276 lexically last duplicate member name. 2278 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2279 be with the algorithm descriptions that use them. 2281 o Added a Serializations section with parallel treatment of the JWE 2282 Compact Serialization and the JWE JSON Serialization and also 2283 moved the former Implementation Considerations content there. 2285 o Restored use of the term "AEAD". 2287 o Changed terminology from "block encryption" to "content 2288 encryption". 2290 -11 2292 o Added Key Identification section. 2294 o Removed the Encrypted Key value from the AAD computation since it 2295 is already effectively integrity protected by the encryption 2296 process. The AAD value now only contains the representation of 2297 the JWE Encrypted Header. 2299 o For the JWE JSON Serialization, enable Header Parameter values to 2300 be specified in any of three parameters: the "protected" member 2301 that is integrity protected and shared among all recipients, the 2302 "unprotected" member that is not integrity protected and shared 2303 among all recipients, and the "header" member that is not 2304 integrity protected and specific to a particular recipient. (This 2305 does not affect the JWE Compact Serialization, in which all Header 2306 Parameter values are in a single integrity protected JWE Header 2307 value.) 2309 o Shortened the names "authentication_tag" to "tag" and 2310 "initialization_vector" to "iv" in the JWE JSON Serialization, 2311 addressing issue #20. 2313 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2315 o Removed suggested compact serialization for multiple recipients. 2317 o Changed the MIME type name "application/jwe-js" to 2318 "application/jwe+json", addressing issue #22. 2320 o Tightened the description of the "crit" (critical) header 2321 parameter. 2323 -10 2325 o Changed the JWE processing rules for multiple recipients so that a 2326 single AAD value contains the header parameters and encrypted key 2327 values for all the recipients, enabling AES GCM to be safely used 2328 for multiple recipients. 2330 o Added an appendix suggesting a possible compact serialization for 2331 JWEs with multiple recipients. 2333 -09 2335 o Added JWE JSON Serialization, as specified by 2336 draft-jones-jose-jwe-json-serialization-04. 2338 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2339 parameter value. 2341 o Defined that the default action for header parameters that are not 2342 understood is to ignore them unless specifically designated as 2343 "MUST be understood" or included in the new "crit" (critical) 2344 header parameter list. This addressed issue #6. 2346 o Corrected "x5c" description. This addressed issue #12. 2348 o Changed from using the term "byte" to "octet" when referring to 8 2349 bit values. 2351 o Added Key Management Mode definitions to terminology section and 2352 used the defined terms to provide clearer key management 2353 instructions. This addressed issue #5. 2355 o Added text about preventing the recipient from behaving as an 2356 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2358 o Changed from using the term "Integrity Value" to "Authentication 2359 Tag". 2361 o Changed member name from "integrity_value" to "authentication_tag" 2362 in the JWE JSON Serialization. 2364 o Removed Initialization Vector from the AAD value since it is 2365 already integrity protected by all of the authenticated encryption 2366 algorithms specified in the JWA specification. 2368 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2369 and "A256CBC-HS512". The new algorithms perform the same 2370 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2371 but with the Initialization Vector and Authentication Tag values 2372 remaining separate from the Ciphertext value in the output 2373 representation. Also deleted the header parameters "epu" 2374 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2375 they are no longer used. 2377 -08 2379 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2380 since the term AEAD in the RFC 5116 sense implied the use of a 2381 particular data representation, rather than just referring to the 2382 class of algorithms that perform authenticated encryption with 2383 associated data. 2385 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2386 Tschofenig. Many of these simplified the terminology used. 2388 o Clarified statements of the form "This header parameter is 2389 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2391 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2392 Web Signature and Encryption Header Parameters registry. 2394 o Added seriesInfo information to Internet Draft references. 2396 -07 2397 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2399 o Updated values for example AES CBC calculations. 2401 o Made several local editorial changes to clean up loose ends left 2402 over from to the decision to only support block encryption methods 2403 providing integrity. One of these changes was to explicitly state 2404 that the "enc" (encryption method) algorithm must be an 2405 Authenticated Encryption algorithm with a specified key length. 2407 -06 2409 o Removed the "int" and "kdf" parameters and defined the new 2410 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2411 "A256CBC+HS512" to replace the former uses of AES CBC, which 2412 required the use of separate integrity and key derivation 2413 functions. 2415 o Included additional values in the Concat KDF calculation -- the 2416 desired output size and the algorithm value, and optionally 2417 PartyUInfo and PartyVInfo values. Added the optional header 2418 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2419 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2420 PartyVInfo). Updated the KDF examples accordingly. 2422 o Promoted Initialization Vector from being a header parameter to 2423 being a top-level JWE element. This saves approximately 16 bytes 2424 in the compact serialization, which is a significant savings for 2425 some use cases. Promoting the Initialization Vector out of the 2426 header also avoids repeating this shared value in the JSON 2427 serialization. 2429 o Changed "x5c" (X.509 Certificate Chain) representation from being 2430 a single string to being an array of strings, each containing a 2431 single base64 encoded DER certificate value, representing elements 2432 of the certificate chain. 2434 o Added an AES Key Wrap example. 2436 o Reordered the encryption steps so CMK creation is first, when 2437 required. 2439 o Correct statements in examples about which algorithms produce 2440 reproducible results. 2442 -05 2443 o Support both direct encryption using a shared or agreed upon 2444 symmetric key, and the use of a shared or agreed upon symmetric 2445 key to key wrap the CMK. 2447 o Added statement that "StringOrURI values are compared as case- 2448 sensitive strings with no transformations or canonicalizations 2449 applied". 2451 o Updated open issues. 2453 o Indented artwork elements to better distinguish them from the body 2454 text. 2456 -04 2458 o Refer to the registries as the primary sources of defined values 2459 and then secondarily reference the sections defining the initial 2460 contents of the registries. 2462 o Normatively reference XML Encryption 1.1 for its security 2463 considerations. 2465 o Reference draft-jones-jose-jwe-json-serialization instead of 2466 draft-jones-json-web-encryption-json-serialization. 2468 o Described additional open issues. 2470 o Applied editorial suggestions. 2472 -03 2474 o Added the "kdf" (key derivation function) header parameter to 2475 provide crypto agility for key derivation. The default KDF 2476 remains the Concat KDF with the SHA-256 digest function. 2478 o Reordered encryption steps so that the Encoded JWE Header is 2479 always created before it is needed as an input to the 2480 Authenticated Encryption "additional authenticated data" 2481 parameter. 2483 o Added the "cty" (content type) header parameter for declaring type 2484 information about the secured content, as opposed to the "typ" 2485 (type) header parameter, which declares type information about 2486 this object. 2488 o Moved description of how to determine whether a header is for a 2489 JWS or a JWE from the JWT spec to the JWE spec. 2491 o Added complete encryption examples for both Authenticated 2492 Encryption and non-Authenticated Encryption algorithms. 2494 o Added complete key derivation examples. 2496 o Added "Collision Resistant Namespace" to the terminology section. 2498 o Reference ITU.X690.1994 for DER encoding. 2500 o Added Registry Contents sections to populate registry values. 2502 o Numerous editorial improvements. 2504 -02 2506 o When using Authenticated Encryption algorithms (such as AES GCM), 2507 use the "additional authenticated data" parameter to provide 2508 integrity for the header, encrypted key, and ciphertext and use 2509 the resulting "authentication tag" value as the JWE Authentication 2510 Tag. 2512 o Defined KDF output key sizes. 2514 o Generalized text to allow key agreement to be employed as an 2515 alternative to key wrapping or key encryption. 2517 o Changed compression algorithm from gzip to DEFLATE. 2519 o Clarified that it is an error when a "kid" value is included and 2520 no matching key is found. 2522 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2523 rejected. 2525 o Clarified the relationship between "typ" header parameter values 2526 and MIME types. 2528 o Registered application/jwe MIME type and "JWE" typ header 2529 parameter value. 2531 o Simplified JWK terminology to get replace the "JWK Key Object" and 2532 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2533 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2534 between single keys and sets of keys. As part of this change, the 2535 Header Parameter Name for a public key value was changed from 2536 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2538 o Added suggestion on defining additional header parameters such as 2539 "x5t#S256" in the future for certificate thumbprints using hash 2540 algorithms other than SHA-1. 2542 o Specify RFC 2818 server identity validation, rather than RFC 6125 2543 (paralleling the same decision in the OAuth specs). 2545 o Generalized language to refer to Message Authentication Codes 2546 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2547 unless in a context specific to HMAC algorithms. 2549 o Reformatted to give each header parameter its own section heading. 2551 -01 2553 o Added an integrity check for non-Authenticated Encryption 2554 algorithms. 2556 o Added "jpk" and "x5c" header parameters for including JWK public 2557 keys and X.509 certificate chains directly in the header. 2559 o Clarified that this specification is defining the JWE Compact 2560 Serialization. Referenced the new JWE-JS spec, which defines the 2561 JWE JSON Serialization. 2563 o Added text "New header parameters should be introduced sparingly 2564 since an implementation that does not understand a parameter MUST 2565 reject the JWE". 2567 o Clarified that the order of the encryption and decryption steps is 2568 not significant in cases where there are no dependencies between 2569 the inputs and outputs of the steps. 2571 o Made other editorial improvements suggested by JOSE working group 2572 participants. 2574 -00 2576 o Created the initial IETF draft based upon 2577 draft-jones-json-web-encryption-02 with no normative changes. 2579 o Changed terminology to no longer call both digital signatures and 2580 HMACs "signatures". 2582 Authors' Addresses 2584 Michael B. Jones 2585 Microsoft 2587 Email: mbj@microsoft.com 2588 URI: http://self-issued.info/ 2590 Joe Hildebrand 2591 Cisco Systems, Inc. 2593 Email: jhildebr@cisco.com