idnits 2.17.1 draft-ietf-jose-json-web-encryption-35.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 (October 17, 2014) is 3478 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 1436 -- Looks like a reference, but probably isn't: '197' on line 1436 -- Looks like a reference, but probably isn't: '117' on line 1436 -- Looks like a reference, but probably isn't: '252' on line 1436 -- Looks like a reference, but probably isn't: '2' on line 1436 -- Looks like a reference, but probably isn't: '219' on line 1436 -- Looks like a reference, but probably isn't: '233' on line 1436 -- Looks like a reference, but probably isn't: '68' on line 1436 -- Looks like a reference, but probably isn't: '180' on line 1436 -- Looks like a reference, but probably isn't: '225' on line 1436 -- Looks like a reference, but probably isn't: '77' on line 1436 -- Looks like a reference, but probably isn't: '0' on line 2031 -- Looks like a reference, but probably isn't: '1' on line 2031 -- Looks like a reference, but probably isn't: '152' on line 2031 == Unused Reference: 'AES' is defined on line 1285, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 17 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: April 20, 2015 Cisco 6 October 17, 2014 8 JSON Web Encryption (JWE) 9 draft-ietf-jose-json-web-encryption-35 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 April 20, 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 . . . . . . . . . . . . . . . . . . 21 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 . . . . . . . . . . . . . . . . . . . . . . 27 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 . . . . . . . . . 30 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 . . . . . . . . . . . . . . . . 36 120 A.2.5. Additional Authenticated Data . . . . . . . . . . . . 36 121 A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 36 122 A.2.7. Complete Representation . . . . . . . . . . . . . . . 37 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 . . . . . . . . . . . . . . . . . . . . . 38 127 A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 38 128 A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 38 129 A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 39 130 A.3.5. Additional Authenticated Data . . . . . . . . . . . . 39 131 A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 39 132 A.3.7. Complete Representation . . . . . . . . . . . . . . . 40 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 . . . . . . . . 41 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 . . . . . . . . . . . . 42 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 . . . . . . . . . . . . . . . . . . . . . . . . 57 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 of [JWS]. 191 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 192 of STRING. 194 ASCII(STRING) denotes the octets of the ASCII [RFC20] representation 195 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 defined by the Internet Security Glossary, Version 2 207 [RFC4949] are incorporated into this specification: "Ciphertext", 208 "Digital Signature", "Message Authentication Code (MAC)", and 209 "Plaintext". 211 These terms are defined by this specification: 213 JSON Web Encryption (JWE) 214 A data structure representing an encrypted and integrity protected 215 message. 217 Authenticated Encryption with Associated Data (AEAD) 218 An AEAD algorithm is one that encrypts the Plaintext, allows 219 Additional Authenticated Data to be specified, and provides an 220 integrated content integrity check over the Ciphertext and 221 Additional Authenticated Data. AEAD algorithms accept two inputs, 222 the Plaintext and the Additional Authenticated Data value, and 223 produce two outputs, the Ciphertext and the Authentication Tag 224 value. AES Galois/Counter Mode (GCM) is one such algorithm. 226 Additional Authenticated Data (AAD) 227 An input to an AEAD operation that is integrity protected but not 228 encrypted. 230 Authentication Tag 231 An output of an AEAD operation that ensures the integrity of the 232 Ciphertext and the Additional Authenticated Data. Note that some 233 algorithms may not use an Authentication Tag, in which case this 234 value is the empty octet sequence. 236 Content Encryption Key (CEK) 237 A symmetric key for the AEAD algorithm used to encrypt the 238 Plaintext to produce the Ciphertext and the Authentication Tag. 240 JWE Encrypted Key 241 Encrypted Content Encryption Key (CEK) value. Note that for some 242 algorithms, the JWE Encrypted Key value is specified as being the 243 empty octet sequence. 245 JWE Initialization Vector 246 Initialization vector value used when encrypting the plaintext. 247 Note that some algorithms may not use an Initialization Vector, in 248 which case this value is the empty octet sequence. 250 JWE AAD 251 Additional value to be integrity protected by the authenticated 252 encryption operation. This can only be present when using the JWE 253 JSON Serialization. (Note that this can also be achieved when 254 using either serialization by including the AAD value as an 255 integrity protected Header Parameter value, but at the cost of the 256 value being double base64url encoded.) 258 JWE Ciphertext 259 Ciphertext value resulting from authenticated encryption of the 260 plaintext with additional authenticated data. 262 JWE Authentication Tag 263 Authentication Tag value resulting from authenticated encryption 264 of the plaintext with additional authenticated data. 266 JWE Protected Header 267 JSON object that contains the Header Parameters that are integrity 268 protected by the authenticated encryption operation. These 269 parameters apply to all recipients of the JWE. For the JWE 270 Compact Serialization, this comprises the entire JOSE Header. For 271 the JWE JSON Serialization, this is one component of the JOSE 272 Header. 274 JWE Shared Unprotected Header 275 JSON object that contains the Header Parameters that apply to all 276 recipients of the JWE that are not integrity protected. This can 277 only be present when using the JWE JSON Serialization. 279 JWE Per-Recipient Unprotected Header 280 JSON object that contains Header Parameters that apply to a single 281 recipient of the JWE. These Header Parameter values are not 282 integrity protected. This can only be present when using the JWE 283 JSON Serialization. 285 JWE Compact Serialization 286 A representation of the JWE as a compact, URL-safe string. 288 JWE JSON Serialization 289 A representation of the JWE as a JSON object. The JWE JSON 290 Serialization enables the same content to be encrypted to multiple 291 parties. This representation is neither optimized for compactness 292 nor URL-safe. 294 Key Management Mode 295 A method of determining the Content Encryption Key (CEK) value to 296 use. Each algorithm used for determining the CEK value uses a 297 specific Key Management Mode. Key Management Modes employed by 298 this specification are Key Encryption, Key Wrapping, Direct Key 299 Agreement, Key Agreement with Key Wrapping, and Direct Encryption. 301 Key Encryption 302 A Key Management Mode in which the Content Encryption Key (CEK) 303 value is encrypted to the intended recipient using an asymmetric 304 encryption algorithm. 306 Key Wrapping 307 A Key Management Mode in which the Content Encryption Key (CEK) 308 value is encrypted to the intended recipient using a symmetric key 309 wrapping algorithm. 311 Direct Key Agreement 312 A Key Management Mode in which a key agreement algorithm is used 313 to agree upon the Content Encryption Key (CEK) value. 315 Key Agreement with Key Wrapping 316 A Key Management Mode in which a key agreement algorithm is used 317 to agree upon a symmetric key used to encrypt the Content 318 Encryption Key (CEK) value to the intended recipient using a 319 symmetric key wrapping algorithm. 321 Direct Encryption 322 A Key Management Mode in which the Content Encryption Key (CEK) 323 value used is the secret symmetric key value shared between the 324 parties. 326 3. JSON Web Encryption (JWE) Overview 328 JWE represents encrypted content using JSON data structures and 329 base64url encoding. These JSON data structures MAY contain white 330 space and/or line breaks. A JWE represents these logical values 331 (each of which is defined in Section 2): 333 o JOSE Header 334 o JWE Encrypted Key 335 o JWE Initialization Vector 336 o JWE AAD 337 o JWE Ciphertext 338 o JWE Authentication Tag 340 For a JWE object, the JOSE Header members are the union of the 341 members of these values (each of which is defined in Section 2): 343 o JWE Protected Header 344 o JWE Shared Unprotected Header 345 o JWE Per-Recipient Unprotected Header 347 JWE utilizes authenticated encryption to ensure the confidentiality 348 and integrity of the Plaintext and the integrity of the JWE Protected 349 Header and the JWE AAD. 351 This document defines two serializations for JWE objects: a compact, 352 URL-safe serialization called the JWE Compact Serialization and a 353 JSON serialization called the JWE JSON Serialization. In both 354 serializations, the JWE Protected Header, JWE Encrypted Key, JWE 355 Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are 356 base64url encoded, since JSON lacks a way to directly represent 357 arbitrary octet sequences. When present, the JWE AAD is also 358 base64url encoded. 360 3.1. JWE Compact Serialization Overview 362 In the JWE Compact Serialization, no JWE Shared Unprotected Header or 363 JWE Per-Recipient Unprotected Header are used. In this case, the 364 JOSE Header and the JWE Protected Header are the same. 366 In the JWE Compact Serialization, a JWE object is represented as the 367 concatenation: 369 BASE64URL(UTF8(JWE Protected Header)) || '.' || 370 BASE64URL(JWE Encrypted Key) || '.' || 371 BASE64URL(JWE Initialization Vector) || '.' || 372 BASE64URL(JWE Ciphertext) || '.' || 373 BASE64URL(JWE Authentication Tag) 375 See Section 7.1 for more information about the JWE Compact 376 Serialization. 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 union of the members of the JWE Protected Header, 384 JWE Shared Unprotected Header, and JWE Per-Recipient Unprotected 385 Header values that are present. 387 In the JWE JSON Serialization, a JWE object is represented as the 388 combination of these eight values: 390 BASE64URL(UTF8(JWE Protected Header)) 391 JWE Shared Unprotected Header 392 JWE Per-Recipient Unprotected Header 393 BASE64URL(JWE Encrypted Key) 394 BASE64URL(JWE Initialization Vector) 395 BASE64URL(JWE Ciphertext) 396 BASE64URL(JWE Authentication Tag) 397 BASE64URL(JWE AAD) 399 The six base64url encoded result strings and the two unprotected JSON 400 object values are represented as members within a JSON object. The 401 inclusion of some of these values is OPTIONAL. The JWE JSON 402 Serialization can also encrypt the plaintext to multiple recipients. 403 See Section 7.2 for more information about the JWE JSON 404 Serialization. 406 3.3. Example JWE 408 This example encrypts the plaintext "The true sign of intelligence is 409 not knowledge but imagination." to the recipient. 411 The following example JWE Protected Header declares that: 413 o The Content Encryption Key is encrypted to the recipient using the 414 RSAES OAEP [RFC3447] algorithm to produce the JWE Encrypted Key. 416 o Authenticated encryption is performed on the Plaintext using the 417 AES GCM [AES, NIST.800-38D] algorithm with a 256 bit key to 418 produce the Ciphertext and the Authentication Tag. 420 {"alg":"RSA-OAEP","enc":"A256GCM"} 422 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 423 Header)) gives this value: 425 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 427 The remaining steps to finish creating this JWE are: 428 o Generate a random Content Encryption Key (CEK). 429 o Encrypt the CEK with the recipient's public key using the RSAES 430 OAEP algorithm to produce the JWE Encrypted Key. 431 o Base64url encode the JWE Encrypted Key. 432 o Generate a random JWE Initialization Vector. 433 o Base64url encode the JWE Initialization Vector. 434 o Let the Additional Authenticated Data encryption parameter be 435 ASCII(BASE64URL(UTF8(JWE Protected Header))). 437 o Perform authenticated encryption on the Plaintext with the AES GCM 438 algorithm using the CEK as the encryption key, the JWE 439 Initialization Vector, and the Additional Authenticated Data 440 value, requesting a 128 bit Authentication Tag output. 441 o Base64url encode the Ciphertext. 442 o Base64url encode the Authentication Tag. 443 o Assemble the final representation: The Compact Serialization of 444 this result is the string BASE64URL(UTF8(JWE Protected Header)) || 445 '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE 446 Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' 447 || BASE64URL(JWE Authentication Tag). 449 The final result in this example (with line breaks for display 450 purposes only) is: 452 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 453 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 454 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 455 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 456 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 457 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 458 6UklfCpIMfIjf7iGdXKHzg. 459 48V1_ALb6US04U3b. 460 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 461 SdiwkIr3ajwQzaBtQD_A. 462 XFBoMYUZodetZdvTiFvSkQ 464 See Appendix A.1 for the complete details of computing this JWE. See 465 other parts of Appendix A for additional examples, including an 466 example using the JWE JSON Serialization in Appendix A.4. 468 4. JOSE Header 470 For a JWE object, the members of the JSON object(s) representing the 471 JOSE Header describe the encryption applied to the Plaintext and 472 optionally additional properties of the JWE. The Header Parameter 473 names within the JOSE Header MUST be unique, just as described in 474 Section 4 of [JWS]. The rules about handling Header Parameters that 475 are not understood by the implementation are also the same. The 476 classes of Header Parameter names are likewise the same. 478 4.1. Registered Header Parameter Names 480 The following Header Parameter names for use in JWE objects are 481 registered in the IANA JSON Web Signature and Encryption Header 482 Parameters registry defined in [JWS], with meanings as defined below. 484 As indicated by the common registry, JWSs and JWEs share a common 485 Header Parameter space; when a parameter is used by both 486 specifications, its usage must be compatible between the 487 specifications. 489 4.1.1. "alg" (Algorithm) Header Parameter 491 This parameter has the same meaning, syntax, and processing rules as 492 the "alg" Header Parameter defined in Section 4.1.1 of [JWS], except 493 that the Header Parameter identifies the cryptographic algorithm used 494 to encrypt or determine the value of the Content Encryption Key 495 (CEK). The encrypted content is not usable if the "alg" value does 496 not represent a supported algorithm, or if the recipient does not 497 have a key that can be used with that algorithm. 499 A list of defined "alg" values for this use can be found in the IANA 500 JSON Web Signature and Encryption Algorithms registry defined in 501 [JWA]; the initial contents of this registry are the values defined 502 in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. 504 4.1.2. "enc" (Encryption Algorithm) Header Parameter 506 The "enc" (encryption algorithm) Header Parameter identifies the 507 content encryption algorithm used to perform authenticated encryption 508 on the Plaintext to produce the Ciphertext and the Authentication 509 Tag. This algorithm MUST be an AEAD algorithm with a specified key 510 length. The recipient MUST reject the JWE if the "enc" value does 511 not represent a supported algorithm. "enc" values should either be 512 registered in the IANA JSON Web Signature and Encryption Algorithms 513 registry defined in [JWA] or be a value that contains a Collision- 514 Resistant Name. The "enc" value is a case-sensitive string 515 containing a StringOrURI value. This Header Parameter MUST be 516 present and MUST be understood and processed by implementations. 518 A list of defined "enc" values for this use can be found in the IANA 519 JSON Web Signature and Encryption Algorithms registry defined in 520 [JWA]; the initial contents of this registry are the values defined 521 in Section 5.1 of the JSON Web Algorithms (JWA) [JWA] specification. 523 4.1.3. "zip" (Compression Algorithm) Header Parameter 525 The "zip" (compression algorithm) applied to the Plaintext before 526 encryption, if any. The "zip" value defined by this specification 527 is: 529 o "DEF" - Compression with the DEFLATE [RFC1951] algorithm 531 Other values MAY be used. Compression algorithm values can be 532 registered in the IANA JSON Web Encryption Compression Algorithm 533 registry defined in [JWA]. The "zip" value is a case-sensitive 534 string. If no "zip" parameter is present, no compression is applied 535 to the Plaintext before encryption. When used, this Header Parameter 536 MUST be integrity protected; therefore, it MUST occur only within the 537 JWE Protected Header. Use of this Header Parameter is OPTIONAL. 538 This Header Parameter MUST be understood and processed by 539 implementations. 541 4.1.4. "jku" (JWK Set URL) Header Parameter 543 This parameter has the same meaning, syntax, and processing rules as 544 the "jku" Header Parameter defined in Section 4.1.2 of [JWS], except 545 that the JWK Set resource contains the public key to which the JWE 546 was encrypted; this can be used to determine the private key needed 547 to decrypt the JWE. 549 4.1.5. "jwk" (JSON Web Key) Header Parameter 551 This parameter has the same meaning, syntax, and processing rules as 552 the "jwk" Header Parameter defined in Section 4.1.3 of [JWS], except 553 that the key is the public key to which the JWE was encrypted; this 554 can be used to determine the private key needed to decrypt the JWE. 556 4.1.6. "kid" (Key ID) Header Parameter 558 This parameter has the same meaning, syntax, and processing rules as 559 the "kid" Header Parameter defined in Section 4.1.4 of [JWS], except 560 that the key hint references the public key to which the JWE was 561 encrypted; this can be used to determine the private key needed to 562 decrypt the JWE. This parameter allows originators to explicitly 563 signal a change of key to JWE recipients. 565 4.1.7. "x5u" (X.509 URL) Header Parameter 567 This parameter has the same meaning, syntax, and processing rules as 568 the "x5u" Header Parameter defined in Section 4.1.5 of [JWS], except 569 that the X.509 public key certificate or certificate chain [RFC5280] 570 contains the public key to which the JWE was encrypted; this can be 571 used to determine the private key needed to decrypt the JWE. 573 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 575 This parameter has the same meaning, syntax, and processing rules as 576 the "x5c" Header Parameter defined in Section 4.1.6 of [JWS], except 577 that the X.509 public key certificate or certificate chain [RFC5280] 578 contains the public key to which the JWE was encrypted; this can be 579 used to determine the private key needed to decrypt the JWE. 581 See Appendix B of [JWS] for an example "x5c" value. 583 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 585 This parameter has the same meaning, syntax, and processing rules as 586 the "x5t" Header Parameter defined in Section 4.1.7 of [JWS], except 587 that the certificate referenced by the thumbprint contains the public 588 key to which the JWE was encrypted; this can be used to determine the 589 private key needed to decrypt the JWE. Note that certificate 590 thumbprints are also sometimes known as certificate fingerprints. 592 4.1.10. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header 593 Parameter 595 This parameter has the same meaning, syntax, and processing rules as 596 the "x5t#S256" Header Parameter defined in Section 4.1.8 of [JWS], 597 except that the certificate referenced by the thumbprint contains the 598 public key to which the JWE was encrypted; this can be used to 599 determine the private key needed to decrypt the JWE. Note that 600 certificate thumbprints are also sometimes known as certificate 601 fingerprints. 603 4.1.11. "typ" (Type) Header Parameter 605 This parameter has the same meaning, syntax, and processing rules as 606 the "typ" Header Parameter defined in Section 4.1.9 of [JWS], except 607 that the type is that of this complete JWE object. 609 4.1.12. "cty" (Content Type) Header Parameter 611 This parameter has the same meaning, syntax, and processing rules as 612 the "cty" Header Parameter defined in Section 4.1.10 of [JWS], except 613 that the type is that of the secured content (the plaintext). 615 4.1.13. "crit" (Critical) Header Parameter 617 This parameter has the same meaning, syntax, and processing rules as 618 the "crit" Header Parameter defined in Section 4.1.11 of [JWS], 619 except that Header Parameters for a JWE object are being referred to, 620 rather than Header Parameters for a JWS object. 622 4.2. Public Header Parameter Names 624 Additional Header Parameter names can be defined by those using JWEs. 625 However, in order to prevent collisions, any new Header Parameter 626 name should either be registered in the IANA JSON Web Signature and 627 Encryption Header Parameters registry defined in [JWS] or be a Public 628 Name: a value that contains a Collision-Resistant Name. In each 629 case, the definer of the name or value needs to take reasonable 630 precautions to make sure they are in control of the part of the 631 namespace they use to define the Header Parameter name. 633 New Header Parameters should be introduced sparingly, as they can 634 result in non-interoperable JWEs. 636 4.3. Private Header Parameter Names 638 A producer and consumer of a JWE may agree to use Header Parameter 639 names that are Private Names: names that are not Registered Header 640 Parameter names Section 4.1 or Public Header Parameter names 641 Section 4.2. Unlike Public Header Parameter names, Private Header 642 Parameter names are subject to collision and should be used with 643 caution. 645 5. Producing and Consuming JWEs 647 5.1. Message Encryption 649 The message encryption process is as follows. The order of the steps 650 is not significant in cases where there are no dependencies between 651 the inputs and outputs of the steps. 653 1. Determine the Key Management Mode employed by the algorithm used 654 to determine the Content Encryption Key (CEK) value. (This is 655 the algorithm recorded in the "alg" (algorithm) Header Parameter 656 of the resulting JWE.) 658 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 659 Wrapping are employed, generate a random Content Encryption Key 660 (CEK) value. See RFC 4086 [RFC4086] for considerations on 661 generating random values. The CEK MUST have a length equal to 662 that required for the content encryption algorithm. 664 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 665 employed, use the key agreement algorithm to compute the value 666 of the agreed upon key. When Direct Key Agreement is employed, 667 let the Content Encryption Key (CEK) be the agreed upon key. 668 When Key Agreement with Key Wrapping is employed, the agreed 669 upon key will be used to wrap the CEK. 671 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 672 Wrapping are employed, encrypt the CEK to the recipient and let 673 the result be the JWE Encrypted Key. 675 5. When Direct Key Agreement or Direct Encryption are employed, let 676 the JWE Encrypted Key be the empty octet sequence. 678 6. When Direct Encryption is employed, let the Content Encryption 679 Key (CEK) be the shared symmetric key. 681 7. Compute the encoded key value BASE64URL(JWE Encrypted Key). 683 8. If the JWE JSON Serialization is being used, repeat this process 684 (steps 1-7) for each recipient. 686 9. Generate a random JWE Initialization Vector of the correct size 687 for the content encryption algorithm (if required for the 688 algorithm); otherwise, let the JWE Initialization Vector be the 689 empty octet sequence. 691 10. Compute the encoded initialization vector value BASE64URL(JWE 692 Initialization Vector). 694 11. If a "zip" parameter was included, compress the Plaintext using 695 the specified compression algorithm and let M be the octet 696 sequence representing the compressed Plaintext; otherwise, let M 697 be the octet sequence representing the Plaintext. 699 12. Create the JSON object(s) containing the desired set of Header 700 Parameters, which together comprise the JOSE Header: if the JWE 701 Compact Serialization is being used, the JWE Protected Header, 702 or if the JWE JSON Serialization is being used, one or more of 703 the JWE Protected Header, the JWE Shared Unprotected Header, and 704 the JWE Per-Recipient Unprotected Header. 706 13. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 707 Protected Header)). If the JWE Protected Header is not present 708 (which can only happen when using the JWE JSON Serialization and 709 no "protected" member is present), let this value be the empty 710 string. 712 14. Let the Additional Authenticated Data encryption parameter be 713 ASCII(Encoded Protected Header). However if a JWE AAD value is 714 present (which can only be the case when using the JWE JSON 715 Serialization), instead let the Additional Authenticated Data 716 encryption parameter be ASCII(Encoded Protected Header || '.' || 717 BASE64URL(JWE AAD)). 719 15. Encrypt M using the CEK, the JWE Initialization Vector, and the 720 Additional Authenticated Data value using the specified content 721 encryption algorithm to create the JWE Ciphertext value and the 722 JWE Authentication Tag (which is the Authentication Tag output 723 from the encryption operation). 725 16. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext). 727 17. Compute the encoded authentication tag value BASE64URL(JWE 728 Authentication Tag). 730 18. If a JWE AAD value is present, compute the encoded AAD value 731 BASE64URL(JWE AAD). 733 19. Create the desired serialized output. The Compact Serialization 734 of this result is the string BASE64URL(UTF8(JWE Protected 735 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 736 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 737 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). The 738 JWE JSON Serialization is described in Section 7.2. 740 5.2. Message Decryption 742 The message decryption process is the reverse of the encryption 743 process. The order of the steps is not significant in cases where 744 there are no dependencies between the inputs and outputs of the 745 steps. If any of these steps fails, the encrypted content cannot be 746 validated. 748 When there are multiple recipients, it is an application decision 749 which of the recipients' encrypted content must successfully validate 750 for the JWE to be accepted. In some cases, encrypted content for all 751 recipients must successfully validate or the JWE will be rejected. 752 In other cases, only the encrypted content for a single recipient 753 needs to be successfully validated. However, in all cases, the 754 encrypted content for at least one recipient MUST successfully 755 validate or the JWE MUST be rejected. 757 1. Parse the JWE representation to extract the serialized values 758 for the components of the JWE. When using the JWE Compact 759 Serialization, these components are the base64url encoded 760 representations of the JWE Protected Header, the JWE Encrypted 761 Key, the JWE Initialization Vector, the JWE Ciphertext, and the 762 JWE Authentication Tag, and when using the JWE JSON 763 Serialization, these components also include the base64url 764 encoded representation of the JWE AAD and the unencoded JWE 765 Shared Unprotected Header and JWE Per-Recipient Unprotected 766 Header values. When using the JWE Compact Serialization, the 767 JWE Protected Header, the JWE Encrypted Key, the JWE 768 Initialization Vector, the JWE Ciphertext, and the JWE 769 Authentication Tag are represented as base64url encoded values 770 in that order, with each value being separated from the next by 771 a single period ('.') character, resulting in exactly four 772 delimiting period characters being used. The JWE JSON 773 Serialization is described in Section 7.2. 775 2. Base64url decode the encoded representations of the JWE 776 Protected Header, the JWE Encrypted Key, the JWE Initialization 777 Vector, the JWE Ciphertext, the JWE Authentication Tag, and the 778 JWE AAD, following the restriction that no line breaks, white 779 space, or other additional characters have been used. 781 3. Verify that the octet sequence resulting from decoding the 782 encoded JWE Protected Header is a UTF-8 encoded representation 783 of a completely valid JSON object conforming to RFC 7159 784 [RFC7159]; let the JWE Protected Header be this JSON object. 786 4. If using the JWE Compact Serialization, let the JOSE Header be 787 the JWE Protected Header. Otherwise, when using the JWE JSON 788 Serialization, let the JOSE Header be the union of the members 789 of the JWE Protected Header, the JWE Shared Unprotected Header 790 and the corresponding JWE Per-Recipient Unprotected Header, all 791 of which must be completely valid JSON objects. During this 792 step, verify that the resulting JOSE Header does not contain 793 duplicate Header Parameter names. When using the JWE JSON 794 Serialization, this restriction includes that the same Header 795 Parameter name also MUST NOT occur in distinct JSON object 796 values that together comprise the JOSE Header. 798 5. Verify that the implementation understands and can process all 799 fields that it is required to support, whether required by this 800 specification, by the algorithms being used, or by the "crit" 801 Header Parameter value, and that the values of those parameters 802 are also understood and supported. 804 6. Determine the Key Management Mode employed by the algorithm 805 specified by the "alg" (algorithm) Header Parameter. 807 7. Verify that the JWE uses a key known to the recipient. 809 8. When Direct Key Agreement or Key Agreement with Key Wrapping are 810 employed, use the key agreement algorithm to compute the value 811 of the agreed upon key. When Direct Key Agreement is employed, 812 let the Content Encryption Key (CEK) be the agreed upon key. 813 When Key Agreement with Key Wrapping is employed, the agreed 814 upon key will be used to decrypt the JWE Encrypted Key. 816 9. When Key Wrapping, Key Encryption, or Key Agreement with Key 817 Wrapping are employed, decrypt the JWE Encrypted Key to produce 818 the Content Encryption Key (CEK). The CEK MUST have a length 819 equal to that required for the content encryption algorithm. 820 Note that when there are multiple recipients, each recipient 821 will only be able decrypt any JWE Encrypted Key values that were 822 encrypted to a key in that recipient's possession. It is 823 therefore normal to only be able to decrypt one of the per- 824 recipient JWE Encrypted Key values to obtain the CEK value. 825 Also, see Section 11.5 for security considerations on mitigating 826 timing attacks. 828 10. When Direct Key Agreement or Direct Encryption are employed, 829 verify that the JWE Encrypted Key value is empty octet sequence. 831 11. When Direct Encryption is employed, let the Content Encryption 832 Key (CEK) be the shared symmetric key. 834 12. Record whether the CEK could be successfully determined for this 835 recipient or not. 837 13. If the JWE JSON Serialization is being used, repeat this process 838 (steps 4-12) for each recipient contained in the representation. 840 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 841 Protected Header)). If the JWE Protected Header is not present 842 (which can only happen when using the JWE JSON Serialization and 843 no "protected" member is present), let this value be the empty 844 string. 846 15. Let the Additional Authenticated Data encryption parameter be 847 ASCII(Encoded Protected Header). However if a JWE AAD value is 848 present (which can only be the case when using the JWE JSON 849 Serialization), instead let the Additional Authenticated Data 850 encryption parameter be ASCII(Encoded Protected Header || '.' || 851 BASE64URL(JWE AAD)). 853 16. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 854 Vector, the Additional Authenticated Data value, and the JWE 855 Authentication Tag (which is the Authentication Tag input to the 856 calculation) using the specified content encryption algorithm, 857 returning the decrypted plaintext and validating the JWE 858 Authentication Tag in the manner specified for the algorithm, 859 rejecting the input without emitting any decrypted output if the 860 JWE Authentication Tag is incorrect. 862 17. If a "zip" parameter was included, uncompress the decrypted 863 plaintext using the specified compression algorithm. 865 18. If there was no recipient for which all of the decryption steps 866 succeeded, then the JWE MUST be rejected. Otherwise, output the 867 Plaintext. In the JWE JSON Serialization case, also return a 868 result to the application indicating for which of the recipients 869 the decryption succeeded and failed. 871 Finally, note that it is an application decision which algorithms may 872 be used in a given context. Even if a JWE can be successfully 873 decrypted, unless the algorithms used in the JWE are acceptable to 874 the application, it SHOULD reject the JWE. 876 5.3. String Comparison Rules 878 The string comparison rules for this specification are the same as 879 those defined in Section 5.3 of [JWS]. 881 6. Key Identification 883 The key identification methods for this specification are the same as 884 those defined in Section 6 of [JWS], except that the key being 885 identified is the public key to which the JWE was encrypted. 887 7. Serializations 889 JWE objects use one of two serializations, the JWE Compact 890 Serialization or the JWE JSON Serialization. Applications using this 891 specification need to specify what serialization and serialization 892 features are used for that application. For instance, applications 893 might specify that only the JWE JSON Serialization is used, that only 894 JWE JSON Serialization support for a single recipient is used, or 895 that support for multiple recipients is used. JWE implementations 896 only need to implement the features needed for the applications they 897 are designed to support. 899 7.1. JWE Compact Serialization 901 The JWE Compact Serialization represents encrypted content as a 902 compact, URL-safe string. This string is: 904 BASE64URL(UTF8(JWE Protected Header)) || '.' || 905 BASE64URL(JWE Encrypted Key) || '.' || 906 BASE64URL(JWE Initialization Vector) || '.' || 907 BASE64URL(JWE Ciphertext) || '.' || 908 BASE64URL(JWE Authentication Tag) 910 Only one recipient is supported by the JWE Compact Serialization and 911 it provides no syntax to represent JWE Shared Unprotected Header, JWE 912 Per-Recipient Unprotected Header, or JWE AAD values. 914 7.2. JWE JSON Serialization 916 The JWE JSON Serialization represents encrypted content as a JSON 917 object. Content using the JWE JSON Serialization can be encrypted to 918 more than one recipient. This representation is neither optimized 919 for compactness nor URL-safe. 921 The following members are defined for use in top-level JSON objects 922 used for the JWE JSON Serialization: 924 protected 925 The "protected" member MUST be present and contain the value 926 BASE64URL(UTF8(JWE Protected Header)) when the JWE Protected 927 Header value is non-empty; otherwise, it MUST be absent. These 928 Header Parameter values are integrity protected. 930 unprotected 931 The "unprotected" member MUST be present and contain the value JWE 932 Shared Unprotected Header when the JWE Shared Unprotected Header 933 value is non-empty; otherwise, it MUST be absent. This value is 934 represented as an unencoded JSON object, rather than as a string. 935 These Header Parameter values are not integrity protected. 937 iv 938 The "iv" member MUST be present and contain the value 939 BASE64URL(JWE Initialization Vector) when the JWE Initialization 940 Vector value is non-empty; otherwise, it MUST be absent. 942 aad 943 The "aad" member MUST be present and contain the value 944 BASE64URL(JWE AAD)) when the JWE AAD value is non-empty; 945 otherwise, it MUST be absent. A JWE AAD value can be included to 946 supply a base64url encoded value to be integrity protected but not 947 encrypted. 949 ciphertext 950 The "ciphertext" member MUST be present and contain the value 951 BASE64URL(JWE Ciphertext). 953 tag 954 The "tag" member MUST be present and contain the value 955 BASE64URL(JWE Authentication Tag) when the JWE Authentication Tag 956 value is non-empty; otherwise, it MUST be absent. 958 recipients 959 The "recipients" member value MUST be an array of JSON objects. 960 Each object contains information specific to a single recipient. 961 This member MUST be present with exactly one array element per 962 recipient, even if some or all of the array element values are the 963 empty JSON object "{}" (which can happen when all Header Parameter 964 values are shared between all recipients and when no encrypted key 965 is used, such as when doing Direct Encryption). 967 The following members are defined for use in the JSON objects that 968 are elements of the "recipients" array: 970 header 971 The "header" member MUST be present and contain the value JWE Per- 972 Recipient Unprotected Header when the JWE Per-Recipient 973 Unprotected Header value is non-empty; otherwise, it MUST be 974 absent. This value is represented as an unencoded JSON object, 975 rather than as a string. These Header Parameter values are not 976 integrity protected. 978 encrypted_key 979 The "encrypted_key" member MUST be present and contain the value 980 BASE64URL(JWE Encrypted Key) when the JWE Encrypted Key value is 981 non-empty; otherwise, it MUST be absent. 983 At least one of the "header", "protected", and "unprotected" members 984 MUST be present so that "alg" and "enc" Header Parameter values are 985 conveyed for each recipient computation. 987 Additional members can be present in both the JSON objects defined 988 above; if not understood by implementations encountering them, they 989 MUST be ignored. 991 Some Header Parameters, including the "alg" parameter, can be shared 992 among all recipient computations. Header Parameters in the JWE 993 Protected Header and JWE Shared Unprotected Header values are shared 994 among all recipients. 996 The Header Parameter values used when creating or validating per- 997 recipient Ciphertext and Authentication Tag values are the union of 998 the three sets of Header Parameter values that may be present: (1) 999 the JWE Protected Header represented in the "protected" member, (2) 1000 the JWE Shared Unprotected Header represented in the "unprotected" 1001 member, and (3) the JWE Per-Recipient Unprotected Header represented 1002 in the "header" member of the recipient's array element. The union 1003 of these sets of Header Parameters comprises the JOSE Header. The 1004 Header Parameter names in the three locations MUST be disjoint. 1006 Each JWE Encrypted Key value is computed using the parameters of the 1007 corresponding JOSE Header value in the same manner as for the JWE 1008 Compact Serialization. This has the desirable property that each JWE 1009 Encrypted Key value in the "recipients" array is identical to the 1010 value that would have been computed for the same parameter in the JWE 1011 Compact Serialization. Likewise, the JWE Ciphertext and JWE 1012 Authentication Tag values match those produced for the JWE Compact 1013 Serialization, provided that the JWE Protected Header value (which 1014 represents the integrity-protected Header Parameter values) matches 1015 that used in the JWE Compact Serialization. 1017 All recipients use the same JWE Protected Header, JWE Initialization 1018 Vector, JWE Ciphertext, and JWE Authentication Tag values, when 1019 present, resulting in potentially significant space savings if the 1020 message is large. Therefore, all Header Parameters that specify the 1021 treatment of the Plaintext value MUST be the same for all recipients. 1022 This primarily means that the "enc" (encryption algorithm) Header 1023 Parameter value in the JOSE Header for each recipient and any 1024 parameters of that algorithm MUST be the same. 1026 In summary, the syntax of a JWE using the JWE JSON Serialization is 1027 as follows: 1029 {"protected":"", 1030 "unprotected":, 1031 "recipients":[ 1032 {"header":, 1033 "encrypted_key":""}, 1034 ... 1035 {"header":, 1036 "encrypted_key":""}], 1037 "aad":"", 1038 "iv":"", 1039 "ciphertext":"", 1040 "tag":"" 1041 } 1043 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1044 Serialization. 1046 8. TLS Requirements 1048 The TLS requirements for this specification are the same as those 1049 defined in Section 8 of [JWS]. 1051 9. Distinguishing between JWS and JWE Objects 1053 There are several ways of distinguishing whether an object is a JWS 1054 or JWE object. All these methods will yield the same result for all 1055 legal input values; they may yield different results for malformed 1056 inputs. 1058 o If the object is using the JWS Compact Serialization or the JWE 1059 Compact Serialization, the number of base64url encoded segments 1060 separated by period ('.') characters differs for JWSs and JWEs. 1061 JWSs have three segments separated by two period ('.') characters. 1062 JWEs have five segments separated by four period ('.') characters. 1064 o If the object is using the JWS JSON Serialization or the JWE JSON 1065 Serialization, the members used will be different. JWSs have a 1066 "signatures" member and JWEs do not. JWEs have a "recipients" 1067 member and JWSs do not. 1069 o The JOSE Header for a JWS object can be distinguished from the 1070 JOSE Header for a JWE object by examining the "alg" (algorithm) 1071 Header Parameter value. If the value represents a digital 1072 signature or MAC algorithm, or is the value "none", it is for a 1073 JWS; if it represents a Key Encryption, Key Wrapping, Direct Key 1074 Agreement, Key Agreement with Key Wrapping, or Direct Encryption 1075 algorithm, it is for a JWE. (Extracting the "alg" value to 1076 examine is straightforward when using the JWS Compact 1077 Serialization or the JWE Compact Serialization and may be more 1078 difficult when using the JWS JSON Serialization or the JWE JSON 1079 Serialization.) 1081 o The JOSE Header for a JWS object can also be distinguished from 1082 the JOSE Header for a JWE object by determining whether an "enc" 1083 (encryption algorithm) member exists. If the "enc" member exists, 1084 it is a JWE; otherwise, it is a JWS. 1086 10. IANA Considerations 1088 10.1. JSON Web Signature and Encryption Header Parameters Registration 1090 This specification registers the Header Parameter names defined in 1091 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1092 Parameters registry defined in [JWS]. 1094 10.1.1. Registry Contents 1096 o Header Parameter Name: "alg" 1097 o Header Parameter Description: Algorithm 1098 o Header Parameter Usage Location(s): JWE 1099 o Change Controller: IESG 1100 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1101 o Header Parameter Name: "enc" 1102 o Header Parameter Description: Encryption Algorithm 1103 o Header Parameter Usage Location(s): JWE 1104 o Change Controller: IESG 1105 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1107 o Header Parameter Name: "zip" 1108 o Header Parameter Description: Compression Algorithm 1109 o Header Parameter Usage Location(s): JWE 1110 o Change Controller: IESG 1111 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1113 o Header Parameter Name: "jku" 1114 o Header Parameter Description: JWK Set URL 1115 o Header Parameter Usage Location(s): JWE 1116 o Change Controller: IESG 1117 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1119 o Header Parameter Name: "jwk" 1120 o Header Parameter Description: JSON Web Key 1121 o Header Parameter Usage Location(s): JWE 1122 o Change Controller: IESG 1123 o Specification document(s): Section 4.1.5 of [[ this document ]] 1125 o Header Parameter Name: "kid" 1126 o Header Parameter Description: Key ID 1127 o Header Parameter Usage Location(s): JWE 1128 o Change Controller: IESG 1129 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1131 o Header Parameter Name: "x5u" 1132 o Header Parameter Description: X.509 URL 1133 o Header Parameter Usage Location(s): JWE 1134 o Change Controller: IESG 1135 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1137 o Header Parameter Name: "x5c" 1138 o Header Parameter Description: X.509 Certificate Chain 1139 o Header Parameter Usage Location(s): JWE 1140 o Change Controller: IESG 1141 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1143 o Header Parameter Name: "x5t" 1144 o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint 1145 o Header Parameter Usage Location(s): JWE 1146 o Change Controller: IESG 1147 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1149 o Header Parameter Name: "x5t#S256" 1150 o Header Parameter Description: X.509 Certificate SHA-256 Thumbprint 1151 o Header Parameter Usage Location(s): JWE 1152 o Change Controller: IESG 1153 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1155 o Header Parameter Name: "typ" 1156 o Header Parameter Description: Type 1157 o Header Parameter Usage Location(s): JWE 1158 o Change Controller: IESG 1159 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1161 o Header Parameter Name: "cty" 1162 o Header Parameter Description: Content Type 1163 o Header Parameter Usage Location(s): JWE 1164 o Change Controller: IESG 1165 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1167 o Header Parameter Name: "crit" 1168 o Header Parameter Description: Critical 1169 o Header Parameter Usage Location(s): JWE 1170 o Change Controller: IESG 1171 o Specification Document(s): Section 4.1.13 of [[ this document ]] 1173 11. Security Considerations 1175 All of the security issues that are pertinent to any cryptographic 1176 application must be addressed by JWS/JWE/JWK agents. Among these 1177 issues are protecting the user's asymmetric private and symmetric 1178 secret keys and employing countermeasures to various attacks. 1180 All the security considerations in the JWS specification also apply 1181 to this specification. Likewise, all the security considerations in 1182 XML Encryption 1.1 [W3C.REC-xmlenc-core1-20130411] also apply, other 1183 than those that are XML specific. 1185 11.1. Key Entropy and Random Values 1187 See Section 10.1 of [JWS] for security considerations on key entropy 1188 and random values. In addition to the uses of random values listed 1189 there, note that random values are also used for content encryption 1190 keys (CEKs) and initialization vectors (IVs) when performing 1191 encryption. 1193 11.2. Key Protection 1195 See Section 10.2 of [JWS] for security considerations on key 1196 protection. In addition to the keys listed there that must be 1197 protected, implementations performing encryption must protect the key 1198 encryption key and the content encryption key. Compromise of the key 1199 encryption key may result in the disclosure of all contents protected 1200 with that key. Similarly, compromise of the content encryption key 1201 may result in disclosure of the associated encrypted content. 1203 11.3. Using Matching Algorithm Strengths 1205 Algorithms of matching strengths should be used together whenever 1206 possible. For instance, when AES Key Wrap is used with a given key 1207 size, using the same key size is recommended when AES GCM is also 1208 used. If the key encryption and content encryption algorithms are 1209 different, the effective security is determined by the weaker of the 1210 two algorithms. 1212 Also, see RFC 3766 [RFC3766] for information on determining strengths 1213 for public keys used for exchanging symmetric keys. 1215 11.4. Adaptive Chosen-Ciphertext Attacks 1217 When decrypting, particular care must be taken not to allow the JWE 1218 recipient to be used as an oracle for decrypting messages. RFC 3218 1219 [RFC3218] should be consulted for specific countermeasures to attacks 1220 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1221 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1222 formatting error that can be detected and used to recover the CEK 1223 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1224 particularly important to report all formatting errors to the CEK, 1225 Additional Authenticated Data, or ciphertext as a single error when 1226 the encrypted content is rejected. 1228 Additionally, this type of attack can be prevented by restricting the 1229 use of a key to a limited set of algorithms -- usually one. This 1230 means, for instance, that if the key is marked as being for 1231 "RSA-OAEP" only, any attempt to decrypt a message using the "RSA1_5" 1232 algorithm with that key should fail immediately due to invalid use of 1233 the key. 1235 11.5. Timing Attacks 1237 To mitigate the attacks described in RFC 3218 [RFC3218], the 1238 recipient MUST NOT distinguish between format, padding, and length 1239 errors of encrypted keys. It is strongly recommended, in the event 1240 of receiving an improperly formatted key, that the recipient 1241 substitute a randomly generated CEK and proceed to the next step, to 1242 mitigate timing attacks. 1244 12. References 1246 12.1. Normative References 1248 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1249 draft-ietf-jose-json-web-algorithms (work in progress), 1250 October 2014. 1252 [JWK] Jones, M., "JSON Web Key (JWK)", 1253 draft-ietf-jose-json-web-key (work in progress), 1254 October 2014. 1256 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1257 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1258 in progress), October 2014. 1260 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1261 version 1.3", RFC 1951, May 1996. 1263 [RFC20] Cerf, V., "ASCII format for Network Interchange", RFC 20, 1264 October 1969. 1266 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1267 Requirement Levels", BCP 14, RFC 2119, March 1997. 1269 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1270 10646", STD 63, RFC 3629, November 2003. 1272 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 1273 RFC 4949, August 2007. 1275 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1276 Housley, R., and W. Polk, "Internet X.509 Public Key 1277 Infrastructure Certificate and Certificate Revocation List 1278 (CRL) Profile", RFC 5280, May 2008. 1280 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1281 Interchange Format", RFC 7159, March 2014. 1283 12.2. Informative References 1285 [AES] National Institute of Standards and Technology (NIST), 1286 "Advanced Encryption Standard (AES)", FIPS PUB 197, 1287 November 2001. 1289 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1290 McGrew, D., Foley, J., and K. Paterson, "Authenticated 1291 Encryption with AES-CBC and HMAC-SHA", 1292 draft-mcgrew-aead-aes-cbc-hmac-sha2-05 (work in progress), 1293 July 2014. 1295 [I-D.rescorla-jsms] 1296 Rescorla, E. and J. Hildebrand, "JavaScript Message 1297 Security Format", draft-rescorla-jsms-00 (work in 1298 progress), March 2011. 1300 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1301 Encryption", September 2010. 1303 [NIST.800-38D] 1304 National Institute of Standards and Technology (NIST), 1305 "Recommendation for Block Cipher Modes of Operation: 1306 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 1307 December 2001. 1309 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1310 Cryptographic Message Syntax", RFC 3218, January 2002. 1312 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1313 Standards (PKCS) #1: RSA Cryptography Specifications 1314 Version 2.1", RFC 3447, February 2003. 1316 [RFC3766] Orman, H. and P. Hoffman, "Determining Strengths For 1317 Public Keys Used For Exchanging Symmetric Keys", BCP 86, 1318 RFC 3766, April 2004. 1320 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1321 Requirements for Security", BCP 106, RFC 4086, June 2005. 1323 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1324 RFC 5652, September 2009. 1326 [W3C.REC-xmlenc-core1-20130411] 1327 Eastlake, D., Reagle, J., Hirsch, F., and T. Roessler, 1328 "XML Encryption Syntax and Processing Version 1.1", World 1329 Wide Web Consortium Recommendation REC-xmlenc-core1- 1330 20130411, April 2013, 1331 . 1333 Appendix A. JWE Examples 1335 This section provides examples of JWE computations. 1337 A.1. Example JWE using RSAES OAEP and AES GCM 1339 This example encrypts the plaintext "The true sign of intelligence is 1340 not knowledge but imagination." to the recipient using RSAES OAEP for 1341 key encryption and AES GCM for content encryption. The 1342 representation of this plaintext (using JSON array notation) is: 1344 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1345 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1346 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1347 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1348 110, 97, 116, 105, 111, 110, 46] 1350 A.1.1. JOSE Header 1352 The following example JWE Protected Header declares that: 1354 o The Content Encryption Key is encrypted to the recipient using the 1355 RSAES OAEP algorithm to produce the JWE Encrypted Key. 1357 o Authenticated encryption is performed on the Plaintext using the 1358 AES GCM algorithm with a 256 bit key to produce the Ciphertext and 1359 the Authentication Tag. 1361 {"alg":"RSA-OAEP","enc":"A256GCM"} 1363 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1364 Header)) gives this value: 1366 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1368 A.1.2. Content Encryption Key (CEK) 1370 Generate a 256 bit random Content Encryption Key (CEK). In this 1371 example, the value (using JSON array notation) is: 1373 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1374 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1375 234, 64, 252] 1377 A.1.3. Key Encryption 1379 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1380 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1381 key represented in JSON Web Key [JWK] format below (with line breaks 1382 within values for display purposes only): 1384 {"kty":"RSA", 1385 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1386 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1387 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1388 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1389 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1390 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1391 "e":"AQAB", 1392 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1393 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1394 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1395 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1396 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1397 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ" 1398 } 1400 The resulting JWE Encrypted Key value is: 1402 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1403 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1404 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1405 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1406 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1407 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1408 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1409 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1410 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1411 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1412 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1413 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1414 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1415 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1416 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1417 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1418 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1419 117, 114, 135, 206] 1421 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1422 this value (with line breaks for display purposes only): 1424 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1425 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1426 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1427 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1428 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1429 6UklfCpIMfIjf7iGdXKHzg 1431 A.1.4. Initialization Vector 1433 Generate a random 96 bit JWE Initialization Vector. In this example, 1434 the value is: 1436 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1438 Encoding this JWE Initialization Vector as BASE64URL(JWE 1439 Initialization Vector) gives this value: 1441 48V1_ALb6US04U3b 1443 A.1.5. Additional Authenticated Data 1445 Let the Additional Authenticated Data encryption parameter be 1446 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1448 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1449 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1450 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1452 A.1.6. Content Encryption 1454 Perform authenticated encryption on the Plaintext with the AES GCM 1455 algorithm using the CEK as the encryption key, the JWE Initialization 1456 Vector, and the Additional Authenticated Data value above, requesting 1457 a 128 bit Authentication Tag output. The resulting Ciphertext is: 1459 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1460 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1461 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1462 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1463 160, 109, 64, 63, 192] 1465 The resulting Authentication Tag value is: 1467 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1468 210, 145] 1470 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1471 value (with line breaks for display purposes only): 1473 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1474 SdiwkIr3ajwQzaBtQD_A 1476 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1477 Tag) gives this value: 1479 XFBoMYUZodetZdvTiFvSkQ 1481 A.1.7. Complete Representation 1483 Assemble the final representation: The Compact Serialization of this 1484 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1485 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1486 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1487 Authentication Tag). 1489 The final result in this example (with line breaks for display 1490 purposes only) is: 1492 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1493 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1494 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1495 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1496 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1497 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1498 6UklfCpIMfIjf7iGdXKHzg. 1499 48V1_ALb6US04U3b. 1500 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1501 SdiwkIr3ajwQzaBtQD_A. 1502 XFBoMYUZodetZdvTiFvSkQ 1504 A.1.8. Validation 1506 This example illustrates the process of creating a JWE with RSAES 1507 OAEP for key encryption and AES GCM for content encryption. These 1508 results can be used to validate JWE decryption implementations for 1509 these algorithms. Note that since the RSAES OAEP computation 1510 includes random values, the encryption results above will not be 1511 completely reproducible. However, since the AES GCM computation is 1512 deterministic, the JWE Encrypted Ciphertext values will be the same 1513 for all encryptions performed using these inputs. 1515 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1517 This example encrypts the plaintext "Live long and prosper." to the 1518 recipient using RSAES-PKCS1-V1_5 for key encryption and 1519 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1520 of this plaintext (using JSON array notation) is: 1522 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1523 112, 114, 111, 115, 112, 101, 114, 46] 1525 A.2.1. JOSE Header 1527 The following example JWE Protected Header declares that: 1529 o The Content Encryption Key is encrypted to the recipient using the 1530 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. 1532 o Authenticated encryption is performed on the Plaintext using the 1533 AES_128_CBC_HMAC_SHA_256 algorithm to produce the Ciphertext and 1534 the Authentication Tag. 1536 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1538 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1539 Header)) gives this value: 1541 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1543 A.2.2. Content Encryption Key (CEK) 1545 Generate a 256 bit random Content Encryption Key (CEK). In this 1546 example, the key value is: 1548 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1549 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1550 44, 207] 1552 A.2.3. Key Encryption 1554 Encrypt the CEK with the recipient's public key using the RSAES- 1555 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1556 uses the RSA key represented in JSON Web Key [JWK] format below (with 1557 line breaks within values for display purposes only): 1559 {"kty":"RSA", 1560 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1561 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1562 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1563 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1564 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1565 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1566 "e":"AQAB", 1567 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1568 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1569 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1570 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1571 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1572 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1573 } 1575 The resulting JWE Encrypted Key value is: 1577 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1578 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1579 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1580 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1581 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1582 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1583 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1584 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1585 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1586 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1587 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1588 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1589 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1590 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1591 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1592 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1593 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1594 146, 114, 165, 204, 71, 136, 41, 252] 1596 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1597 this value (with line breaks for display purposes only): 1599 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1600 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1601 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1602 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1603 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1604 -B3oWh2TbqmScqXMR4gp_A 1606 A.2.4. Initialization Vector 1608 Generate a random 128 bit JWE Initialization Vector. In this 1609 example, the value is: 1611 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1612 101] 1614 Encoding this JWE Initialization Vector as BASE64URL(JWE 1615 Initialization Vector) gives this value: 1617 AxY8DCtDaGlsbGljb3RoZQ 1619 A.2.5. Additional Authenticated Data 1621 Let the Additional Authenticated Data encryption parameter be 1622 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1624 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1625 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1626 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1627 50, 73, 110, 48] 1629 A.2.6. Content Encryption 1631 Perform authenticated encryption on the Plaintext with the 1632 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1633 key, the JWE Initialization Vector, and the Additional Authenticated 1634 Data value above. The steps for doing this using the values from 1635 Appendix A.3 are detailed in Appendix B. The resulting Ciphertext 1636 is: 1638 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1639 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1640 112, 56, 102] 1642 The resulting Authentication Tag value is: 1644 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1645 191] 1647 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1648 value: 1650 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1652 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1653 Tag) gives this value: 1655 9hH0vgRfYgPnAHOd8stkvw 1657 A.2.7. Complete Representation 1659 Assemble the final representation: The Compact Serialization of this 1660 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1661 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1662 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1663 Authentication Tag). 1665 The final result in this example (with line breaks for display 1666 purposes only) is: 1668 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1669 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1670 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1671 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1672 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1673 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1674 -B3oWh2TbqmScqXMR4gp_A. 1675 AxY8DCtDaGlsbGljb3RoZQ. 1676 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1677 9hH0vgRfYgPnAHOd8stkvw 1679 A.2.8. Validation 1681 This example illustrates the process of creating a JWE with RSAES- 1682 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1683 encryption. These results can be used to validate JWE decryption 1684 implementations for these algorithms. Note that since the RSAES- 1685 PKCS1-V1_5 computation includes random values, the encryption results 1686 above will not be completely reproducible. However, since the AES 1687 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1688 will be the same for all encryptions performed using these inputs. 1690 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1692 This example encrypts the plaintext "Live long and prosper." to the 1693 recipient using AES Key Wrap for key encryption and 1694 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1695 of this plaintext (using JSON array notation) is: 1697 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1698 112, 114, 111, 115, 112, 101, 114, 46] 1700 A.3.1. JOSE Header 1702 The following example JWE Protected Header declares that: 1704 o The Content Encryption Key is encrypted to the recipient using the 1705 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1706 Encrypted Key. 1708 o Authenticated encryption is performed on the Plaintext using the 1709 AES_128_CBC_HMAC_SHA_256 algorithm to produce the Ciphertext and 1710 the Authentication Tag. 1712 {"alg":"A128KW","enc":"A128CBC-HS256"} 1714 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1715 Header)) gives this value: 1717 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1719 A.3.2. Content Encryption Key (CEK) 1721 Generate a 256 bit random Content Encryption Key (CEK). In this 1722 example, the value is: 1724 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1725 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1726 44, 207] 1728 A.3.3. Key Encryption 1730 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1731 algorithm to produce the JWE Encrypted Key. This example uses the 1732 symmetric key represented in JSON Web Key [JWK] format below: 1734 {"kty":"oct", 1735 "k":"GawgguFyGrWKav7AX4VKUg" 1736 } 1738 The resulting JWE Encrypted Key value is: 1740 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1741 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1742 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1744 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1745 this value: 1747 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1749 A.3.4. Initialization Vector 1751 Generate a random 128 bit JWE Initialization Vector. In this 1752 example, the value is: 1754 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1755 101] 1757 Encoding this JWE Initialization Vector as BASE64URL(JWE 1758 Initialization Vector) gives this value: 1760 AxY8DCtDaGlsbGljb3RoZQ 1762 A.3.5. Additional Authenticated Data 1764 Let the Additional Authenticated Data encryption parameter be 1765 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1767 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1768 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1769 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1770 110, 48] 1772 A.3.6. Content Encryption 1774 Perform authenticated encryption on the Plaintext with the 1775 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1776 key, the JWE Initialization Vector, and the Additional Authenticated 1777 Data value above. The steps for doing this using the values from 1778 this example are detailed in Appendix B. The resulting Ciphertext 1779 is: 1781 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1782 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1783 112, 56, 102] 1785 The resulting Authentication Tag value is: 1787 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1788 194, 85] 1790 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1791 value: 1793 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1795 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1796 Tag) gives this value: 1798 U0m_YmjN04DJvceFICbCVQ 1800 A.3.7. Complete Representation 1802 Assemble the final representation: The Compact Serialization of this 1803 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1804 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1805 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1806 Authentication Tag). 1808 The final result in this example (with line breaks for display 1809 purposes only) is: 1811 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1812 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1813 AxY8DCtDaGlsbGljb3RoZQ. 1814 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1815 U0m_YmjN04DJvceFICbCVQ 1817 A.3.8. Validation 1819 This example illustrates the process of creating a JWE with AES Key 1820 Wrap for key encryption and AES GCM for content encryption. These 1821 results can be used to validate JWE decryption implementations for 1822 these algorithms. Also, since both the AES Key Wrap and AES GCM 1823 computations are deterministic, the resulting JWE value will be the 1824 same for all encryptions performed using these inputs. Since the 1825 computation is reproducible, these results can also be used to 1826 validate JWE encryption implementations for these algorithms. 1828 A.4. Example JWE using JWE JSON Serialization 1830 This section contains an example using the JWE JSON Serialization. 1831 This example demonstrates the capability for encrypting the same 1832 plaintext to multiple recipients. 1834 Two recipients are present in this example. The algorithm and key 1835 used for the first recipient are the same as that used in 1836 Appendix A.2. The algorithm and key used for the second recipient 1837 are the same as that used in Appendix A.3. The resulting JWE 1838 Encrypted Key values are therefore the same; those computations are 1839 not repeated here. 1841 The Plaintext, the Content Encryption Key (CEK), JWE Initialization 1842 Vector, and JWE Protected Header are shared by all recipients (which 1843 must be the case, since the Ciphertext and Authentication Tag are 1844 also shared). 1846 A.4.1. JWE Per-Recipient Unprotected Headers 1848 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1849 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1850 encrypt the CEK. Key ID values are supplied for both keys. The two 1851 per-recipient header values used to represent these algorithms and 1852 Key IDs are: 1854 {"alg":"RSA1_5","kid":"2011-04-29"} 1856 and 1858 {"alg":"A128KW","kid":"7"} 1860 A.4.2. JWE Protected Header 1862 Authenticated encryption is performed on the Plaintext using the 1863 AES_128_CBC_HMAC_SHA_256 algorithm to produce the common JWE 1864 Ciphertext and JWE Authentication Tag values. The JWE Protected 1865 Header value representing this is: 1867 {"enc":"A128CBC-HS256"} 1869 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1870 Header)) gives this value: 1872 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1874 A.4.3. JWE Unprotected Header 1876 This JWE uses the "jku" Header Parameter to reference a JWK Set. This 1877 is represented in the following JWE Unprotected Header value as: 1879 {"jku":"https://server.example.com/keys.jwks"} 1881 A.4.4. Complete JOSE Header Values 1883 Combining the per-recipient, protected, and unprotected header values 1884 supplied, the JOSE Header values used for the first and second 1885 recipient respectively are: 1887 {"alg":"RSA1_5", 1888 "kid":"2011-04-29", 1889 "enc":"A128CBC-HS256", 1890 "jku":"https://server.example.com/keys.jwks"} 1892 and 1894 {"alg":"A128KW", 1895 "kid":"7", 1896 "enc":"A128CBC-HS256", 1897 "jku":"https://server.example.com/keys.jwks"} 1899 A.4.5. Additional Authenticated Data 1901 Let the Additional Authenticated Data encryption parameter be 1902 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1904 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1905 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1907 A.4.6. Content Encryption 1909 Perform authenticated encryption on the Plaintext with the 1910 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1911 key, the JWE Initialization Vector, and the Additional Authenticated 1912 Data value above. The steps for doing this using the values from 1913 Appendix A.3 are detailed in Appendix B. The resulting Ciphertext 1914 is: 1916 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1917 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1918 112, 56, 102] 1920 The resulting Authentication Tag value is: 1922 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1923 207] 1925 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1926 value: 1928 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1930 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1931 Tag) gives this value: 1933 Mz-VPPyU4RlcuYv1IwIvzw 1935 A.4.7. Complete JWE JSON Serialization Representation 1937 The complete JSON Web Encryption JSON Serialization for these values 1938 is as follows (with line breaks within values for display purposes 1939 only): 1941 {"protected": 1942 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1943 "unprotected": 1944 {"jku":"https://server.example.com/keys.jwks"}, 1945 "recipients":[ 1946 {"header": 1947 {"alg":"RSA1_5","kid":"2011-04-29"}, 1948 "encrypted_key": 1949 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1950 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1951 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 1952 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 1953 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 1954 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 1955 {"header": 1956 {"alg":"A128KW","kid":"7"}, 1957 "encrypted_key": 1958 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1959 "iv": 1960 "AxY8DCtDaGlsbGljb3RoZQ", 1961 "ciphertext": 1962 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1963 "tag": 1964 "Mz-VPPyU4RlcuYv1IwIvzw" 1965 } 1967 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 1969 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 1970 authenticated encryption computation using the values from the 1971 example in Appendix A.3. As described where this algorithm is 1972 defined in Sections 5.2 and 5.2.3 of JWA, the AES_CBC_HMAC_SHA2 1973 family of algorithms are implemented using Advanced Encryption 1974 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #7 1975 padding to perform the encryption and an HMAC SHA-2 function to 1976 perform the integrity calculation - in this case, HMAC SHA-256. 1978 B.1. Extract MAC_KEY and ENC_KEY from Key 1980 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example 1981 (using JSON array notation) is: 1983 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1984 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1985 44, 207] 1987 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 1988 which is: 1990 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1991 206] 1993 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 1994 is: 1996 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 1997 207] 1999 Note that the MAC key comes before the encryption key in the input 2000 key K; this is in the opposite order of the algorithm names in the 2001 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 2003 B.2. Encrypt Plaintext to Create Ciphertext 2005 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 2006 using PKCS #7 padding using the ENC_KEY above. The Plaintext in this 2007 example is: 2009 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 2010 112, 114, 111, 115, 112, 101, 114, 46] 2012 The encryption result is as follows, which is the Ciphertext output: 2014 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 2015 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 2016 112, 56, 102] 2018 B.3. 64 Bit Big Endian Representation of AAD Length 2020 The Additional Authenticated Data (AAD) in this example is: 2022 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2023 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2024 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2025 110, 48] 2027 This AAD is 51 bytes long, which is 408 bits long. The octet string 2028 AL, which is the number of bits in AAD expressed as a big endian 64 2029 bit unsigned integer is: 2031 [0, 0, 0, 0, 0, 0, 1, 152] 2033 B.4. Initialization Vector Value 2035 The Initialization Vector value used in this example is: 2037 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 2038 101] 2040 B.5. Create Input to HMAC Computation 2042 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 2043 the AL value. The result of this concatenation is: 2045 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2046 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2047 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2048 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 2049 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 2050 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 2051 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 2053 B.6. Compute HMAC Value 2055 Compute the HMAC SHA-256 of the concatenated value above. This 2056 result M is: 2058 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2059 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 2060 86, 229, 116] 2062 B.7. Truncate HMAC Value to Create Authentication Tag 2064 Use the first half (128 bits) of the HMAC output M as the 2065 Authentication Tag output T. This truncated value is: 2067 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2068 194, 85] 2070 Appendix C. Acknowledgements 2072 Solutions for encrypting JSON content were also explored by JSON 2073 Simple Encryption [JSE] and JavaScript Message Security Format 2074 [I-D.rescorla-jsms], both of which significantly influenced this 2075 draft. This draft attempts to explicitly reuse as many of the 2076 relevant concepts from XML Encryption 1.1 2077 [W3C.REC-xmlenc-core1-20130411] and RFC 5652 [RFC5652] as possible, 2078 while utilizing simple, compact JSON-based data structures. 2080 Special thanks are due to John Bradley, Eric Rescorla, and Nat 2081 Sakimura for the discussions that helped inform the content of this 2082 specification, to Eric Rescorla and Joe Hildebrand for allowing the 2083 reuse of text from [I-D.rescorla-jsms] in this document, and to Eric 2084 Rescorla for co-authoring many drafts of this specification. 2086 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2087 Jay for validating the examples in this specification. 2089 This specification is the work of the JOSE Working Group, which 2090 includes dozens of active and dedicated participants. In particular, 2091 the following individuals contributed ideas, feedback, and wording 2092 that influenced this specification: 2094 Richard Barnes, John Bradley, Brian Campbell, Alissa Cooper, Breno de 2095 Medeiros, Stephen Farrell, Dick Hardt, Jeff Hodges, Russ Housley, 2096 Edmund Jay, Scott Kelly, Stephen Kent, Barry Leiba, James Manger, 2097 Matt Miller, Kathleen Moriarty, Tony Nadalin, Hideki Nara, Axel 2098 Nennker, Ray Polk, Emmanuel Raviart, Eric Rescorla, Pete Resnick, Nat 2099 Sakimura, Jim Schaad, Hannes Tschofenig, and Sean Turner. 2101 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2102 Sean Turner, Stephen Farrell, and Kathleen Moriarty served as 2103 Security area directors during the creation of this specification. 2105 Appendix D. Document History 2107 [[ to be removed by the RFC Editor before publication as an RFC ]] 2109 -35 2111 o Addressed AppsDir reviews by Ray Polk. 2113 -34 2115 o Addressed IESG review comments by Barry Leiba, Alissa Cooper, Pete 2116 Resnick, Stephen Farrell, and Richard Barnes. 2118 -33 2120 o Noted that certificate thumbprints are also sometimes known as 2121 certificate fingerprints. 2123 o Changed to use the term "authenticated encryption" instead of 2124 "encryption", where appropriate. 2126 o Acknowledged additional contributors. 2128 -32 2130 o Addressed Gen-ART review comments by Russ Housley. 2132 o Addressed secdir review comments by Scott Kelly, Tero Kivinen, and 2133 Stephen Kent. 2135 -31 2137 o Updated the reference to draft-mcgrew-aead-aes-cbc-hmac-sha2. 2139 -30 2141 o Added subsection headings within the Overview section for the two 2142 serializations. 2144 o Added references and cleaned up the reference syntax in a few 2145 places. 2147 o Applied minor wording changes to the Security Considerations 2148 section and made other local editorial improvements. 2150 -29 2152 o Replaced the terms JWS Header, JWE Header, and JWT Header with a 2153 single JOSE Header term defined in the JWS specification. This 2154 also enabled a single Header Parameter definition to be used and 2155 reduced other areas of duplication between specifications. 2157 -28 2159 o Specified the use of PKCS #7 padding with AES CBC, rather than 2160 PKCS #5. (PKCS #7 is a superset of PKCS #5, and is appropriate 2161 for the 16 octet blocks used by AES CBC.) 2163 o Revised the introduction to the Security Considerations section. 2164 Also moved a security consideration item here from the JWA draft. 2166 -27 2168 o Described additional security considerations. 2170 o Added the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) header 2171 parameter. 2173 -26 2174 o Noted that octet sequences are depicted using JSON array notation. 2176 o Updated references, including to W3C specifications. 2178 -25 2180 o Corrected two external section number references that had changed. 2182 o Corrected a typo in an algorithm name in the prose of an example. 2184 -24 2186 o Corrected complete JSON Serialization example. 2188 o Replaced uses of the term "associated data" wherever it was used 2189 to refer to a data value with "additional authenticated data", 2190 since both terms were being used as synonyms, causing confusion. 2192 o Updated the JSON reference to RFC 7159. 2194 o Thanked Eric Rescorla for helping to author of most of the drafts 2195 of this specification and removed him from the current author 2196 list. 2198 -23 2200 o Corrected a use of the word "payload" to "plaintext". 2202 -22 2204 o Corrected RFC 2119 terminology usage. 2206 o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. 2208 -21 2210 o Changed some references from being normative to informative, 2211 addressing issue #90. 2213 o Applied review comments to the JSON Serialization section, 2214 addressing issue #178. 2216 -20 2218 o Made terminology definitions more consistent, addressing issue 2219 #165. 2221 o Restructured the JSON Serialization section to call out the 2222 parameters used in hanging lists, addressing issue #178. 2224 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 2225 addressing issue #90. 2227 -19 2229 o Reordered the key selection parameters. 2231 -18 2233 o Updated the mandatory-to-implement (MTI) language to say that 2234 applications using this specification need to specify what 2235 serialization and serialization features are used for that 2236 application, addressing issue #176. 2238 o Changes to address editorial and minor issues #89, #135, #165, 2239 #174, #175, #177, #179, and #180. 2241 o Used Header Parameter Description registry field. 2243 -17 2245 o Refined the "typ" and "cty" definitions to always be MIME Media 2246 Types, with the omission of "application/" prefixes recommended 2247 for brevity, addressing issue #50. 2249 o Updated the mandatory-to-implement (MTI) language to say that 2250 general-purpose implementations must implement the single 2251 recipient case for both serializations whereas special-purpose 2252 implementations can implement just one serialization if that meets 2253 the needs of the use cases the implementation is designed for, 2254 addressing issue #176. 2256 o Explicitly named all the logical components of a JWE and defined 2257 the processing rules and serializations in terms of those 2258 components, addressing issues #60, #61, and #62. 2260 o Replaced verbose repetitive phases such as "base64url encode the 2261 octets of the UTF-8 representation of X" with mathematical 2262 notation such as "BASE64URL(UTF8(X))". 2264 o Header Parameters and processing rules occurring in both JWS and 2265 JWE are now referenced in JWS by JWE, rather than duplicated, 2266 addressing issue #57. 2268 o Terms used in multiple documents are now defined in one place and 2269 incorporated by reference. Some lightly used or obvious terms 2270 were also removed. This addresses issue #58. 2272 -16 2274 o Changes to address editorial and minor issues #163, #168, #169, 2275 #170, #172, and #173. 2277 -15 2279 o Clarified that it is an application decision which recipients' 2280 encrypted content must successfully validate for the JWE to be 2281 accepted, addressing issue #35. 2283 o Changes to address editorial issues #34, #164, and #169. 2285 -14 2287 o Clarified that the "protected", "unprotected", "header", "iv", 2288 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2289 JSON Serialization when their values would be empty. Stated that 2290 the "recipients" array must always be present. 2292 -13 2294 o Added an "aad" (Additional Authenticated Data) member for the JWE 2295 JSON Serialization, enabling Additional Authenticated Data to be 2296 supplied that is not double base64url encoded, addressing issue 2297 #29. 2299 -12 2301 o Clarified that the "typ" and "cty" header parameters are used in 2302 an application-specific manner and have no effect upon the JWE 2303 processing. 2305 o Replaced the MIME types "application/jwe+json" and 2306 "application/jwe" with "application/jose+json" and 2307 "application/jose". 2309 o Stated that recipients MUST either reject JWEs with duplicate 2310 Header Parameter Names or use a JSON parser that returns only the 2311 lexically last duplicate member name. 2313 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2314 be with the algorithm descriptions that use them. 2316 o Added a Serializations section with parallel treatment of the JWE 2317 Compact Serialization and the JWE JSON Serialization and also 2318 moved the former Implementation Considerations content there. 2320 o Restored use of the term "AEAD". 2322 o Changed terminology from "block encryption" to "content 2323 encryption". 2325 -11 2327 o Added Key Identification section. 2329 o Removed the Encrypted Key value from the AAD computation since it 2330 is already effectively integrity protected by the encryption 2331 process. The AAD value now only contains the representation of 2332 the JWE Encrypted Header. 2334 o For the JWE JSON Serialization, enable Header Parameter values to 2335 be specified in any of three parameters: the "protected" member 2336 that is integrity protected and shared among all recipients, the 2337 "unprotected" member that is not integrity protected and shared 2338 among all recipients, and the "header" member that is not 2339 integrity protected and specific to a particular recipient. (This 2340 does not affect the JWE Compact Serialization, in which all Header 2341 Parameter values are in a single integrity protected JWE Header 2342 value.) 2344 o Shortened the names "authentication_tag" to "tag" and 2345 "initialization_vector" to "iv" in the JWE JSON Serialization, 2346 addressing issue #20. 2348 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2350 o Removed suggested compact serialization for multiple recipients. 2352 o Changed the MIME type name "application/jwe-js" to 2353 "application/jwe+json", addressing issue #22. 2355 o Tightened the description of the "crit" (critical) header 2356 parameter. 2358 -10 2360 o Changed the JWE processing rules for multiple recipients so that a 2361 single AAD value contains the header parameters and encrypted key 2362 values for all the recipients, enabling AES GCM to be safely used 2363 for multiple recipients. 2365 o Added an appendix suggesting a possible compact serialization for 2366 JWEs with multiple recipients. 2368 -09 2370 o Added JWE JSON Serialization, as specified by 2371 draft-jones-jose-jwe-json-serialization-04. 2373 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2374 parameter value. 2376 o Defined that the default action for header parameters that are not 2377 understood is to ignore them unless specifically designated as 2378 "MUST be understood" or included in the new "crit" (critical) 2379 header parameter list. This addressed issue #6. 2381 o Corrected "x5c" description. This addressed issue #12. 2383 o Changed from using the term "byte" to "octet" when referring to 8 2384 bit values. 2386 o Added Key Management Mode definitions to terminology section and 2387 used the defined terms to provide clearer key management 2388 instructions. This addressed issue #5. 2390 o Added text about preventing the recipient from behaving as an 2391 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2393 o Changed from using the term "Integrity Value" to "Authentication 2394 Tag". 2396 o Changed member name from "integrity_value" to "authentication_tag" 2397 in the JWE JSON Serialization. 2399 o Removed Initialization Vector from the AAD value since it is 2400 already integrity protected by all of the authenticated encryption 2401 algorithms specified in the JWA specification. 2403 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2404 and "A256CBC-HS512". The new algorithms perform the same 2405 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2406 but with the Initialization Vector and Authentication Tag values 2407 remaining separate from the Ciphertext value in the output 2408 representation. Also deleted the header parameters "epu" 2409 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2410 they are no longer used. 2412 -08 2413 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2414 since the term AEAD in the RFC 5116 sense implied the use of a 2415 particular data representation, rather than just referring to the 2416 class of algorithms that perform authenticated encryption with 2417 associated data. 2419 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2420 Tschofenig. Many of these simplified the terminology used. 2422 o Clarified statements of the form "This header parameter is 2423 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2425 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2426 Web Signature and Encryption Header Parameters registry. 2428 o Added seriesInfo information to Internet Draft references. 2430 -07 2432 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2434 o Updated values for example AES CBC calculations. 2436 o Made several local editorial changes to clean up loose ends left 2437 over from to the decision to only support block encryption methods 2438 providing integrity. One of these changes was to explicitly state 2439 that the "enc" (encryption method) algorithm must be an 2440 Authenticated Encryption algorithm with a specified key length. 2442 -06 2444 o Removed the "int" and "kdf" parameters and defined the new 2445 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2446 "A256CBC+HS512" to replace the former uses of AES CBC, which 2447 required the use of separate integrity and key derivation 2448 functions. 2450 o Included additional values in the Concat KDF calculation -- the 2451 desired output size and the algorithm value, and optionally 2452 PartyUInfo and PartyVInfo values. Added the optional header 2453 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2454 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2455 PartyVInfo). Updated the KDF examples accordingly. 2457 o Promoted Initialization Vector from being a header parameter to 2458 being a top-level JWE element. This saves approximately 16 bytes 2459 in the compact serialization, which is a significant savings for 2460 some use cases. Promoting the Initialization Vector out of the 2461 header also avoids repeating this shared value in the JSON 2462 serialization. 2464 o Changed "x5c" (X.509 Certificate Chain) representation from being 2465 a single string to being an array of strings, each containing a 2466 single base64 encoded DER certificate value, representing elements 2467 of the certificate chain. 2469 o Added an AES Key Wrap example. 2471 o Reordered the encryption steps so CMK creation is first, when 2472 required. 2474 o Correct statements in examples about which algorithms produce 2475 reproducible results. 2477 -05 2479 o Support both direct encryption using a shared or agreed upon 2480 symmetric key, and the use of a shared or agreed upon symmetric 2481 key to key wrap the CMK. 2483 o Added statement that "StringOrURI values are compared as case- 2484 sensitive strings with no transformations or canonicalizations 2485 applied". 2487 o Updated open issues. 2489 o Indented artwork elements to better distinguish them from the body 2490 text. 2492 -04 2494 o Refer to the registries as the primary sources of defined values 2495 and then secondarily reference the sections defining the initial 2496 contents of the registries. 2498 o Normatively reference XML Encryption 1.1 for its security 2499 considerations. 2501 o Reference draft-jones-jose-jwe-json-serialization instead of 2502 draft-jones-json-web-encryption-json-serialization. 2504 o Described additional open issues. 2506 o Applied editorial suggestions. 2508 -03 2509 o Added the "kdf" (key derivation function) header parameter to 2510 provide crypto agility for key derivation. The default KDF 2511 remains the Concat KDF with the SHA-256 digest function. 2513 o Reordered encryption steps so that the Encoded JWE Header is 2514 always created before it is needed as an input to the 2515 Authenticated Encryption "additional authenticated data" 2516 parameter. 2518 o Added the "cty" (content type) header parameter for declaring type 2519 information about the secured content, as opposed to the "typ" 2520 (type) header parameter, which declares type information about 2521 this object. 2523 o Moved description of how to determine whether a header is for a 2524 JWS or a JWE from the JWT spec to the JWE spec. 2526 o Added complete encryption examples for both Authenticated 2527 Encryption and non-Authenticated Encryption algorithms. 2529 o Added complete key derivation examples. 2531 o Added "Collision Resistant Namespace" to the terminology section. 2533 o Reference ITU.X690.1994 for DER encoding. 2535 o Added Registry Contents sections to populate registry values. 2537 o Numerous editorial improvements. 2539 -02 2541 o When using Authenticated Encryption algorithms (such as AES GCM), 2542 use the "additional authenticated data" parameter to provide 2543 integrity for the header, encrypted key, and ciphertext and use 2544 the resulting "authentication tag" value as the JWE Authentication 2545 Tag. 2547 o Defined KDF output key sizes. 2549 o Generalized text to allow key agreement to be employed as an 2550 alternative to key wrapping or key encryption. 2552 o Changed compression algorithm from gzip to DEFLATE. 2554 o Clarified that it is an error when a "kid" value is included and 2555 no matching key is found. 2557 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2558 rejected. 2560 o Clarified the relationship between "typ" header parameter values 2561 and MIME types. 2563 o Registered application/jwe MIME type and "JWE" typ header 2564 parameter value. 2566 o Simplified JWK terminology to get replace the "JWK Key Object" and 2567 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2568 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2569 between single keys and sets of keys. As part of this change, the 2570 Header Parameter Name for a public key value was changed from 2571 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2573 o Added suggestion on defining additional header parameters such as 2574 "x5t#S256" in the future for certificate thumbprints using hash 2575 algorithms other than SHA-1. 2577 o Specify RFC 2818 server identity validation, rather than RFC 6125 2578 (paralleling the same decision in the OAuth specs). 2580 o Generalized language to refer to Message Authentication Codes 2581 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2582 unless in a context specific to HMAC algorithms. 2584 o Reformatted to give each header parameter its own section heading. 2586 -01 2588 o Added an integrity check for non-Authenticated Encryption 2589 algorithms. 2591 o Added "jpk" and "x5c" header parameters for including JWK public 2592 keys and X.509 certificate chains directly in the header. 2594 o Clarified that this specification is defining the JWE Compact 2595 Serialization. Referenced the new JWE-JS spec, which defines the 2596 JWE JSON Serialization. 2598 o Added text "New header parameters should be introduced sparingly 2599 since an implementation that does not understand a parameter MUST 2600 reject the JWE". 2602 o Clarified that the order of the encryption and decryption steps is 2603 not significant in cases where there are no dependencies between 2604 the inputs and outputs of the steps. 2606 o Made other editorial improvements suggested by JOSE working group 2607 participants. 2609 -00 2611 o Created the initial IETF draft based upon 2612 draft-jones-json-web-encryption-02 with no normative changes. 2614 o Changed terminology to no longer call both digital signatures and 2615 HMACs "signatures". 2617 Authors' Addresses 2619 Michael B. Jones 2620 Microsoft 2622 Email: mbj@microsoft.com 2623 URI: http://self-issued.info/ 2625 Joe Hildebrand 2626 Cisco Systems, Inc. 2628 Email: jhildebr@cisco.com