idnits 2.17.1 draft-ietf-jose-json-web-encryption-29.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 (June 20, 2014) is 3598 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 1400 -- Looks like a reference, but probably isn't: '197' on line 1400 -- Looks like a reference, but probably isn't: '117' on line 1400 -- Looks like a reference, but probably isn't: '252' on line 1400 -- Looks like a reference, but probably isn't: '2' on line 1400 -- Looks like a reference, but probably isn't: '219' on line 1400 -- Looks like a reference, but probably isn't: '233' on line 1400 -- Looks like a reference, but probably isn't: '68' on line 1400 -- Looks like a reference, but probably isn't: '180' on line 1400 -- Looks like a reference, but probably isn't: '225' on line 1400 -- Looks like a reference, but probably isn't: '77' on line 1400 -- Looks like a reference, but probably isn't: '0' on line 1987 -- Looks like a reference, but probably isn't: '1' on line 1987 -- Looks like a reference, but probably isn't: '152' on line 1987 ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' == Outdated reference: A later version (-05) exists of draft-mcgrew-aead-aes-cbc-hmac-sha2-04 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 17 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track J. Hildebrand 5 Expires: December 22, 2014 Cisco 6 June 20, 2014 8 JSON Web Encryption (JWE) 9 draft-ietf-jose-json-web-encryption-29 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 December 22, 2014. 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. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 10 60 4. JOSE Header . . . . . . . . . . . . . . . . . . . . . . . . . 12 61 4.1. Registered Header Parameter Names . . . . . . . . . . . . 12 62 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 12 63 4.1.2. "enc" (Encryption Algorithm) Header Parameter . . . . 13 64 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 13 65 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 13 66 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 14 67 4.1.6. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14 68 4.1.7. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 14 69 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 14 70 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 71 Parameter . . . . . . . . . . . . . . . . . . . . . . 14 72 4.1.10. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) 73 Header Parameter . . . . . . . . . . . . . . . . . . . 14 74 4.1.11. "typ" (Type) Header Parameter . . . . . . . . . . . . 15 75 4.1.12. "cty" (Content Type) Header Parameter . . . . . . . . 15 76 4.1.13. "crit" (Critical) Header Parameter . . . . . . . . . . 15 77 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15 78 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 15 79 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 16 80 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 16 81 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 18 82 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20 83 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20 84 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 20 85 7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 21 86 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21 87 8. TLS Requirements . . . . . . . . . . . . . . . . . . . . . . . 24 88 9. Distinguishing between JWS and JWE Objects . . . . . . . . . . 24 89 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 90 10.1. JSON Web Signature and Encryption Header Parameters 91 Registration . . . . . . . . . . . . . . . . . . . . . . . 24 92 10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25 93 11. Security Considerations . . . . . . . . . . . . . . . . . . . 26 94 11.1. Using Matching Algorithm Strengths . . . . . . . . . . . . 27 95 11.2. Adaptive Chosen-Ciphertext Attacks . . . . . . . . . . . . 27 96 11.3. Timing Attacks . . . . . . . . . . . . . . . . . . . . . . 27 97 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 98 12.1. Normative References . . . . . . . . . . . . . . . . . . . 27 99 12.2. Informative References . . . . . . . . . . . . . . . . . . 28 100 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 29 101 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 29 102 A.1.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 29 103 A.1.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 30 104 A.1.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 30 105 A.1.4. Initialization Vector . . . . . . . . . . . . . . . . 31 106 A.1.5. Additional Authenticated Data . . . . . . . . . . . . 31 107 A.1.6. Content Encryption . . . . . . . . . . . . . . . . . . 31 108 A.1.7. Complete Representation . . . . . . . . . . . . . . . 32 109 A.1.8. Validation . . . . . . . . . . . . . . . . . . . . . . 32 110 A.2. Example JWE using RSAES-PKCS1-V1_5 and 111 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 33 112 A.2.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 33 113 A.2.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 33 114 A.2.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 33 115 A.2.4. Initialization Vector . . . . . . . . . . . . . . . . 35 116 A.2.5. Additional Authenticated Data . . . . . . . . . . . . 35 117 A.2.6. Content Encryption . . . . . . . . . . . . . . . . . . 35 118 A.2.7. Complete Representation . . . . . . . . . . . . . . . 36 119 A.2.8. Validation . . . . . . . . . . . . . . . . . . . . . . 36 120 A.3. Example JWE using AES Key Wrap and 121 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 36 122 A.3.1. JOSE Header . . . . . . . . . . . . . . . . . . . . . 37 123 A.3.2. Content Encryption Key (CEK) . . . . . . . . . . . . . 37 124 A.3.3. Key Encryption . . . . . . . . . . . . . . . . . . . . 37 125 A.3.4. Initialization Vector . . . . . . . . . . . . . . . . 38 126 A.3.5. Additional Authenticated Data . . . . . . . . . . . . 38 127 A.3.6. Content Encryption . . . . . . . . . . . . . . . . . . 38 128 A.3.7. Complete Representation . . . . . . . . . . . . . . . 39 129 A.3.8. Validation . . . . . . . . . . . . . . . . . . . . . . 39 130 A.4. Example JWE using JWE JSON Serialization . . . . . . . . . 39 131 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 40 132 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 40 133 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 40 134 A.4.4. Complete JOSE Header Values . . . . . . . . . . . . . 40 135 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 41 136 A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 41 137 A.4.7. Complete JWE JSON Serialization Representation . . . . 41 138 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 42 139 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 42 140 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 43 141 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 43 142 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 44 143 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 44 144 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 44 145 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 44 146 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 44 147 Appendix D. Document History . . . . . . . . . . . . . . . . . . 45 148 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 55 150 1. Introduction 152 JSON Web Encryption (JWE) represents encrypted content using 153 JavaScript Object Notation (JSON) [RFC7159] based data structures. 154 The JWE cryptographic mechanisms encrypt and provide integrity 155 protection for an arbitrary sequence of octets. 157 Two closely related serializations for JWE objects are defined. The 158 JWE Compact Serialization is a compact, URL-safe representation 159 intended for space constrained environments such as HTTP 160 Authorization headers and URI query parameters. The JWE JSON 161 Serialization represents JWE objects as JSON objects and enables the 162 same content to be encrypted to multiple parties. Both share the 163 same cryptographic underpinnings. 165 Cryptographic algorithms and identifiers for use with this 166 specification are described in the separate JSON Web Algorithms (JWA) 167 [JWA] specification and IANA registries defined by that 168 specification. Related digital signature and MAC capabilities are 169 described in the separate JSON Web Signature (JWS) [JWS] 170 specification. 172 Names defined by this specification are short because a core goal is 173 for the resulting representations to be compact. 175 1.1. Notational Conventions 177 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 178 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 179 "OPTIONAL" in this document are to be interpreted as described in Key 180 words for use in RFCs to Indicate Requirement Levels [RFC2119]. If 181 these words are used without being spelled in uppercase then they are 182 to be interpreted with their normal natural language meanings. 184 BASE64URL(OCTETS) denotes the base64url encoding of OCTETS, per 185 Section 2. 187 UTF8(STRING) denotes the octets of the UTF-8 [RFC3629] representation 188 of STRING. 190 ASCII(STRING) denotes the octets of the ASCII [USASCII] 191 representation of STRING. 193 The concatenation of two values A and B is denoted as A || B. 195 2. Terminology 197 These terms defined by the JSON Web Signature (JWS) [JWS] 198 specification are incorporated into this specification: "JSON Web 199 Signature (JWS)", "Base64url Encoding", "Collision-Resistant Name", 200 "Header Parameter", "JOSE Header", and "StringOrURI". 202 These terms are defined by this specification: 204 JSON Web Encryption (JWE) 205 A data structure representing an encrypted and integrity protected 206 message. 208 Authenticated Encryption with Associated Data (AEAD) 209 An AEAD algorithm is one that encrypts the Plaintext, allows 210 Additional Authenticated Data to be specified, and provides an 211 integrated content integrity check over the Ciphertext and 212 Additional Authenticated Data. AEAD algorithms accept two inputs, 213 the Plaintext and the Additional Authenticated Data value, and 214 produce two outputs, the Ciphertext and the Authentication Tag 215 value. AES Galois/Counter Mode (GCM) is one such algorithm. 217 Plaintext 218 The sequence of octets to be encrypted -- a.k.a., the message. 219 The plaintext can contain an arbitrary sequence of octets. 221 Ciphertext 222 An encrypted representation of the Plaintext. 224 Additional Authenticated Data (AAD) 225 An input to an AEAD operation that is integrity protected but not 226 encrypted. 228 Authentication Tag 229 An output of an AEAD operation that ensures the integrity of the 230 Ciphertext and the Additional Authenticated Data. Note that some 231 algorithms may not use an Authentication Tag, in which case this 232 value is the empty octet sequence. 234 Content Encryption Key (CEK) 235 A symmetric key for the AEAD algorithm used to encrypt the 236 Plaintext for the recipient to produce the Ciphertext and the 237 Authentication Tag. 239 JWE Encrypted Key 240 Encrypted Content Encryption Key (CEK) value. Note that for some 241 algorithms, the JWE Encrypted Key value is specified as being the 242 empty octet sequence. 244 JWE Initialization Vector 245 Initialization vector value used when encrypting the plaintext. 246 Note that some algorithms may not use an Initialization Vector, in 247 which case this value is the empty octet sequence. 249 JWE AAD 250 Additional value to be integrity protected by the authenticated 251 encryption operation. This can only be present when using the JWE 252 JSON Serialization. (Note that this can also be achieved when 253 using either serialization by including the AAD value as an 254 integrity protected Header Parameter value, but at the cost of the 255 value being double base64url encoded.) 257 JWE Ciphertext 258 Ciphertext value resulting from authenticated encryption of the 259 plaintext with additional authenticated data. 261 JWE Authentication Tag 262 Authentication Tag value resulting from authenticated encryption 263 of the plaintext with additional authenticated data. 265 JWE Protected Header 266 JSON object that contains the Header Parameters that are integrity 267 protected by the authenticated encryption operation. These 268 parameters apply to all recipients of the JWE. For the JWE 269 Compact Serialization, this comprises the entire JOSE Header. For 270 the JWE JSON Serialization, this is one component of the JOSE 271 Header. 273 JWE Shared Unprotected Header 274 JSON object that contains the Header Parameters that apply to all 275 recipients of the JWE that are not integrity protected. This can 276 only be present when using the JWE JSON Serialization. 278 JWE Per-Recipient Unprotected Header 279 JSON object that contains Header Parameters that apply to a single 280 recipient of the JWE. These Header Parameter values are not 281 integrity protected. This can only be present when using the JWE 282 JSON Serialization. 284 JWE Compact Serialization 285 A representation of the JWE as a compact, URL-safe string. 287 JWE JSON Serialization 288 A representation of the JWE as a JSON object. The JWE JSON 289 Serialization enables the same content to be encrypted to multiple 290 parties. This representation is neither optimized for compactness 291 nor URL-safe. 293 Key Management Mode 294 A method of determining the Content Encryption Key (CEK) value to 295 use. Each algorithm used for determining the CEK value uses a 296 specific Key Management Mode. Key Management Modes employed by 297 this specification are Key Encryption, Key Wrapping, Direct Key 298 Agreement, Key Agreement with Key Wrapping, and Direct Encryption. 300 Key Encryption 301 A Key Management Mode in which the Content Encryption Key (CEK) 302 value is encrypted to the intended recipient using an asymmetric 303 encryption algorithm. 305 Key Wrapping 306 A Key Management Mode in which the Content Encryption Key (CEK) 307 value is encrypted to the intended recipient using a symmetric key 308 wrapping algorithm. 310 Direct Key Agreement 311 A Key Management Mode in which a key agreement algorithm is used 312 to agree upon the Content Encryption Key (CEK) value. 314 Key Agreement with Key Wrapping 315 A Key Management Mode in which a key agreement algorithm is used 316 to agree upon a symmetric key used to encrypt the Content 317 Encryption Key (CEK) value to the intended recipient using a 318 symmetric key wrapping algorithm. 320 Direct Encryption 321 A Key Management Mode in which the Content Encryption Key (CEK) 322 value used is the secret symmetric key value shared between the 323 parties. 325 3. JSON Web Encryption (JWE) Overview 327 JWE represents encrypted content using JSON data structures and 328 base64url encoding. A JWE represents these logical values: 330 JOSE Header 331 JSON object containing the parameters describing the cryptographic 332 operations and parameters employed. For a JWE object, the JOSE 333 Header members are the union of the members of the JWE Protected 334 Header, the JWE Shared Unprotected Header, and the JWE Per- 335 Recipient Unprotected Header, as described below. 337 JWE Encrypted Key 338 Encrypted Content Encryption Key (CEK) value. 340 JWE Initialization Vector 341 Initialization Vector value used when encrypting the plaintext. 343 JWE AAD 344 Additional value to be integrity protected by the authenticated 345 encryption operation. 347 JWE Ciphertext 348 Ciphertext value resulting from authenticated encryption of the 349 plaintext with additional authenticated data. 351 JWE Authentication Tag 352 Authentication Tag value resulting from authenticated encryption 353 of the plaintext with additional authenticated data. 355 For a JWE object, the JOSE Header represents the combination of these 356 logical values: 358 JWE Protected Header 359 JSON object that contains the Header Parameters that are integrity 360 protected by the authenticated encryption operation. These 361 parameters apply to all recipients of the JWE. 363 JWE Shared Unprotected Header 364 JSON object that contains the Header Parameters that apply to all 365 recipients of the JWE that are not integrity protected. 367 JWE Per-Recipient Unprotected Header 368 JSON object that contains Header Parameters that apply to a single 369 recipient of the JWE. These Header Parameter values are not 370 integrity protected. 372 This document defines two serializations for JWE objects: a compact, 373 URL-safe serialization called the JWE Compact Serialization and a 374 JSON serialization called the JWE JSON Serialization. In both 375 serializations, the JWE Protected Header, JWE Encrypted Key, JWE 376 Initialization Vector, JWE Ciphertext, and JWE Authentication Tag are 377 base64url encoded for transmission, since JSON lacks a way to 378 directly represent octet sequences. When present, the JWE AAD is 379 also base64url encoded for transmission. 381 In the JWE Compact Serialization, no JWE Shared Unprotected Header or 382 JWE Per-Recipient Unprotected Header are used. In this case, the 383 JOSE Header and the JWE Protected Header are the same. 385 In the JWE Compact Serialization, a JWE object is represented as the 386 combination of these five string values, 387 BASE64URL(UTF8(JWE Protected Header)), 388 BASE64URL(JWE Encrypted Key), 389 BASE64URL(JWE Initialization Vector), 390 BASE64URL(JWE Ciphertext), and 391 BASE64URL(JWE Authentication Tag), 392 concatenated in that order, with the five strings being separated by 393 four period ('.') characters. 395 In the JWE JSON Serialization, one or more of the JWE Protected 396 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 397 Unprotected Header MUST be present. In this case, the members of the 398 JOSE Header are the combination of the members of the JWE Protected 399 Header, JWE Shared Unprotected Header, and JWE Per-Recipient 400 Unprotected Header values that are present. 402 In the JWE JSON Serialization, a JWE object is represented as the 403 combination of these eight values, 404 BASE64URL(UTF8(JWE Protected Header)), 405 JWE Shared Unprotected Header, 406 JWE Per-Recipient Unprotected Header, 407 BASE64URL(JWE Encrypted Key), 408 BASE64URL(JWE Initialization Vector), 409 BASE64URL(JWE Ciphertext), 410 BASE64URL(JWE Authentication Tag), and 411 BASE64URL(JWE AAD), 412 with the six base64url encoded result strings and the two unprotected 413 JSON object values being represented as members within a JSON object. 414 The inclusion of some of these values is OPTIONAL. The JWE JSON 415 Serialization can also encrypt the plaintext to multiple recipients. 416 See Section 7.2 for more information about the JWE JSON 417 Serialization. 419 JWE utilizes authenticated encryption to ensure the confidentiality 420 and integrity of the Plaintext and the integrity of the JWE Protected 421 Header and the JWE AAD. 423 3.1. Example JWE 425 This example encrypts the plaintext "The true sign of intelligence is 426 not knowledge but imagination." to the recipient using RSAES OAEP for 427 key encryption and AES GCM for content encryption. 429 The following example JWE Protected Header declares that: 431 o the Content Encryption Key is encrypted to the recipient using the 432 RSAES OAEP algorithm to produce the JWE Encrypted Key and 434 o the Plaintext is encrypted using the AES GCM algorithm with a 256 435 bit key to produce the Ciphertext. 437 {"alg":"RSA-OAEP","enc":"A256GCM"} 439 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 440 Header)) gives this value: 442 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 444 The remaining steps to finish creating this JWE are: 446 o Generate a random Content Encryption Key (CEK). 448 o Encrypt the CEK with the recipient's public key using the RSAES 449 OAEP algorithm to produce the JWE Encrypted Key. 451 o Base64url encode the JWE Encrypted Key. 453 o Generate a random JWE Initialization Vector. 455 o Base64url encode the JWE Initialization Vector. 457 o Let the Additional Authenticated Data encryption parameter be 458 ASCII(BASE64URL(UTF8(JWE Protected Header))). 460 o Encrypt the Plaintext with AES GCM using the CEK as the encryption 461 key, the JWE Initialization Vector, and the Additional 462 Authenticated Data value, requesting a 128 bit Authentication Tag 463 output. 465 o Base64url encode the Ciphertext. 467 o Base64url encode the Authentication Tag. 469 o Assemble the final representation: The Compact Serialization of 470 this result is the string BASE64URL(UTF8(JWE Protected Header)) || 471 '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE 472 Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' 473 || BASE64URL(JWE Authentication Tag). 475 The final result in this example (with line breaks for display 476 purposes only) is: 478 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 479 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 480 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 481 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 482 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 483 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 484 6UklfCpIMfIjf7iGdXKHzg. 485 48V1_ALb6US04U3b. 486 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 487 SdiwkIr3ajwQzaBtQD_A. 488 XFBoMYUZodetZdvTiFvSkQ 490 See Appendix A.1 for the complete details of computing this JWE. See 491 other parts of Appendix A for additional examples. 493 4. JOSE Header 495 For a JWE object, the members of the JSON object(s) representing the 496 JOSE Header describe the encryption applied to the Plaintext and 497 optionally additional properties of the JWE. The Header Parameter 498 names within the JOSE Header MUST be unique, just as described in 499 Section 4 of [JWS]. The rules about handling Header Parameters that 500 are not understood by the implementation are also the same. The 501 classes of Header Parameter names are likewise the same. 503 4.1. Registered Header Parameter Names 505 The following Header Parameter names for use in JWE objects are 506 registered in the IANA JSON Web Signature and Encryption Header 507 Parameters registry defined in [JWS], with meanings as defined below. 509 As indicated by the common registry, JWSs and JWEs share a common 510 Header Parameter space; when a parameter is used by both 511 specifications, its usage must be compatible between the 512 specifications. 514 4.1.1. "alg" (Algorithm) Header Parameter 516 This parameter has the same meaning, syntax, and processing rules as 517 the "alg" Header Parameter defined in Section 4.1.1 of [JWS], except 518 that the Header Parameter identifies the cryptographic algorithm used 519 to encrypt or determine the value of the Content Encryption Key 520 (CEK). The encrypted content is not usable if the "alg" value does 521 not represent a supported algorithm, or if the recipient does not 522 have a key that can be used with that algorithm. 524 A list of defined "alg" values for this use can be found in the IANA 525 JSON Web Signature and Encryption Algorithms registry defined in 526 [JWA]; the initial contents of this registry are the values defined 527 in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. 529 4.1.2. "enc" (Encryption Algorithm) Header Parameter 531 The "enc" (encryption algorithm) Header Parameter identifies the 532 content encryption algorithm used to encrypt the Plaintext to produce 533 the Ciphertext. This algorithm MUST be an AEAD algorithm with a 534 specified key length. The recipient MUST reject the JWE if the "enc" 535 value does not represent a supported algorithm. "enc" values should 536 either be registered in the IANA JSON Web Signature and Encryption 537 Algorithms registry defined in [JWA] or be a value that contains a 538 Collision-Resistant Name. The "enc" value is a case-sensitive string 539 containing a StringOrURI value. This Header Parameter MUST be 540 present and MUST be understood and processed by implementations. 542 A list of defined "enc" values for this use can be found in the IANA 543 JSON Web Signature and Encryption Algorithms registry defined in 544 [JWA]; the initial contents of this registry are the values defined 545 in Section 5.1 of the JSON Web Algorithms (JWA) [JWA] specification. 547 4.1.3. "zip" (Compression Algorithm) Header Parameter 549 The "zip" (compression algorithm) applied to the Plaintext before 550 encryption, if any. The "zip" value defined by this specification 551 is: 553 o "DEF" - Compression with the DEFLATE [RFC1951] algorithm 555 Other values MAY be used. Compression algorithm values can be 556 registered in the IANA JSON Web Encryption Compression Algorithm 557 registry defined in [JWA]. The "zip" value is a case-sensitive 558 string. If no "zip" parameter is present, no compression is applied 559 to the Plaintext before encryption. This Header Parameter MUST be 560 integrity protected, and therefore MUST occur only within the JWE 561 Protected Header, when used. Use of this Header Parameter is 562 OPTIONAL. This Header Parameter MUST be understood and processed by 563 implementations. 565 4.1.4. "jku" (JWK Set URL) Header Parameter 567 This parameter has the same meaning, syntax, and processing rules as 568 the "jku" Header Parameter defined in Section 4.1.2 of [JWS], except 569 that the JWK Set resource contains the public key to which the JWE 570 was encrypted; this can be used to determine the private key needed 571 to decrypt the JWE. 573 4.1.5. "jwk" (JSON Web Key) Header Parameter 575 This parameter has the same meaning, syntax, and processing rules as 576 the "jwk" Header Parameter defined in Section 4.1.3 of [JWS], except 577 that the key is the public key to which the JWE was encrypted; this 578 can be used to determine the private key needed to decrypt the JWE. 580 4.1.6. "kid" (Key ID) Header Parameter 582 This parameter has the same meaning, syntax, and processing rules as 583 the "kid" Header Parameter defined in Section 4.1.4 of [JWS], except 584 that the key hint references the public key to which the JWE was 585 encrypted; this can be used to determine the private key needed to 586 decrypt the JWE. This parameter allows originators to explicitly 587 signal a change of key to JWE recipients. 589 4.1.7. "x5u" (X.509 URL) Header Parameter 591 This parameter has the same meaning, syntax, and processing rules as 592 the "x5u" Header Parameter defined in Section 4.1.5 of [JWS], except 593 that the X.509 public key certificate or certificate chain [RFC5280] 594 contains the public key to which the JWE was encrypted; this can be 595 used to determine the private key needed to decrypt the JWE. 597 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 599 This parameter has the same meaning, syntax, and processing rules as 600 the "x5c" Header Parameter defined in Section 4.1.6 of [JWS], except 601 that the X.509 public key certificate or certificate chain [RFC5280] 602 contains the public key to which the JWE was encrypted; this can be 603 used to determine the private key needed to decrypt the JWE. 605 See Appendix B of [JWS] for an example "x5c" value. 607 4.1.9. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 609 This parameter has the same meaning, syntax, and processing rules as 610 the "x5t" Header Parameter defined in Section 4.1.7 of [JWS], except 611 that the certificate referenced by the thumbprint contains the public 612 key to which the JWE was encrypted; this can be used to determine the 613 private key needed to decrypt the JWE. 615 4.1.10. "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) Header 616 Parameter 618 This parameter has the same meaning, syntax, and processing rules as 619 the "x5t#S256" Header Parameter defined in Section 4.1.8 of [JWS], 620 except that the certificate referenced by the thumbprint contains the 621 public key to which the JWE was encrypted; this can be used to 622 determine the private key needed to decrypt the JWE. 624 4.1.11. "typ" (Type) Header Parameter 626 This parameter has the same meaning, syntax, and processing rules as 627 the "typ" Header Parameter defined in Section 4.1.9 of [JWS], except 628 that the type is that of this complete JWE object. 630 4.1.12. "cty" (Content Type) Header Parameter 632 This parameter has the same meaning, syntax, and processing rules as 633 the "cty" Header Parameter defined in Section 4.1.10 of [JWS], except 634 that the type is that of the secured content (the plaintext). 636 4.1.13. "crit" (Critical) Header Parameter 638 This parameter has the same meaning, syntax, and processing rules as 639 the "crit" Header Parameter defined in Section 4.1.11 of [JWS], 640 except that Header Parameters for a JWE object are being referred to, 641 rather than Header Parameters for a JWS object. 643 4.2. Public Header Parameter Names 645 Additional Header Parameter names can be defined by those using JWEs. 646 However, in order to prevent collisions, any new Header Parameter 647 name should either be registered in the IANA JSON Web Signature and 648 Encryption Header Parameters registry defined in [JWS] or be a Public 649 Name: a value that contains a Collision-Resistant Name. In each 650 case, the definer of the name or value needs to take reasonable 651 precautions to make sure they are in control of the part of the 652 namespace they use to define the Header Parameter name. 654 New Header Parameters should be introduced sparingly, as they can 655 result in non-interoperable JWEs. 657 4.3. Private Header Parameter Names 659 A producer and consumer of a JWE may agree to use Header Parameter 660 names that are Private Names: names that are not Registered Header 661 Parameter names Section 4.1 or Public Header Parameter names 662 Section 4.2. Unlike Public Header Parameter names, Private Header 663 Parameter names are subject to collision and should be used with 664 caution. 666 5. Producing and Consuming JWEs 668 5.1. Message Encryption 670 The message encryption process is as follows. The order of the steps 671 is not significant in cases where there are no dependencies between 672 the inputs and outputs of the steps. 674 1. Determine the Key Management Mode employed by the algorithm used 675 to determine the Content Encryption Key (CEK) value. (This is 676 the algorithm recorded in the "alg" (algorithm) Header Parameter 677 of the resulting JWE.) 679 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 680 Wrapping are employed, generate a random Content Encryption Key 681 (CEK) value. See RFC 4086 [RFC4086] for considerations on 682 generating random values. The CEK MUST have a length equal to 683 that required for the content encryption algorithm. 685 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 686 employed, use the key agreement algorithm to compute the value 687 of the agreed upon key. When Direct Key Agreement is employed, 688 let the Content Encryption Key (CEK) be the agreed upon key. 689 When Key Agreement with Key Wrapping is employed, the agreed 690 upon key will be used to wrap the CEK. 692 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 693 Wrapping are employed, encrypt the CEK to the recipient and let 694 the result be the JWE Encrypted Key. 696 5. When Direct Key Agreement or Direct Encryption are employed, let 697 the JWE Encrypted Key be the empty octet sequence. 699 6. When Direct Encryption is employed, let the Content Encryption 700 Key (CEK) be the shared symmetric key. 702 7. Compute the encoded key value BASE64URL(JWE Encrypted Key). 704 8. If the JWE JSON Serialization is being used, repeat this process 705 (steps 1-7) for each recipient. 707 9. Generate a random JWE Initialization Vector of the correct size 708 for the content encryption algorithm (if required for the 709 algorithm); otherwise, let the JWE Initialization Vector be the 710 empty octet sequence. 712 10. Compute the encoded initialization vector value BASE64URL(JWE 713 Initialization Vector). 715 11. If a "zip" parameter was included, compress the Plaintext using 716 the specified compression algorithm. 718 12. Serialize the (compressed) Plaintext into an octet sequence M. 720 13. Create the JSON object(s) containing the desired set of Header 721 Parameters, which together comprise the JOSE Header: the JWE 722 Protected Header, and if the JWE JSON Serialization is being 723 used, the JWE Shared Unprotected Header and the JWE Per- 724 Recipient Unprotected Header. 726 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 727 Protected Header)). If the JWE Protected Header is not present 728 (which can only happen when using the JWE JSON Serialization and 729 no "protected" member is present), let this value be the empty 730 string. 732 15. Let the Additional Authenticated Data encryption parameter be 733 ASCII(Encoded Protected Header). However if a JWE AAD value is 734 present (which can only be the case when using the JWE JSON 735 Serialization), instead let the Additional Authenticated Data 736 encryption parameter be ASCII(Encoded Protected Header || '.' || 737 BASE64URL(JWE AAD)). 739 16. Encrypt M using the CEK, the JWE Initialization Vector, and the 740 Additional Authenticated Data value using the specified content 741 encryption algorithm to create the JWE Ciphertext value and the 742 JWE Authentication Tag (which is the Authentication Tag output 743 from the encryption operation). 745 17. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext). 747 18. Compute the encoded authentication tag value BASE64URL(JWE 748 Authentication Tag). 750 19. The five encoded values are used in both the JWE Compact 751 Serialization and the JWE JSON Serialization representations. 753 20. If a JWE AAD value is present, compute the encoded AAD value 754 BASE64URL(JWE AAD). 756 21. Create the desired serialized output. The Compact Serialization 757 of this result is the string BASE64URL(UTF8(JWE Protected 758 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 759 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 760 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). The 761 JWE JSON Serialization is described in Section 7.2. 763 5.2. Message Decryption 765 The message decryption process is the reverse of the encryption 766 process. The order of the steps is not significant in cases where 767 there are no dependencies between the inputs and outputs of the 768 steps. If any of these steps fails, the encrypted content cannot be 769 validated. 771 It is an application decision which recipients' encrypted content 772 must successfully validate for the JWE to be accepted. In some 773 cases, encrypted content for all recipients must successfully 774 validate or the JWE will be rejected. In other cases, only the 775 encrypted content for a single recipient needs to be successfully 776 validated. However, in all cases, the encrypted content for at least 777 one recipient MUST successfully validate or the JWE MUST be rejected. 779 1. Parse the JWE representation to extract the serialized values 780 for the components of the JWE -- when using the JWE Compact 781 Serialization, the base64url encoded representations of the JWE 782 Protected Header, the JWE Encrypted Key, the JWE Initialization 783 Vector, the JWE Ciphertext, and the JWE Authentication Tag, and 784 when using the JWE JSON Serialization, also the base64url 785 encoded representation of the JWE AAD and the unencoded JWE 786 Shared Unprotected Header and JWE Per-Recipient Unprotected 787 Header values. When using the JWE Compact Serialization, the 788 JWE Protected Header, the JWE Encrypted Key, the JWE 789 Initialization Vector, the JWE Ciphertext, and the JWE 790 Authentication Tag are represented as base64url encoded values 791 in that order, separated by four period ('.') characters. The 792 JWE JSON Serialization is described in Section 7.2. 794 2. The encoded representations of the JWE Protected Header, the JWE 795 Encrypted Key, the JWE Initialization Vector, the JWE 796 Ciphertext, the JWE Authentication Tag, and the JWE AAD MUST be 797 successfully base64url decoded following the restriction that no 798 padding characters have been used. 800 3. The octet sequence resulting from decoding the encoded JWE 801 Protected Header MUST be a UTF-8 encoded representation of a 802 completely valid JSON object conforming to [RFC7159], which is 803 the JWE Protected Header. 805 4. If using the JWE Compact Serialization, let the JOSE Header be 806 the JWE Protected Header; otherwise, when using the JWE JSON 807 Serialization, let the JOSE Header be the union of the members 808 of the JWE Protected Header, the JWE Shared Unprotected Header 809 and the corresponding JWE Per-Recipient Unprotected Header, all 810 of which must be completely valid JSON objects. 812 5. The resulting JOSE Header MUST NOT contain duplicate Header 813 Parameter names. When using the JWE JSON Serialization, this 814 restriction includes that the same Header Parameter name also 815 MUST NOT occur in distinct JSON object values that together 816 comprise the JOSE Header. 818 6. Verify that the implementation understands and can process all 819 fields that it is required to support, whether required by this 820 specification, by the algorithms being used, or by the "crit" 821 Header Parameter value, and that the values of those parameters 822 are also understood and supported. 824 7. Determine the Key Management Mode employed by the algorithm 825 specified by the "alg" (algorithm) Header Parameter. 827 8. Verify that the JWE uses a key known to the recipient. 829 9. When Direct Key Agreement or Key Agreement with Key Wrapping are 830 employed, use the key agreement algorithm to compute the value 831 of the agreed upon key. When Direct Key Agreement is employed, 832 let the Content Encryption Key (CEK) be the agreed upon key. 833 When Key Agreement with Key Wrapping is employed, the agreed 834 upon key will be used to decrypt the JWE Encrypted Key. 836 10. When Key Wrapping, Key Encryption, or Key Agreement with Key 837 Wrapping are employed, decrypt the JWE Encrypted Key to produce 838 the Content Encryption Key (CEK). The CEK MUST have a length 839 equal to that required for the content encryption algorithm. 840 Note that when there are multiple recipients, each recipient 841 will only be able decrypt any JWE Encrypted Key values that were 842 encrypted to a key in that recipient's possession. It is 843 therefore normal to only be able to decrypt one of the per- 844 recipient JWE Encrypted Key values to obtain the CEK value. 845 Also, see Section 11.3 for security considerations on mitigating 846 timing attacks. 848 11. When Direct Key Agreement or Direct Encryption are employed, 849 verify that the JWE Encrypted Key value is empty octet sequence. 851 12. When Direct Encryption is employed, let the Content Encryption 852 Key (CEK) be the shared symmetric key. 854 13. If the JWE JSON Serialization is being used, repeat this process 855 (steps 4-12) for each recipient contained in the representation 856 until the CEK value has been determined. 858 14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE 859 Protected Header)). If the JWE Protected Header is not present 860 (which can only happen when using the JWE JSON Serialization and 861 no "protected" member is present), let this value be the empty 862 string. 864 15. Let the Additional Authenticated Data encryption parameter be 865 ASCII(Encoded Protected Header). However if a JWE AAD value is 866 present (which can only be the case when using the JWE JSON 867 Serialization), instead let the Additional Authenticated Data 868 encryption parameter be ASCII(Encoded Protected Header || '.' || 869 BASE64URL(JWE AAD)). 871 16. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 872 Vector, the Additional Authenticated Data value, and the JWE 873 Authentication Tag (which is the Authentication Tag input to the 874 calculation) using the specified content encryption algorithm, 875 returning the decrypted plaintext and validating the JWE 876 Authentication Tag in the manner specified for the algorithm, 877 rejecting the input without emitting any decrypted output if the 878 JWE Authentication Tag is incorrect. 880 17. If a "zip" parameter was included, uncompress the decrypted 881 plaintext using the specified compression algorithm. 883 18. If all the previous steps succeeded, output the resulting 884 Plaintext. 886 5.3. String Comparison Rules 888 The string comparison rules for this specification are the same as 889 those defined in Section 5.3 of [JWS]. 891 6. Key Identification 893 The key identification methods for this specification are the same as 894 those defined in Section 6 of [JWS], except that the key being 895 identified is the public key to which the JWE was encrypted. 897 7. Serializations 899 JWE objects use one of two serializations, the JWE Compact 900 Serialization or the JWE JSON Serialization. Applications using this 901 specification need to specify what serialization and serialization 902 features are used for that application. For instance, applications 903 might specify that only the JWE JSON Serialization is used, that only 904 JWE JSON Serialization support for a single recipient is used, or 905 that support for multiple recipients is used. JWE implementations 906 only need to implement the features needed for the applications they 907 are designed to support. 909 7.1. JWE Compact Serialization 911 The JWE Compact Serialization represents encrypted content as a 912 compact URL-safe string. This string is BASE64URL(UTF8(JWE Protected 913 Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || 914 BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE 915 Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). Only one 916 recipient is supported by the JWE Compact Serialization and it 917 provides no syntax to represent JWE Shared Unprotected Header, JWE 918 Per-Recipient Unprotected Header, or JWE AAD values. 920 7.2. JWE JSON Serialization 922 The JWE JSON Serialization represents encrypted content as a JSON 923 object. Content using the JWE JSON Serialization can be encrypted to 924 more than one recipient. This representation is neither optimized 925 for compactness nor URL-safe. 927 The following members are defined for use in top-level JSON objects 928 used for the JWE JSON Serialization: 930 protected 931 The "protected" member MUST be present and contain the value 932 BASE64URL(UTF8(JWE Protected Header)) when the JWE Protected 933 Header value is non-empty; otherwise, it MUST be absent. These 934 Header Parameter values are integrity protected. 936 unprotected 937 The "unprotected" member MUST be present and contain the value JWE 938 Shared Unprotected Header when the JWE Shared Unprotected Header 939 value is non-empty; otherwise, it MUST be absent. This value is 940 represented as an unencoded JSON object, rather than as a string. 941 These Header Parameter values are not integrity protected. 943 iv 944 The "iv" member MUST be present and contain the value 945 BASE64URL(JWE Initialization Vector) when the JWE Initialization 946 Vector value is non-empty; otherwise, it MUST be absent. 948 aad 949 The "aad" member MUST be present and contain the value 950 BASE64URL(JWE AAD)) when the JWE AAD value is non-empty; 951 otherwise, it MUST be absent. A JWE AAD value can be included to 952 supply a base64url encoded value to be integrity protected but not 953 encrypted. 955 ciphertext 956 The "ciphertext" member MUST be present and contain the value 957 BASE64URL(JWE Ciphertext). 959 tag 960 The "tag" member MUST be present and contain the value 961 BASE64URL(JWE Authentication Tag) when the JWE Authentication Tag 962 value is non-empty; otherwise, it MUST be absent. 964 recipients 965 The "recipients" member value MUST be an array of JSON objects. 966 Each object contains information specific to a single recipient. 967 This member MUST be present, even if the array elements contain 968 only the empty JSON object "{}" (which can happen when all Header 969 Parameter values are shared between all recipients and when no 970 encrypted key is used, such as when doing Direct Encryption). 972 The following members are defined for use in the JSON objects that 973 are elements of the "recipients" array: 975 header 976 The "header" member MUST be present and contain the value JWE Per- 977 Recipient Unprotected Header when the JWE Per-Recipient 978 Unprotected Header value is non-empty; otherwise, it MUST be 979 absent. This value is represented as an unencoded JSON object, 980 rather than as a string. These Header Parameter values are not 981 integrity protected. 983 encrypted_key 984 The "encrypted_key" member MUST be present and contain the value 985 BASE64URL(JWE Encrypted Key) when the JWE Encrypted Key value is 986 non-empty; otherwise, it MUST be absent. 988 At least one of the "header", "protected", and "unprotected" members 989 MUST be present so that "alg" and "enc" Header Parameter values are 990 conveyed for each recipient computation. 992 Additional members can be present in both the JSON objects defined 993 above; if not understood by implementations encountering them, they 994 MUST be ignored. 996 Some Header Parameters, including the "alg" parameter, can be shared 997 among all recipient computations. Header Parameters in the JWE 998 Protected Header and JWE Shared Unprotected Header values are shared 999 among all recipients. 1001 The Header Parameter values used when creating or validating per- 1002 recipient Ciphertext and Authentication Tag values are the union of 1003 the three sets of Header Parameter values that may be present: (1) 1004 the JWE Protected Header represented in the "protected" member, (2) 1005 the JWE Shared Unprotected Header represented in the "unprotected" 1006 member, and (3) the JWE Per-Recipient Unprotected Header represented 1007 in the "header" member of the recipient's array element. The union 1008 of these sets of Header Parameters comprises the JOSE Header. The 1009 Header Parameter names in the three locations MUST be disjoint. 1011 Each JWE Encrypted Key value is computed using the parameters of the 1012 corresponding JOSE Header value in the same manner as for the JWE 1013 Compact Serialization. This has the desirable property that each JWE 1014 Encrypted Key value in the "recipients" array is identical to the 1015 value that would have been computed for the same parameter in the JWE 1016 Compact Serialization. Likewise, the JWE Ciphertext and JWE 1017 Authentication Tag values match those produced for the JWE Compact 1018 Serialization, provided that the JWE Protected Header value (which 1019 represents the integrity-protected Header Parameter values) matches 1020 that used in the JWE Compact Serialization. 1022 All recipients use the same JWE Protected Header, JWE Initialization 1023 Vector, JWE Ciphertext, and JWE Authentication Tag values, when 1024 present, resulting in potentially significant space savings if the 1025 message is large. Therefore, all Header Parameters that specify the 1026 treatment of the Plaintext value MUST be the same for all recipients. 1027 This primarily means that the "enc" (encryption algorithm) Header 1028 Parameter value in the JOSE Header for each recipient and any 1029 parameters of that algorithm MUST be the same. 1031 In summary, the syntax of a JWE using the JWE JSON Serialization is 1032 as follows: 1034 {"protected":"", 1035 "unprotected":, 1036 "recipients":[ 1037 {"header":, 1038 "encrypted_key":""}, 1039 ... 1040 {"header":, 1041 "encrypted_key":""}], 1042 "aad":"", 1043 "iv":"", 1044 "ciphertext":"", 1045 "tag":"" 1046 } 1048 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1049 Serialization. 1051 8. TLS Requirements 1053 The TLS requirements for this specification are the same as those 1054 defined in Section 8 of [JWS]. 1056 9. Distinguishing between JWS and JWE Objects 1058 There are several ways of distinguishing whether an object is a JWS 1059 or JWE object. All these methods will yield the same result for all 1060 legal input values; they may yield different results for malformed 1061 inputs. 1063 o If the object is using the JWS Compact Serialization or the JWE 1064 Compact Serialization, the number of base64url encoded segments 1065 separated by period ('.') characters differs for JWSs and JWEs. 1066 JWSs have three segments separated by two period ('.') characters. 1067 JWEs have five segments separated by four period ('.') characters. 1069 o If the object is using the JWS JSON Serialization or the JWE JSON 1070 Serialization, the members used will be different. JWSs have a 1071 "signatures" member and JWEs do not. JWEs have a "recipients" 1072 member and JWSs do not. 1074 o The JOSE Header for a JWS object can be distinguished from the 1075 JOSE Header for a JWE object by examining the "alg" (algorithm) 1076 Header Parameter value. If the value represents a digital 1077 signature or MAC algorithm, or is the value "none", it is for a 1078 JWS; if it represents a Key Encryption, Key Wrapping, Direct Key 1079 Agreement, Key Agreement with Key Wrapping, or Direct Encryption 1080 algorithm, it is for a JWE. (Extracting the "alg" value to 1081 examine is straightforward when using the JWS Compact 1082 Serialization or the JWE Compact Serialization and may be more 1083 difficult when using the JWS JSON Serialization or the JWE JSON 1084 Serialization.) 1086 o The JOSE Header for a JWS object can also be distinguished from 1087 the JOSE Header for a JWE object by determining whether an "enc" 1088 (encryption algorithm) member exists. If the "enc" member exists, 1089 it is a JWE; otherwise, it is a JWS. 1091 10. IANA Considerations 1093 10.1. JSON Web Signature and Encryption Header Parameters Registration 1095 This specification registers the Header Parameter names defined in 1096 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1097 Parameters registry defined in [JWS]. 1099 10.1.1. Registry Contents 1101 o Header Parameter Name: "alg" 1102 o Header Parameter Description: Algorithm 1103 o Header Parameter Usage Location(s): JWE 1104 o Change Controller: IESG 1105 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1107 o Header Parameter Name: "enc" 1108 o Header Parameter Description: Encryption Algorithm 1109 o Header Parameter Usage Location(s): JWE 1110 o Change Controller: IESG 1111 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1113 o Header Parameter Name: "zip" 1114 o Header Parameter Description: Compression Algorithm 1115 o Header Parameter Usage Location(s): JWE 1116 o Change Controller: IESG 1117 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1119 o Header Parameter Name: "jku" 1120 o Header Parameter Description: JWK Set URL 1121 o Header Parameter Usage Location(s): JWE 1122 o Change Controller: IESG 1123 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1125 o Header Parameter Name: "jwk" 1126 o Header Parameter Description: JSON Web Key 1127 o Header Parameter Usage Location(s): JWE 1128 o Change Controller: IESG 1129 o Specification document(s): Section 4.1.5 of [[ this document ]] 1131 o Header Parameter Name: "kid" 1132 o Header Parameter Description: Key ID 1133 o Header Parameter Usage Location(s): JWE 1134 o Change Controller: IESG 1135 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1137 o Header Parameter Name: "x5u" 1138 o Header Parameter Description: X.509 URL 1139 o Header Parameter Usage Location(s): JWE 1140 o Change Controller: IESG 1141 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1142 o Header Parameter Name: "x5c" 1143 o Header Parameter Description: X.509 Certificate Chain 1144 o Header Parameter Usage Location(s): JWE 1145 o Change Controller: IESG 1146 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1148 o Header Parameter Name: "x5t" 1149 o Header Parameter Description: X.509 Certificate SHA-1 Thumbprint 1150 o Header Parameter Usage Location(s): JWE 1151 o Change Controller: IESG 1152 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1154 o Header Parameter Name: "x5t#S256" 1155 o Header Parameter Description: X.509 Certificate SHA-256 Thumbprint 1156 o Header Parameter Usage Location(s): JWE 1157 o Change Controller: IESG 1158 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1160 o Header Parameter Name: "typ" 1161 o Header Parameter Description: Type 1162 o Header Parameter Usage Location(s): JWE 1163 o Change Controller: IESG 1164 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1166 o Header Parameter Name: "cty" 1167 o Header Parameter Description: Content Type 1168 o Header Parameter Usage Location(s): JWE 1169 o Change Controller: IESG 1170 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1172 o Header Parameter Name: "crit" 1173 o Header Parameter Description: Critical 1174 o Header Parameter Usage Location(s): JWE 1175 o Change Controller: IESG 1176 o Specification Document(s): Section 4.1.13 of [[ this document ]] 1178 11. Security Considerations 1180 All of the security issues faced by any cryptographic application 1181 must be faced by a JWS/JWE/JWK agent. Among these issues are 1182 protecting the user's asymmetric private and symmetric secret keys, 1183 preventing various attacks, and helping avoid mistakes such as 1184 inadvertently encrypting a message to the wrong recipient. The 1185 entire list of security considerations is beyond the scope of this 1186 document. 1188 All the security considerations in the JWS specification also apply 1189 to this specification. Likewise, all the security considerations in 1190 XML Encryption 1.1 [W3C.REC-xmlenc-core1-20130411] also apply, other 1191 than those that are XML specific. 1193 11.1. Using Matching Algorithm Strengths 1195 Algorithms of matching strengths should be used together whenever 1196 possible. For instance, when AES Key Wrap is used with a given key 1197 size, using the same key size is recommended when AES GCM is also 1198 used. 1200 11.2. Adaptive Chosen-Ciphertext Attacks 1202 When decrypting, particular care must be taken not to allow the JWE 1203 recipient to be used as an oracle for decrypting messages. RFC 3218 1204 [RFC3218] should be consulted for specific countermeasures to attacks 1205 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1206 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1207 formatting error that can be detected and used to recover the CEK 1208 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1209 particularly important to report all formatting errors to the CEK, 1210 Additional Authenticated Data, or ciphertext as a single error when 1211 the encrypted content is rejected. 1213 Additionally, this type of attack can be prevented by the use of "key 1214 tainting". This method restricts the use of a key to a limited set 1215 of algorithms -- usually one. This means, for instance, that if the 1216 key is marked as being for "RSA-OAEP" only, any attempt to decrypt a 1217 message using the "RSA1_5" algorithm with that key would fail 1218 immediately due to invalid use of the key. 1220 11.3. Timing Attacks 1222 To mitigate the attacks described in RFC 3218 [RFC3218], the 1223 recipient MUST NOT distinguish between format, padding, and length 1224 errors of encrypted keys. It is strongly recommended, in the event 1225 of receiving an improperly formatted key, that the receiver 1226 substitute a randomly generated CEK and proceed to the next step, to 1227 mitigate timing attacks. 1229 12. References 1231 12.1. Normative References 1233 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1234 draft-ietf-jose-json-web-algorithms (work in progress), 1235 June 2014. 1237 [JWK] Jones, M., "JSON Web Key (JWK)", 1238 draft-ietf-jose-json-web-key (work in progress), 1239 June 2014. 1241 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1242 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1243 in progress), June 2014. 1245 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1246 version 1.3", RFC 1951, May 1996. 1248 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1249 Requirement Levels", BCP 14, RFC 2119, March 1997. 1251 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1252 10646", STD 63, RFC 3629, November 2003. 1254 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1255 Housley, R., and W. Polk, "Internet X.509 Public Key 1256 Infrastructure Certificate and Certificate Revocation List 1257 (CRL) Profile", RFC 5280, May 2008. 1259 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1260 Interchange Format", RFC 7159, March 2014. 1262 [USASCII] American National Standards Institute, "Coded Character 1263 Set -- 7-bit American Standard Code for Information 1264 Interchange", ANSI X3.4, 1986. 1266 12.2. Informative References 1268 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1269 McGrew, D., Foley, J., and K. Paterson, "Authenticated 1270 Encryption with AES-CBC and HMAC-SHA", 1271 draft-mcgrew-aead-aes-cbc-hmac-sha2-04 (work in progress), 1272 February 2014. 1274 [I-D.rescorla-jsms] 1275 Rescorla, E. and J. Hildebrand, "JavaScript Message 1276 Security Format", draft-rescorla-jsms-00 (work in 1277 progress), March 2011. 1279 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1280 Encryption", September 2010. 1282 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1283 Cryptographic Message Syntax", RFC 3218, January 2002. 1285 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1286 Requirements for Security", BCP 106, RFC 4086, June 2005. 1288 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1289 RFC 5652, September 2009. 1291 [W3C.REC-xmlenc-core1-20130411] 1292 Eastlake, D., Reagle, J., Hirsch, F., and T. Roessler, 1293 "XML Encryption Syntax and Processing Version 1.1", World 1294 Wide Web Consortium Recommendation REC-xmlenc-core1- 1295 20130411, April 2013, 1296 . 1298 Appendix A. JWE Examples 1300 This section provides examples of JWE computations. 1302 A.1. Example JWE using RSAES OAEP and AES GCM 1304 This example encrypts the plaintext "The true sign of intelligence is 1305 not knowledge but imagination." to the recipient using RSAES OAEP for 1306 key encryption and AES GCM for content encryption. The 1307 representation of this plaintext (using JSON array notation) is: 1309 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1310 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1311 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1312 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1313 110, 97, 116, 105, 111, 110, 46] 1315 A.1.1. JOSE Header 1317 The following example JWE Protected Header declares that: 1319 o the Content Encryption Key is encrypted to the recipient using the 1320 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1322 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1323 bit key to produce the Ciphertext. 1325 {"alg":"RSA-OAEP","enc":"A256GCM"} 1327 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1328 Header)) gives this value: 1330 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1332 A.1.2. Content Encryption Key (CEK) 1334 Generate a 256 bit random Content Encryption Key (CEK). In this 1335 example, the value (using JSON array notation) is: 1337 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1338 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1339 234, 64, 252] 1341 A.1.3. Key Encryption 1343 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1344 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1345 key represented in JSON Web Key [JWK] format below (with line breaks 1346 within values for display purposes only): 1348 {"kty":"RSA", 1349 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1350 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1351 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1352 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1353 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1354 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1355 "e":"AQAB", 1356 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1357 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1358 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1359 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1360 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1361 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ" 1362 } 1364 The resulting JWE Encrypted Key value is: 1366 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1367 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1368 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1369 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1370 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1371 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1372 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1373 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1374 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1375 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1376 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1377 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1378 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1379 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1380 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1381 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1382 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1383 117, 114, 135, 206] 1385 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1386 this value (with line breaks for display purposes only): 1388 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1389 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1390 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1391 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1392 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1393 6UklfCpIMfIjf7iGdXKHzg 1395 A.1.4. Initialization Vector 1397 Generate a random 96 bit JWE Initialization Vector. In this example, 1398 the value is: 1400 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1402 Encoding this JWE Initialization Vector as BASE64URL(JWE 1403 Initialization Vector) gives this value: 1405 48V1_ALb6US04U3b 1407 A.1.5. Additional Authenticated Data 1409 Let the Additional Authenticated Data encryption parameter be 1410 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1412 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1413 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1414 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1416 A.1.6. Content Encryption 1418 Encrypt the Plaintext with AES GCM using the CEK as the encryption 1419 key, the JWE Initialization Vector, and the Additional Authenticated 1420 Data value above, requesting a 128 bit Authentication Tag output. 1421 The resulting Ciphertext is: 1423 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1424 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1425 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1426 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1427 160, 109, 64, 63, 192] 1428 The resulting Authentication Tag value is: 1430 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1431 210, 145] 1433 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1434 value (with line breaks for display purposes only): 1436 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1437 SdiwkIr3ajwQzaBtQD_A 1439 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1440 Tag) gives this value: 1442 XFBoMYUZodetZdvTiFvSkQ 1444 A.1.7. Complete Representation 1446 Assemble the final representation: The Compact Serialization of this 1447 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1448 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1449 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1450 Authentication Tag). 1452 The final result in this example (with line breaks for display 1453 purposes only) is: 1455 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1456 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1457 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1458 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1459 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1460 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1461 6UklfCpIMfIjf7iGdXKHzg. 1462 48V1_ALb6US04U3b. 1463 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1464 SdiwkIr3ajwQzaBtQD_A. 1465 XFBoMYUZodetZdvTiFvSkQ 1467 A.1.8. Validation 1469 This example illustrates the process of creating a JWE with RSAES 1470 OAEP for key encryption and AES GCM for content encryption. These 1471 results can be used to validate JWE decryption implementations for 1472 these algorithms. Note that since the RSAES OAEP computation 1473 includes random values, the encryption results above will not be 1474 completely reproducible. However, since the AES GCM computation is 1475 deterministic, the JWE Encrypted Ciphertext values will be the same 1476 for all encryptions performed using these inputs. 1478 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1480 This example encrypts the plaintext "Live long and prosper." to the 1481 recipient using RSAES-PKCS1-V1_5 for key encryption and 1482 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1483 of this plaintext (using JSON array notation) is: 1485 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1486 112, 114, 111, 115, 112, 101, 114, 46] 1488 A.2.1. JOSE Header 1490 The following example JWE Protected Header declares that: 1492 o the Content Encryption Key is encrypted to the recipient using the 1493 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1495 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1496 algorithm to produce the Ciphertext. 1498 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1500 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1501 Header)) gives this value: 1503 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1505 A.2.2. Content Encryption Key (CEK) 1507 Generate a 256 bit random Content Encryption Key (CEK). In this 1508 example, the key value is: 1510 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1511 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1512 44, 207] 1514 A.2.3. Key Encryption 1516 Encrypt the CEK with the recipient's public key using the RSAES- 1517 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1518 uses the RSA key represented in JSON Web Key [JWK] format below (with 1519 line breaks within values for display purposes only): 1521 {"kty":"RSA", 1522 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1523 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1524 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1525 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1526 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1527 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1528 "e":"AQAB", 1529 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1530 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1531 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1532 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1533 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1534 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1535 } 1537 The resulting JWE Encrypted Key value is: 1539 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1540 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1541 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1542 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1543 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1544 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1545 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1546 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1547 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1548 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1549 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1550 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1551 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1552 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1553 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1554 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1555 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1556 146, 114, 165, 204, 71, 136, 41, 252] 1558 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1559 this value (with line breaks for display purposes only): 1561 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1562 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1563 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1564 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1565 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1566 -B3oWh2TbqmScqXMR4gp_A 1568 A.2.4. Initialization Vector 1570 Generate a random 128 bit JWE Initialization Vector. In this 1571 example, the value is: 1573 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1574 101] 1576 Encoding this JWE Initialization Vector as BASE64URL(JWE 1577 Initialization Vector) gives this value: 1579 AxY8DCtDaGlsbGljb3RoZQ 1581 A.2.5. Additional Authenticated Data 1583 Let the Additional Authenticated Data encryption parameter be 1584 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1586 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1587 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1588 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1589 50, 73, 110, 48] 1591 A.2.6. Content Encryption 1593 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1594 the encryption key, the JWE Initialization Vector, and the Additional 1595 Authenticated Data value above. The steps for doing this using the 1596 values from Appendix A.3 are detailed in Appendix B. The resulting 1597 Ciphertext is: 1599 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1600 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1601 112, 56, 102] 1603 The resulting Authentication Tag value is: 1605 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1606 191] 1608 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1609 value: 1611 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1613 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1614 Tag) gives this value: 1616 9hH0vgRfYgPnAHOd8stkvw 1618 A.2.7. Complete Representation 1620 Assemble the final representation: The Compact Serialization of this 1621 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1622 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1623 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1624 Authentication Tag). 1626 The final result in this example (with line breaks for display 1627 purposes only) is: 1629 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1630 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1631 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1632 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1633 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1634 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1635 -B3oWh2TbqmScqXMR4gp_A. 1636 AxY8DCtDaGlsbGljb3RoZQ. 1637 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1638 9hH0vgRfYgPnAHOd8stkvw 1640 A.2.8. Validation 1642 This example illustrates the process of creating a JWE with RSAES- 1643 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1644 encryption. These results can be used to validate JWE decryption 1645 implementations for these algorithms. Note that since the RSAES- 1646 PKCS1-V1_5 computation includes random values, the encryption results 1647 above will not be completely reproducible. However, since the AES 1648 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1649 will be the same for all encryptions performed using these inputs. 1651 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1653 This example encrypts the plaintext "Live long and prosper." to the 1654 recipient using AES Key Wrap for key encryption and 1655 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1656 of this plaintext (using JSON array notation) is: 1658 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1659 112, 114, 111, 115, 112, 101, 114, 46] 1661 A.3.1. JOSE Header 1663 The following example JWE Protected Header declares that: 1665 o the Content Encryption Key is encrypted to the recipient using the 1666 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1667 Encrypted Key and 1669 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1670 algorithm to produce the Ciphertext. 1672 {"alg":"A128KW","enc":"A128CBC-HS256"} 1674 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1675 Header)) gives this value: 1677 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1679 A.3.2. Content Encryption Key (CEK) 1681 Generate a 256 bit random Content Encryption Key (CEK). In this 1682 example, the value is: 1684 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1685 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1686 44, 207] 1688 A.3.3. Key Encryption 1690 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1691 algorithm to produce the JWE Encrypted Key. This example uses the 1692 symmetric key represented in JSON Web Key [JWK] format below: 1694 {"kty":"oct", 1695 "k":"GawgguFyGrWKav7AX4VKUg" 1696 } 1698 The resulting JWE Encrypted Key value is: 1700 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1701 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1702 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1704 Encoding this JWE Encrypted Key as BASE64URL(JWE Encrypted Key) gives 1705 this value: 1707 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1709 A.3.4. Initialization Vector 1711 Generate a random 128 bit JWE Initialization Vector. In this 1712 example, the value is: 1714 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1715 101] 1717 Encoding this JWE Initialization Vector as BASE64URL(JWE 1718 Initialization Vector) gives this value: 1720 AxY8DCtDaGlsbGljb3RoZQ 1722 A.3.5. Additional Authenticated Data 1724 Let the Additional Authenticated Data encryption parameter be 1725 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1727 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1728 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1729 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1730 110, 48] 1732 A.3.6. Content Encryption 1734 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1735 the encryption key, the JWE Initialization Vector, and the Additional 1736 Authenticated Data value above. The steps for doing this using the 1737 values from this example are detailed in Appendix B. The resulting 1738 Ciphertext is: 1740 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1741 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1742 112, 56, 102] 1744 The resulting Authentication Tag value is: 1746 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1747 194, 85] 1749 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1750 value: 1752 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1754 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1755 Tag) gives this value: 1757 U0m_YmjN04DJvceFICbCVQ 1759 A.3.7. Complete Representation 1761 Assemble the final representation: The Compact Serialization of this 1762 result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || 1763 BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization 1764 Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE 1765 Authentication Tag). 1767 The final result in this example (with line breaks for display 1768 purposes only) is: 1770 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1771 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1772 AxY8DCtDaGlsbGljb3RoZQ. 1773 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1774 U0m_YmjN04DJvceFICbCVQ 1776 A.3.8. Validation 1778 This example illustrates the process of creating a JWE with AES Key 1779 Wrap for key encryption and AES GCM for content encryption. These 1780 results can be used to validate JWE decryption implementations for 1781 these algorithms. Also, since both the AES Key Wrap and AES GCM 1782 computations are deterministic, the resulting JWE value will be the 1783 same for all encryptions performed using these inputs. Since the 1784 computation is reproducible, these results can also be used to 1785 validate JWE encryption implementations for these algorithms. 1787 A.4. Example JWE using JWE JSON Serialization 1789 This section contains an example using the JWE JSON Serialization. 1790 This example demonstrates the capability for encrypting the same 1791 plaintext to multiple recipients. 1793 Two recipients are present in this example. The algorithm and key 1794 used for the first recipient are the same as that used in 1795 Appendix A.2. The algorithm and key used for the second recipient 1796 are the same as that used in Appendix A.3. The resulting JWE 1797 Encrypted Key values are therefore the same; those computations are 1798 not repeated here. 1800 The Plaintext, the Content Encryption Key (CEK), JWE Initialization 1801 Vector, and JWE Protected Header are shared by all recipients (which 1802 must be the case, since the Ciphertext and Authentication Tag are 1803 also shared). 1805 A.4.1. JWE Per-Recipient Unprotected Headers 1807 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1808 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1809 encrypt the CEK. Key ID values are supplied for both keys. The two 1810 per-recipient header values used to represent these algorithms and 1811 Key IDs are: 1813 {"alg":"RSA1_5","kid":"2011-04-29"} 1815 and 1817 {"alg":"A128KW","kid":"7"} 1819 A.4.2. JWE Protected Header 1821 The Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1822 algorithm to produce the common JWE Ciphertext and JWE Authentication 1823 Tag values. The JWE Protected Header value representing this is: 1825 {"enc":"A128CBC-HS256"} 1827 Encoding this JWE Protected Header as BASE64URL(UTF8(JWE Protected 1828 Header)) gives this value: 1830 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1832 A.4.3. JWE Unprotected Header 1834 This JWE uses the "jku" Header Parameter to reference a JWK Set. This 1835 is represented in the following JWE Unprotected Header value as: 1837 {"jku":"https://server.example.com/keys.jwks"} 1839 A.4.4. Complete JOSE Header Values 1841 Combining the per-recipient, protected, and unprotected header values 1842 supplied, the JOSE Header values used for the first and second 1843 recipient respectively are: 1845 {"alg":"RSA1_5", 1846 "kid":"2011-04-29", 1847 "enc":"A128CBC-HS256", 1848 "jku":"https://server.example.com/keys.jwks"} 1850 and 1851 {"alg":"A128KW", 1852 "kid":"7", 1853 "enc":"A128CBC-HS256", 1854 "jku":"https://server.example.com/keys.jwks"} 1856 A.4.5. Additional Authenticated Data 1858 Let the Additional Authenticated Data encryption parameter be 1859 ASCII(BASE64URL(UTF8(JWE Protected Header))). This value is: 1861 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1862 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1864 A.4.6. Content Encryption 1866 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1867 the encryption key, the JWE Initialization Vector, and the Additional 1868 Authenticated Data value above. The steps for doing this using the 1869 values from Appendix A.3 are detailed in Appendix B. The resulting 1870 Ciphertext is: 1872 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1873 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1874 112, 56, 102] 1876 The resulting Authentication Tag value is: 1878 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1879 207] 1881 Encoding this JWE Ciphertext as BASE64URL(JWE Ciphertext) gives this 1882 value: 1884 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1886 Encoding this JWE Authentication Tag as BASE64URL(JWE Authentication 1887 Tag) gives this value: 1889 Mz-VPPyU4RlcuYv1IwIvzw 1891 A.4.7. Complete JWE JSON Serialization Representation 1893 The complete JSON Web Encryption JSON Serialization for these values 1894 is as follows (with line breaks within values for display purposes 1895 only): 1897 {"protected": 1898 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1899 "unprotected": 1900 {"jku":"https://server.example.com/keys.jwks"}, 1901 "recipients":[ 1902 {"header": 1903 {"alg":"RSA1_5","kid":"2011-04-29"}, 1904 "encrypted_key": 1905 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1906 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1907 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 1908 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 1909 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 1910 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 1911 {"header": 1912 {"alg":"A128KW","kid":"7"}, 1913 "encrypted_key": 1914 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1915 "iv": 1916 "AxY8DCtDaGlsbGljb3RoZQ", 1917 "ciphertext": 1918 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1919 "tag": 1920 "Mz-VPPyU4RlcuYv1IwIvzw" 1921 } 1923 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 1925 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 1926 authenticated encryption computation using the values from the 1927 example in Appendix A.3. As described where this algorithm is 1928 defined in Sections 5.2 and 5.2.3 of JWA, the AES_CBC_HMAC_SHA2 1929 family of algorithms are implemented using Advanced Encryption 1930 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #7 1931 padding to perform the encryption and an HMAC SHA-2 function to 1932 perform the integrity calculation - in this case, HMAC SHA-256. 1934 B.1. Extract MAC_KEY and ENC_KEY from Key 1936 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example 1937 (using JSON array notation) is: 1939 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1940 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1941 44, 207] 1943 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 1944 which is: 1946 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1947 206] 1949 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 1950 is: 1952 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 1953 207] 1955 Note that the MAC key comes before the encryption key in the input 1956 key K; this is in the opposite order of the algorithm names in the 1957 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 1959 B.2. Encrypt Plaintext to Create Ciphertext 1961 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 1962 using PKCS #7 padding using the ENC_KEY above. The Plaintext in this 1963 example is: 1965 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1966 112, 114, 111, 115, 112, 101, 114, 46] 1968 The encryption result is as follows, which is the Ciphertext output: 1970 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1971 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1972 112, 56, 102] 1974 B.3. 64 Bit Big Endian Representation of AAD Length 1976 The Additional Authenticated Data (AAD) in this example is: 1978 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1979 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1980 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1981 110, 48] 1983 This AAD is 51 bytes long, which is 408 bits long. The octet string 1984 AL, which is the number of bits in AAD expressed as a big endian 64 1985 bit unsigned integer is: 1987 [0, 0, 0, 0, 0, 0, 1, 152] 1989 B.4. Initialization Vector Value 1991 The Initialization Vector value used in this example is: 1993 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1994 101] 1996 B.5. Create Input to HMAC Computation 1998 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 1999 the AL value. The result of this concatenation is: 2001 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2002 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2003 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2004 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 2005 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 2006 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 2007 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 2009 B.6. Compute HMAC Value 2011 Compute the HMAC SHA-256 of the concatenated value above. This 2012 result M is: 2014 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2015 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 2016 86, 229, 116] 2018 B.7. Truncate HMAC Value to Create Authentication Tag 2020 Use the first half (128 bits) of the HMAC output M as the 2021 Authentication Tag output T. This truncated value is: 2023 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2024 194, 85] 2026 Appendix C. Acknowledgements 2028 Solutions for encrypting JSON content were also explored by JSON 2029 Simple Encryption [JSE] and JavaScript Message Security Format 2030 [I-D.rescorla-jsms], both of which significantly influenced this 2031 draft. This draft attempts to explicitly reuse as many of the 2032 relevant concepts from XML Encryption 1.1 2033 [W3C.REC-xmlenc-core1-20130411] and RFC 5652 [RFC5652] as possible, 2034 while utilizing simple, compact JSON-based data structures. 2036 Special thanks are due to John Bradley, Eric Rescorla, and Nat 2037 Sakimura for the discussions that helped inform the content of this 2038 specification, to Eric Rescorla and Joe Hildebrand for allowing the 2039 reuse of text from [I-D.rescorla-jsms] in this document, and to Eric 2040 Rescorla for co-authoring many drafts of this specification. 2042 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2043 Jay for validating the examples in this specification. 2045 This specification is the work of the JOSE Working Group, which 2046 includes dozens of active and dedicated participants. In particular, 2047 the following individuals contributed ideas, feedback, and wording 2048 that influenced this specification: 2050 Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick 2051 Hardt, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Tony 2052 Nadalin, Hideki Nara, Axel Nennker, Emmanuel Raviart, Eric Rescorla, 2053 Nat Sakimura, Jim Schaad, Hannes Tschofenig, and Sean Turner. 2055 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2056 Sean Turner, Stephen Farrell, and Kathleen Moriarty served as 2057 Security area directors during the creation of this specification. 2059 Appendix D. Document History 2061 [[ to be removed by the RFC Editor before publication as an RFC ]] 2063 -29 2065 o Replaced the terms JWS Header, JWE Header, and JWT Header with a 2066 single JOSE Header term defined in the JWS specification. This 2067 also enabled a single Header Parameter definition to be used and 2068 reduced other areas of duplication between specifications. 2070 -28 2072 o Specified the use of PKCS #7 padding with AES CBC, rather than 2073 PKCS #5. (PKCS #7 is a superset of PKCS #5, and is appropriate 2074 for the 16 octet blocks used by AES CBC.) 2076 o Revised the introduction to the Security Considerations section. 2077 Also moved a security consideration item here from the JWA draft. 2079 -27 2081 o Described additional security considerations. 2083 o Added the "x5t#S256" (X.509 Certificate SHA-256 Thumbprint) header 2084 parameter. 2086 -26 2088 o Noted that octet sequences are depicted using JSON array notation. 2090 o Updated references, including to W3C specifications. 2092 -25 2094 o Corrected two external section number references that had changed. 2096 o Corrected a typo in an algorithm name in the prose of an example. 2098 -24 2100 o Corrected complete JSON Serialization example. 2102 o Replaced uses of the term "associated data" wherever it was used 2103 to refer to a data value with "additional authenticated data", 2104 since both terms were being used as synonyms, causing confusion. 2106 o Updated the JSON reference to RFC 7159. 2108 o Thanked Eric Rescorla for helping to author of most of the drafts 2109 of this specification and removed him from the current author 2110 list. 2112 -23 2114 o Corrected a use of the word "payload" to "plaintext". 2116 -22 2118 o Corrected RFC 2119 terminology usage. 2120 o Replaced references to draft-ietf-json-rfc4627bis with RFC 7158. 2122 -21 2124 o Changed some references from being normative to informative, 2125 addressing issue #90. 2127 o Applied review comments to the JSON Serialization section, 2128 addressing issue #178. 2130 -20 2131 o Made terminology definitions more consistent, addressing issue 2132 #165. 2134 o Restructured the JSON Serialization section to call out the 2135 parameters used in hanging lists, addressing issue #178. 2137 o Replaced references to RFC 4627 with draft-ietf-json-rfc4627bis, 2138 addressing issue #90. 2140 -19 2142 o Reordered the key selection parameters. 2144 -18 2146 o Updated the mandatory-to-implement (MTI) language to say that 2147 applications using this specification need to specify what 2148 serialization and serialization features are used for that 2149 application, addressing issue #176. 2151 o Changes to address editorial and minor issues #89, #135, #165, 2152 #174, #175, #177, #179, and #180. 2154 o Used Header Parameter Description registry field. 2156 -17 2158 o Refined the "typ" and "cty" definitions to always be MIME Media 2159 Types, with the omission of "application/" prefixes recommended 2160 for brevity, addressing issue #50. 2162 o Updated the mandatory-to-implement (MTI) language to say that 2163 general-purpose implementations must implement the single 2164 recipient case for both serializations whereas special-purpose 2165 implementations can implement just one serialization if that meets 2166 the needs of the use cases the implementation is designed for, 2167 addressing issue #176. 2169 o Explicitly named all the logical components of a JWE and defined 2170 the processing rules and serializations in terms of those 2171 components, addressing issues #60, #61, and #62. 2173 o Replaced verbose repetitive phases such as "base64url encode the 2174 octets of the UTF-8 representation of X" with mathematical 2175 notation such as "BASE64URL(UTF8(X))". 2177 o Header Parameters and processing rules occurring in both JWS and 2178 JWE are now referenced in JWS by JWE, rather than duplicated, 2179 addressing issue #57. 2181 o Terms used in multiple documents are now defined in one place and 2182 incorporated by reference. Some lightly used or obvious terms 2183 were also removed. This addresses issue #58. 2185 -16 2187 o Changes to address editorial and minor issues #163, #168, #169, 2188 #170, #172, and #173. 2190 -15 2192 o Clarified that it is an application decision which recipients' 2193 encrypted content must successfully validate for the JWE to be 2194 accepted, addressing issue #35. 2196 o Changes to address editorial issues #34, #164, and #169. 2198 -14 2200 o Clarified that the "protected", "unprotected", "header", "iv", 2201 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2202 JSON Serialization when their values would be empty. Stated that 2203 the "recipients" array must always be present. 2205 -13 2207 o Added an "aad" (Additional Authenticated Data) member for the JWE 2208 JSON Serialization, enabling Additional Authenticated Data to be 2209 supplied that is not double base64url encoded, addressing issue 2210 #29. 2212 -12 2214 o Clarified that the "typ" and "cty" header parameters are used in 2215 an application-specific manner and have no effect upon the JWE 2216 processing. 2218 o Replaced the MIME types "application/jwe+json" and 2219 "application/jwe" with "application/jose+json" and 2220 "application/jose". 2222 o Stated that recipients MUST either reject JWEs with duplicate 2223 Header Parameter Names or use a JSON parser that returns only the 2224 lexically last duplicate member name. 2226 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2227 be with the algorithm descriptions that use them. 2229 o Added a Serializations section with parallel treatment of the JWE 2230 Compact Serialization and the JWE JSON Serialization and also 2231 moved the former Implementation Considerations content there. 2233 o Restored use of the term "AEAD". 2235 o Changed terminology from "block encryption" to "content 2236 encryption". 2238 -11 2240 o Added Key Identification section. 2242 o Removed the Encrypted Key value from the AAD computation since it 2243 is already effectively integrity protected by the encryption 2244 process. The AAD value now only contains the representation of 2245 the JWE Encrypted Header. 2247 o For the JWE JSON Serialization, enable Header Parameter values to 2248 be specified in any of three parameters: the "protected" member 2249 that is integrity protected and shared among all recipients, the 2250 "unprotected" member that is not integrity protected and shared 2251 among all recipients, and the "header" member that is not 2252 integrity protected and specific to a particular recipient. (This 2253 does not affect the JWE Compact Serialization, in which all Header 2254 Parameter values are in a single integrity protected JWE Header 2255 value.) 2257 o Shortened the names "authentication_tag" to "tag" and 2258 "initialization_vector" to "iv" in the JWE JSON Serialization, 2259 addressing issue #20. 2261 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2263 o Removed suggested compact serialization for multiple recipients. 2265 o Changed the MIME type name "application/jwe-js" to 2266 "application/jwe+json", addressing issue #22. 2268 o Tightened the description of the "crit" (critical) header 2269 parameter. 2271 -10 2272 o Changed the JWE processing rules for multiple recipients so that a 2273 single AAD value contains the header parameters and encrypted key 2274 values for all the recipients, enabling AES GCM to be safely used 2275 for multiple recipients. 2277 o Added an appendix suggesting a possible compact serialization for 2278 JWEs with multiple recipients. 2280 -09 2282 o Added JWE JSON Serialization, as specified by 2283 draft-jones-jose-jwe-json-serialization-04. 2285 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2286 parameter value. 2288 o Defined that the default action for header parameters that are not 2289 understood is to ignore them unless specifically designated as 2290 "MUST be understood" or included in the new "crit" (critical) 2291 header parameter list. This addressed issue #6. 2293 o Corrected "x5c" description. This addressed issue #12. 2295 o Changed from using the term "byte" to "octet" when referring to 8 2296 bit values. 2298 o Added Key Management Mode definitions to terminology section and 2299 used the defined terms to provide clearer key management 2300 instructions. This addressed issue #5. 2302 o Added text about preventing the recipient from behaving as an 2303 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2305 o Changed from using the term "Integrity Value" to "Authentication 2306 Tag". 2308 o Changed member name from "integrity_value" to "authentication_tag" 2309 in the JWE JSON Serialization. 2311 o Removed Initialization Vector from the AAD value since it is 2312 already integrity protected by all of the authenticated encryption 2313 algorithms specified in the JWA specification. 2315 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2316 and "A256CBC-HS512". The new algorithms perform the same 2317 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2318 but with the Initialization Vector and Authentication Tag values 2319 remaining separate from the Ciphertext value in the output 2320 representation. Also deleted the header parameters "epu" 2321 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2322 they are no longer used. 2324 -08 2326 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2327 since the term AEAD in the RFC 5116 sense implied the use of a 2328 particular data representation, rather than just referring to the 2329 class of algorithms that perform authenticated encryption with 2330 associated data. 2332 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2333 Tschofenig. Many of these simplified the terminology used. 2335 o Clarified statements of the form "This header parameter is 2336 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2338 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2339 Web Signature and Encryption Header Parameters registry. 2341 o Added seriesInfo information to Internet Draft references. 2343 -07 2345 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2347 o Updated values for example AES CBC calculations. 2349 o Made several local editorial changes to clean up loose ends left 2350 over from to the decision to only support block encryption methods 2351 providing integrity. One of these changes was to explicitly state 2352 that the "enc" (encryption method) algorithm must be an 2353 Authenticated Encryption algorithm with a specified key length. 2355 -06 2357 o Removed the "int" and "kdf" parameters and defined the new 2358 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2359 "A256CBC+HS512" to replace the former uses of AES CBC, which 2360 required the use of separate integrity and key derivation 2361 functions. 2363 o Included additional values in the Concat KDF calculation -- the 2364 desired output size and the algorithm value, and optionally 2365 PartyUInfo and PartyVInfo values. Added the optional header 2366 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2367 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2368 PartyVInfo). Updated the KDF examples accordingly. 2370 o Promoted Initialization Vector from being a header parameter to 2371 being a top-level JWE element. This saves approximately 16 bytes 2372 in the compact serialization, which is a significant savings for 2373 some use cases. Promoting the Initialization Vector out of the 2374 header also avoids repeating this shared value in the JSON 2375 serialization. 2377 o Changed "x5c" (X.509 Certificate Chain) representation from being 2378 a single string to being an array of strings, each containing a 2379 single base64 encoded DER certificate value, representing elements 2380 of the certificate chain. 2382 o Added an AES Key Wrap example. 2384 o Reordered the encryption steps so CMK creation is first, when 2385 required. 2387 o Correct statements in examples about which algorithms produce 2388 reproducible results. 2390 -05 2392 o Support both direct encryption using a shared or agreed upon 2393 symmetric key, and the use of a shared or agreed upon symmetric 2394 key to key wrap the CMK. 2396 o Added statement that "StringOrURI values are compared as case- 2397 sensitive strings with no transformations or canonicalizations 2398 applied". 2400 o Updated open issues. 2402 o Indented artwork elements to better distinguish them from the body 2403 text. 2405 -04 2407 o Refer to the registries as the primary sources of defined values 2408 and then secondarily reference the sections defining the initial 2409 contents of the registries. 2411 o Normatively reference XML Encryption 1.1 for its security 2412 considerations. 2414 o Reference draft-jones-jose-jwe-json-serialization instead of 2415 draft-jones-json-web-encryption-json-serialization. 2417 o Described additional open issues. 2419 o Applied editorial suggestions. 2421 -03 2423 o Added the "kdf" (key derivation function) header parameter to 2424 provide crypto agility for key derivation. The default KDF 2425 remains the Concat KDF with the SHA-256 digest function. 2427 o Reordered encryption steps so that the Encoded JWE Header is 2428 always created before it is needed as an input to the 2429 Authenticated Encryption "additional authenticated data" 2430 parameter. 2432 o Added the "cty" (content type) header parameter for declaring type 2433 information about the secured content, as opposed to the "typ" 2434 (type) header parameter, which declares type information about 2435 this object. 2437 o Moved description of how to determine whether a header is for a 2438 JWS or a JWE from the JWT spec to the JWE spec. 2440 o Added complete encryption examples for both Authenticated 2441 Encryption and non-Authenticated Encryption algorithms. 2443 o Added complete key derivation examples. 2445 o Added "Collision Resistant Namespace" to the terminology section. 2447 o Reference ITU.X690.1994 for DER encoding. 2449 o Added Registry Contents sections to populate registry values. 2451 o Numerous editorial improvements. 2453 -02 2455 o When using Authenticated Encryption algorithms (such as AES GCM), 2456 use the "additional authenticated data" parameter to provide 2457 integrity for the header, encrypted key, and ciphertext and use 2458 the resulting "authentication tag" value as the JWE Authentication 2459 Tag. 2461 o Defined KDF output key sizes. 2463 o Generalized text to allow key agreement to be employed as an 2464 alternative to key wrapping or key encryption. 2466 o Changed compression algorithm from gzip to DEFLATE. 2468 o Clarified that it is an error when a "kid" value is included and 2469 no matching key is found. 2471 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2472 rejected. 2474 o Clarified the relationship between "typ" header parameter values 2475 and MIME types. 2477 o Registered application/jwe MIME type and "JWE" typ header 2478 parameter value. 2480 o Simplified JWK terminology to get replace the "JWK Key Object" and 2481 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2482 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2483 between single keys and sets of keys. As part of this change, the 2484 Header Parameter Name for a public key value was changed from 2485 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2487 o Added suggestion on defining additional header parameters such as 2488 "x5t#S256" in the future for certificate thumbprints using hash 2489 algorithms other than SHA-1. 2491 o Specify RFC 2818 server identity validation, rather than RFC 6125 2492 (paralleling the same decision in the OAuth specs). 2494 o Generalized language to refer to Message Authentication Codes 2495 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2496 unless in a context specific to HMAC algorithms. 2498 o Reformatted to give each header parameter its own section heading. 2500 -01 2502 o Added an integrity check for non-Authenticated Encryption 2503 algorithms. 2505 o Added "jpk" and "x5c" header parameters for including JWK public 2506 keys and X.509 certificate chains directly in the header. 2508 o Clarified that this specification is defining the JWE Compact 2509 Serialization. Referenced the new JWE-JS spec, which defines the 2510 JWE JSON Serialization. 2512 o Added text "New header parameters should be introduced sparingly 2513 since an implementation that does not understand a parameter MUST 2514 reject the JWE". 2516 o Clarified that the order of the encryption and decryption steps is 2517 not significant in cases where there are no dependencies between 2518 the inputs and outputs of the steps. 2520 o Made other editorial improvements suggested by JOSE working group 2521 participants. 2523 -00 2525 o Created the initial IETF draft based upon 2526 draft-jones-json-web-encryption-02 with no normative changes. 2528 o Changed terminology to no longer call both digital signatures and 2529 HMACs "signatures". 2531 Authors' Addresses 2533 Michael B. Jones 2534 Microsoft 2536 Email: mbj@microsoft.com 2537 URI: http://self-issued.info/ 2539 Joe Hildebrand 2540 Cisco Systems, Inc. 2542 Email: jhildebr@cisco.com