idnits 2.17.1 draft-ietf-jose-json-web-encryption-33.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 25, 2014) is 3499 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 1429 -- Looks like a reference, but probably isn't: '197' on line 1429 -- Looks like a reference, but probably isn't: '117' on line 1429 -- Looks like a reference, but probably isn't: '252' on line 1429 -- Looks like a reference, but probably isn't: '2' on line 1429 -- Looks like a reference, but probably isn't: '219' on line 1429 -- Looks like a reference, but probably isn't: '233' on line 1429 -- Looks like a reference, but probably isn't: '68' on line 1429 -- Looks like a reference, but probably isn't: '180' on line 1429 -- Looks like a reference, but probably isn't: '225' on line 1429 -- Looks like a reference, but probably isn't: '77' on line 1429 -- Looks like a reference, but probably isn't: '0' on line 2024 -- Looks like a reference, but probably isn't: '1' on line 2024 -- Looks like a reference, but probably isn't: '152' on line 2024 == Unused Reference: 'AES' is defined on line 1278, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' -- Obsolete informational reference (is this intentional?): RFC 3447 (Obsoleted by RFC 8017) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 18 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track J. Hildebrand 5 Expires: March 29, 2015 Cisco 6 September 25, 2014 8 JSON Web Encryption (JWE) 9 draft-ietf-jose-json-web-encryption-33 11 Abstract 13 JSON Web Encryption (JWE) represents encrypted content using 14 JavaScript Object Notation (JSON) based data structures. 15 Cryptographic algorithms and identifiers for use with this 16 specification are described in the separate JSON Web Algorithms (JWA) 17 specification and IANA registries defined by that specification. 18 Related digital signature and MAC capabilities are described in the 19 separate JSON Web Signature (JWS) specification. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on March 29, 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. 191 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 192 of STRING. 194 ASCII(STRING) denotes the octets of the ASCII [USASCII] 195 representation of STRING. 197 The concatenation of two values A and B is denoted as A || B. 199 2. Terminology 201 These terms defined by the JSON Web Signature (JWS) [JWS] 202 specification are incorporated into this specification: "JSON Web 203 Signature (JWS)", "Base64url Encoding", "Collision-Resistant Name", 204 "Header Parameter", "JOSE Header", and "StringOrURI". 206 These terms are defined by this specification: 208 JSON Web Encryption (JWE) 209 A data structure representing an encrypted and integrity protected 210 message. 212 Authenticated Encryption with Associated Data (AEAD) 213 An AEAD algorithm is one that encrypts the Plaintext, allows 214 Additional Authenticated Data to be specified, and provides an 215 integrated content integrity check over the Ciphertext and 216 Additional Authenticated Data. AEAD algorithms accept two inputs, 217 the Plaintext and the Additional Authenticated Data value, and 218 produce two outputs, the Ciphertext and the Authentication Tag 219 value. AES Galois/Counter Mode (GCM) is one such algorithm. 221 Plaintext 222 The sequence of octets to be encrypted -- a.k.a., the message. 223 The plaintext can contain an arbitrary sequence of octets. 225 Ciphertext 226 An encrypted representation of the Plaintext. 228 Additional Authenticated Data (AAD) 229 An input to an AEAD operation that is integrity protected but not 230 encrypted. 232 Authentication Tag 233 An output of an AEAD operation that ensures the integrity of the 234 Ciphertext and the Additional Authenticated Data. Note that some 235 algorithms may not use an Authentication Tag, in which case this 236 value is the empty octet sequence. 238 Content Encryption Key (CEK) 239 A symmetric key for the AEAD algorithm used to encrypt the 240 Plaintext to produce the Ciphertext and the Authentication Tag. 242 JWE Encrypted Key 243 Encrypted Content Encryption Key (CEK) value. Note that for some 244 algorithms, the JWE Encrypted Key value is specified as being the 245 empty octet sequence. 247 JWE Initialization Vector 248 Initialization vector value used when encrypting the plaintext. 249 Note that some algorithms may not use an Initialization Vector, in 250 which case this value is the empty octet sequence. 252 JWE AAD 253 Additional value to be integrity protected by the authenticated 254 encryption operation. This can only be present when using the JWE 255 JSON Serialization. (Note that this can also be achieved when 256 using either serialization by including the AAD value as an 257 integrity protected Header Parameter value, but at the cost of the 258 value being double base64url encoded.) 260 JWE Ciphertext 261 Ciphertext value resulting from authenticated encryption of the 262 plaintext with additional authenticated data. 264 JWE Authentication Tag 265 Authentication Tag value resulting from authenticated encryption 266 of the plaintext with additional authenticated data. 268 JWE Protected Header 269 JSON object that contains the Header Parameters that are integrity 270 protected by the authenticated encryption operation. These 271 parameters apply to all recipients of the JWE. For the JWE 272 Compact Serialization, this comprises the entire JOSE Header. For 273 the JWE JSON Serialization, this is one component of the JOSE 274 Header. 276 JWE Shared Unprotected Header 277 JSON object that contains the Header Parameters that apply to all 278 recipients of the JWE that are not integrity protected. This can 279 only be present when using the JWE JSON Serialization. 281 JWE Per-Recipient Unprotected Header 282 JSON object that contains Header Parameters that apply to a single 283 recipient of the JWE. These Header Parameter values are not 284 integrity protected. This can only be present when using the JWE 285 JSON Serialization. 287 JWE Compact Serialization 288 A representation of the JWE as a compact, URL-safe string. 290 JWE JSON Serialization 291 A representation of the JWE as a JSON object. The JWE JSON 292 Serialization enables the same content to be encrypted to multiple 293 parties. This representation is neither optimized for compactness 294 nor URL-safe. 296 Key Management Mode 297 A method of determining the Content Encryption Key (CEK) value to 298 use. Each algorithm used for determining the CEK value uses a 299 specific Key Management Mode. Key Management Modes employed by 300 this specification are Key Encryption, Key Wrapping, Direct Key 301 Agreement, Key Agreement with Key Wrapping, and Direct Encryption. 303 Key Encryption 304 A Key Management Mode in which the Content Encryption Key (CEK) 305 value is encrypted to the intended recipient using an asymmetric 306 encryption algorithm. 308 Key Wrapping 309 A Key Management Mode in which the Content Encryption Key (CEK) 310 value is encrypted to the intended recipient using a symmetric key 311 wrapping algorithm. 313 Direct Key Agreement 314 A Key Management Mode in which a key agreement algorithm is used 315 to agree upon the Content Encryption Key (CEK) value. 317 Key Agreement with Key Wrapping 318 A Key Management Mode in which a key agreement algorithm is used 319 to agree upon a symmetric key used to encrypt the Content 320 Encryption Key (CEK) value to the intended recipient using a 321 symmetric key wrapping algorithm. 323 Direct Encryption 324 A Key Management Mode in which the Content Encryption Key (CEK) 325 value used is the secret symmetric key value shared between the 326 parties. 328 3. JSON Web Encryption (JWE) Overview 330 JWE represents encrypted content using JSON data structures and 331 base64url encoding. These JSON data structures MAY contain white 332 space and/or line breaks. A JWE represents these logical values 333 (each of which is defined in Section 2): 335 o JOSE Header 336 o JWE Encrypted Key 337 o JWE Initialization Vector 338 o JWE AAD 339 o JWE Ciphertext 340 o JWE Authentication Tag 342 For a JWE object, the JOSE Header members are the union of the 343 members of these values (each of which is defined in Section 2): 345 o JWE Protected Header 346 o JWE Shared Unprotected Header 347 o JWE Per-Recipient Unprotected Header 349 JWE utilizes authenticated encryption to ensure the confidentiality 350 and integrity of the Plaintext and the integrity of the JWE Protected 351 Header and the JWE AAD. 353 This document defines two serializations for JWE objects: a compact, 354 URL-safe serialization called the JWE Compact Serialization and a 355 JSON serialization called the JWE JSON Serialization. In both 356 serializations, the JWE Protected Header, JWE Encrypted Key, JWE 357 Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are 358 base64url encoded for transmission, since JSON lacks a way to 359 directly represent arbitrary octet sequences. When present, the JWE 360 AAD is also base64url encoded for transmission. 362 3.1. JWE Compact Serialization Overview 364 In the JWE Compact Serialization, no JWE Shared Unprotected Header or 365 JWE Per-Recipient Unprotected Header are used. In this case, the 366 JOSE Header and the JWE Protected Header are the same. 368 In the JWE Compact Serialization, a JWE object is represented as the 369 concatenation: 371 BASE64URL(UTF8(JWE Protected Header)) || '.' || 372 BASE64URL(JWE Encrypted Key) || '.' || 373 BASE64URL(JWE Initialization Vector) || '.' || 374 BASE64URL(JWE Ciphertext) || '.' || 375 BASE64URL(JWE Authentication Tag) 377 3.2. JWE JSON Serialization Overview 379 In the JWE JSON Serialization, one or more of the JWE Protected 380 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 381 Unprotected Header MUST be present. In this case, the members of the 382 JOSE Header are the combination of the members of the JWE Protected 383 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 384 Unprotected Header values that are present. 386 In the JWE JSON Serialization, a JWE object is represented as the 387 combination of these eight values, 388 BASE64URL(UTF8(JWE Protected Header)), 389 JWE Shared Unprotected Header, 390 JWE Per-Recipient Unprotected Header, 391 BASE64URL(JWE Encrypted Key), 392 BASE64URL(JWE Initialization Vector), 393 BASE64URL(JWE Ciphertext), 394 BASE64URL(JWE Authentication Tag), and 395 BASE64URL(JWE AAD), 396 with the six base64url encoded result strings and the two unprotected 397 JSON object values being represented as members within a JSON object. 398 The inclusion of some of these values is OPTIONAL. The JWE JSON 399 Serialization can also encrypt the plaintext to multiple recipients. 400 See Section 7.2 for more information about the JWE JSON 401 Serialization. 403 3.3. Example JWE 405 This example encrypts the plaintext "The true sign of intelligence is 406 not knowledge but imagination." to the recipient. 408 The following example JWE Protected Header declares that: 409 o the Content Encryption Key is encrypted to the recipient using the 410 RSAES OAEP [RFC3447] algorithm to produce the JWE Encrypted Key 411 and 412 o authenticated encryption is performed on the Plaintext using the 413 AES GCM [AES, NIST.800-38D] algorithm with a 256 bit key to 414 produce the Ciphertext and the Authentication Tag. 416 {"alg":"RSA-OAEP","enc":"A256GCM"} 418 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 419 Header)) gives this value: 421 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 423 The remaining steps to finish creating this JWE are: 424 o Generate a random Content Encryption Key (CEK). 425 o Encrypt the CEK with the recipient's public key using the RSAES 426 OAEP algorithm to produce the JWE Encrypted Key. 427 o Base64url encode the JWE Encrypted Key. 428 o Generate a random JWE Initialization Vector. 429 o Base64url encode the JWE Initialization Vector. 430 o Let the Additional Authenticated Data encryption parameter be 431 ASCII(BASE64URL(UTF8(JWE Protected Header))). 432 o Perform authenticated encryption on the Plaintext with the AES GCM 433 algorithm using the CEK as the encryption key, the JWE 434 Initialization Vector, and the Additional Authenticated Data 435 value, requesting a 128 bit Authentication Tag output. 437 o Base64url encode the Ciphertext. 438 o Base64url encode the Authentication Tag. 439 o Assemble the final representation: The Compact Serialization of 440 this result is the string BASE64URL(UTF8(JWE Protected Header)) || 441 '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE 442 Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' 443 || BASE64URL(JWE Authentication Tag). 445 The final result in this example (with line breaks for display 446 purposes only) is: 448 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 449 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 450 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 451 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 452 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 453 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 454 6UklfCpIMfIjf7iGdXKHzg. 455 48V1_ALb6US04U3b. 456 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 457 SdiwkIr3ajwQzaBtQD_A. 458 XFBoMYUZodetZdvTiFvSkQ 460 See Appendix A.1 for the complete details of computing this JWE. See 461 other parts of Appendix A for additional examples. 463 4. JOSE Header 465 For a JWE object, the members of the JSON object(s) representing the 466 JOSE Header describe the encryption applied to the Plaintext and 467 optionally additional properties of the JWE. The Header Parameter 468 names within the JOSE Header MUST be unique, just as described in 469 Section 4 of [JWS]. The rules about handling Header Parameters that 470 are not understood by the implementation are also the same. The 471 classes of Header Parameter names are likewise the same. 473 4.1. Registered Header Parameter Names 475 The following Header Parameter names for use in JWE objects are 476 registered in the IANA JSON Web Signature and Encryption Header 477 Parameters registry defined in [JWS], with meanings as defined below. 479 As indicated by the common registry, JWSs and JWEs share a common 480 Header Parameter space; when a parameter is used by both 481 specifications, its usage must be compatible between the 482 specifications. 484 4.1.1. "alg" (Algorithm) Header Parameter 486 This parameter has the same meaning, syntax, and processing rules as 487 the "alg" Header Parameter defined in Section 4.1.1 of [JWS], except 488 that the Header Parameter identifies the cryptographic algorithm used 489 to encrypt or determine the value of the Content Encryption Key 490 (CEK). The encrypted content is not usable if the "alg" value does 491 not represent a supported algorithm, or if the recipient does not 492 have a key that can be used with that algorithm. 494 A list of defined "alg" values for this use can be found in the IANA 495 JSON Web Signature and Encryption Algorithms registry defined in 496 [JWA]; the initial contents of this registry are the values defined 497 in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. 499 4.1.2. "enc" (Encryption Algorithm) Header Parameter 501 The "enc" (encryption algorithm) Header Parameter identifies the 502 content encryption algorithm used to perform authenticated encryption 503 on the Plaintext to produce the Ciphertext and the Authentication 504 Tag. This algorithm MUST be an AEAD algorithm with a specified key 505 length. The recipient MUST reject the JWE if the "enc" value does 506 not represent a supported algorithm. "enc" values should either be 507 registered in the IANA JSON Web Signature and Encryption Algorithms 508 registry defined in [JWA] or be a value that contains a Collision- 509 Resistant Name. The "enc" value is a case-sensitive string 510 containing a StringOrURI value. This Header Parameter MUST be 511 present and MUST be understood and processed by implementations. 513 A list of defined "enc" values for this use can be found in the IANA 514 JSON Web Signature and Encryption Algorithms registry defined in 515 [JWA]; the initial contents of this registry are the values defined 516 in Section 5.1 of the JSON Web Algorithms (JWA) [JWA] specification. 518 4.1.3. "zip" (Compression Algorithm) Header Parameter 520 The "zip" (compression algorithm) applied to the Plaintext before 521 encryption, if any. The "zip" value defined by this specification 522 is: 524 o "DEF" - Compression with the DEFLATE [RFC1951] algorithm 526 Other values MAY be used. Compression algorithm values can be 527 registered in the IANA JSON Web Encryption Compression Algorithm 528 registry defined in [JWA]. The "zip" value is a case-sensitive 529 string. If no "zip" parameter is present, no compression is applied 530 to the Plaintext before encryption. This Header Parameter MUST be 531 integrity protected, and therefore MUST occur only within the JWE 532 Protected Header, when used. Use of this Header Parameter is 533 OPTIONAL. This Header Parameter MUST be understood and processed by 534 implementations. 536 4.1.4. "jku" (JWK Set URL) Header Parameter 538 This parameter has the same meaning, syntax, and processing rules as 539 the "jku" Header Parameter defined in Section 4.1.2 of [JWS], except 540 that the JWK Set resource contains the public key to which the JWE 541 was encrypted; this can be used to determine the private key needed 542 to decrypt the JWE. 544 4.1.5. "jwk" (JSON Web Key) Header Parameter 546 This parameter has the same meaning, syntax, and processing rules as 547 the "jwk" Header Parameter defined in Section 4.1.3 of [JWS], except 548 that the key is the public key to which the JWE was encrypted; this 549 can be used to determine the private key needed to decrypt the JWE. 551 4.1.6. "kid" (Key ID) Header Parameter 553 This parameter has the same meaning, syntax, and processing rules as 554 the "kid" Header Parameter defined in Section 4.1.4 of [JWS], except 555 that the key hint references the public key to which the JWE was 556 encrypted; this can be used to determine the private key needed to 557 decrypt the JWE. This parameter allows originators to explicitly 558 signal a change of key to JWE recipients. 560 4.1.7. "x5u" (X.509 URL) Header Parameter 562 This parameter has the same meaning, syntax, and processing rules as 563 the "x5u" Header Parameter defined in Section 4.1.5 of [JWS], except 564 that the X.509 public key certificate or certificate chain [RFC5280] 565 contains the public key to which the JWE was encrypted; this can be 566 used to determine the private key needed to decrypt the JWE. 568 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 570 This parameter has the same meaning, syntax, and processing rules as 571 the "x5c" Header Parameter defined in Section 4.1.6 of [JWS], except 572 that the X.509 public key certificate or certificate chain [RFC5280] 573 contains the public key to which the JWE was encrypted; this can be 574 used to determine the private key needed to decrypt the JWE. 576 See Appendix B of [JWS] for an example "x5c" value. 578 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 580 This parameter has the same meaning, syntax, and processing rules as 581 the "x5t" Header Parameter defined in Section 4.1.7 of [JWS], except 582 that the certificate referenced by the thumbprint contains the public 583 key to which the JWE was encrypted; this can be used to determine the 584 private key needed to decrypt the JWE. Note that certificate 585 thumbprints are also sometimes known as certificate fingerprints. 587 4.1.10. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header 588 Parameter 590 This parameter has the same meaning, syntax, and processing rules as 591 the "x5t#S256" Header Parameter defined in Section 4.1.8 of [JWS], 592 except that the certificate referenced by the thumbprint contains the 593 public key to which the JWE was encrypted; this can be used to 594 determine the private key needed to decrypt the JWE. Note that 595 certificate thumbprints are also sometimes known as certificate 596 fingerprints. 598 4.1.11. "typ" (Type) Header Parameter 600 This parameter has the same meaning, syntax, and processing rules as 601 the "typ" Header Parameter defined in Section 4.1.9 of [JWS], except 602 that the type is that of this complete JWE object. 604 4.1.12. "cty" (Content Type) Header Parameter 606 This parameter has the same meaning, syntax, and processing rules as 607 the "cty" Header Parameter defined in Section 4.1.10 of [JWS], except 608 that the type is that of the secured content (the plaintext). 610 4.1.13. "crit" (Critical) Header Parameter 612 This parameter has the same meaning, syntax, and processing rules as 613 the "crit" Header Parameter defined in Section 4.1.11 of [JWS], 614 except that Header Parameters for a JWE object are being referred to, 615 rather than Header Parameters for a JWS object. 617 4.2. Public Header Parameter Names 619 Additional Header Parameter names can be defined by those using JWEs. 620 However, in order to prevent collisions, any new Header Parameter 621 name should either be registered in the IANA JSON Web Signature and 622 Encryption Header Parameters registry defined in [JWS] or be a Public 623 Name: a value that contains a Collision-Resistant Name. In each 624 case, the definer of the name or value needs to take reasonable 625 precautions to make sure they are in control of the part of the 626 namespace they use to define the Header Parameter name. 628 New Header Parameters should be introduced sparingly, as they can 629 result in non-interoperable JWEs. 631 4.3. Private Header Parameter Names 633 A producer and consumer of a JWE may agree to use Header Parameter 634 names that are Private Names: names that are not Registered Header 635 Parameter names Section 4.1 or Public Header Parameter names 636 Section 4.2. Unlike Public Header Parameter names, Private Header 637 Parameter names are subject to collision and should be used with 638 caution. 640 5. Producing and Consuming JWEs 642 5.1. Message Encryption 644 The message encryption process is as follows. The order of the steps 645 is not significant in cases where there are no dependencies between 646 the inputs and outputs of the steps. 648 1. Determine the Key Management Mode employed by the algorithm used 649 to determine the Content Encryption Key (CEK) value. (This is 650 the algorithm recorded in the "alg" (algorithm) Header Parameter 651 of the resulting JWE.) 653 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 654 Wrapping are employed, generate a random Content Encryption Key 655 (CEK) value. See RFC 4086 [RFC4086] for considerations on 656 generating random values. The CEK MUST have a length equal to 657 that required for the content encryption algorithm. 659 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 660 employed, use the key agreement algorithm to compute the value 661 of the agreed upon key. When Direct Key Agreement is employed, 662 let the Content Encryption Key (CEK) be the agreed upon key. 663 When Key Agreement with Key Wrapping is employed, the agreed 664 upon key will be used to wrap the CEK. 666 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 667 Wrapping are employed, encrypt the CEK to the recipient and let 668 the result be the JWE Encrypted Key. 670 5. When Direct Key Agreement or Direct Encryption are employed, let 671 the JWE Encrypted Key be the empty octet sequence. 673 6. When Direct Encryption is employed, let the Content Encryption 674 Key (CEK) be the shared symmetric key. 676 7. Compute the encoded key value BASE64URL(JWE Encrypted Key). 678 8. If the JWE JSON Serialization is being used, repeat this process 679 (steps 1-7) for each recipient. 681 9. Generate a random JWE Initialization Vector of the correct size 682 for the content encryption algorithm (if required for the 683 algorithm); otherwise, let the JWE Initialization Vector be the 684 empty octet sequence. 686 10. Compute the encoded initialization vector value BASE64URL(JWE 687 Initialization Vector). 689 11. If a "zip" parameter was included, compress the Plaintext using 690 the specified compression algorithm and let M be the octet 691 sequence representing the compressed Plaintext; otherwise, let M 692 be the octet sequence representing the Plaintext. 694 12. Create the JSON object(s) containing the desired set of Header 695 Parameters, which together comprise the JOSE Header: the JWE 696 Protected Header, and if the JWE JSON Serialization is being 697 used, the JWE Shared Unprotected Header and the JWE Per- 698 Recipient Unprotected Header. 700 13. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 701 Protected Header)). If the JWE Protected Header is not present 702 (which can only happen when using the JWE JSON Serialization and 703 no "protected" member is present), let this value be the empty 704 string. 706 14. Let the Additional Authenticated Data encryption parameter be 707 ASCII(Encoded Protected Header). However if a JWE AAD value is 708 present (which can only be the case when using the JWE JSON 709 Serialization), instead let the Additional Authenticated Data 710 encryption parameter be ASCII(Encoded Protected Header || '.' || 711 BASE64URL(JWE AAD)). 713 15. Encrypt M using the CEK, the JWE Initialization Vector, and the 714 Additional Authenticated Data value using the specified content 715 encryption algorithm to create the JWE Ciphertext value and the 716 JWE Authentication Tag (which is the Authentication Tag output 717 from the encryption operation). 719 16. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext). 721 17. Compute the encoded authentication tag value BASE64URL(JWE 722 Authentication Tag). 724 18. The five encoded values are used in both the JWE Compact 725 Serialization and the JWE JSON Serialization representations. 727 19. If a JWE AAD value is present, compute the encoded AAD value 728 BASE64URL(JWE AAD). 730 20. Create the desired serialized output. The Compact Serialization 731 of this result is the string BASE64URL(UTF8(JWE Protected 732 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 733 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 734 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). The 735 JWE JSON Serialization is described in Section 7.2. 737 5.2. Message Decryption 739 The message decryption process is the reverse of the encryption 740 process. The order of the steps is not significant in cases where 741 there are no dependencies between the inputs and outputs of the 742 steps. If any of these steps fails, the encrypted content cannot be 743 validated. 745 When there are multiple recipients, it is an application decision 746 which of the recipients' encrypted content must successfully validate 747 for the JWE to be accepted. In some cases, encrypted content for all 748 recipients must successfully validate or the JWE will be rejected. 749 In other cases, only the encrypted content for a single recipient 750 needs to be successfully validated. However, in all cases, the 751 encrypted content for at least one recipient MUST successfully 752 validate or the JWE MUST be rejected. 754 1. Parse the JWE representation to extract the serialized values 755 for the components of the JWE. When using the JWE Compact 756 Serialization, these components are the base64url encoded 757 representations of the JWE Protected Header, the JWE Encrypted 758 Key, the JWE Initialization Vector, the JWE Ciphertext, and the 759 JWE Authentication Tag, and when using the JWE JSON 760 Serialization, these components also include the base64url 761 encoded representation of the JWE AAD and the unencoded JWE 762 Shared Unprotected Header and JWE Per-Recipient Unprotected 763 Header values. When using the JWE Compact Serialization, the 764 JWE Protected Header, the JWE Encrypted Key, the JWE 765 Initialization Vector, the JWE Ciphertext, and the JWE 766 Authentication Tag are represented as base64url encoded values 767 in that order, separated by four period ('.') characters. The 768 JWE JSON Serialization is described in Section 7.2. 770 2. The encoded representations of the JWE Protected Header, the JWE 771 Encrypted Key, the JWE Initialization Vector, the JWE 772 Ciphertext, the JWE Authentication Tag, and the JWE AAD MUST be 773 successfully base64url decoded following the restriction that no 774 padding characters have been used. 776 3. The octet sequence resulting from decoding the encoded JWE 777 Protected Header MUST be a UTF-8 encoded representation of a 778 completely valid JSON object conforming to RFC 7159 [RFC7159], 779 which is the JWE Protected Header. 781 4. If using the JWE Compact Serialization, let the JOSE Header be 782 the JWE Protected Header. Otherwise, when using the JWE JSON 783 Serialization, let the JOSE Header be the union of the members 784 of the JWE Protected Header, the JWE Shared Unprotected Header 785 and the corresponding JWE Per-Recipient Unprotected Header, all 786 of which must be completely valid JSON objects. 788 5. The resulting JOSE Header MUST NOT contain duplicate Header 789 Parameter names. When using the JWE JSON Serialization, this 790 restriction includes that the same Header Parameter name also 791 MUST NOT occur in distinct JSON object values that together 792 comprise the JOSE Header. 794 6. Verify that the implementation understands and can process all 795 fields that it is required to support, whether required by this 796 specification, by the algorithms being used, or by the "crit" 797 Header Parameter value, and that the values of those parameters 798 are also understood and supported. 800 7. Determine the Key Management Mode employed by the algorithm 801 specified by the "alg" (algorithm) Header Parameter. 803 8. Verify that the JWE uses a key known to the recipient. 805 9. When Direct Key Agreement or Key Agreement with Key Wrapping are 806 employed, use the key agreement algorithm to compute the value 807 of the agreed upon key. When Direct Key Agreement is employed, 808 let the Content Encryption Key (CEK) be the agreed upon key. 809 When Key Agreement with Key Wrapping is employed, the agreed 810 upon key will be used to decrypt the JWE Encrypted Key. 812 10. When Key Wrapping, Key Encryption, or Key Agreement with Key 813 Wrapping are employed, decrypt the JWE Encrypted Key to produce 814 the Content Encryption Key (CEK). The CEK MUST have a length 815 equal to that required for the content encryption algorithm. 816 Note that when there are multiple recipients, each recipient 817 will only be able decrypt any JWE Encrypted Key values that were 818 encrypted to a key in that recipient's possession. It is 819 therefore normal to only be able to decrypt one of the per- 820 recipient JWE Encrypted Key values to obtain the CEK value. 821 Also, see Section 11.5 for security considerations on mitigating 822 timing attacks. 824 11. When Direct Key Agreement or Direct Encryption are employed, 825 verify that the JWE Encrypted Key value is empty octet sequence. 827 12. When Direct Encryption is employed, let the Content Encryption 828 Key (CEK) be the shared symmetric key. 830 13. Record whether the CEK could be successfully determined for this 831 recipient or not. 833 14. If the JWE JSON Serialization is being used, repeat this process 834 (steps 4-13) for each recipient contained in the representation. 836 15. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 837 Protected Header)). If the JWE Protected Header is not present 838 (which can only happen when using the JWE JSON Serialization and 839 no "protected" member is present), let this value be the empty 840 string. 842 16. Let the Additional Authenticated Data encryption parameter be 843 ASCII(Encoded Protected Header). However if a JWE AAD value is 844 present (which can only be the case when using the JWE JSON 845 Serialization), instead let the Additional Authenticated Data 846 encryption parameter be ASCII(Encoded Protected Header || '.' || 847 BASE64URL(JWE AAD)). 849 17. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 850 Vector, the Additional Authenticated Data value, and the JWE 851 Authentication Tag (which is the Authentication Tag input to the 852 calculation) using the specified content encryption algorithm, 853 returning the decrypted plaintext and validating the JWE 854 Authentication Tag in the manner specified for the algorithm, 855 rejecting the input without emitting any decrypted output if the 856 JWE Authentication Tag is incorrect. 858 18. If a "zip" parameter was included, uncompress the decrypted 859 plaintext using the specified compression algorithm. 861 19. If there was no recipient for which all of the decryption steps 862 succeeded, then the JWE MUST be rejected. Otherwise, output the 863 Plaintext. In the JWE JSON Serialization case, also return a 864 result to the application indicating for which of the recipients 865 the decryption succeeded and failed. 867 Finally, note that it is an application decision which algorithms are 868 acceptable in a given context. Even if a JWE can be successfully 869 decrypted, unless the algorithms used in the JWE are acceptable to 870 the application, it SHOULD reject the JWE. 872 5.3. String Comparison Rules 874 The string comparison rules for this specification are the same as 875 those defined in Section 5.3 of [JWS]. 877 6. Key Identification 879 The key identification methods for this specification are the same as 880 those defined in Section 6 of [JWS], except that the key being 881 identified is the public key to which the JWE was encrypted. 883 7. Serializations 885 JWE objects use one of two serializations, the JWE Compact 886 Serialization or the JWE JSON Serialization. Applications using this 887 specification need to specify what serialization and serialization 888 features are used for that application. For instance, applications 889 might specify that only the JWE JSON Serialization is used, that only 890 JWE JSON Serialization support for a single recipient is used, or 891 that support for multiple recipients is used. JWE implementations 892 only need to implement the features needed for the applications they 893 are designed to support. 895 7.1. JWE Compact Serialization 897 The JWE Compact Serialization represents encrypted content as a 898 compact, URL-safe string. This string is: 900 BASE64URL(UTF8(JWE Protected Header)) || '.' || 901 BASE64URL(JWE Encrypted Key) || '.' || 902 BASE64URL(JWE Initialization Vector) || '.' || 903 BASE64URL(JWE Ciphertext) || '.' || 904 BASE64URL(JWE Authentication Tag) 906 Only one recipient is supported by the JWE Compact Serialization and 907 it provides no syntax to represent JWE Shared Unprotected Header, JWE 908 Per-Recipient Unprotected Header, or JWE AAD values. 910 7.2. JWE JSON Serialization 912 The JWE JSON Serialization represents encrypted content as a JSON 913 object. Content using the JWE JSON Serialization can be encrypted to 914 more than one recipient. This representation is neither optimized 915 for compactness nor URL-safe. 917 The following members are defined for use in top-level JSON objects 918 used for the JWE JSON Serialization: 920 protected 921 The "protected" member MUST be present and contain the value 922 BASE64URL(UTF8(JWE Protected Header)) when the JWE Protected 923 Header value is non-empty; otherwise, it MUST be absent. These 924 Header Parameter values are integrity protected. 926 unprotected 927 The "unprotected" member MUST be present and contain the value JWE 928 Shared Unprotected Header when the JWE Shared Unprotected Header 929 value is non-empty; otherwise, it MUST be absent. This value is 930 represented as an unencoded JSON object, rather than as a string. 931 These Header Parameter values are not integrity protected. 933 iv 934 The "iv" member MUST be present and contain the value 935 BASE64URL(JWE Initialization Vector) when the JWE Initialization 936 Vector value is non-empty; otherwise, it MUST be absent. 938 aad 939 The "aad" member MUST be present and contain the value 940 BASE64URL(JWE AAD)) when the JWE AAD value is non-empty; 941 otherwise, it MUST be absent. A JWE AAD value can be included to 942 supply a base64url encoded value to be integrity protected but not 943 encrypted. 945 ciphertext 946 The "ciphertext" member MUST be present and contain the value 947 BASE64URL(JWE Ciphertext). 949 tag 950 The "tag" member MUST be present and contain the value 951 BASE64URL(JWE Authentication Tag) when the JWE Authentication Tag 952 value is non-empty; otherwise, it MUST be absent. 954 recipients 955 The "recipients" member value MUST be an array of JSON objects. 956 Each object contains information specific to a single recipient. 957 This member MUST be present, even if the array elements contain 958 only the empty JSON object "{}" (which can happen when all Header 959 Parameter values are shared between all recipients and when no 960 encrypted key is used, such as when doing Direct Encryption). 962 The following members are defined for use in the JSON objects that 963 are elements of the "recipients" array: 965 header 966 The "header" member MUST be present and contain the value JWE Per- 967 Recipient Unprotected Header when the JWE Per-Recipient 968 Unprotected Header value is non-empty; otherwise, it MUST be 969 absent. This value is represented as an unencoded JSON object, 970 rather than as a string. These Header Parameter values are not 971 integrity protected. 973 encrypted_key 974 The "encrypted_key" member MUST be present and contain the value 975 BASE64URL(JWE Encrypted Key) when the JWE Encrypted Key value is 976 non-empty; otherwise, it MUST be absent. 978 At least one of the "header", "protected", and "unprotected" members 979 MUST be present so that "alg" and "enc" Header Parameter values are 980 conveyed for each recipient computation. 982 Additional members can be present in both the JSON objects defined 983 above; if not understood by implementations encountering them, they 984 MUST be ignored. 986 Some Header Parameters, including the "alg" parameter, can be shared 987 among all recipient computations. Header Parameters in the JWE 988 Protected Header and JWE Shared Unprotected Header values are shared 989 among all recipients. 991 The Header Parameter values used when creating or validating per- 992 recipient Ciphertext and Authentication Tag values are the union of 993 the three sets of Header Parameter values that may be present: (1) 994 the JWE Protected Header represented in the "protected" member, (2) 995 the JWE Shared Unprotected Header represented in the "unprotected" 996 member, and (3) the JWE Per-Recipient Unprotected Header represented 997 in the "header" member of the recipient's array element. The union 998 of these sets of Header Parameters comprises the JOSE Header. The 999 Header Parameter names in the three locations MUST be disjoint. 1001 Each JWE Encrypted Key value is computed using the parameters of the 1002 corresponding JOSE Header value in the same manner as for the JWE 1003 Compact Serialization. This has the desirable property that each JWE 1004 Encrypted Key value in the "recipients" array is identical to the 1005 value that would have been computed for the same parameter in the JWE 1006 Compact Serialization. Likewise, the JWE Ciphertext and JWE 1007 Authentication Tag values match those produced for the JWE Compact 1008 Serialization, provided that the JWE Protected Header value (which 1009 represents the integrity-protected Header Parameter values) matches 1010 that used in the JWE Compact Serialization. 1012 All recipients use the same JWE Protected Header, JWE Initialization 1013 Vector, JWE Ciphertext, and JWE Authentication Tag values, when 1014 present, resulting in potentially significant space savings if the 1015 message is large. Therefore, all Header Parameters that specify the 1016 treatment of the Plaintext value MUST be the same for all recipients. 1017 This primarily means that the "enc" (encryption algorithm) Header 1018 Parameter value in the JOSE Header for each recipient and any 1019 parameters of that algorithm MUST be the same. 1021 In summary, the syntax of a JWE using the JWE JSON Serialization is 1022 as follows: 1024 {"protected":"", 1025 "unprotected":, 1026 "recipients":[ 1027 {"header":, 1028 "encrypted_key":""}, 1029 ... 1030 {"header":, 1031 "encrypted_key":""}], 1032 "aad":"", 1033 "iv":"", 1034 "ciphertext":"", 1035 "tag":"" 1036 } 1038 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1039 Serialization. 1041 8. TLS Requirements 1043 The TLS requirements for this specification are the same as those 1044 defined in Section 8 of [JWS]. 1046 9. Distinguishing between JWS and JWE Objects 1048 There are several ways of distinguishing whether an object is a JWS 1049 or JWE object. All these methods will yield the same result for all 1050 legal input values; they may yield different results for malformed 1051 inputs. 1053 o If the object is using the JWS Compact Serialization or the JWE 1054 Compact Serialization, the number of base64url encoded segments 1055 separated by period ('.') characters differs for JWSs and JWEs. 1056 JWSs have three segments separated by two period ('.') characters. 1057 JWEs have five segments separated by four period ('.') characters. 1059 o If the object is using the JWS JSON Serialization or the JWE JSON 1060 Serialization, the members used will be different. JWSs have a 1061 "signatures" member and JWEs do not. JWEs have a "recipients" 1062 member and JWSs do not. 1064 o The JOSE Header for a JWS object can be distinguished from the 1065 JOSE Header for a JWE object by examining the "alg" (algorithm) 1066 Header Parameter value. If the value represents a digital 1067 signature or MAC algorithm, or is the value "none", it is for a 1068 JWS; if it represents a Key Encryption, Key Wrapping, Direct Key 1069 Agreement, Key Agreement with Key Wrapping, or Direct Encryption 1070 algorithm, it is for a JWE. (Extracting the "alg" value to 1071 examine is straightforward when using the JWS Compact 1072 Serialization or the JWE Compact Serialization and may be more 1073 difficult when using the JWS JSON Serialization or the JWE JSON 1074 Serialization.) 1076 o The JOSE Header for a JWS object can also be distinguished from 1077 the JOSE Header for a JWE object by determining whether an "enc" 1078 (encryption algorithm) member exists. If the "enc" member exists, 1079 it is a JWE; otherwise, it is a JWS. 1081 10. IANA Considerations 1083 10.1. JSON Web Signature and Encryption Header Parameters Registration 1085 This specification registers the Header Parameter names defined in 1086 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1087 Parameters registry defined in [JWS]. 1089 10.1.1. Registry Contents 1091 o Header Parameter Name: "alg" 1092 o Header Parameter Description: Algorithm 1093 o Header Parameter Usage Location(s): JWE 1094 o Change Controller: IESG 1095 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1097 o Header Parameter Name: "enc" 1098 o Header Parameter Description: Encryption Algorithm 1099 o Header Parameter Usage Location(s): JWE 1100 o Change Controller: IESG 1101 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1103 o Header Parameter Name: "zip" 1104 o Header Parameter Description: Compression Algorithm 1105 o Header Parameter Usage Location(s): JWE 1106 o Change Controller: IESG 1107 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1109 o Header Parameter Name: "jku" 1110 o Header Parameter Description: JWK Set URL 1111 o Header Parameter Usage Location(s): JWE 1112 o Change Controller: IESG 1113 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1115 o Header Parameter Name: "jwk" 1116 o Header Parameter Description: JSON Web Key 1117 o Header Parameter Usage Location(s): JWE 1118 o Change Controller: IESG 1119 o Specification document(s): Section 4.1.5 of [[ this document ]] 1121 o Header Parameter Name: "kid" 1122 o Header Parameter Description: Key ID 1123 o Header Parameter Usage Location(s): JWE 1124 o Change Controller: IESG 1125 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1127 o Header Parameter Name: "x5u" 1128 o Header Parameter Description: X.509 URL 1129 o Header Parameter Usage Location(s): JWE 1130 o Change Controller: IESG 1131 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1133 o Header Parameter Name: "x5c" 1134 o Header Parameter Description: X.509 Certificate Chain 1135 o Header Parameter Usage Location(s): JWE 1136 o Change Controller: IESG 1137 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1139 o Header Parameter Name: "x5t" 1140 o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint 1141 o Header Parameter Usage Location(s): JWE 1142 o Change Controller: IESG 1143 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1144 o Header Parameter Name: "x5t#S256" 1145 o Header Parameter Description: X.509 Certificate SHA-256 Thumbprint 1146 o Header Parameter Usage Location(s): JWE 1147 o Change Controller: IESG 1148 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1150 o Header Parameter Name: "typ" 1151 o Header Parameter Description: Type 1152 o Header Parameter Usage Location(s): JWE 1153 o Change Controller: IESG 1154 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1156 o Header Parameter Name: "cty" 1157 o Header Parameter Description: Content Type 1158 o Header Parameter Usage Location(s): JWE 1159 o Change Controller: IESG 1160 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1162 o Header Parameter Name: "crit" 1163 o Header Parameter Description: Critical 1164 o Header Parameter Usage Location(s): JWE 1165 o Change Controller: IESG 1166 o Specification Document(s): Section 4.1.13 of [[ this document ]] 1168 11. Security Considerations 1170 All of the security issues that are pertinent to any cryptographic 1171 application must be addressed by JWS/JWE/JWK agents. Among these 1172 issues are protecting the user's asymmetric private and symmetric 1173 secret keys and employing countermeasures to various attacks. 1175 All the security considerations in the JWS specification also apply 1176 to this specification. Likewise, all the security considerations in 1177 XML Encryption 1.1 [W3C.REC-xmlenc-core1-20130411] also apply, other 1178 than those that are XML specific. 1180 11.1. Key Entropy and Random Values 1182 See Section 10.1 of [JWS] for security considerations on key entropy 1183 and random values. In addition to the uses of random values listed 1184 there, note that random values are also used for content encryption 1185 keys (CEKs) and initialization vectors (IVs) when performing 1186 encryption. 1188 11.2. Key Protection 1190 See Section 10.2 of [JWS] for security considerations on key 1191 protection. In addition to the keys listed there that must be 1192 protected, implementations performing encryption must protect the key 1193 encryption key and the content encryption key. Compromise of the key 1194 encryption key may result in the disclosure of all contents protected 1195 with that key. Similarly, compromise of the content encryption key 1196 may result in disclosure of the associated encrypted content. 1198 11.3. Using Matching Algorithm Strengths 1200 Algorithms of matching strengths should be used together whenever 1201 possible. For instance, when AES Key Wrap is used with a given key 1202 size, using the same key size is recommended when AES GCM is also 1203 used. If the key encryption and content encryption algorithms are 1204 different, the effective security is determined by the weaker of the 1205 two algorithms. 1207 Also, see RFC 3766 [RFC3766] for information on determining strengths 1208 for public keys used for exchanging symmetric keys. 1210 11.4. Adaptive Chosen-Ciphertext Attacks 1212 When decrypting, particular care must be taken not to allow the JWE 1213 recipient to be used as an oracle for decrypting messages. RFC 3218 1214 [RFC3218] should be consulted for specific countermeasures to attacks 1215 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1216 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1217 formatting error that can be detected and used to recover the CEK 1218 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1219 particularly important to report all formatting errors to the CEK, 1220 Additional Authenticated Data, or ciphertext as a single error when 1221 the encrypted content is rejected. 1223 Additionally, this type of attack can be prevented by restricting the 1224 use of a key to a limited set of algorithms -- usually one. This 1225 means, for instance, that if the key is marked as being for 1226 "RSA-OAEP" only, any attempt to decrypt a message using the "RSA1_5" 1227 algorithm with that key should fail immediately due to invalid use of 1228 the key. 1230 11.5. Timing Attacks 1232 To mitigate the attacks described in RFC 3218 [RFC3218], the 1233 recipient MUST NOT distinguish between format, padding, and length 1234 errors of encrypted keys. It is strongly recommended, in the event 1235 of receiving an improperly formatted key, that the receiver 1236 substitute a randomly generated CEK and proceed to the next step, to 1237 mitigate timing attacks. 1239 12. References 1241 12.1. Normative References 1243 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1244 draft-ietf-jose-json-web-algorithms (work in progress), 1245 September 2014. 1247 [JWK] Jones, M., "JSON Web Key (JWK)", 1248 draft-ietf-jose-json-web-key (work in progress), 1249 September 2014. 1251 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1252 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1253 in progress), September 2014. 1255 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1256 version 1.3", RFC 1951, May 1996. 1258 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1259 Requirement Levels", BCP 14, RFC 2119, March 1997. 1261 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1262 10646", STD 63, RFC 3629, November 2003. 1264 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1265 Housley, R., and W. Polk, "Internet X.509 Public Key 1266 Infrastructure Certificate and Certificate Revocation List 1267 (CRL) Profile", RFC 5280, May 2008. 1269 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1270 Interchange Format", RFC 7159, March 2014. 1272 [USASCII] American National Standards Institute, "Coded Character 1273 Set -- 7-bit American Standard Code for Information 1274 Interchange", ANSI X3.4, 1986. 1276 12.2. Informative References 1278 [AES] National Institute of Standards and Technology (NIST), 1279 "Advanced Encryption Standard (AES)", FIPS PUB 197, 1280 November 2001. 1282 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1283 McGrew, D., Foley, J., and K. Paterson, "Authenticated 1284 Encryption with AES-CBC and HMAC-SHA", 1285 draft-mcgrew-aead-aes-cbc-hmac-sha2-05 (work in progress), 1286 July 2014. 1288 [I-D.rescorla-jsms] 1289 Rescorla, E. and J. Hildebrand, "JavaScript Message 1290 Security Format", draft-rescorla-jsms-00 (work in 1291 progress), March 2011. 1293 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1294 Encryption", September 2010. 1296 [NIST.800-38D] 1297 National Institute of Standards and Technology (NIST), 1298 "Recommendation for Block Cipher Modes of Operation: 1299 Galois/Counter Mode (GCM) and GMAC", NIST PUB 800-38D, 1300 December 2001. 1302 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1303 Cryptographic Message Syntax", RFC 3218, January 2002. 1305 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1306 Standards (PKCS) #1: RSA Cryptography Specifications 1307 Version 2.1", RFC 3447, February 2003. 1309 [RFC3766] Orman, H. and P. Hoffman, "Determining Strengths For 1310 Public Keys Used For Exchanging Symmetric Keys", BCP 86, 1311 RFC 3766, April 2004. 1313 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1314 Requirements for Security", BCP 106, RFC 4086, June 2005. 1316 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1317 RFC 5652, September 2009. 1319 [W3C.REC-xmlenc-core1-20130411] 1320 Eastlake, D., Reagle, J., Hirsch, F., and T. Roessler, 1321 "XML Encryption Syntax and Processing Version 1.1", World 1322 Wide Web Consortium Recommendation REC-xmlenc-core1- 1323 20130411, April 2013, 1324 . 1326 Appendix A. JWE Examples 1328 This section provides examples of JWE computations. 1330 A.1. Example JWE using RSAES OAEP and AES GCM 1332 This example encrypts the plaintext "The true sign of intelligence is 1333 not knowledge but imagination." to the recipient using RSAES OAEP for 1334 key encryption and AES GCM for content encryption. The 1335 representation of this plaintext (using JSON array notation) is: 1337 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1338 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1339 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1340 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1341 110, 97, 116, 105, 111, 110, 46] 1343 A.1.1. JOSE Header 1345 The following example JWE Protected Header declares that: 1347 o the Content Encryption Key is encrypted to the recipient using the 1348 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1350 o authenticated encryption is performed on the Plaintext using the 1351 AES GCM algorithm with a 256 bit key to produce the Ciphertext and 1352 the Authentication Tag. 1354 {"alg":"RSA-OAEP","enc":"A256GCM"} 1356 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1357 Header)) gives this value: 1359 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1361 A.1.2. Content Encryption Key (CEK) 1363 Generate a 256 bit random Content Encryption Key (CEK). In this 1364 example, the value (using JSON array notation) is: 1366 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1367 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1368 234, 64, 252] 1370 A.1.3. Key Encryption 1372 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1373 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1374 key represented in JSON Web Key [JWK] format below (with line breaks 1375 within values for display purposes only): 1377 {"kty":"RSA", 1378 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1379 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1380 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1381 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1382 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1383 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1384 "e":"AQAB", 1385 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1386 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1387 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1388 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1389 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1390 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ" 1391 } 1393 The resulting JWE Encrypted Key value is: 1395 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1396 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1397 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1398 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1399 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1400 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1401 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1402 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1403 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1404 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1405 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1406 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1407 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1408 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1409 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1410 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1411 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1412 117, 114, 135, 206] 1414 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1415 this value (with line breaks for display purposes only): 1417 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1418 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1419 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1420 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1421 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1422 6UklfCpIMfIjf7iGdXKHzg 1424 A.1.4. Initialization Vector 1426 Generate a random 96 bit JWE Initialization Vector. In this example, 1427 the value is: 1429 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1431 Encoding this JWE Initialization Vector as BASE64URL(JWE 1432 Initialization Vector) gives this value: 1434 48V1_ALb6US04U3b 1436 A.1.5. Additional Authenticated Data 1438 Let the Additional Authenticated Data encryption parameter be 1439 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1441 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1442 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1443 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1445 A.1.6. Content Encryption 1447 Perform authenticated encryption on the Plaintext with the AES GCM 1448 algorithm using the CEK as the encryption key, the JWE Initialization 1449 Vector, and the Additional Authenticated Data value above, requesting 1450 a 128 bit Authentication Tag output. The resulting Ciphertext is: 1452 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1453 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1454 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1455 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1456 160, 109, 64, 63, 192] 1458 The resulting Authentication Tag value is: 1460 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1461 210, 145] 1463 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1464 value (with line breaks for display purposes only): 1466 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1467 SdiwkIr3ajwQzaBtQD_A 1469 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1470 Tag) gives this value: 1472 XFBoMYUZodetZdvTiFvSkQ 1474 A.1.7. Complete Representation 1476 Assemble the final representation: The Compact Serialization of this 1477 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1478 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1479 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1480 Authentication Tag). 1482 The final result in this example (with line breaks for display 1483 purposes only) is: 1485 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1486 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1487 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1488 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1489 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1490 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1491 6UklfCpIMfIjf7iGdXKHzg. 1492 48V1_ALb6US04U3b. 1493 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1494 SdiwkIr3ajwQzaBtQD_A. 1495 XFBoMYUZodetZdvTiFvSkQ 1497 A.1.8. Validation 1499 This example illustrates the process of creating a JWE with RSAES 1500 OAEP for key encryption and AES GCM for content encryption. These 1501 results can be used to validate JWE decryption implementations for 1502 these algorithms. Note that since the RSAES OAEP computation 1503 includes random values, the encryption results above will not be 1504 completely reproducible. However, since the AES GCM computation is 1505 deterministic, the JWE Encrypted Ciphertext values will be the same 1506 for all encryptions performed using these inputs. 1508 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1510 This example encrypts the plaintext "Live long and prosper." to the 1511 recipient using RSAES-PKCS1-V1_5 for key encryption and 1512 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1513 of this plaintext (using JSON array notation) is: 1515 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1516 112, 114, 111, 115, 112, 101, 114, 46] 1518 A.2.1. JOSE Header 1520 The following example JWE Protected Header declares that: 1522 o the Content Encryption Key is encrypted to the recipient using the 1523 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1525 o authenticated encryption is performed on the Plaintext using the 1526 AES_128_CBC_HMAC_SHA_256 algorithm to produce the Ciphertext and 1527 the Authentication Tag. 1529 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1531 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1532 Header)) gives this value: 1534 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1536 A.2.2. Content Encryption Key (CEK) 1538 Generate a 256 bit random Content Encryption Key (CEK). In this 1539 example, the key value is: 1541 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1542 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1543 44, 207] 1545 A.2.3. Key Encryption 1547 Encrypt the CEK with the recipient's public key using the RSAES- 1548 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1549 uses the RSA key represented in JSON Web Key [JWK] format below (with 1550 line breaks within values for display purposes only): 1552 {"kty":"RSA", 1553 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1554 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1555 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1556 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1557 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1558 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1559 "e":"AQAB", 1560 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1561 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1562 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1563 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1564 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1565 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1566 } 1568 The resulting JWE Encrypted Key value is: 1570 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1571 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1572 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1573 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1574 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1575 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1576 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1577 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1578 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1579 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1580 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1581 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1582 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1583 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1584 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1585 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1586 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1587 146, 114, 165, 204, 71, 136, 41, 252] 1589 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1590 this value (with line breaks for display purposes only): 1592 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1593 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1594 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1595 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1596 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1597 -B3oWh2TbqmScqXMR4gp_A 1599 A.2.4. Initialization Vector 1601 Generate a random 128 bit JWE Initialization Vector. In this 1602 example, the value is: 1604 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1605 101] 1607 Encoding this JWE Initialization Vector as BASE64URL(JWE 1608 Initialization Vector) gives this value: 1610 AxY8DCtDaGlsbGljb3RoZQ 1612 A.2.5. Additional Authenticated Data 1614 Let the Additional Authenticated Data encryption parameter be 1615 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1617 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1618 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1619 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1620 50, 73, 110, 48] 1622 A.2.6. Content Encryption 1624 Perform authenticated encryption on the Plaintext with the 1625 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1626 key, the JWE Initialization Vector, and the Additional Authenticated 1627 Data value above. The steps for doing this using the values from 1628 Appendix A.3 are detailed in Appendix B. The resulting Ciphertext 1629 is: 1631 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1632 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1633 112, 56, 102] 1635 The resulting Authentication Tag value is: 1637 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1638 191] 1640 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1641 value: 1643 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1645 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1646 Tag) gives this value: 1648 9hH0vgRfYgPnAHOd8stkvw 1650 A.2.7. Complete Representation 1652 Assemble the final representation: The Compact Serialization of this 1653 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1654 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1655 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1656 Authentication Tag). 1658 The final result in this example (with line breaks for display 1659 purposes only) is: 1661 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1662 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1663 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1664 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1665 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1666 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1667 -B3oWh2TbqmScqXMR4gp_A. 1668 AxY8DCtDaGlsbGljb3RoZQ. 1669 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1670 9hH0vgRfYgPnAHOd8stkvw 1672 A.2.8. Validation 1674 This example illustrates the process of creating a JWE with RSAES- 1675 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1676 encryption. These results can be used to validate JWE decryption 1677 implementations for these algorithms. Note that since the RSAES- 1678 PKCS1-V1_5 computation includes random values, the encryption results 1679 above will not be completely reproducible. However, since the AES 1680 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1681 will be the same for all encryptions performed using these inputs. 1683 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1685 This example encrypts the plaintext "Live long and prosper." to the 1686 recipient using AES Key Wrap for key encryption and 1687 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1688 of this plaintext (using JSON array notation) is: 1690 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1691 112, 114, 111, 115, 112, 101, 114, 46] 1693 A.3.1. JOSE Header 1695 The following example JWE Protected Header declares that: 1697 o the Content Encryption Key is encrypted to the recipient using the 1698 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1699 Encrypted Key and 1701 o authenticated encryption is performed on the Plaintext using the 1702 AES_128_CBC_HMAC_SHA_256 algorithm to produce the Ciphertext and 1703 the Authentication Tag. 1705 {"alg":"A128KW","enc":"A128CBC-HS256"} 1707 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1708 Header)) gives this value: 1710 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1712 A.3.2. Content Encryption Key (CEK) 1714 Generate a 256 bit random Content Encryption Key (CEK). In this 1715 example, the value is: 1717 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1718 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1719 44, 207] 1721 A.3.3. Key Encryption 1723 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1724 algorithm to produce the JWE Encrypted Key. This example uses the 1725 symmetric key represented in JSON Web Key [JWK] format below: 1727 {"kty":"oct", 1728 "k":"GawgguFyGrWKav7AX4VKUg" 1729 } 1731 The resulting JWE Encrypted Key value is: 1733 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1734 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1735 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1737 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1738 this value: 1740 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1742 A.3.4. Initialization Vector 1744 Generate a random 128 bit JWE Initialization Vector. In this 1745 example, the value is: 1747 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1748 101] 1750 Encoding this JWE Initialization Vector as BASE64URL(JWE 1751 Initialization Vector) gives this value: 1753 AxY8DCtDaGlsbGljb3RoZQ 1755 A.3.5. Additional Authenticated Data 1757 Let the Additional Authenticated Data encryption parameter be 1758 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1760 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1761 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1762 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1763 110, 48] 1765 A.3.6. Content Encryption 1767 Perform authenticated encryption on the Plaintext with the 1768 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1769 key, the JWE Initialization Vector, and the Additional Authenticated 1770 Data value above. The steps for doing this using the values from 1771 this example are detailed in Appendix B. The resulting Ciphertext 1772 is: 1774 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1775 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1776 112, 56, 102] 1778 The resulting Authentication Tag value is: 1780 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1781 194, 85] 1783 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1784 value: 1786 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1788 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1789 Tag) gives this value: 1791 U0m_YmjN04DJvceFICbCVQ 1793 A.3.7. Complete Representation 1795 Assemble the final representation: The Compact Serialization of this 1796 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1797 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1798 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1799 Authentication Tag). 1801 The final result in this example (with line breaks for display 1802 purposes only) is: 1804 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1805 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1806 AxY8DCtDaGlsbGljb3RoZQ. 1807 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1808 U0m_YmjN04DJvceFICbCVQ 1810 A.3.8. Validation 1812 This example illustrates the process of creating a JWE with AES Key 1813 Wrap for key encryption and AES GCM for content encryption. These 1814 results can be used to validate JWE decryption implementations for 1815 these algorithms. Also, since both the AES Key Wrap and AES GCM 1816 computations are deterministic, the resulting JWE value will be the 1817 same for all encryptions performed using these inputs. Since the 1818 computation is reproducible, these results can also be used to 1819 validate JWE encryption implementations for these algorithms. 1821 A.4. Example JWE using JWE JSON Serialization 1823 This section contains an example using the JWE JSON Serialization. 1824 This example demonstrates the capability for encrypting the same 1825 plaintext to multiple recipients. 1827 Two recipients are present in this example. The algorithm and key 1828 used for the first recipient are the same as that used in 1829 Appendix A.2. The algorithm and key used for the second recipient 1830 are the same as that used in Appendix A.3. The resulting JWE 1831 Encrypted Key values are therefore the same; those computations are 1832 not repeated here. 1834 The Plaintext, the Content Encryption Key (CEK), JWE Initialization 1835 Vector, and JWE Protected Header are shared by all recipients (which 1836 must be the case, since the Ciphertext and Authentication Tag are 1837 also shared). 1839 A.4.1. JWE Per-Recipient Unprotected Headers 1841 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1842 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1843 encrypt the CEK. Key ID values are supplied for both keys. The two 1844 per-recipient header values used to represent these algorithms and 1845 Key IDs are: 1847 {"alg":"RSA1_5","kid":"2011-04-29"} 1849 and 1851 {"alg":"A128KW","kid":"7"} 1853 A.4.2. JWE Protected Header 1855 Authenticated encryption is performed on the Plaintext using the 1856 AES_128_CBC_HMAC_SHA_256 algorithm to produce the common JWE 1857 Ciphertext and JWE Authentication Tag values. The JWE Protected 1858 Header value representing this is: 1860 {"enc":"A128CBC-HS256"} 1862 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1863 Header)) gives this value: 1865 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1867 A.4.3. JWE Unprotected Header 1869 This JWE uses the "jku" Header Parameter to reference a JWK Set. This 1870 is represented in the following JWE Unprotected Header value as: 1872 {"jku":"https://server.example.com/keys.jwks"} 1874 A.4.4. Complete JOSE Header Values 1876 Combining the per-recipient, protected, and unprotected header values 1877 supplied, the JOSE Header values used for the first and second 1878 recipient respectively are: 1880 {"alg":"RSA1_5", 1881 "kid":"2011-04-29", 1882 "enc":"A128CBC-HS256", 1883 "jku":"https://server.example.com/keys.jwks"} 1885 and 1887 {"alg":"A128KW", 1888 "kid":"7", 1889 "enc":"A128CBC-HS256", 1890 "jku":"https://server.example.com/keys.jwks"} 1892 A.4.5. Additional Authenticated Data 1894 Let the Additional Authenticated Data encryption parameter be 1895 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1897 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1898 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1900 A.4.6. Content Encryption 1902 Perform authenticated encryption on the Plaintext with the 1903 AES_128_CBC_HMAC_SHA_256 algorithm using the CEK as the encryption 1904 key, the JWE Initialization Vector, and the Additional Authenticated 1905 Data value above. The steps for doing this using the values from 1906 Appendix A.3 are detailed in Appendix B. The resulting Ciphertext 1907 is: 1909 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1910 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1911 112, 56, 102] 1913 The resulting Authentication Tag value is: 1915 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1916 207] 1918 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1919 value: 1921 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1923 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1924 Tag) gives this value: 1926 Mz-VPPyU4RlcuYv1IwIvzw 1928 A.4.7. Complete JWE JSON Serialization Representation 1930 The complete JSON Web Encryption JSON Serialization for these values 1931 is as follows (with line breaks within values for display purposes 1932 only): 1934 {"protected": 1935 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1936 "unprotected": 1937 {"jku":"https://server.example.com/keys.jwks"}, 1938 "recipients":[ 1939 {"header": 1940 {"alg":"RSA1_5","kid":"2011-04-29"}, 1941 "encrypted_key": 1942 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1943 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1944 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 1945 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 1946 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 1947 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 1948 {"header": 1949 {"alg":"A128KW","kid":"7"}, 1950 "encrypted_key": 1951 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1952 "iv": 1953 "AxY8DCtDaGlsbGljb3RoZQ", 1954 "ciphertext": 1955 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1956 "tag": 1957 "Mz-VPPyU4RlcuYv1IwIvzw" 1958 } 1960 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 1962 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 1963 authenticated encryption computation using the values from the 1964 example in Appendix A.3. As described where this algorithm is 1965 defined in Sections 5.2 and 5.2.3 of JWA, the AES_CBC_HMAC_SHA2 1966 family of algorithms are implemented using Advanced Encryption 1967 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #7 1968 padding to perform the encryption and an HMAC SHA-2 function to 1969 perform the integrity calculation - in this case, HMAC SHA-256. 1971 B.1. Extract MAC_KEY and ENC_KEY from Key 1973 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example 1974 (using JSON array notation) is: 1976 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1977 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1978 44, 207] 1980 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 1981 which is: 1983 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1984 206] 1986 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 1987 is: 1989 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 1990 207] 1992 Note that the MAC key comes before the encryption key in the input 1993 key K; this is in the opposite order of the algorithm names in the 1994 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 1996 B.2. Encrypt Plaintext to Create Ciphertext 1998 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 1999 using PKCS #7 padding using the ENC_KEY above. The Plaintext in this 2000 example is: 2002 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 2003 112, 114, 111, 115, 112, 101, 114, 46] 2005 The encryption result is as follows, which is the Ciphertext output: 2007 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 2008 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 2009 112, 56, 102] 2011 B.3. 64 Bit Big Endian Representation of AAD Length 2013 The Additional Authenticated Data (AAD) in this example is: 2015 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2016 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2017 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2018 110, 48] 2020 This AAD is 51 bytes long, which is 408 bits long. The octet string 2021 AL, which is the number of bits in AAD expressed as a big endian 64 2022 bit unsigned integer is: 2024 [0, 0, 0, 0, 0, 0, 1, 152] 2026 B.4. Initialization Vector Value 2028 The Initialization Vector value used in this example is: 2030 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 2031 101] 2033 B.5. Create Input to HMAC Computation 2035 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 2036 the AL value. The result of this concatenation is: 2038 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2039 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2040 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2041 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 2042 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 2043 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 2044 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 2046 B.6. Compute HMAC Value 2048 Compute the HMAC SHA-256 of the concatenated value above. This 2049 result M is: 2051 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2052 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 2053 86, 229, 116] 2055 B.7. Truncate HMAC Value to Create Authentication Tag 2057 Use the first half (128 bits) of the HMAC output M as the 2058 Authentication Tag output T. This truncated value is: 2060 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2061 194, 85] 2063 Appendix C. Acknowledgements 2065 Solutions for encrypting JSON content were also explored by JSON 2066 Simple Encryption [JSE] and JavaScript Message Security Format 2067 [I-D.rescorla-jsms], both of which significantly influenced this 2068 draft. This draft attempts to explicitly reuse as many of the 2069 relevant concepts from XML Encryption 1.1 2070 [W3C.REC-xmlenc-core1-20130411] and RFC 5652 [RFC5652] as possible, 2071 while utilizing simple, compact JSON-based data structures. 2073 Special thanks are due to John Bradley, Eric Rescorla, and Nat 2074 Sakimura for the discussions that helped inform the content of this 2075 specification, to Eric Rescorla and Joe Hildebrand for allowing the 2076 reuse of text from [I-D.rescorla-jsms] in this document, and to Eric 2077 Rescorla for co-authoring many drafts of this specification. 2079 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2080 Jay for validating the examples in this specification. 2082 This specification is the work of the JOSE Working Group, which 2083 includes dozens of active and dedicated participants. In particular, 2084 the following individuals contributed ideas, feedback, and wording 2085 that influenced this specification: 2087 Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick 2088 Hardt, Jeff Hodges, Russ Housley, Edmund Jay, Scott Kelly, Stephen 2089 Kent, James Manger, Matt Miller, Kathleen Moriarty, Tony Nadalin, 2090 Hideki Nara, Axel Nennker, Emmanuel Raviart, Eric Rescorla, Nat 2091 Sakimura, Jim Schaad, Hannes Tschofenig, and Sean Turner. 2093 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2094 Sean Turner, Stephen Farrell, and Kathleen Moriarty served as 2095 Security area directors during the creation of this specification. 2097 Appendix D. Document History 2099 [[ to be removed by the RFC Editor before publication as an RFC ]] 2101 -33 2103 o Noted that certificate thumbprints are also sometimes known as 2104 certificate fingerprints. 2106 o Changed to use the term "authenticated encryption" instead of 2107 "encryption", where appropriate. 2109 o Acknowledged additional contributors. 2111 -32 2113 o Addressed Gen-ART review comments by Russ Housley. 2115 o Addressed secdir review comments by Scott Kelly, Tero Kivinen, and 2116 Stephen Kent. 2118 -31 2119 o Updated the reference to draft-mcgrew-aead-aes-cbc-hmac-sha2. 2121 -30 2123 o Added subsection headings within the Overview section for the two 2124 serializations. 2126 o Added references and cleaned up the reference syntax in a few 2127 places. 2129 o Applied minor wording changes to the Security Considerations 2130 section and made other local editorial improvements. 2132 -29 2134 o Replaced the terms JWS Header, JWE Header, and JWT Header with a 2135 single JOSE Header term defined in the JWS specification. This 2136 also enabled a single Header Parameter definition to be used and 2137 reduced other areas of duplication between specifications. 2139 -28 2141 o Specified the use of PKCS #7 padding with AES CBC, rather than 2142 PKCS #5. (PKCS #7 is a superset of PKCS #5, and is appropriate 2143 for the 16 octet blocks used by AES CBC.) 2145 o Revised the introduction to the Security Considerations section. 2146 Also moved a security consideration item here from the JWA draft. 2148 -27 2150 o Described additional security considerations. 2152 o Added the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) header 2153 parameter. 2155 -26 2157 o Noted that octet sequences are depicted using JSON array notation. 2159 o Updated references, including to W3C specifications. 2161 -25 2163 o Corrected two external section number references that had changed. 2165 o Corrected a typo in an algorithm name in the prose of an example. 2167 -24 2169 o Corrected complete JSON Serialization example. 2171 o Replaced uses of the term "associated data" wherever it was used 2172 to refer to a data value with "additional authenticated data", 2173 since both terms were being used as synonyms, causing confusion. 2175 o Updated the JSON reference to RFC 7159. 2177 o Thanked Eric Rescorla for helping to author of most of the drafts 2178 of this specification and removed him from the current author 2179 list. 2181 -23 2183 o Corrected a use of the word "payload" to "plaintext". 2185 -22 2187 o Corrected RFC 2119 terminology usage. 2189 o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. 2191 -21 2193 o Changed some references from being normative to informative, 2194 addressing issue #90. 2196 o Applied review comments to the JSON Serialization section, 2197 addressing issue #178. 2199 -20 2201 o Made terminology definitions more consistent, addressing issue 2202 #165. 2204 o Restructured the JSON Serialization section to call out the 2205 parameters used in hanging lists, addressing issue #178. 2207 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 2208 addressing issue #90. 2210 -19 2212 o Reordered the key selection parameters. 2214 -18 2215 o Updated the mandatory-to-implement (MTI) language to say that 2216 applications using this specification need to specify what 2217 serialization and serialization features are used for that 2218 application, addressing issue #176. 2220 o Changes to address editorial and minor issues #89, #135, #165, 2221 #174, #175, #177, #179, and #180. 2223 o Used Header Parameter Description registry field. 2225 -17 2227 o Refined the "typ" and "cty" definitions to always be MIME Media 2228 Types, with the omission of "application/" prefixes recommended 2229 for brevity, addressing issue #50. 2231 o Updated the mandatory-to-implement (MTI) language to say that 2232 general-purpose implementations must implement the single 2233 recipient case for both serializations whereas special-purpose 2234 implementations can implement just one serialization if that meets 2235 the needs of the use cases the implementation is designed for, 2236 addressing issue #176. 2238 o Explicitly named all the logical components of a JWE and defined 2239 the processing rules and serializations in terms of those 2240 components, addressing issues #60, #61, and #62. 2242 o Replaced verbose repetitive phases such as "base64url encode the 2243 octets of the UTF-8 representation of X" with mathematical 2244 notation such as "BASE64URL(UTF8(X))". 2246 o Header Parameters and processing rules occurring in both JWS and 2247 JWE are now referenced in JWS by JWE, rather than duplicated, 2248 addressing issue #57. 2250 o Terms used in multiple documents are now defined in one place and 2251 incorporated by reference. Some lightly used or obvious terms 2252 were also removed. This addresses issue #58. 2254 -16 2256 o Changes to address editorial and minor issues #163, #168, #169, 2257 #170, #172, and #173. 2259 -15 2261 o Clarified that it is an application decision which recipients' 2262 encrypted content must successfully validate for the JWE to be 2263 accepted, addressing issue #35. 2265 o Changes to address editorial issues #34, #164, and #169. 2267 -14 2269 o Clarified that the "protected", "unprotected", "header", "iv", 2270 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2271 JSON Serialization when their values would be empty. Stated that 2272 the "recipients" array must always be present. 2274 -13 2276 o Added an "aad" (Additional Authenticated Data) member for the JWE 2277 JSON Serialization, enabling Additional Authenticated Data to be 2278 supplied that is not double base64url encoded, addressing issue 2279 #29. 2281 -12 2283 o Clarified that the "typ" and "cty" header parameters are used in 2284 an application-specific manner and have no effect upon the JWE 2285 processing. 2287 o Replaced the MIME types "application/jwe+json" and 2288 "application/jwe" with "application/jose+json" and 2289 "application/jose". 2291 o Stated that recipients MUST either reject JWEs with duplicate 2292 Header Parameter Names or use a JSON parser that returns only the 2293 lexically last duplicate member name. 2295 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2296 be with the algorithm descriptions that use them. 2298 o Added a Serializations section with parallel treatment of the JWE 2299 Compact Serialization and the JWE JSON Serialization and also 2300 moved the former Implementation Considerations content there. 2302 o Restored use of the term "AEAD". 2304 o Changed terminology from "block encryption" to "content 2305 encryption". 2307 -11 2309 o Added Key Identification section. 2311 o Removed the Encrypted Key value from the AAD computation since it 2312 is already effectively integrity protected by the encryption 2313 process. The AAD value now only contains the representation of 2314 the JWE Encrypted Header. 2316 o For the JWE JSON Serialization, enable Header Parameter values to 2317 be specified in any of three parameters: the "protected" member 2318 that is integrity protected and shared among all recipients, the 2319 "unprotected" member that is not integrity protected and shared 2320 among all recipients, and the "header" member that is not 2321 integrity protected and specific to a particular recipient. (This 2322 does not affect the JWE Compact Serialization, in which all Header 2323 Parameter values are in a single integrity protected JWE Header 2324 value.) 2326 o Shortened the names "authentication_tag" to "tag" and 2327 "initialization_vector" to "iv" in the JWE JSON Serialization, 2328 addressing issue #20. 2330 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2332 o Removed suggested compact serialization for multiple recipients. 2334 o Changed the MIME type name "application/jwe-js" to 2335 "application/jwe+json", addressing issue #22. 2337 o Tightened the description of the "crit" (critical) header 2338 parameter. 2340 -10 2342 o Changed the JWE processing rules for multiple recipients so that a 2343 single AAD value contains the header parameters and encrypted key 2344 values for all the recipients, enabling AES GCM to be safely used 2345 for multiple recipients. 2347 o Added an appendix suggesting a possible compact serialization for 2348 JWEs with multiple recipients. 2350 -09 2352 o Added JWE JSON Serialization, as specified by 2353 draft-jones-jose-jwe-json-serialization-04. 2355 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2356 parameter value. 2358 o Defined that the default action for header parameters that are not 2359 understood is to ignore them unless specifically designated as 2360 "MUST be understood" or included in the new "crit" (critical) 2361 header parameter list. This addressed issue #6. 2363 o Corrected "x5c" description. This addressed issue #12. 2365 o Changed from using the term "byte" to "octet" when referring to 8 2366 bit values. 2368 o Added Key Management Mode definitions to terminology section and 2369 used the defined terms to provide clearer key management 2370 instructions. This addressed issue #5. 2372 o Added text about preventing the recipient from behaving as an 2373 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2375 o Changed from using the term "Integrity Value" to "Authentication 2376 Tag". 2378 o Changed member name from "integrity_value" to "authentication_tag" 2379 in the JWE JSON Serialization. 2381 o Removed Initialization Vector from the AAD value since it is 2382 already integrity protected by all of the authenticated encryption 2383 algorithms specified in the JWA specification. 2385 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2386 and "A256CBC-HS512". The new algorithms perform the same 2387 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2388 but with the Initialization Vector and Authentication Tag values 2389 remaining separate from the Ciphertext value in the output 2390 representation. Also deleted the header parameters "epu" 2391 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2392 they are no longer used. 2394 -08 2396 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2397 since the term AEAD in the RFC 5116 sense implied the use of a 2398 particular data representation, rather than just referring to the 2399 class of algorithms that perform authenticated encryption with 2400 associated data. 2402 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2403 Tschofenig. Many of these simplified the terminology used. 2405 o Clarified statements of the form "This header parameter is 2406 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2408 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2409 Web Signature and Encryption Header Parameters registry. 2411 o Added seriesInfo information to Internet Draft references. 2413 -07 2415 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2417 o Updated values for example AES CBC calculations. 2419 o Made several local editorial changes to clean up loose ends left 2420 over from to the decision to only support block encryption methods 2421 providing integrity. One of these changes was to explicitly state 2422 that the "enc" (encryption method) algorithm must be an 2423 Authenticated Encryption algorithm with a specified key length. 2425 -06 2427 o Removed the "int" and "kdf" parameters and defined the new 2428 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2429 "A256CBC+HS512" to replace the former uses of AES CBC, which 2430 required the use of separate integrity and key derivation 2431 functions. 2433 o Included additional values in the Concat KDF calculation -- the 2434 desired output size and the algorithm value, and optionally 2435 PartyUInfo and PartyVInfo values. Added the optional header 2436 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2437 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2438 PartyVInfo). Updated the KDF examples accordingly. 2440 o Promoted Initialization Vector from being a header parameter to 2441 being a top-level JWE element. This saves approximately 16 bytes 2442 in the compact serialization, which is a significant savings for 2443 some use cases. Promoting the Initialization Vector out of the 2444 header also avoids repeating this shared value in the JSON 2445 serialization. 2447 o Changed "x5c" (X.509 Certificate Chain) representation from being 2448 a single string to being an array of strings, each containing a 2449 single base64 encoded DER certificate value, representing elements 2450 of the certificate chain. 2452 o Added an AES Key Wrap example. 2454 o Reordered the encryption steps so CMK creation is first, when 2455 required. 2457 o Correct statements in examples about which algorithms produce 2458 reproducible results. 2460 -05 2462 o Support both direct encryption using a shared or agreed upon 2463 symmetric key, and the use of a shared or agreed upon symmetric 2464 key to key wrap the CMK. 2466 o Added statement that "StringOrURI values are compared as case- 2467 sensitive strings with no transformations or canonicalizations 2468 applied". 2470 o Updated open issues. 2472 o Indented artwork elements to better distinguish them from the body 2473 text. 2475 -04 2477 o Refer to the registries as the primary sources of defined values 2478 and then secondarily reference the sections defining the initial 2479 contents of the registries. 2481 o Normatively reference XML Encryption 1.1 for its security 2482 considerations. 2484 o Reference draft-jones-jose-jwe-json-serialization instead of 2485 draft-jones-json-web-encryption-json-serialization. 2487 o Described additional open issues. 2489 o Applied editorial suggestions. 2491 -03 2493 o Added the "kdf" (key derivation function) header parameter to 2494 provide crypto agility for key derivation. The default KDF 2495 remains the Concat KDF with the SHA-256 digest function. 2497 o Reordered encryption steps so that the Encoded JWE Header is 2498 always created before it is needed as an input to the 2499 Authenticated Encryption "additional authenticated data" 2500 parameter. 2502 o Added the "cty" (content type) header parameter for declaring type 2503 information about the secured content, as opposed to the "typ" 2504 (type) header parameter, which declares type information about 2505 this object. 2507 o Moved description of how to determine whether a header is for a 2508 JWS or a JWE from the JWT spec to the JWE spec. 2510 o Added complete encryption examples for both Authenticated 2511 Encryption and non-Authenticated Encryption algorithms. 2513 o Added complete key derivation examples. 2515 o Added "Collision Resistant Namespace" to the terminology section. 2517 o Reference ITU.X690.1994 for DER encoding. 2519 o Added Registry Contents sections to populate registry values. 2521 o Numerous editorial improvements. 2523 -02 2525 o When using Authenticated Encryption algorithms (such as AES GCM), 2526 use the "additional authenticated data" parameter to provide 2527 integrity for the header, encrypted key, and ciphertext and use 2528 the resulting "authentication tag" value as the JWE Authentication 2529 Tag. 2531 o Defined KDF output key sizes. 2533 o Generalized text to allow key agreement to be employed as an 2534 alternative to key wrapping or key encryption. 2536 o Changed compression algorithm from gzip to DEFLATE. 2538 o Clarified that it is an error when a "kid" value is included and 2539 no matching key is found. 2541 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2542 rejected. 2544 o Clarified the relationship between "typ" header parameter values 2545 and MIME types. 2547 o Registered application/jwe MIME type and "JWE" typ header 2548 parameter value. 2550 o Simplified JWK terminology to get replace the "JWK Key Object" and 2551 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2552 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2553 between single keys and sets of keys. As part of this change, the 2554 Header Parameter Name for a public key value was changed from 2555 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2557 o Added suggestion on defining additional header parameters such as 2558 "x5t#S256" in the future for certificate thumbprints using hash 2559 algorithms other than SHA-1. 2561 o Specify RFC 2818 server identity validation, rather than RFC 6125 2562 (paralleling the same decision in the OAuth specs). 2564 o Generalized language to refer to Message Authentication Codes 2565 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2566 unless in a context specific to HMAC algorithms. 2568 o Reformatted to give each header parameter its own section heading. 2570 -01 2572 o Added an integrity check for non-Authenticated Encryption 2573 algorithms. 2575 o Added "jpk" and "x5c" header parameters for including JWK public 2576 keys and X.509 certificate chains directly in the header. 2578 o Clarified that this specification is defining the JWE Compact 2579 Serialization. Referenced the new JWE-JS spec, which defines the 2580 JWE JSON Serialization. 2582 o Added text "New header parameters should be introduced sparingly 2583 since an implementation that does not understand a parameter MUST 2584 reject the JWE". 2586 o Clarified that the order of the encryption and decryption steps is 2587 not significant in cases where there are no dependencies between 2588 the inputs and outputs of the steps. 2590 o Made other editorial improvements suggested by JOSE working group 2591 participants. 2593 -00 2594 o Created the initial IETF draft based upon 2595 draft-jones-json-web-encryption-02 with no normative changes. 2597 o Changed terminology to no longer call both digital signatures and 2598 HMACs "signatures". 2600 Authors' Addresses 2602 Michael B. Jones 2603 Microsoft 2605 Email: mbj@microsoft.com 2606 URI: http://self-issued.info/ 2608 Joe Hildebrand 2609 Cisco Systems, Inc. 2611 Email: jhildebr@cisco.com