idnits 2.17.00 (12 Aug 2021) /tmp/idnits48752/draft-ietf-jose-json-web-encryption-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 30, 2012) is 3581 days in the past. Is this intentional? 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: '1' on line 1813 -- Looks like a reference, but probably isn't: '0' on line 1858 -- Looks like a reference, but probably isn't: '69' on line 1811 -- Looks like a reference, but probably isn't: '110' on line 1811 -- Looks like a reference, but probably isn't: '99' on line 1811 -- Looks like a reference, but probably isn't: '114' on line 1811 -- Looks like a reference, but probably isn't: '121' on line 1811 -- Looks like a reference, but probably isn't: '112' on line 1811 -- Looks like a reference, but probably isn't: '116' on line 1811 -- Looks like a reference, but probably isn't: '105' on line 1811 -- Looks like a reference, but probably isn't: '111' on line 1811 -- Looks like a reference, but probably isn't: '2' on line 1858 -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X690.1994' -- Possible downref: Non-RFC (?) normative reference: ref. 'JWA' -- Possible downref: Non-RFC (?) normative reference: ref. 'JWK' -- Possible downref: Non-RFC (?) normative reference: ref. 'JWS' ** Downref: Normative reference to an Historic RFC: RFC 1421 ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Downref: Normative reference to an Informational RFC: RFC 2818 ** Obsolete normative reference: RFC 4288 (Obsoleted by RFC 6838) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) Summary: 6 errors (**), 0 flaws (~~), 1 warning (==), 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 E. Rescorla 5 Expires: January 31, 2013 RTFM 6 J. Hildebrand 7 Cisco 8 July 30, 2012 10 JSON Web Encryption (JWE) 11 draft-ietf-jose-json-web-encryption-05 13 Abstract 15 JSON Web Encryption (JWE) is a means of representing encrypted 16 content using JavaScript Object Notation (JSON) data structures. 17 Cryptographic algorithms and identifiers for use with this 18 specification are described in the separate JSON Web Algorithms (JWA) 19 specification. Related digital signature and MAC capabilities are 20 described in the separate JSON Web Signature (JWS) specification. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on January 31, 2013. 39 Copyright Notice 41 Copyright (c) 2012 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 58 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 6 60 3.1. Example JWE with an Integrated Integrity Check . . . . . . 6 61 3.2. Example JWE with a Separate Integrity Check . . . . . . . 8 62 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10 63 4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 10 64 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 11 65 4.1.2. "enc" (Encryption Method) Header Parameter . . . . . . 11 66 4.1.3. "int" (Integrity Algorithm) Header Parameter . . . . . 11 67 4.1.4. "kdf" (Key Derivation Function) Header Parameter . . . 12 68 4.1.5. "iv" (Initialization Vector) Header Parameter . . . . 12 69 4.1.6. "epk" (Ephemeral Public Key) Header Parameter . . . . 12 70 4.1.7. "zip" (Compression Algorithm) Header Parameter . . . . 12 71 4.1.8. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 13 72 4.1.9. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 13 73 4.1.10. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 13 74 4.1.11. "x5t" (X.509 Certificate Thumbprint) Header 75 Parameter . . . . . . . . . . . . . . . . . . . . . . 13 76 4.1.12. "x5c" (X.509 Certificate Chain) Header Parameter . . . 14 77 4.1.13. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14 78 4.1.14. "typ" (Type) Header Parameter . . . . . . . . . . . . 14 79 4.1.15. "cty" (Content Type) Header Parameter . . . . . . . . 15 80 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15 81 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 15 82 5. Message Encryption . . . . . . . . . . . . . . . . . . . . . . 15 83 6. Message Decryption . . . . . . . . . . . . . . . . . . . . . . 17 84 7. CMK Encryption . . . . . . . . . . . . . . . . . . . . . . . . 18 85 8. Integrity Value Calculation . . . . . . . . . . . . . . . . . 19 86 9. Encrypting JWEs with Cryptographic Algorithms . . . . . . . . 19 87 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 88 10.1. Registration of JWE Header Parameter Names . . . . . . . . 20 89 10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 20 90 10.2. JSON Web Signature and Encryption Type Values 91 Registration . . . . . . . . . . . . . . . . . . . . . . . 22 92 10.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 22 93 10.3. Media Type Registration . . . . . . . . . . . . . . . . . 22 94 10.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 22 95 11. Security Considerations . . . . . . . . . . . . . . . . . . . 23 96 12. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 23 97 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24 98 13.1. Normative References . . . . . . . . . . . . . . . . . . . 24 99 13.2. Informative References . . . . . . . . . . . . . . . . . . 26 100 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 26 101 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 26 102 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 26 103 A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 27 104 A.1.3. Content Master Key (CMK) . . . . . . . . . . . . . . . 27 105 A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 27 106 A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 30 107 A.1.6. "Additional Authenticated Data" Parameter . . . . . . 30 108 A.1.7. Plaintext Encryption . . . . . . . . . . . . . . . . . 31 109 A.1.8. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 31 110 A.1.9. Encoded JWE Integrity Value . . . . . . . . . . . . . 31 111 A.1.10. Complete Representation . . . . . . . . . . . . . . . 31 112 A.1.11. Validation . . . . . . . . . . . . . . . . . . . . . . 32 113 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES CBC . . . . . . 32 114 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 32 115 A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 33 116 A.2.3. Content Master Key (CMK) . . . . . . . . . . . . . . . 33 117 A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 33 118 A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 36 119 A.2.6. Key Derivation . . . . . . . . . . . . . . . . . . . . 36 120 A.2.7. Plaintext Encryption . . . . . . . . . . . . . . . . . 36 121 A.2.8. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 36 122 A.2.9. Secured Input Value . . . . . . . . . . . . . . . . . 37 123 A.2.10. JWE Integrity Value . . . . . . . . . . . . . . . . . 38 124 A.2.11. Encoded JWE Integrity Value . . . . . . . . . . . . . 38 125 A.2.12. Complete Representation . . . . . . . . . . . . . . . 38 126 A.2.13. Validation . . . . . . . . . . . . . . . . . . . . . . 39 127 A.3. Example Key Derivation with Outputs <= Hash Size . . . . . 39 128 A.3.1. CEK Generation . . . . . . . . . . . . . . . . . . . . 39 129 A.3.2. CIK Generation . . . . . . . . . . . . . . . . . . . . 40 130 A.4. Example Key Derivation with Outputs >= Hash Size . . . . . 40 131 A.4.1. CEK Generation . . . . . . . . . . . . . . . . . . . . 40 132 A.4.2. CIK Generation . . . . . . . . . . . . . . . . . . . . 41 133 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 42 134 Appendix C. Document History . . . . . . . . . . . . . . . . . . 42 135 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 45 137 1. Introduction 139 JSON Web Encryption (JWE) is a compact encryption format intended for 140 space constrained environments such as HTTP Authorization headers and 141 URI query parameters. It represents this content using JavaScript 142 Object Notation (JSON) [RFC4627] based data structures. The JWE 143 cryptographic mechanisms encrypt and provide integrity protection for 144 arbitrary sequences of bytes. 146 Cryptographic algorithms and identifiers for use with this 147 specification are described in the separate JSON Web Algorithms (JWA) 148 [JWA] specification. Related digital signature and MAC capabilities 149 are described in the separate JSON Web Signature (JWS) [JWS] 150 specification. 152 1.1. Notational Conventions 154 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 155 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 156 document are to be interpreted as described in Key words for use in 157 RFCs to Indicate Requirement Levels [RFC2119]. 159 2. Terminology 161 JSON Web Encryption (JWE) A data structure representing an encrypted 162 message. The structure consists of four parts: the JWE Header, 163 the JWE Encrypted Key, the JWE Ciphertext, and the JWE Integrity 164 Value. 166 Plaintext The bytes to be encrypted - a.k.a., the message. The 167 plaintext can contain an arbitrary sequence of bytes. 169 Ciphertext An encrypted representation of the Plaintext. 171 Content Encryption Key (CEK) A symmetric key used to encrypt the 172 Plaintext for the recipient to produce the Ciphertext. 174 Content Integrity Key (CIK) A key used with a MAC function to ensure 175 the integrity of the Ciphertext and the parameters used to create 176 it. 178 Content Master Key (CMK) A key from which the CEK and CIK are 179 derived. When key wrapping or key encryption are employed, the 180 CMK is randomly generated and encrypted to the recipient as the 181 JWE Encrypted Key. When direct encryption with a shared symmetric 182 key is employed, the CMK is the shared key. When key agreement 183 without key wrapping is employed, the CMK is the result of the key 184 agreement algorithm. 186 JWE Header A string representing a JSON object that describes the 187 encryption operations applied to create the JWE Encrypted Key, the 188 JWE Ciphertext, and the JWE Integrity Value. 190 JWE Encrypted Key When key wrapping or key encryption are employed, 191 the Content Master Key (CMK) is encrypted with the intended 192 recipient's key and the resulting encrypted content is recorded as 193 a byte array, which is referred to as the JWE Encrypted Key. 194 Otherwise, when direct encryption with a shared or agreed upon 195 symmetric key is employed, the JWE Encrypted Key is the empty byte 196 array. 198 JWE Ciphertext A byte array containing the Ciphertext. 200 JWE Integrity Value A byte array containing a MAC value that ensures 201 the integrity of the Ciphertext and the parameters used to create 202 it. 204 Base64url Encoding The URL- and filename-safe Base64 encoding 205 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 206 safe) '=' padding characters omitted, as permitted by Section 3.2. 207 (See Appendix C of [JWS] for notes on implementing base64url 208 encoding without padding.) 210 Encoded JWE Header Base64url encoding of the bytes of the UTF-8 211 [RFC3629] representation of the JWE Header. 213 Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted 214 Key. 216 Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. 218 Encoded JWE Integrity Value Base64url encoding of the JWE Integrity 219 Value. 221 Header Parameter Name The name of a member of the JSON object 222 representing a JWE Header. 224 Header Parameter Value The value of a member of the JSON object 225 representing a JWE Header. 227 JWE Compact Serialization A representation of the JWE as the 228 concatenation of the Encoded JWE Header, the Encoded JWE Encrypted 229 Key, the Encoded JWE Ciphertext, and the Encoded JWE Integrity 230 Value in that order, with the four strings being separated by 231 period ('.') characters. 233 AEAD Algorithm An Authenticated Encryption with Associated Data 234 (AEAD) [RFC5116] encryption algorithm is one that provides an 235 integrated content integrity check. AES Galois/Counter Mode (GCM) 236 is one such algorithm. 238 Collision Resistant Namespace A namespace that allows names to be 239 allocated in a manner such that they are highly unlikely to 240 collide with other names. For instance, collision resistance can 241 be achieved through administrative delegation of portions of the 242 namespace or through use of collision-resistant name allocation 243 functions. Examples of Collision Resistant Namespaces include: 244 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 245 X.660 and X.670 Recommendation series, and Universally Unique 246 IDentifiers (UUIDs) [RFC4122]. When using an administratively 247 delegated namespace, the definer of a name needs to take 248 reasonable precautions to ensure they are in control of the 249 portion of the namespace they use to define the name. 251 StringOrURI A JSON string value, with the additional requirement 252 that while arbitrary string values MAY be used, any value 253 containing a ":" character MUST be a URI [RFC3986]. StringOrURI 254 values are compared as case-sensitive strings with no 255 transformations or canonicalizations applied. 257 3. JSON Web Encryption (JWE) Overview 259 JWE represents encrypted content using JSON data structures and 260 base64url encoding. The representation consists of four parts: the 261 JWE Header, the JWE Encrypted Key, the JWE Ciphertext, and the JWE 262 Integrity Value. In the Compact Serialization, the four parts are 263 base64url-encoded for transmission, and represented as the 264 concatenation of the encoded strings in that order, with the four 265 strings being separated by period ('.') characters. (A JSON 266 Serialization for this information is defined in the separate JSON 267 Web Encryption JSON Serialization (JWE-JS) [JWE-JS] specification.) 269 JWE utilizes encryption to ensure the confidentiality of the 270 Plaintext. JWE adds a content integrity check if not provided by the 271 underlying encryption algorithm. 273 3.1. Example JWE with an Integrated Integrity Check 275 This example encrypts the plaintext "Live long and prosper." to the 276 recipient using RSAES OAEP and AES GCM. The AES GCM algorithm has an 277 integrated integrity check. 279 The following example JWE Header declares that: 281 o the Content Master Key is encrypted to the recipient using the 282 RSAES OAEP algorithm to produce the JWE Encrypted Key, 284 o the Plaintext is encrypted using the AES GCM algorithm with a 256 285 bit key to produce the Ciphertext, and 287 o the 96 bit Initialization Vector (IV) with the base64url encoding 288 "48V1_ALb6US04U3b" was used. 290 {"alg":"RSA-OAEP","enc":"A256GCM","iv":"48V1_ALb6US04U3b"} 292 Base64url encoding the bytes of the UTF-8 representation of the JWE 293 Header yields this Encoded JWE Header value (with line breaks for 294 display purposes only): 296 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00iLCJpdiI6IjQ4VjFfQUxi 297 NlVTMDRVM2IifQ 299 The remaining steps to finish creating this JWE are: 301 o Generate a random Content Master Key (CMK) 303 o Encrypt the CMK with the recipient's public key using the RSAES 304 OAEP algorithm to produce the JWE Encrypted Key 306 o Base64url encode the JWE Encrypted Key to produce the Encoded JWE 307 Encrypted Key 309 o Concatenate the Encoded JWE Header value, a period character 310 ('.'), and the Encoded JWE Encrypted Key to create the "additional 311 authenticated data" parameter for the AES GCM algorithm. 313 o Encrypt the Plaintext with AES GCM, using the IV, the CMK as the 314 encryption key, and the "additional authenticated data" value 315 above, requesting a 128 bit "authentication tag" output 317 o Base64url encode the resulting Ciphertext to create the Encoded 318 JWE Ciphertext 320 o Base64url encode the resulting "authentication tag" to create the 321 Encoded JWE Integrity Value 323 o Assemble the final representation: The Compact Serialization of 324 this result is the concatenation of the Encoded JWE Header, the 325 Encoded JWE Encrypted Key, the Encoded JWE Ciphertext, and the 326 Encoded JWE Integrity Value in that order, with the four strings 327 being separated by three period ('.') characters. 329 The final result in this example (with line breaks for display 330 purposes only) is: 332 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00iLCJpdiI6IjQ4VjFfQUxi 333 NlVTMDRVM2IifQ. 334 jvwoyhWxOMboB5cxX6ncAi7Wp3Q5FKRtlmIx35pfR9HpEa6Oy-iEpxEqM30W3YcR 335 Q8WU9ouRoO5jd6tfdcpX-2X-OteHw4dnMXdMLjHGGx86LMDeFRAN2KGz7EGPJiva 336 w0yM80fzT3zY0PKrIvU5ml1M5szqUnX4Jw0-PNcIM_j-L5YkLhv3Yk04XCwTJwxN 337 NmXCflYAQO9f00Aa213TJJr6dbHV6I642FwU-EWvtEfN3evgX3EFIVYSnT3HCHkA 338 AIdBQ9ykD-abRzVA_dGp_yJAZQcrZuNTqzThd_22YMPhIpzTygfC_4k7qqxI6t7L 339 e_l5_o-taUG7vaNAl5FjEQ. 340 _e21tGGhac_peEFkLXr2dMPUZiUkrw. 341 YbZSeHCNDZBqAdzpROlyiw 343 See Appendix A.1 for the complete details of computing this JWE. 345 3.2. Example JWE with a Separate Integrity Check 347 This example encrypts the plaintext "Now is the time for all good men 348 to come to the aid of their country." to the recipient using RSAES- 349 PKCS1-V1_5 and AES CBC. AES CBC does not have an integrated 350 integrity check, so a separate integrity check calculation is 351 performed using HMAC SHA-256, with separate encryption and integrity 352 keys being derived from a master key using the Concat KDF with the 353 SHA-256 digest function. 355 The following example JWE Header (with line breaks for display 356 purposes only) declares that: 358 o the Content Master Key is encrypted to the recipient using the 359 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key, 361 o the Plaintext is encrypted using the AES CBC algorithm with a 128 362 bit key to produce the Ciphertext, 364 o the JWE Integrity Value safeguarding the integrity of the 365 Ciphertext and the parameters used to create it was computed with 366 the HMAC SHA-256 algorithm, and 368 o the 128 bit Initialization Vector (IV) with the base64url encoding 369 "AxY8DCtDaGlsbGljb3RoZQ" was used. 371 {"alg":"RSA1_5","enc":"A128CBC","int":"HS256","iv":"AxY8DCtDaGls 372 bGljb3RoZQ"} 374 Base64url encoding the bytes of the UTF-8 representation of the JWE 375 Header yields this Encoded JWE Header value (with line breaks for 376 display purposes only): 378 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDIiwiaW50IjoiSFMyNTYiLCJp 379 diI6IkF4WThEQ3REYUdsc2JHbGpiM1JvWlEifQ 381 The remaining steps to finish creating this JWE are like the previous 382 example, but with an additional step to compute the separate 383 integrity value: 385 o Generate a random Content Master Key (CMK) 387 o Encrypt the CMK with the recipient's public key using the RSAES- 388 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key 390 o Base64url encode the JWE Encrypted Key to produce the Encoded JWE 391 Encrypted Key 393 o Use the Concat key derivation function to derive Content 394 Encryption Key (CEK) and Content Integrity Key (CIK) values from 395 the CMK 397 o Encrypt the Plaintext with AES CBC using the CEK and IV to produce 398 the Ciphertext 400 o Base64url encode the resulting Ciphertext to create the Encoded 401 JWE Ciphertext 403 o Concatenate the Encoded JWE Header value, a period character 404 ('.'), the Encoded JWE Encrypted Key, a second period character, 405 and the Encoded JWE Ciphertext to create the value to integrity 406 protect 408 o Compute the HMAC SHA-256 of this value using the CIK to create the 409 JWE Integrity Value 411 o Base64url encode the resulting JWE Integrity Value to create the 412 Encoded JWE Integrity Value 414 o Assemble the final representation: The Compact Serialization of 415 this result is the concatenation of the Encoded JWE Header, the 416 Encoded JWE Encrypted Key, the Encoded JWE Ciphertext, and the 417 Encoded JWE Integrity Value in that order, with the four strings 418 being separated by three period ('.') characters. 420 The final result in this example (with line breaks for display 421 purposes only) is: 423 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDIiwiaW50IjoiSFMyNTYiLCJp 424 diI6IkF4WThEQ3REYUdsc2JHbGpiM1JvWlEifQ. 425 IPI_z172hSWHMFgED8EG9DM6hIXU_6NaO1DImCn0vNeuoBq847Sl6qw_GHSYHJUQ 426 XtXJq7S_CxWVrI82wjrOyaQca5tLZRZc45BfKHeqByThKI261QevEK56SyAwwXfK 427 KZjSvkQ5dwTFSgfy76rMSUvVynHYEhdCatBF9HWTAiXPx7hgZixG1FeP_QCmOylz 428 2VClVyYFCbjKREOwBFf-puNYfO75S3LNlJUtTsGGQL2oTKpMsEiUTdefkje91VX9 429 h8g7908lFsggbjV7NicJsufuXxnTj1fcWIrRDeNIOmakiPEODi0gTSz0ou-W-LWK 430 -3T1zYlOIiIKBjsExQKZ-w. 431 _Z_djlIoC4MDSCKireWS2beti4Q6iSG2UjFujQvdz-_PQdUcFNkOulegD6BgjgdF 432 LjeB4HHOO7UHvP8PEDu0a0sA2a_-CI0w2YQQ2QQe35M. 433 c41k4T4eAgCCt63m8ZNmiOinMciFFypOFpvid7i6D0k 435 See Appendix A.2 for the complete details of computing this JWE. 437 4. JWE Header 439 The members of the JSON object represented by the JWE Header describe 440 the encryption applied to the Plaintext and optionally additional 441 properties of the JWE. The Header Parameter Names within this object 442 MUST be unique; JWEs with duplicate Header Parameter Names MUST be 443 rejected. Implementations MUST understand the entire contents of the 444 header; otherwise, the JWE MUST be rejected. 446 There are two ways of distinguishing whether a header is a JWS Header 447 or a JWE Header. The first is by examining the "alg" (algorithm) 448 header value. If the value represents a digital signature or MAC 449 algorithm, or is the value "none", it is for a JWS; if it represents 450 an encryption or key agreement algorithm, it is for a JWE. A second 451 method is determining whether an "enc" (encryption method) member 452 exists. If the "enc" member exists, it is a JWE; otherwise, it is a 453 JWS. Both methods will yield the same result for all legal input 454 values. 456 There are three classes of Header Parameter Names: Reserved Header 457 Parameter Names, Public Header Parameter Names, and Private Header 458 Parameter Names. 460 4.1. Reserved Header Parameter Names 462 The following header parameter names are reserved with meanings as 463 defined below. All the names are short because a core goal of JWE is 464 for the representations to be compact. 466 Additional reserved header parameter names MAY be defined via the 467 IANA JSON Web Signature and Encryption Header Parameters registry 468 [JWS]. As indicated by the common registry, JWSs and JWEs share a 469 common header parameter space; when a parameter is used by both 470 specifications, its usage must be compatible between the 471 specifications. 473 4.1.1. "alg" (Algorithm) Header Parameter 475 The "alg" (algorithm) header parameter identifies the cryptographic 476 algorithm used to encrypt or determine the value of the Content 477 Master Key (CMK). The algorithm specified by the "alg" value MUST be 478 supported by the implementation and there MUST be a key for use with 479 that algorithm associated with the intended recipient or the JWE MUST 480 be rejected. "alg" values SHOULD either be registered in the IANA 481 JSON Web Signature and Encryption Algorithms registry [JWA] or be a 482 URI that contains a Collision Resistant Namespace. The "alg" value 483 is a case sensitive string containing a StringOrURI value. This 484 header parameter is REQUIRED. 486 A list of defined "alg" values can be found in the IANA JSON Web 487 Signature and Encryption Algorithms registry [JWA]; the initial 488 contents of this registry is the values defined in Section 4.1 of the 489 JSON Web Algorithms (JWA) [JWA] specification. 491 4.1.2. "enc" (Encryption Method) Header Parameter 493 The "enc" (encryption method) header parameter identifies the 494 symmetric encryption algorithm used to encrypt the Plaintext to 495 produce the Ciphertext. The algorithm specified by the "enc" value 496 MUST be supported by the implementation or the JWE MUST be rejected. 497 "enc" values SHOULD either be registered in the IANA JSON Web 498 Signature and Encryption Algorithms registry [JWA] or be a URI that 499 contains a Collision Resistant Namespace. The "enc" value is a case 500 sensitive string containing a StringOrURI value. This header 501 parameter is REQUIRED. 503 A list of defined "enc" values can be found in the IANA JSON Web 504 Signature and Encryption Algorithms registry [JWA]; the initial 505 contents of this registry is the values defined in Section 4.2 of the 506 JSON Web Algorithms (JWA) [JWA] specification. 508 4.1.3. "int" (Integrity Algorithm) Header Parameter 510 The "int" (integrity algorithm) header parameter identifies the 511 cryptographic algorithm used to safeguard the integrity of the 512 Ciphertext and the parameters used to create it. The "int" parameter 513 uses the MAC subset of the algorithm values used by the JWS "alg" 514 parameter. "int" values SHOULD either be registered in the IANA JSON 515 Web Signature and Encryption Algorithms registry [JWA] or be a URI 516 that contains a Collision Resistant Namespace. The "int" value is a 517 case sensitive string containing a StringOrURI value. This header 518 parameter is REQUIRED when an AEAD algorithm is not used to encrypt 519 the Plaintext and MUST NOT be present when an AEAD algorithm is used. 521 A list of defined "int" values can be found in the IANA JSON Web 522 Signature and Encryption Algorithms registry [JWA]; the initial 523 contents of this registry is the values defined in Section 4.3 of the 524 JSON Web Algorithms (JWA) [JWA] specification. 526 4.1.4. "kdf" (Key Derivation Function) Header Parameter 528 The "kdf" (key derivation function) header parameter identifies the 529 cryptographic algorithm used to derive the CEK and CIK from the CMK. 530 "kdf" values SHOULD either be registered in the IANA JSON Web 531 Signature and Encryption Algorithms registry [JWA] or be a URI that 532 contains a Collision Resistant Namespace. The "kdf" value is a case 533 sensitive string containing a StringOrURI value. This header 534 parameter is OPTIONAL when an AEAD algorithm is not used to encrypt 535 the Plaintext and MUST NOT be present when an AEAD algorithm is used. 537 When an AEAD algorithm is not used and no "kdf" header parameter is 538 present, the "CS256" KDF [JWA] SHALL be used. 540 A list of defined "kdf" values can be found in the IANA JSON Web 541 Signature and Encryption Algorithms registry [JWA]; the initial 542 contents of this registry is the values defined in Section 4.4 of the 543 JSON Web Algorithms (JWA) [JWA] specification. 545 4.1.5. "iv" (Initialization Vector) Header Parameter 547 The "iv" (initialization vector) value for algorithms requiring it, 548 represented as a base64url encoded string. This header parameter is 549 OPTIONAL, although its use is REQUIRED with some "enc" algorithms. 551 4.1.6. "epk" (Ephemeral Public Key) Header Parameter 553 The "epk" (ephemeral public key) value created by the originator for 554 the use in key agreement algorithms. This key is represented as a 555 JSON Web Key [JWK] value. This header parameter is OPTIONAL, 556 although its use is REQUIRED with some "alg" algorithms. 558 4.1.7. "zip" (Compression Algorithm) Header Parameter 560 The "zip" (compression algorithm) applied to the Plaintext before 561 encryption, if any. If present, the value of the "zip" header 562 parameter MUST be the case sensitive string "DEF". Compression is 563 performed with the DEFLATE [RFC1951] algorithm. If no "zip" 564 parameter is present, no compression is applied to the Plaintext 565 before encryption. This header parameter is OPTIONAL. 567 4.1.8. "jku" (JWK Set URL) Header Parameter 569 The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that 570 refers to a resource for a set of JSON-encoded public keys, one of 571 which corresponds to the key used to encrypt the JWE; this can be 572 used to determine the private key needed to decrypt the JWE. The 573 keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The 574 protocol used to acquire the resource MUST provide integrity 575 protection; an HTTP GET request to retrieve the certificate MUST use 576 TLS [RFC2818] [RFC5246]; the identity of the server MUST be 577 validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. This 578 header parameter is OPTIONAL. 580 4.1.9. "jwk" (JSON Web Key) Header Parameter 582 The "jwk" (JSON Web Key) header parameter is a public key that 583 corresponds to the key used to encrypt the JWE; this can be used to 584 determine the private key needed to decrypt the JWE. This key is 585 represented as a JSON Web Key [JWK]. This header parameter is 586 OPTIONAL. 588 4.1.10. "x5u" (X.509 URL) Header Parameter 590 The "x5u" (X.509 URL) header parameter is a URI [RFC3986] that refers 591 to a resource for the X.509 public key certificate or certificate 592 chain [RFC5280] corresponding to the key used to encrypt the JWE; 593 this can be used to determine the private key needed to decrypt the 594 JWE. The identified resource MUST provide a representation of the 595 certificate or certificate chain that conforms to RFC 5280 [RFC5280] 596 in PEM encoded form [RFC1421]. The certificate containing the public 597 key of the entity that encrypted the JWE MUST be the first 598 certificate. This MAY be followed by additional certificates, with 599 each subsequent certificate being the one used to certify the 600 previous one. The protocol used to acquire the resource MUST provide 601 integrity protection; an HTTP GET request to retrieve the certificate 602 MUST use TLS [RFC2818] [RFC5246]; the identity of the server MUST be 603 validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. This 604 header parameter is OPTIONAL. 606 4.1.11. "x5t" (X.509 Certificate Thumbprint) Header Parameter 608 The "x5t" (X.509 Certificate Thumbprint) header parameter provides a 609 base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER 610 encoding of the X.509 certificate [RFC5280] corresponding to the key 611 used to encrypt the JWE; this can be used to determine the private 612 key needed to decrypt the JWE. This header parameter is OPTIONAL. 614 If, in the future, certificate thumbprints need to be computed using 615 hash functions other than SHA-1, it is suggested that additional 616 related header parameters be defined for that purpose. For example, 617 it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint 618 using SHA-256) header parameter could be defined by registering it in 619 the IANA JSON Web Signature and Encryption Header Parameters registry 620 [JWS]. 622 4.1.12. "x5c" (X.509 Certificate Chain) Header Parameter 624 The "x5c" (X.509 Certificate Chain) header parameter contains the 625 X.509 public key certificate or certificate chain [RFC5280] 626 corresponding to the key used to encrypt the JWE; this can be used to 627 determine the private key needed to decrypt the JWE. The certificate 628 or certificate chain is represented as an array of certificate 629 values. Each value is a base64 encoded ([RFC4648] Section 4 - not 630 base64url encoded) DER [ITU.X690.1994] PKIX certificate value. The 631 certificate containing the public key of the entity that encrypted 632 the JWE MUST be the first certificate. This MAY be followed by 633 additional certificates, with each subsequent certificate being the 634 one used to certify the previous one. The recipient MUST verify the 635 certificate chain according to [RFC5280] and reject the JWE if any 636 validation failure occurs. This header parameter is OPTIONAL. 638 See Appendix B of [JWS] for an example "x5c" value. 640 4.1.13. "kid" (Key ID) Header Parameter 642 The "kid" (key ID) header parameter is a hint indicating which key 643 was used to encrypt the JWE; this can be used to determine the 644 private key needed to decrypt the JWE. This parameter allows 645 originators to explicitly signal a change of key to recipients. 646 Should the recipient be unable to locate a key corresponding to the 647 "kid" value, they SHOULD treat that condition as an error. The 648 interpretation of the "kid" value is unspecified. Its value MUST be 649 a string. This header parameter is OPTIONAL. 651 When used with a JWK, the "kid" value MAY be used to match a JWK 652 "kid" parameter value. 654 4.1.14. "typ" (Type) Header Parameter 656 The "typ" (type) header parameter is used to declare the type of this 657 object. The type value "JWE" MAY be used to indicate that this 658 object is a JWE. The "typ" value is a case sensitive string. This 659 header parameter is OPTIONAL. 661 MIME Media Type [RFC2046] values MAY be used as "typ" values. 663 "typ" values SHOULD either be registered in the IANA JSON Web 664 Signature and Encryption Type Values registry [JWS] or be a URI that 665 contains a Collision Resistant Namespace. 667 4.1.15. "cty" (Content Type) Header Parameter 669 The "cty" (content type) header parameter is used to declare the type 670 of the encrypted content (the Plaintext). The "cty" value is a case 671 sensitive string. This header parameter is OPTIONAL. 673 The values used for the "cty" header parameter come from the same 674 value space as the "typ" header parameter, with the same rules 675 applying. 677 4.2. Public Header Parameter Names 679 Additional header parameter names can be defined by those using JWEs. 680 However, in order to prevent collisions, any new header parameter 681 name SHOULD either be registered in the IANA JSON Web Signature and 682 Encryption Header Parameters registry [JWS] or be a URI that contains 683 a Collision Resistant Namespace. In each case, the definer of the 684 name or value needs to take reasonable precautions to make sure they 685 are in control of the part of the namespace they use to define the 686 header parameter name. 688 New header parameters should be introduced sparingly, as they can 689 result in non-interoperable JWEs. 691 4.3. Private Header Parameter Names 693 A producer and consumer of a JWE may agree to any header parameter 694 name that is not a Reserved Name Section 4.1 or a Public Name 695 Section 4.2. Unlike Public Names, these private names are subject to 696 collision and should be used with caution. 698 5. Message Encryption 700 The message encryption process is as follows. The order of the steps 701 is not significant in cases where there are no dependencies between 702 the inputs and outputs of the steps. 704 1. When key agreement is employed, use the key agreement algorithm 705 to compute the value of the agreed upon key. When key agreement 706 without key wrapping is employed, let the Content Master Key 707 (CMK) be the agreed upon key. When key agreement with key 708 wrapping is employed, the agreed upon key will be used to wrap 709 the CMK. 711 2. When key wrapping, key encryption, or key agreement with key 712 wrapping are employed, generate a random Content Master Key 713 (CMK). See RFC 4086 [RFC4086] for considerations on generating 714 random values. The CMK MUST have a length equal to that of the 715 larger of the required encryption and integrity keys. 717 3. When key wrapping, key encryption, or key agreement with key 718 wrapping are employed, encrypt the CMK for the recipient (see 719 Section 7) and let the result be the JWE Encrypted Key. 720 Otherwise, when direct encryption with a shared or agreed upon 721 symmetric key is employed, let the JWE Encrypted Key be the 722 empty byte array. 724 4. When direct encryption with a shared symmetric key is employed, 725 let the Content Master Key (CMK) be the shared key. 727 5. Base64url encode the JWE Encrypted Key to create the Encoded JWE 728 Encrypted Key. 730 6. Generate a random Initialization Vector (IV) of the correct size 731 for the algorithm (if required for the algorithm). 733 7. If not using an AEAD algorithm, run the key derivation algorithm 734 specified by the "kdf" header parameter to generate the Content 735 Encryption Key (CEK) and the Content Integrity Key (CIK); 736 otherwise (when using an AEAD algorithm), set the CEK to be the 737 CMK. 739 8. Compress the Plaintext if a "zip" parameter was included. 741 9. Serialize the (compressed) Plaintext into a byte sequence M. 743 10. Create a JWE Header containing the encryption parameters used. 744 Note that white space is explicitly allowed in the 745 representation and no canonicalization need be performed before 746 encoding. 748 11. Base64url encode the bytes of the UTF-8 representation of the 749 JWE Header to create the Encoded JWE Header. 751 12. Encrypt M using the CEK and IV to form the byte sequence C. If 752 an AEAD algorithm is used, use the bytes of the ASCII 753 representation of the concatenation of the Encoded JWE Header, a 754 period ('.') character, and the Encoded JWE Encrypted Key as the 755 "additional authenticated data" parameter value for the 756 encryption. 758 13. Base64url encode C to create the Encoded JWE Ciphertext. 760 14. If not using an AEAD algorithm, run the integrity algorithm (see 761 Section 8) using the CIK to compute the JWE Integrity Value; 762 otherwise (when using an AEAD algorithm), set the JWE Integrity 763 Value to be the "authentication tag" value produced by the AEAD 764 algorithm. 766 15. Base64url encode the JWE Integrity Value to create the Encoded 767 JWE Integrity Value. 769 16. The four encoded parts, taken together, are the result. 771 17. The Compact Serialization of this result is the concatenation of 772 the Encoded JWE Header, the Encoded JWE Encrypted Key, the 773 Encoded JWE Ciphertext, and the Encoded JWE Integrity Value in 774 that order, with the four strings being separated by period 775 ('.') characters. 777 6. Message Decryption 779 The message decryption process is the reverse of the encryption 780 process. The order of the steps is not significant in cases where 781 there are no dependencies between the inputs and outputs of the 782 steps. If any of these steps fails, the JWE MUST be rejected. 784 1. Determine the Encoded JWE Header, the Encoded JWE Encrypted Key, 785 the Encoded JWE Ciphertext, and the Encoded JWE Integrity Value 786 values contained in the JWE. When using the Compact 787 Serialization, these four values are represented in that order, 788 separated by period characters. 790 2. The Encoded JWE Header, the Encoded JWE Encrypted Key, the 791 Encoded JWE Ciphertext, and the Encoded JWE Integrity Value MUST 792 be successfully base64url decoded following the restriction that 793 no padding characters have been used. 795 3. The resulting JWE Header MUST be completely valid JSON syntax 796 conforming to RFC 4627 [RFC4627]. 798 4. The resulting JWE Header MUST be validated to only include 799 parameters and values whose syntax and semantics are both 800 understood and supported. 802 5. Verify that the JWE uses a key known to the recipient. 804 6. When key agreement is employed, use the key agreement algorithm 805 to compute the value of the agreed upon key. When key agreement 806 without key wrapping is employed, let the Content Master Key 807 (CMK) be the agreed upon key. When key agreement with key 808 wrapping is employed, the agreed upon key will be used to 809 decrypt the JWE Encrypted Key. 811 7. When key wrapping, key encryption, or key agreement with key 812 wrapping are employed, decrypt the JWE Encrypted Key to produce 813 the Content Master Key (CMK). The CMK MUST have a length equal 814 to that of the larger of the required encryption and integrity 815 keys. 817 8. When direct encryption with a shared symmetric key is employed, 818 let the Content Master Key (CMK) be the shared key. 820 9. If not using an AEAD algorithm, run the key derivation algorithm 821 specified by the "kdf" header parameter to generate the Content 822 Encryption Key (CEK) and the Content Integrity Key (CIK); 823 otherwise (when using an AEAD algorithm), set the CEK to be the 824 CMK. 826 10. Decrypt the binary representation of the JWE Ciphertext using 827 the CEK and IV. If an AEAD algorithm is used, use the bytes of 828 the ASCII representation of the concatenation of the Encoded JWE 829 Header, a period ('.') character, and the Encoded JWE Encrypted 830 Key as the "additional authenticated data" parameter value for 831 the decryption. 833 11. If not using an AEAD algorithm, run the integrity algorithm (see 834 Section 8) using the CIK to compute an integrity value for the 835 input received. This computed value MUST match the received JWE 836 Integrity Value; otherwise (when using an AEAD algorithm), the 837 received JWE Integrity Value MUST match the "authentication tag" 838 value produced by the AEAD algorithm. 840 12. Uncompress the result of the previous step, if a "zip" parameter 841 was included. 843 13. Output the resulting Plaintext. 845 7. CMK Encryption 847 JWE supports three forms of Content Master Key (CMK) encryption: 849 o Asymmetric encryption under the recipient's public key. 851 o Symmetric encryption under a key shared between the sender and 852 receiver. 854 o Symmetric encryption under a key agreed upon between the sender 855 and receiver. 857 See the algorithms registered for "enc" usage in the IANA JSON Web 858 Signature and Encryption Algorithms registry [JWA] and Section 4.1 of 859 the JSON Web Algorithms (JWA) [JWA] specification for lists of 860 encryption algorithms that can be used for CMK encryption. 862 8. Integrity Value Calculation 864 When a non-AEAD algorithm is used (an algorithm without an integrated 865 content check), JWE adds an explicit integrity check value to the 866 representation. This value is computed in the manner described in 867 the JSON Web Signature (JWS) [JWS] specification, with these 868 modifications: 870 o The algorithm used is taken from the "int" (integrity algorithm) 871 header parameter rather than the "alg" header parameter. 873 o The algorithm MUST be a MAC algorithm (such as HMAC SHA-256). 875 o The JWS Secured Input used is the bytes of the ASCII 876 representation of the concatenation of the Encoded JWE Header, a 877 period ('.') character, the Encoded JWE Encrypted Key, a period 878 ('.') character, and the Encoded JWE Ciphertext. 880 o The CIK is used as the MAC key. 882 The computed JWS Signature value is the resulting integrity value. 884 9. Encrypting JWEs with Cryptographic Algorithms 886 JWE uses cryptographic algorithms to encrypt the Plaintext and the 887 Content Encryption Key (CMK) and to provide integrity protection for 888 the JWE Header, JWE Encrypted Key, and JWE Ciphertext. The JSON Web 889 Algorithms (JWA) [JWA] specification specifies a set of cryptographic 890 algorithms and identifiers to be used with this specification and 891 defines registries for additional such algorithms. Specifically, 892 Section 4.1 specifies a set of "alg" (algorithm) header parameter 893 values, Section 4.2 specifies a set of "enc" (encryption method) 894 header parameter values, Section 4.3 specifies a set of "int" 895 (integrity algorithm) header parameter values, and Section 4.4 896 specifies a set of "kdf" (key derivation function) header parameter 897 values intended for use this specification. It also describes the 898 semantics and operations that are specific to these algorithms and 899 algorithm families. 901 Public keys employed for encryption can be identified using the 902 Header Parameter methods described in Section 4.1 or can be 903 distributed using methods that are outside the scope of this 904 specification. 906 10. IANA Considerations 908 10.1. Registration of JWE Header Parameter Names 910 This specification registers the Header Parameter Names defined in 911 Section 4.1 in the IANA JSON Web Signature and Encryption Header 912 Parameters registry [JWS]. 914 10.1.1. Registry Contents 916 o Header Parameter Name: "alg" 918 o Change Controller: IETF 920 o Specification Document(s): Section 4.1.1 of [[ this document ]] 922 o Header Parameter Name: "enc" 924 o Change Controller: IETF 926 o Specification Document(s): Section 4.1.2 of [[ this document ]] 928 o Header Parameter Name: "int" 930 o Change Controller: IETF 932 o Specification Document(s): Section 4.1.3 of [[ this document ]] 934 o Header Parameter Name: "kdf" 936 o Change Controller: IETF 938 o Specification Document(s): Section 4.1.4 of [[ this document ]] 940 o Header Parameter Name: "iv" 942 o Change Controller: IETF 943 o Specification Document(s): Section 4.1.5 of [[ this document ]] 945 o Header Parameter Name: "epk" 947 o Change Controller: IETF 949 o Specification Document(s): Section 4.1.6 of [[ this document ]] 951 o Header Parameter Name: "zip" 953 o Change Controller: IETF 955 o Specification Document(s): Section 4.1.7 of [[ this document ]] 957 o Header Parameter Name: "jku" 959 o Change Controller: IETF 961 o Specification Document(s): Section 4.1.8 of [[ this document ]] 963 o Header Parameter Name: "jwk" 965 o Change Controller: IETF 967 o Specification document(s): Section 4.1.9 of [[ this document ]] 969 o Header Parameter Name: "x5u" 971 o Change Controller: IETF 973 o Specification Document(s): Section 4.1.10 of [[ this document ]] 975 o Header Parameter Name: "x5t" 977 o Change Controller: IETF 979 o Specification Document(s): Section 4.1.11 of [[ this document ]] 981 o Header Parameter Name: "x5c" 983 o Change Controller: IETF 985 o Specification Document(s): Section 4.1.12 of [[ this document ]] 987 o Header Parameter Name: "kid" 989 o Change Controller: IETF 990 o Specification Document(s): Section 4.1.13 of [[ this document ]] 992 o Header Parameter Name: "typ" 994 o Change Controller: IETF 996 o Specification Document(s): Section 4.1.14 of [[ this document ]] 998 o Header Parameter Name: "cty" 1000 o Change Controller: IETF 1002 o Specification Document(s): Section 4.1.15 of [[ this document ]] 1004 10.2. JSON Web Signature and Encryption Type Values Registration 1006 10.2.1. Registry Contents 1008 This specification registers the "JWE" type value in the IANA JSON 1009 Web Signature and Encryption Type Values registry [JWS]: 1011 o "typ" Header Parameter Value: "JWE" 1013 o Abbreviation for MIME Type: application/jwe 1015 o Change Controller: IETF 1017 o Specification Document(s): Section 4.1.14 of [[ this document ]] 1019 10.3. Media Type Registration 1021 10.3.1. Registry Contents 1023 This specification registers the "application/jwe" Media Type 1024 [RFC2046] in the MIME Media Type registry [RFC4288] to indicate that 1025 the content is a JWE using the Compact Serialization. 1027 o Type Name: application 1029 o Subtype Name: jwe 1031 o Required Parameters: n/a 1033 o Optional Parameters: n/a 1035 o Encoding considerations: JWE values are encoded as a series of 1036 base64url encoded values (some of which may be the empty string) 1037 separated by period ('.') characters 1039 o Security Considerations: See the Security Considerations section 1040 of this document 1042 o Interoperability Considerations: n/a 1044 o Published Specification: [[ this document ]] 1046 o Applications that use this media type: OpenID Connect and other 1047 applications using encrypted JWTs 1049 o Additional Information: Magic number(s): n/a, File extension(s): 1050 n/a, Macintosh file type code(s): n/a 1052 o Person & email address to contact for further information: Michael 1053 B. Jones, mbj@microsoft.com 1055 o Intended Usage: COMMON 1057 o Restrictions on Usage: none 1059 o Author: Michael B. Jones, mbj@microsoft.com 1061 o Change Controller: IETF 1063 11. Security Considerations 1065 All of the security issues faced by any cryptographic application 1066 must be faced by a JWS/JWE/JWK agent. Among these issues are 1067 protecting the user's private key, preventing various attacks, and 1068 helping the user avoid mistakes such as inadvertently encrypting a 1069 message for the wrong recipient. The entire list of security 1070 considerations is beyond the scope of this document, but some 1071 significant concerns are listed here. 1073 All the security considerations in the JWS specification also apply 1074 to this specification. Likewise, all the security considerations in 1075 XML Encryption 1.1 [W3C.CR-xmlenc-core1-20120313] also apply to JWE, 1076 other than those that are XML specific. 1078 12. Open Issues 1080 [[ to be removed by the RFC editor before publication as an RFC ]] 1082 The following items remain to be considered or done in this draft: 1084 o Should we define an optional nonce and/or timestamp header 1085 parameter? (Use of a nonce is an effective countermeasure to some 1086 kinds of attacks.) 1088 o Do we want to consolidate the combination of the "enc", "int", and 1089 "kdf" parameters into a single new "enc" parameter defining 1090 composite AEAD algorithms? For instance, we might define a 1091 composite algorithm A128CBC with HS256 and CS256 and another 1092 composite algorithm A256CBC with HS512 and CS512. A symmetry 1093 argument for doing this is that the "int" and "kdf" parameters are 1094 not used with AEAD algorithms. An argument against it is that in 1095 some cases, integrity is not needed because it's provided by other 1096 means, and so having the flexibility to not use an "int" algorithm 1097 or key derivation with a non-AEAD "enc" algorithm could be useful. 1099 o Do we want to represent the JWE IV as a separate dot-separated 1100 element or continue to have it be in the header? An IV is always 1101 required in practice for the block encryption algorithms we've 1102 specified. This would save 15 and 17 characters, respectively, 1103 for the current AES GCM and AES CBC examples. 1105 13. References 1107 13.1. Normative References 1109 [ITU.X690.1994] 1110 International Telecommunications Union, "Information 1111 Technology - ASN.1 encoding rules: Specification of Basic 1112 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1113 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1114 X.690, 1994. 1116 [JWA] Jones, M., "JSON Web Algorithms (JWA)", July 2012. 1118 [JWK] Jones, M., "JSON Web Key (JWK)", July 2012. 1120 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1121 Signature (JWS)", July 2012. 1123 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 1124 Mail: Part I: Message Encryption and Authentication 1125 Procedures", RFC 1421, February 1993. 1127 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1128 version 1.3", RFC 1951, May 1996. 1130 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1131 Extensions (MIME) Part Two: Media Types", RFC 2046, 1132 November 1996. 1134 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1135 Requirement Levels", BCP 14, RFC 2119, March 1997. 1137 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1139 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1140 10646", STD 63, RFC 3629, November 2003. 1142 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1143 Resource Identifier (URI): Generic Syntax", STD 66, 1144 RFC 3986, January 2005. 1146 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1147 Requirements for Security", BCP 106, RFC 4086, June 2005. 1149 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 1150 Registration Procedures", BCP 13, RFC 4288, December 2005. 1152 [RFC4627] Crockford, D., "The application/json Media Type for 1153 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1155 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1156 Encodings", RFC 4648, October 2006. 1158 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 1159 Encryption", RFC 5116, January 2008. 1161 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1162 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1164 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1165 Housley, R., and W. Polk, "Internet X.509 Public Key 1166 Infrastructure Certificate and Certificate Revocation List 1167 (CRL) Profile", RFC 5280, May 2008. 1169 [W3C.CR-xmlenc-core1-20120313] 1170 Eastlake, D., Reagle, J., Hirsch, F., and T. Roessler, 1171 "XML Encryption Syntax and Processing Version 1.1", World 1172 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1173 March 2012, 1174 . 1176 13.2. Informative References 1178 [I-D.rescorla-jsms] 1179 Rescorla, E. and J. Hildebrand, "JavaScript Message 1180 Security Format", draft-rescorla-jsms-00 (work in 1181 progress), March 2011. 1183 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1184 Encryption", September 2010. 1186 [JWE-JS] Jones, M., "JSON Web Encryption JSON Serialization 1187 (JWE-JS)", July 2012. 1189 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1190 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1191 July 2005. 1193 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1194 RFC 5652, September 2009. 1196 Appendix A. JWE Examples 1198 This section provides examples of JWE computations. 1200 A.1. Example JWE using RSAES OAEP and AES GCM 1202 This example encrypts the plaintext "Live long and prosper." to the 1203 recipient using RSAES OAEP and AES GCM. The AES GCM algorithm has an 1204 integrated integrity check. The representation of this plaintext is: 1206 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1207 112, 114, 111, 115, 112, 101, 114, 46] 1209 A.1.1. JWE Header 1211 The following example JWE Header declares that: 1213 o the Content Master Key is encrypted to the recipient using the 1214 RSAES OAEP algorithm to produce the JWE Encrypted Key, 1216 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1217 bit key to produce the Ciphertext, and 1219 o the 96 bit Initialization Vector (IV) [227, 197, 117, 252, 2, 219, 1220 233, 68, 180, 225, 77, 219] with the base64url encoding 1221 "48V1_ALb6US04U3b" was used. 1223 {"alg":"RSA-OAEP","enc":"A256GCM","iv":"48V1_ALb6US04U3b"} 1225 A.1.2. Encoded JWE Header 1227 Base64url encoding the bytes of the UTF-8 representation of the JWE 1228 Header yields this Encoded JWE Header value (with line breaks for 1229 display purposes only): 1231 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00iLCJpdiI6IjQ4VjFfQUxi 1232 NlVTMDRVM2IifQ 1234 A.1.3. Content Master Key (CMK) 1236 Generate a random Content Master Key (CMK). In this example, the key 1237 value is: 1239 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1240 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1241 234, 64, 252] 1243 A.1.4. Key Encryption 1245 Encrypt the CMK with the recipient's public key using the RSAES OAEP 1246 algorithm to produce the JWE Encrypted Key. In this example, the RSA 1247 key parameters are: 1249 +-----------+-------------------------------------------------------+ 1250 | Parameter | Value | 1251 | Name | | 1252 +-----------+-------------------------------------------------------+ 1253 | Modulus | [161, 168, 84, 34, 133, 176, 208, 173, 46, 176, 163, | 1254 | | 110, 57, 30, 135, 227, 9, 31, 226, 128, 84, 92, 116, | 1255 | | 241, 70, 248, 27, 227, 193, 62, 5, 91, 241, 145, 224, | 1256 | | 205, 141, 176, 184, 133, 239, 43, 81, 103, 9, 161, | 1257 | | 153, 157, 179, 104, 123, 51, 189, 34, 152, 69, 97, | 1258 | | 69, 78, 93, 140, 131, 87, 182, 169, 101, 92, 142, 3, | 1259 | | 22, 167, 8, 212, 56, 35, 79, 210, 222, 192, 208, 252, | 1260 | | 49, 109, 138, 173, 253, 210, 166, 201, 63, 102, 74, | 1261 | | 5, 158, 41, 90, 144, 108, 160, 79, 10, 89, 222, 231, | 1262 | | 172, 31, 227, 197, 0, 19, 72, 81, 138, 78, 136, 221, | 1263 | | 121, 118, 196, 17, 146, 10, 244, 188, 72, 113, 55, | 1264 | | 221, 162, 217, 171, 27, 57, 233, 210, 101, 236, 154, | 1265 | | 199, 56, 138, 239, 101, 48, 198, 186, 202, 160, 76, | 1266 | | 111, 234, 71, 57, 183, 5, 211, 171, 136, 126, 64, 40, | 1267 | | 75, 58, 89, 244, 254, 107, 84, 103, 7, 236, 69, 163, | 1268 | | 18, 180, 251, 58, 153, 46, 151, 174, 12, 103, 197, | 1269 | | 181, 161, 162, 55, 250, 235, 123, 110, 17, 11, 158, | 1270 | | 24, 47, 133, 8, 199, 235, 107, 126, 130, 246, 73, | 1271 | | 195, 20, 108, 202, 176, 214, 187, 45, 146, 182, 118, | 1272 | | 54, 32, 200, 61, 201, 71, 243, 1, 255, 131, 84, 37, | 1273 | | 111, 211, 168, 228, 45, 192, 118, 27, 197, 235, 232, | 1274 | | 36, 10, 230, 248, 190, 82, 182, 140, 35, 204, 108, | 1275 | | 190, 253, 186, 186, 27] | 1276 | Exponent | [1, 0, 1] | 1277 | Private | [144, 183, 109, 34, 62, 134, 108, 57, 44, 252, 10, | 1278 | Exponent | 66, 73, 54, 16, 181, 233, 92, 54, 219, 101, 42, 35, | 1279 | | 178, 63, 51, 43, 92, 119, 136, 251, 41, 53, 23, 191, | 1280 | | 164, 164, 60, 88, 227, 229, 152, 228, 213, 149, 228, | 1281 | | 169, 237, 104, 71, 151, 75, 88, 252, 216, 77, 251, | 1282 | | 231, 28, 97, 88, 193, 215, 202, 248, 216, 121, 195, | 1283 | | 211, 245, 250, 112, 71, 243, 61, 129, 95, 39, 244, | 1284 | | 122, 225, 217, 169, 211, 165, 48, 253, 220, 59, 122, | 1285 | | 219, 42, 86, 223, 32, 236, 39, 48, 103, 78, 122, 216, | 1286 | | 187, 88, 176, 89, 24, 1, 42, 177, 24, 99, 142, 170, | 1287 | | 1, 146, 43, 3, 108, 64, 194, 121, 182, 95, 187, 134, | 1288 | | 71, 88, 96, 134, 74, 131, 167, 69, 106, 143, 121, 27, | 1289 | | 72, 44, 245, 95, 39, 194, 179, 175, 203, 122, 16, | 1290 | | 112, 183, 17, 200, 202, 31, 17, 138, 156, 184, 210, | 1291 | | 157, 184, 154, 131, 128, 110, 12, 85, 195, 122, 241, | 1292 | | 79, 251, 229, 183, 117, 21, 123, 133, 142, 220, 153, | 1293 | | 9, 59, 57, 105, 81, 255, 138, 77, 82, 54, 62, 216, | 1294 | | 38, 249, 208, 17, 197, 49, 45, 19, 232, 157, 251, | 1295 | | 131, 137, 175, 72, 126, 43, 229, 69, 179, 117, 82, | 1296 | | 157, 213, 83, 35, 57, 210, 197, 252, 171, 143, 194, | 1297 | | 11, 47, 163, 6, 253, 75, 252, 96, 11, 187, 84, 130, | 1298 | | 210, 7, 121, 78, 91, 79, 57, 251, 138, 132, 220, 60, | 1299 | | 224, 173, 56, 224, 201] | 1300 +-----------+-------------------------------------------------------+ 1302 The resulting JWE Encrypted Key value is: 1304 [142, 252, 40, 202, 21, 177, 56, 198, 232, 7, 151, 49, 95, 169, 220, 1305 2, 46, 214, 167, 116, 57, 20, 164, 109, 150, 98, 49, 223, 154, 95, 1306 71, 209, 233, 17, 174, 142, 203, 232, 132, 167, 17, 42, 51, 125, 22, 1307 221, 135, 17, 67, 197, 148, 246, 139, 145, 160, 238, 99, 119, 171, 1308 95, 117, 202, 87, 251, 101, 254, 58, 215, 135, 195, 135, 103, 49, 1309 119, 76, 46, 49, 198, 27, 31, 58, 44, 192, 222, 21, 16, 13, 216, 161, 1310 179, 236, 65, 143, 38, 43, 218, 195, 76, 140, 243, 71, 243, 79, 124, 1311 216, 208, 242, 171, 34, 245, 57, 154, 93, 76, 230, 204, 234, 82, 117, 1312 248, 39, 13, 62, 60, 215, 8, 51, 248, 254, 47, 150, 36, 46, 27, 247, 1313 98, 77, 56, 92, 44, 19, 39, 12, 77, 54, 101, 194, 126, 86, 0, 64, 1314 239, 95, 211, 64, 26, 219, 93, 211, 36, 154, 250, 117, 177, 213, 232, 1315 142, 184, 216, 92, 20, 248, 69, 175, 180, 71, 205, 221, 235, 224, 95, 1316 113, 5, 33, 86, 18, 157, 61, 199, 8, 121, 0, 0, 135, 65, 67, 220, 1317 164, 15, 230, 155, 71, 53, 64, 253, 209, 169, 255, 34, 64, 101, 7, 1318 43, 102, 227, 83, 171, 52, 225, 119, 253, 182, 96, 195, 225, 34, 156, 1319 211, 202, 7, 194, 255, 137, 59, 170, 172, 72, 234, 222, 203, 123, 1320 249, 121, 254, 143, 173, 105, 65, 187, 189, 163, 64, 151, 145, 99, 1321 17] 1323 A.1.5. Encoded JWE Encrypted Key 1325 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1326 Encrypted Key. This result (with line breaks for display purposes 1327 only) is: 1329 jvwoyhWxOMboB5cxX6ncAi7Wp3Q5FKRtlmIx35pfR9HpEa6Oy-iEpxEqM30W3YcR 1330 Q8WU9ouRoO5jd6tfdcpX-2X-OteHw4dnMXdMLjHGGx86LMDeFRAN2KGz7EGPJiva 1331 w0yM80fzT3zY0PKrIvU5ml1M5szqUnX4Jw0-PNcIM_j-L5YkLhv3Yk04XCwTJwxN 1332 NmXCflYAQO9f00Aa213TJJr6dbHV6I642FwU-EWvtEfN3evgX3EFIVYSnT3HCHkA 1333 AIdBQ9ykD-abRzVA_dGp_yJAZQcrZuNTqzThd_22YMPhIpzTygfC_4k7qqxI6t7L 1334 e_l5_o-taUG7vaNAl5FjEQ 1336 A.1.6. "Additional Authenticated Data" Parameter 1338 Concatenate the Encoded JWE Header value, a period character ('.'), 1339 and the Encoded JWE Encrypted Key to create the "additional 1340 authenticated data" parameter for the AES GCM algorithm. This result 1341 (with line breaks for display purposes only) is: 1343 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00iLCJpdiI6IjQ4VjFfQUxi 1344 NlVTMDRVM2IifQ. 1345 jvwoyhWxOMboB5cxX6ncAi7Wp3Q5FKRtlmIx35pfR9HpEa6Oy-iEpxEqM30W3YcR 1346 Q8WU9ouRoO5jd6tfdcpX-2X-OteHw4dnMXdMLjHGGx86LMDeFRAN2KGz7EGPJiva 1347 w0yM80fzT3zY0PKrIvU5ml1M5szqUnX4Jw0-PNcIM_j-L5YkLhv3Yk04XCwTJwxN 1348 NmXCflYAQO9f00Aa213TJJr6dbHV6I642FwU-EWvtEfN3evgX3EFIVYSnT3HCHkA 1349 AIdBQ9ykD-abRzVA_dGp_yJAZQcrZuNTqzThd_22YMPhIpzTygfC_4k7qqxI6t7L 1350 e_l5_o-taUG7vaNAl5FjEQ 1352 The representation of this value is: 1354 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1355 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1356 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 76, 67, 74, 1357 112, 100, 105, 73, 54, 73, 106, 81, 52, 86, 106, 70, 102, 81, 85, 1358 120, 105, 78, 108, 86, 84, 77, 68, 82, 86, 77, 50, 73, 105, 102, 81, 1359 46, 106, 118, 119, 111, 121, 104, 87, 120, 79, 77, 98, 111, 66, 53, 1360 99, 120, 88, 54, 110, 99, 65, 105, 55, 87, 112, 51, 81, 53, 70, 75, 1361 82, 116, 108, 109, 73, 120, 51, 53, 112, 102, 82, 57, 72, 112, 69, 1362 97, 54, 79, 121, 45, 105, 69, 112, 120, 69, 113, 77, 51, 48, 87, 51, 1363 89, 99, 82, 81, 56, 87, 85, 57, 111, 117, 82, 111, 79, 53, 106, 100, 1364 54, 116, 102, 100, 99, 112, 88, 45, 50, 88, 45, 79, 116, 101, 72, 1365 119, 52, 100, 110, 77, 88, 100, 77, 76, 106, 72, 71, 71, 120, 56, 54, 1366 76, 77, 68, 101, 70, 82, 65, 78, 50, 75, 71, 122, 55, 69, 71, 80, 74, 1367 105, 118, 97, 119, 48, 121, 77, 56, 48, 102, 122, 84, 51, 122, 89, 1368 48, 80, 75, 114, 73, 118, 85, 53, 109, 108, 49, 77, 53, 115, 122, 1369 113, 85, 110, 88, 52, 74, 119, 48, 45, 80, 78, 99, 73, 77, 95, 106, 1370 45, 76, 53, 89, 107, 76, 104, 118, 51, 89, 107, 48, 52, 88, 67, 119, 1371 84, 74, 119, 120, 78, 78, 109, 88, 67, 102, 108, 89, 65, 81, 79, 57, 1372 102, 48, 48, 65, 97, 50, 49, 51, 84, 74, 74, 114, 54, 100, 98, 72, 1373 86, 54, 73, 54, 52, 50, 70, 119, 85, 45, 69, 87, 118, 116, 69, 102, 1374 78, 51, 101, 118, 103, 88, 51, 69, 70, 73, 86, 89, 83, 110, 84, 51, 1375 72, 67, 72, 107, 65, 65, 73, 100, 66, 81, 57, 121, 107, 68, 45, 97, 1376 98, 82, 122, 86, 65, 95, 100, 71, 112, 95, 121, 74, 65, 90, 81, 99, 1377 114, 90, 117, 78, 84, 113, 122, 84, 104, 100, 95, 50, 50, 89, 77, 80, 1378 104, 73, 112, 122, 84, 121, 103, 102, 67, 95, 52, 107, 55, 113, 113, 1379 120, 73, 54, 116, 55, 76, 101, 95, 108, 53, 95, 111, 45, 116, 97, 85, 1380 71, 55, 118, 97, 78, 65, 108, 53, 70, 106, 69, 81] 1382 A.1.7. Plaintext Encryption 1384 Encrypt the Plaintext with AES GCM, using the IV, the CMK as the 1385 encryption key, and the "additional authenticated data" value above, 1386 requesting a 128 bit "authentication tag" output. The resulting 1387 Ciphertext is: 1389 [253, 237, 181, 180, 97, 161, 105, 207, 233, 120, 65, 100, 45, 122, 1390 246, 116, 195, 212, 102, 37, 36, 175] 1392 The resulting "authentication tag" value is: 1394 [97, 182, 82, 120, 112, 141, 13, 144, 106, 1, 220, 233, 68, 233, 114, 1395 139] 1397 A.1.8. Encoded JWE Ciphertext 1399 Base64url encode the resulting Ciphertext to create the Encoded JWE 1400 Ciphertext. This result is: 1402 _e21tGGhac_peEFkLXr2dMPUZiUkrw 1404 A.1.9. Encoded JWE Integrity Value 1406 Base64url encode the resulting "authentication tag" to create the 1407 Encoded JWE Integrity Value. This result is: 1409 YbZSeHCNDZBqAdzpROlyiw 1411 A.1.10. Complete Representation 1413 Assemble the final representation: The Compact Serialization of this 1414 result is the concatenation of the Encoded JWE Header, the Encoded 1415 JWE Encrypted Key, the Encoded JWE Ciphertext, and the Encoded JWE 1416 Integrity Value in that order, with the four strings being separated 1417 by three period ('.') characters. 1419 The final result in this example (with line breaks for display 1420 purposes only) is: 1422 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00iLCJpdiI6IjQ4VjFfQUxi 1423 NlVTMDRVM2IifQ. 1424 jvwoyhWxOMboB5cxX6ncAi7Wp3Q5FKRtlmIx35pfR9HpEa6Oy-iEpxEqM30W3YcR 1425 Q8WU9ouRoO5jd6tfdcpX-2X-OteHw4dnMXdMLjHGGx86LMDeFRAN2KGz7EGPJiva 1426 w0yM80fzT3zY0PKrIvU5ml1M5szqUnX4Jw0-PNcIM_j-L5YkLhv3Yk04XCwTJwxN 1427 NmXCflYAQO9f00Aa213TJJr6dbHV6I642FwU-EWvtEfN3evgX3EFIVYSnT3HCHkA 1428 AIdBQ9ykD-abRzVA_dGp_yJAZQcrZuNTqzThd_22YMPhIpzTygfC_4k7qqxI6t7L 1429 e_l5_o-taUG7vaNAl5FjEQ. 1430 _e21tGGhac_peEFkLXr2dMPUZiUkrw. 1431 YbZSeHCNDZBqAdzpROlyiw 1433 A.1.11. Validation 1435 This example illustrates the process of creating a JWE with an AEAD 1436 algorithm. These results can be used to validate JWE decryption 1437 implementations for these algorithms. However, note that since the 1438 RSAES OAEP computation includes random values, the results above will 1439 not be repeatable. 1441 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES CBC 1443 This example encrypts the plaintext "Now is the time for all good men 1444 to come to the aid of their country." to the recipient using RSAES- 1445 PKCS1-V1_5 and AES CBC. AES CBC does not have an integrated 1446 integrity check, so a separate integrity check calculation is 1447 performed using HMAC SHA-256, with separate encryption and integrity 1448 keys being derived from a master key using the Concat KDF with the 1449 SHA-256 digest function. The representation of this plaintext is: 1451 [78, 111, 119, 32, 105, 115, 32, 116, 104, 101, 32, 116, 105, 109, 1452 101, 32, 102, 111, 114, 32, 97, 108, 108, 32, 103, 111, 111, 100, 32, 1453 109, 101, 110, 32, 116, 111, 32, 99, 111, 109, 101, 32, 116, 111, 32, 1454 116, 104, 101, 32, 97, 105, 100, 32, 111, 102, 32, 116, 104, 101, 1455 105, 114, 32, 99, 111, 117, 110, 116, 114, 121, 46] 1457 A.2.1. JWE Header 1459 The following example JWE Header (with line breaks for display 1460 purposes only) declares that: 1462 o the Content Master Key is encrypted to the recipient using the 1463 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key, 1465 o the Plaintext is encrypted using the AES CBC algorithm with a 128 1466 bit key to produce the Ciphertext, 1468 o the JWE Integrity Value safeguarding the integrity of the 1469 Ciphertext and the parameters used to create it was computed with 1470 the HMAC SHA-256 algorithm, and 1472 o the 128 bit Initialization Vector (IV) [3, 22, 60, 12, 43, 67, 1473 104, 105, 108, 108, 105, 99, 111, 116, 104, 101] with the 1474 base64url encoding "AxY8DCtDaGlsbGljb3RoZQ" was used. 1476 {"alg":"RSA1_5","enc":"A128CBC","int":"HS256","iv":"AxY8DCtDaGls 1477 bGljb3RoZQ"} 1479 A.2.2. Encoded JWE Header 1481 Base64url encoding the bytes of the UTF-8 representation of the JWE 1482 Header yields this Encoded JWE Header value (with line breaks for 1483 display purposes only): 1485 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDIiwiaW50IjoiSFMyNTYiLCJp 1486 diI6IkF4WThEQ3REYUdsc2JHbGpiM1JvWlEifQ 1488 A.2.3. Content Master Key (CMK) 1490 Generate a random Content Master Key (CMK). In this example, the key 1491 value is: 1493 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1494 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1495 44, 207] 1497 A.2.4. Key Encryption 1499 Encrypt the CMK with the recipient's public key using the RSAES- 1500 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. In this 1501 example, the RSA key parameters are: 1503 +-----------+-------------------------------------------------------+ 1504 | Parameter | Value | 1505 | Name | | 1506 +-----------+-------------------------------------------------------+ 1507 | Modulus | [177, 119, 33, 13, 164, 30, 108, 121, 207, 136, 107, | 1508 | | 242, 12, 224, 19, 226, 198, 134, 17, 71, 173, 75, 42, | 1509 | | 61, 48, 162, 206, 161, 97, 108, 185, 234, 226, 219, | 1510 | | 118, 206, 118, 5, 169, 224, 60, 181, 90, 85, 51, 123, | 1511 | | 6, 224, 4, 122, 29, 230, 151, 12, 244, 127, 121, 25, | 1512 | | 4, 85, 220, 144, 215, 110, 130, 17, 68, 228, 129, | 1513 | | 138, 7, 130, 231, 40, 212, 214, 17, 179, 28, 124, | 1514 | | 151, 178, 207, 20, 14, 154, 222, 113, 176, 24, 198, | 1515 | | 73, 211, 113, 9, 33, 178, 80, 13, 25, 21, 25, 153, | 1516 | | 212, 206, 67, 154, 147, 70, 194, 192, 183, 160, 83, | 1517 | | 98, 236, 175, 85, 23, 97, 75, 199, 177, 73, 145, 50, | 1518 | | 253, 206, 32, 179, 254, 236, 190, 82, 73, 67, 129, | 1519 | | 253, 252, 220, 108, 136, 138, 11, 192, 1, 36, 239, | 1520 | | 228, 55, 81, 113, 17, 25, 140, 63, 239, 146, 3, 172, | 1521 | | 96, 60, 227, 233, 64, 255, 224, 173, 225, 228, 229, | 1522 | | 92, 112, 72, 99, 97, 26, 87, 187, 123, 46, 50, 90, | 1523 | | 202, 117, 73, 10, 153, 47, 224, 178, 163, 77, 48, 46, | 1524 | | 154, 33, 148, 34, 228, 33, 172, 216, 89, 46, 225, | 1525 | | 127, 68, 146, 234, 30, 147, 54, 146, 5, 133, 45, 78, | 1526 | | 254, 85, 55, 75, 213, 86, 194, 218, 215, 163, 189, | 1527 | | 194, 54, 6, 83, 36, 18, 153, 53, 7, 48, 89, 35, 66, | 1528 | | 144, 7, 65, 154, 13, 97, 75, 55, 230, 132, 3, 13, | 1529 | | 239, 71] | 1530 | Exponent | [1, 0, 1] | 1531 | Private | [84, 80, 150, 58, 165, 235, 242, 123, 217, 55, 38, | 1532 | Exponent | 154, 36, 181, 221, 156, 211, 215, 100, 164, 90, 88, | 1533 | | 40, 228, 83, 148, 54, 122, 4, 16, 165, 48, 76, 194, | 1534 | | 26, 107, 51, 53, 179, 165, 31, 18, 198, 173, 78, 61, | 1535 | | 56, 97, 252, 158, 140, 80, 63, 25, 223, 156, 36, 203, | 1536 | | 214, 252, 120, 67, 180, 167, 3, 82, 243, 25, 97, 214, | 1537 | | 83, 133, 69, 16, 104, 54, 160, 200, 41, 83, 164, 187, | 1538 | | 70, 153, 111, 234, 242, 158, 175, 28, 198, 48, 211, | 1539 | | 45, 148, 58, 23, 62, 227, 74, 52, 117, 42, 90, 41, | 1540 | | 249, 130, 154, 80, 119, 61, 26, 193, 40, 125, 10, | 1541 | | 152, 174, 227, 225, 205, 32, 62, 66, 6, 163, 100, 99, | 1542 | | 219, 19, 253, 25, 105, 80, 201, 29, 252, 157, 237, | 1543 | | 69, 1, 80, 171, 167, 20, 196, 156, 109, 249, 88, 0, | 1544 | | 3, 152, 38, 165, 72, 87, 6, 152, 71, 156, 214, 16, | 1545 | | 71, 30, 82, 51, 103, 76, 218, 63, 9, 84, 163, 249, | 1546 | | 91, 215, 44, 238, 85, 101, 240, 148, 1, 82, 224, 91, | 1547 | | 135, 105, 127, 84, 171, 181, 152, 210, 183, 126, 24, | 1548 | | 46, 196, 90, 173, 38, 245, 219, 186, 222, 27, 240, | 1549 | | 212, 194, 15, 66, 135, 226, 178, 190, 52, 245, 74, | 1550 | | 65, 224, 81, 100, 85, 25, 204, 165, 203, 187, 175, | 1551 | | 84, 100, 82, 15, 11, 23, 202, 151, 107, 54, 41, 207, | 1552 | | 3, 136, 229, 134, 131, 93, 139, 50, 182, 204, 93, | 1553 | | 130, 89] | 1554 +-----------+-------------------------------------------------------+ 1556 The resulting JWE Encrypted Key value is: 1558 [32, 242, 63, 207, 94, 246, 133, 37, 135, 48, 88, 4, 15, 193, 6, 244, 1559 51, 58, 132, 133, 212, 255, 163, 90, 59, 80, 200, 152, 41, 244, 188, 1560 215, 174, 160, 26, 188, 227, 180, 165, 234, 172, 63, 24, 116, 152, 1561 28, 149, 16, 94, 213, 201, 171, 180, 191, 11, 21, 149, 172, 143, 54, 1562 194, 58, 206, 201, 164, 28, 107, 155, 75, 101, 22, 92, 227, 144, 95, 1563 40, 119, 170, 7, 36, 225, 40, 141, 186, 213, 7, 175, 16, 174, 122, 1564 75, 32, 48, 193, 119, 202, 41, 152, 210, 190, 68, 57, 119, 4, 197, 1565 74, 7, 242, 239, 170, 204, 73, 75, 213, 202, 113, 216, 18, 23, 66, 1566 106, 208, 69, 244, 117, 147, 2, 37, 207, 199, 184, 96, 102, 44, 70, 1567 212, 87, 143, 253, 0, 166, 59, 41, 115, 217, 80, 165, 87, 38, 5, 9, 1568 184, 202, 68, 67, 176, 4, 87, 254, 166, 227, 88, 124, 238, 249, 75, 1569 114, 205, 148, 149, 45, 78, 193, 134, 64, 189, 168, 76, 170, 76, 176, 1570 72, 148, 77, 215, 159, 146, 55, 189, 213, 85, 253, 135, 200, 59, 247, 1571 79, 37, 22, 200, 32, 110, 53, 123, 54, 39, 9, 178, 231, 238, 95, 25, 1572 211, 143, 87, 220, 88, 138, 209, 13, 227, 72, 58, 102, 164, 136, 241, 1573 14, 14, 45, 32, 77, 44, 244, 162, 239, 150, 248, 181, 138, 251, 116, 1574 245, 205, 137, 78, 34, 34, 10, 6, 59, 4, 197, 2, 153, 251] 1576 A.2.5. Encoded JWE Encrypted Key 1578 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1579 Encrypted Key. This result (with line breaks for display purposes 1580 only) is: 1582 IPI_z172hSWHMFgED8EG9DM6hIXU_6NaO1DImCn0vNeuoBq847Sl6qw_GHSYHJUQ 1583 XtXJq7S_CxWVrI82wjrOyaQca5tLZRZc45BfKHeqByThKI261QevEK56SyAwwXfK 1584 KZjSvkQ5dwTFSgfy76rMSUvVynHYEhdCatBF9HWTAiXPx7hgZixG1FeP_QCmOylz 1585 2VClVyYFCbjKREOwBFf-puNYfO75S3LNlJUtTsGGQL2oTKpMsEiUTdefkje91VX9 1586 h8g7908lFsggbjV7NicJsufuXxnTj1fcWIrRDeNIOmakiPEODi0gTSz0ou-W-LWK 1587 -3T1zYlOIiIKBjsExQKZ-w 1589 A.2.6. Key Derivation 1591 Use the Concat key derivation function to derive Content Encryption 1592 Key (CEK) and Content Integrity Key (CIK) values from the CMK. The 1593 details of this derivation are shown in Appendix A.3. The resulting 1594 CEK value is: 1596 [249, 255, 87, 218, 224, 223, 221, 53, 204, 121, 166, 130, 195, 184, 1597 50, 69] 1599 The resulting CIK value is: 1601 [218, 209, 130, 50, 169, 45, 70, 214, 29, 187, 123, 20, 3, 158, 111, 1602 122, 182, 94, 57, 133, 245, 76, 97, 44, 193, 80, 81, 246, 115, 177, 1603 225, 159] 1605 A.2.7. Plaintext Encryption 1607 Encrypt the Plaintext with AES CBC using the CEK and IV to produce 1608 the Ciphertext. The resulting Ciphertext is: 1610 [253, 159, 221, 142, 82, 40, 11, 131, 3, 72, 34, 162, 173, 229, 146, 1611 217, 183, 173, 139, 132, 58, 137, 33, 182, 82, 49, 110, 141, 11, 221, 1612 207, 239, 207, 65, 213, 28, 20, 217, 14, 186, 87, 160, 15, 160, 96, 1613 142, 7, 69, 46, 55, 129, 224, 113, 206, 59, 181, 7, 188, 255, 15, 16, 1614 59, 180, 107, 75, 0, 217, 175, 254, 8, 141, 48, 217, 132, 16, 217, 4, 1615 30, 223, 147] 1617 A.2.8. Encoded JWE Ciphertext 1619 Base64url encode the resulting Ciphertext to create the Encoded JWE 1620 Ciphertext. This result (with line breaks for display purposes only) 1621 is: 1623 _Z_djlIoC4MDSCKireWS2beti4Q6iSG2UjFujQvdz-_PQdUcFNkOulegD6BgjgdF 1624 LjeB4HHOO7UHvP8PEDu0a0sA2a_-CI0w2YQQ2QQe35M 1626 A.2.9. Secured Input Value 1628 Concatenate the Encoded JWE Header value, a period character ('.'), 1629 the Encoded JWE Encrypted Key, a second period character, and the 1630 Encoded JWE Ciphertext to create the value to integrity protect. 1631 This result (with line breaks for display purposes only) is: 1633 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDIiwiaW50IjoiSFMyNTYiLCJp 1634 diI6IkF4WThEQ3REYUdsc2JHbGpiM1JvWlEifQ. 1635 IPI_z172hSWHMFgED8EG9DM6hIXU_6NaO1DImCn0vNeuoBq847Sl6qw_GHSYHJUQ 1636 XtXJq7S_CxWVrI82wjrOyaQca5tLZRZc45BfKHeqByThKI261QevEK56SyAwwXfK 1637 KZjSvkQ5dwTFSgfy76rMSUvVynHYEhdCatBF9HWTAiXPx7hgZixG1FeP_QCmOylz 1638 2VClVyYFCbjKREOwBFf-puNYfO75S3LNlJUtTsGGQL2oTKpMsEiUTdefkje91VX9 1639 h8g7908lFsggbjV7NicJsufuXxnTj1fcWIrRDeNIOmakiPEODi0gTSz0ou-W-LWK 1640 -3T1zYlOIiIKBjsExQKZ-w. 1641 _Z_djlIoC4MDSCKireWS2beti4Q6iSG2UjFujQvdz-_PQdUcFNkOulegD6BgjgdF 1642 LjeB4HHOO7UHvP8PEDu0a0sA2a_-CI0w2YQQ2QQe35M 1644 The representation of this value is: 1646 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1647 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1648 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 73, 105, 119, 105, 97, 87, 1649 53, 48, 73, 106, 111, 105, 83, 70, 77, 121, 78, 84, 89, 105, 76, 67, 1650 74, 112, 100, 105, 73, 54, 73, 107, 70, 52, 87, 84, 104, 69, 81, 51, 1651 82, 69, 89, 85, 100, 115, 99, 50, 74, 72, 98, 71, 112, 105, 77, 49, 1652 74, 118, 87, 108, 69, 105, 102, 81, 46, 73, 80, 73, 95, 122, 49, 55, 1653 50, 104, 83, 87, 72, 77, 70, 103, 69, 68, 56, 69, 71, 57, 68, 77, 54, 1654 104, 73, 88, 85, 95, 54, 78, 97, 79, 49, 68, 73, 109, 67, 110, 48, 1655 118, 78, 101, 117, 111, 66, 113, 56, 52, 55, 83, 108, 54, 113, 119, 1656 95, 71, 72, 83, 89, 72, 74, 85, 81, 88, 116, 88, 74, 113, 55, 83, 95, 1657 67, 120, 87, 86, 114, 73, 56, 50, 119, 106, 114, 79, 121, 97, 81, 99, 1658 97, 53, 116, 76, 90, 82, 90, 99, 52, 53, 66, 102, 75, 72, 101, 113, 1659 66, 121, 84, 104, 75, 73, 50, 54, 49, 81, 101, 118, 69, 75, 53, 54, 1660 83, 121, 65, 119, 119, 88, 102, 75, 75, 90, 106, 83, 118, 107, 81, 1661 53, 100, 119, 84, 70, 83, 103, 102, 121, 55, 54, 114, 77, 83, 85, 1662 118, 86, 121, 110, 72, 89, 69, 104, 100, 67, 97, 116, 66, 70, 57, 72, 1663 87, 84, 65, 105, 88, 80, 120, 55, 104, 103, 90, 105, 120, 71, 49, 70, 1664 101, 80, 95, 81, 67, 109, 79, 121, 108, 122, 50, 86, 67, 108, 86, 1665 121, 89, 70, 67, 98, 106, 75, 82, 69, 79, 119, 66, 70, 102, 45, 112, 1666 117, 78, 89, 102, 79, 55, 53, 83, 51, 76, 78, 108, 74, 85, 116, 84, 1667 115, 71, 71, 81, 76, 50, 111, 84, 75, 112, 77, 115, 69, 105, 85, 84, 1668 100, 101, 102, 107, 106, 101, 57, 49, 86, 88, 57, 104, 56, 103, 55, 1669 57, 48, 56, 108, 70, 115, 103, 103, 98, 106, 86, 55, 78, 105, 99, 74, 1670 115, 117, 102, 117, 88, 120, 110, 84, 106, 49, 102, 99, 87, 73, 114, 1671 82, 68, 101, 78, 73, 79, 109, 97, 107, 105, 80, 69, 79, 68, 105, 48, 1672 103, 84, 83, 122, 48, 111, 117, 45, 87, 45, 76, 87, 75, 45, 51, 84, 1673 49, 122, 89, 108, 79, 73, 105, 73, 75, 66, 106, 115, 69, 120, 81, 75, 1674 90, 45, 119, 46, 95, 90, 95, 100, 106, 108, 73, 111, 67, 52, 77, 68, 1675 83, 67, 75, 105, 114, 101, 87, 83, 50, 98, 101, 116, 105, 52, 81, 54, 1676 105, 83, 71, 50, 85, 106, 70, 117, 106, 81, 118, 100, 122, 45, 95, 1677 80, 81, 100, 85, 99, 70, 78, 107, 79, 117, 108, 101, 103, 68, 54, 66, 1678 103, 106, 103, 100, 70, 76, 106, 101, 66, 52, 72, 72, 79, 79, 55, 85, 1679 72, 118, 80, 56, 80, 69, 68, 117, 48, 97, 48, 115, 65, 50, 97, 95, 1680 45, 67, 73, 48, 119, 50, 89, 81, 81, 50, 81, 81, 101, 51, 53, 77] 1682 A.2.10. JWE Integrity Value 1684 Compute the HMAC SHA-256 of this value using the CIK to create the 1685 JWE Integrity Value. This result is: 1687 [115, 141, 100, 225, 62, 30, 2, 0, 130, 183, 173, 230, 241, 147, 102, 1688 136, 232, 167, 49, 200, 133, 23, 42, 78, 22, 155, 226, 119, 184, 186, 1689 15, 73] 1691 A.2.11. Encoded JWE Integrity Value 1693 Base64url encode the resulting JWE Integrity Value to create the 1694 Encoded JWE Integrity Value. This result is: 1696 c41k4T4eAgCCt63m8ZNmiOinMciFFypOFpvid7i6D0k 1698 A.2.12. Complete Representation 1700 Assemble the final representation: The Compact Serialization of this 1701 result is the concatenation of the Encoded JWE Header, the Encoded 1702 JWE Encrypted Key, the Encoded JWE Ciphertext, and the Encoded JWE 1703 Integrity Value in that order, with the four strings being separated 1704 by three period ('.') characters. 1706 The final result in this example (with line breaks for display 1707 purposes only) is: 1709 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDIiwiaW50IjoiSFMyNTYiLCJp 1710 diI6IkF4WThEQ3REYUdsc2JHbGpiM1JvWlEifQ. 1711 IPI_z172hSWHMFgED8EG9DM6hIXU_6NaO1DImCn0vNeuoBq847Sl6qw_GHSYHJUQ 1712 XtXJq7S_CxWVrI82wjrOyaQca5tLZRZc45BfKHeqByThKI261QevEK56SyAwwXfK 1713 KZjSvkQ5dwTFSgfy76rMSUvVynHYEhdCatBF9HWTAiXPx7hgZixG1FeP_QCmOylz 1714 2VClVyYFCbjKREOwBFf-puNYfO75S3LNlJUtTsGGQL2oTKpMsEiUTdefkje91VX9 1715 h8g7908lFsggbjV7NicJsufuXxnTj1fcWIrRDeNIOmakiPEODi0gTSz0ou-W-LWK 1716 -3T1zYlOIiIKBjsExQKZ-w. 1717 _Z_djlIoC4MDSCKireWS2beti4Q6iSG2UjFujQvdz-_PQdUcFNkOulegD6BgjgdF 1718 LjeB4HHOO7UHvP8PEDu0a0sA2a_-CI0w2YQQ2QQe35M. 1719 c41k4T4eAgCCt63m8ZNmiOinMciFFypOFpvid7i6D0k 1721 A.2.13. Validation 1723 This example illustrates the process of creating a JWE with a non- 1724 AEAD algorithm. These results can be used to validate JWE decryption 1725 implementations for these algorithms. Since all the algorithms used 1726 in this example produce deterministic results, the results above 1727 should be repeatable. 1729 A.3. Example Key Derivation with Outputs <= Hash Size 1731 This example uses the Concat KDF to derive the Content Encryption Key 1732 (CEK) and Content Integrity Key (CIK) from the Content Master Key 1733 (CMK) in the manner described in Section 4.12 of [JWA]. In this 1734 example, a 256 bit CMK is used to derive a 128 bit CEK and a 256 bit 1735 CIK. 1737 The CMK value is: 1739 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1740 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1741 44, 207] 1743 A.3.1. CEK Generation 1745 When deriving the CEK from the CMK, the ASCII label "Encryption" 1746 ([69, 110, 99, 114, 121, 112, 116, 105, 111, 110]) is used. The 1747 input to the first hash round is the concatenation of the big endian 1748 number 1 ([0, 0, 0, 1]), the CMK, and the label. Thus the round 1 1749 hash input is: 1751 [0, 0, 0, 1, 4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 1752 63, 170, 106, 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 1753 240, 143, 156, 44, 207, 69, 110, 99, 114, 121, 112, 116, 105, 111, 1754 110] 1756 The SHA-256 hash of this value, which is the round 1 hash output, is: 1758 [249, 255, 87, 218, 224, 223, 221, 53, 204, 121, 166, 130, 195, 184, 1759 50, 69, 11, 237, 202, 71, 10, 96, 59, 199, 140, 88, 126, 147, 146, 1760 113, 222, 41] 1762 Given that 128 bits are needed for the CEK and the hash has produced 1763 256 bits, the CEK value is the first 128 bits of that value: 1765 [249, 255, 87, 218, 224, 223, 221, 53, 204, 121, 166, 130, 195, 184, 1766 50, 69] 1768 A.3.2. CIK Generation 1770 When deriving the CIK from the CMK, the ASCII label "Integrity" ([73, 1771 110, 116, 101, 103, 114, 105, 116, 121]) is used. The input to the 1772 first hash round is the concatenation of the big endian number 1 ([0, 1773 0, 0, 1]), the CMK, and the label. Thus the round 1 hash input is: 1775 [0, 0, 0, 1, 4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 1776 63, 170, 106, 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 1777 240, 143, 156, 44, 207, 73, 110, 116, 101, 103, 114, 105, 116, 121] 1779 The SHA-256 hash of this value, which is the round 1 hash output, is: 1781 [218, 209, 130, 50, 169, 45, 70, 214, 29, 187, 123, 20, 3, 158, 111, 1782 122, 182, 94, 57, 133, 245, 76, 97, 44, 193, 80, 81, 246, 115, 177, 1783 225, 159] 1785 Given that 256 bits are needed for the CIK and the hash has produced 1786 256 bits, the CIK value is that same value: 1788 [218, 209, 130, 50, 169, 45, 70, 214, 29, 187, 123, 20, 3, 158, 111, 1789 122, 182, 94, 57, 133, 245, 76, 97, 44, 193, 80, 81, 246, 115, 177, 1790 225, 159] 1792 A.4. Example Key Derivation with Outputs >= Hash Size 1794 This example uses the Concat KDF to derive the Content Encryption Key 1795 (CEK) and Content Integrity Key (CIK) from the Content Master Key 1796 (CMK) in the manner described in Section 4.12 of [JWA]. In this 1797 example, a 512 bit CMK is used to derive a 256 bit CEK and a 512 bit 1798 CIK. 1800 The CMK value is: 1802 [148, 116, 199, 126, 2, 117, 233, 76, 150, 149, 89, 193, 61, 34, 239, 1803 226, 109, 71, 59, 160, 192, 140, 150, 235, 106, 204, 49, 176, 68, 1804 119, 13, 34, 49, 19, 41, 69, 5, 20, 252, 145, 104, 129, 137, 138, 67, 1805 23, 153, 83, 81, 234, 82, 247, 48, 211, 41, 130, 35, 124, 45, 156, 1806 249, 7, 225, 168] 1808 A.4.1. CEK Generation 1810 When deriving the CEK from the CMK, the ASCII label "Encryption" 1811 ([69, 110, 99, 114, 121, 112, 116, 105, 111, 110]) is used. The 1812 input to the first hash round is the concatenation of the big endian 1813 number 1 ([0, 0, 0, 1]), the CMK, and the label. Thus the round 1 1814 hash input is: 1816 [0, 0, 0, 1, 148, 116, 199, 126, 2, 117, 233, 76, 150, 149, 89, 193, 1817 61, 34, 239, 226, 109, 71, 59, 160, 192, 140, 150, 235, 106, 204, 49, 1818 176, 68, 119, 13, 34, 49, 19, 41, 69, 5, 20, 252, 145, 104, 129, 137, 1819 138, 67, 23, 153, 83, 81, 234, 82, 247, 48, 211, 41, 130, 35, 124, 1820 45, 156, 249, 7, 225, 168, 69, 110, 99, 114, 121, 112, 116, 105, 111, 1821 110] 1823 The SHA-256 hash of this value, which is the round 1 hash output, is: 1825 [137, 5, 92, 9, 17, 47, 17, 86, 253, 235, 34, 247, 121, 78, 11, 144, 1826 10, 172, 38, 247, 108, 243, 201, 237, 95, 80, 49, 150, 116, 240, 159, 1827 64] 1829 Given that 256 bits are needed for the CEK and the hash has produced 1830 256 bits, the CEK value is that same value: 1832 [137, 5, 92, 9, 17, 47, 17, 86, 253, 235, 34, 247, 121, 78, 11, 144, 1833 10, 172, 38, 247, 108, 243, 201, 237, 95, 80, 49, 150, 116, 240, 159, 1834 64] 1836 A.4.2. CIK Generation 1838 When deriving the CIK from the CMK, the ASCII label "Integrity" ([73, 1839 110, 116, 101, 103, 114, 105, 116, 121]) is used. The input to the 1840 first hash round is the concatenation of the big endian number 1 ([0, 1841 0, 0, 1]), the CMK, and the label. Thus the round 1 hash input is: 1843 [0, 0, 0, 1, 148, 116, 199, 126, 2, 117, 233, 76, 150, 149, 89, 193, 1844 61, 34, 239, 226, 109, 71, 59, 160, 192, 140, 150, 235, 106, 204, 49, 1845 176, 68, 119, 13, 34, 49, 19, 41, 69, 5, 20, 252, 145, 104, 129, 137, 1846 138, 67, 23, 153, 83, 81, 234, 82, 247, 48, 211, 41, 130, 35, 124, 1847 45, 156, 249, 7, 225, 168, 73, 110, 116, 101, 103, 114, 105, 116, 1848 121] 1850 The SHA-256 hash of this value, which is the round 1 hash output, is: 1852 [11, 179, 132, 177, 171, 24, 126, 19, 113, 1, 200, 102, 100, 74, 88, 1853 149, 31, 41, 71, 57, 51, 179, 106, 242, 113, 211, 56, 56, 37, 198, 1854 57, 17] 1856 Given that 512 bits are needed for the CIK and the hash has produced 1857 only 256 bits, another round is needed. The input to the second hash 1858 round is the concatenation of the big endian number 2 ([0, 0, 0, 2]), 1859 the CMK, and the label. Thus the round 2 hash input is: 1861 [0, 0, 0, 2, 148, 116, 199, 126, 2, 117, 233, 76, 150, 149, 89, 193, 1862 61, 34, 239, 226, 109, 71, 59, 160, 192, 140, 150, 235, 106, 204, 49, 1863 176, 68, 119, 13, 34, 49, 19, 41, 69, 5, 20, 252, 145, 104, 129, 137, 1864 138, 67, 23, 153, 83, 81, 234, 82, 247, 48, 211, 41, 130, 35, 124, 1865 45, 156, 249, 7, 225, 168, 73, 110, 116, 101, 103, 114, 105, 116, 1866 121] 1868 The SHA-256 hash of this value, which is the round 2 hash output, is: 1870 [149, 209, 221, 113, 40, 191, 95, 252, 142, 254, 141, 230, 39, 113, 1871 139, 84, 44, 156, 247, 47, 223, 101, 229, 180, 82, 231, 38, 96, 170, 1872 119, 236, 81] 1874 Given that 512 bits are needed for the CIK and the two rounds have 1875 collectively produced 512 bits of output, the CIK is the 1876 concatenation of the round 1 and round 2 hash outputs, which is: 1878 [11, 179, 132, 177, 171, 24, 126, 19, 113, 1, 200, 102, 100, 74, 88, 1879 149, 31, 41, 71, 57, 51, 179, 106, 242, 113, 211, 56, 56, 37, 198, 1880 57, 17, 149, 209, 221, 113, 40, 191, 95, 252, 142, 254, 141, 230, 39, 1881 113, 139, 84, 44, 156, 247, 47, 223, 101, 229, 180, 82, 231, 38, 96, 1882 170, 119, 236, 81] 1884 Appendix B. Acknowledgements 1886 Solutions for encrypting JSON content were also explored by JSON 1887 Simple Encryption [JSE] and JavaScript Message Security Format 1888 [I-D.rescorla-jsms], both of which significantly influenced this 1889 draft. This draft attempts to explicitly reuse as many of the 1890 relevant concepts from XML Encryption 1.1 1891 [W3C.CR-xmlenc-core1-20120313] and RFC 5652 [RFC5652] as possible, 1892 while utilizing simple compact JSON-based data structures. 1894 Special thanks are due to John Bradley and Nat Sakimura for the 1895 discussions that helped inform the content of this specification and 1896 to Eric Rescorla and Joe Hildebrand for allowing the reuse of text 1897 from [I-D.rescorla-jsms] in this document. 1899 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 1900 Jay for validating the examples in this specification. 1902 Appendix C. Document History 1904 [[ to be removed by the RFC editor before publication as an RFC ]] 1906 -05 1908 o Support both direct encryption using a shared or agreed upon 1909 symmetric key, and the use of a shared or agreed upon symmetric 1910 key to key wrap the CMK. 1912 o Added statement that "StringOrURI values are compared as case- 1913 sensitive strings with no transformations or canonicalizations 1914 applied". 1916 o Updated open issues. 1918 o Indented artwork elements to better distinguish them from the body 1919 text. 1921 -04 1923 o Refer to the registries as the primary sources of defined values 1924 and then secondarily reference the sections defining the initial 1925 contents of the registries. 1927 o Normatively reference XML Encryption 1.1 1928 [W3C.CR-xmlenc-core1-20120313] for its security considerations. 1930 o Reference draft-jones-jose-jwe-json-serialization instead of 1931 draft-jones-json-web-encryption-json-serialization. 1933 o Described additional open issues. 1935 o Applied editorial suggestions. 1937 -03 1939 o Added the "kdf" (key derivation function) header parameter to 1940 provide crypto agility for key derivation. The default KDF 1941 remains the Concat KDF with the SHA-256 digest function. 1943 o Reordered encryption steps so that the Encoded JWE Header is 1944 always created before it is needed as an input to the AEAD 1945 "additional authenticated data" parameter. 1947 o Added the "cty" (content type) header parameter for declaring type 1948 information about the secured content, as opposed to the "typ" 1949 (type) header parameter, which declares type information about 1950 this object. 1952 o Moved description of how to determine whether a header is for a 1953 JWS or a JWE from the JWT spec to the JWE spec. 1955 o Added complete encryption examples for both AEAD and non-AEAD 1956 algorithms. 1958 o Added complete key derivation examples. 1960 o Added "Collision Resistant Namespace" to the terminology section. 1962 o Reference ITU.X690.1994 for DER encoding. 1964 o Added Registry Contents sections to populate registry values. 1966 o Numerous editorial improvements. 1968 -02 1970 o When using AEAD algorithms (such as AES GCM), use the "additional 1971 authenticated data" parameter to provide integrity for the header, 1972 encrypted key, and ciphertext and use the resulting 1973 "authentication tag" value as the JWE Integrity Value. 1975 o Defined KDF output key sizes. 1977 o Generalized text to allow key agreement to be employed as an 1978 alternative to key wrapping or key encryption. 1980 o Changed compression algorithm from gzip to DEFLATE. 1982 o Clarified that it is an error when a "kid" value is included and 1983 no matching key is found. 1985 o Clarified that JWEs with duplicate Header Parameter Names MUST be 1986 rejected. 1988 o Clarified the relationship between "typ" header parameter values 1989 and MIME types. 1991 o Registered application/jwe MIME type and "JWE" typ header 1992 parameter value. 1994 o Simplified JWK terminology to get replace the "JWK Key Object" and 1995 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 1996 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 1997 between single keys and sets of keys. As part of this change, the 1998 header parameter name for a public key value was changed from 1999 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2001 o Added suggestion on defining additional header parameters such as 2002 "x5t#S256" in the future for certificate thumbprints using hash 2003 algorithms other than SHA-1. 2005 o Specify RFC 2818 server identity validation, rather than RFC 6125 2006 (paralleling the same decision in the OAuth specs). 2008 o Generalized language to refer to Message Authentication Codes 2009 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2010 unless in a context specific to HMAC algorithms. 2012 o Reformatted to give each header parameter its own section heading. 2014 -01 2016 o Added an integrity check for non-AEAD algorithms. 2018 o Added "jpk" and "x5c" header parameters for including JWK public 2019 keys and X.509 certificate chains directly in the header. 2021 o Clarified that this specification is defining the JWE Compact 2022 Serialization. Referenced the new JWE-JS spec, which defines the 2023 JWE JSON Serialization. 2025 o Added text "New header parameters should be introduced sparingly 2026 since an implementation that does not understand a parameter MUST 2027 reject the JWE". 2029 o Clarified that the order of the encryption and decryption steps is 2030 not significant in cases where there are no dependencies between 2031 the inputs and outputs of the steps. 2033 o Made other editorial improvements suggested by JOSE working group 2034 participants. 2036 -00 2038 o Created the initial IETF draft based upon 2039 draft-jones-json-web-encryption-02 with no normative changes. 2041 o Changed terminology to no longer call both digital signatures and 2042 HMACs "signatures". 2044 Authors' Addresses 2046 Michael B. Jones 2047 Microsoft 2049 Email: mbj@microsoft.com 2050 URI: http://self-issued.info/ 2051 Eric Rescorla 2052 RTFM, Inc. 2054 Email: ekr@rtfm.com 2056 Joe Hildebrand 2057 Cisco Systems, Inc. 2059 Email: jhildebr@cisco.com