idnits 2.17.1 draft-ietf-jose-json-web-encryption-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 15, 2012) is 4209 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 1952 -- Looks like a reference, but probably isn't: '0' on line 1952 -- Looks like a reference, but probably isn't: '227' on line 1225 -- Looks like a reference, but probably isn't: '197' on line 1225 -- Looks like a reference, but probably isn't: '117' on line 1225 -- Looks like a reference, but probably isn't: '252' on line 1225 -- Looks like a reference, but probably isn't: '2' on line 1225 -- Looks like a reference, but probably isn't: '219' on line 1225 -- Looks like a reference, but probably isn't: '233' on line 1225 -- Looks like a reference, but probably isn't: '68' on line 1225 -- Looks like a reference, but probably isn't: '180' on line 1225 -- Looks like a reference, but probably isn't: '225' on line 1225 -- Looks like a reference, but probably isn't: '77' on line 1225 -- Looks like a reference, but probably isn't: '253' on line 1693 -- Looks like a reference, but probably isn't: '220' on line 1693 -- Looks like a reference, but probably isn't: '80' on line 1693 -- Looks like a reference, but probably isn't: '25' on line 1693 -- Looks like a reference, but probably isn't: '166' on line 1693 -- Looks like a reference, but probably isn't: '152' on line 1693 -- Looks like a reference, but probably isn't: '178' on line 1693 -- Looks like a reference, but probably isn't: '168' on line 1693 -- Looks like a reference, but probably isn't: '97' on line 1693 -- Looks like a reference, but probably isn't: '99' on line 1921 -- Looks like a reference, but probably isn't: '67' on line 1693 -- Looks like a reference, but probably isn't: '89' on line 1693 -- Looks like a reference, but probably isn't: '69' on line 1921 -- Looks like a reference, but probably isn't: '110' on line 1969 -- Looks like a reference, but probably isn't: '114' on line 1969 -- Looks like a reference, but probably isn't: '121' on line 1969 -- Looks like a reference, but probably isn't: '112' on line 1921 -- Looks like a reference, but probably isn't: '116' on line 1969 -- Looks like a reference, but probably isn't: '105' on line 1969 -- Looks like a reference, but probably isn't: '111' on line 1921 -- Looks like a reference, but probably isn't: '73' on line 1969 -- Looks like a reference, but probably isn't: '101' on line 1969 -- Looks like a reference, but probably isn't: '103' on line 1969 -- 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 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** 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 (==), 41 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: April 18, 2013 RTFM 6 J. Hildebrand 7 Cisco 8 October 15, 2012 10 JSON Web Encryption (JWE) 11 draft-ietf-jose-json-web-encryption-06 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 April 18, 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 . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 58 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 7 60 3.1. Example JWE with an Integrated Integrity Check . . . . . . 8 61 3.2. Example JWE with a Separate Integrity Check . . . . . . . 9 62 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11 63 4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 12 64 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 12 65 4.1.2. "enc" (Encryption Method) Header Parameter . . . . . . 12 66 4.1.3. "epk" (Ephemeral Public Key) Header Parameter . . . . 13 67 4.1.4. "zip" (Compression Algorithm) Header Parameter . . . . 13 68 4.1.5. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 13 69 4.1.6. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 13 70 4.1.7. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 13 71 4.1.8. "x5t" (X.509 Certificate Thumbprint) Header 72 Parameter . . . . . . . . . . . . . . . . . . . . . . 14 73 4.1.9. "x5c" (X.509 Certificate Chain) Header Parameter . . . 14 74 4.1.10. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14 75 4.1.11. "typ" (Type) Header Parameter . . . . . . . . . . . . 15 76 4.1.12. "cty" (Content Type) Header Parameter . . . . . . . . 15 77 4.1.13. "apu" (Agreement PartyUInfo) Header Parameter . . . . 15 78 4.1.14. "apv" (Agreement PartyVInfo) Header Parameter . . . . 15 79 4.1.15. "epu" (Encryption PartyUInfo) Header Parameter . . . . 15 80 4.1.16. "epv" (Encryption PartyVInfo) Header Parameter . . . . 16 81 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 16 82 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 16 83 5. Message Encryption . . . . . . . . . . . . . . . . . . . . . . 16 84 6. Message Decryption . . . . . . . . . . . . . . . . . . . . . . 18 85 7. CMK Encryption . . . . . . . . . . . . . . . . . . . . . . . . 19 86 8. Encrypting JWEs with Cryptographic Algorithms . . . . . . . . 19 87 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 88 9.1. Registration of JWE Header Parameter Names . . . . . . . . 20 89 9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 20 90 9.2. JSON Web Signature and Encryption Type Values 91 Registration . . . . . . . . . . . . . . . . . . . . . . . 21 92 9.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 93 9.3. Media Type Registration . . . . . . . . . . . . . . . . . 21 94 9.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 21 95 10. Security Considerations . . . . . . . . . . . . . . . . . . . 22 96 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 97 11.1. Normative References . . . . . . . . . . . . . . . . . . . 22 98 11.2. Informative References . . . . . . . . . . . . . . . . . . 24 99 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 24 100 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 24 101 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 25 102 A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 25 103 A.1.3. Content Master Key (CMK) . . . . . . . . . . . . . . . 25 104 A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 25 105 A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 28 106 A.1.6. Initialization Vector . . . . . . . . . . . . . . . . 28 107 A.1.7. "Additional Authenticated Data" Parameter . . . . . . 28 108 A.1.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 29 109 A.1.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 29 110 A.1.10. Encoded JWE Integrity Value . . . . . . . . . . . . . 30 111 A.1.11. Complete Representation . . . . . . . . . . . . . . . 30 112 A.1.12. Validation . . . . . . . . . . . . . . . . . . . . . . 30 113 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES CBC . . . . . . 30 114 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 31 115 A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 31 116 A.2.3. Content Master Key (CMK) . . . . . . . . . . . . . . . 31 117 A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 31 118 A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 34 119 A.2.6. Key Derivation . . . . . . . . . . . . . . . . . . . . 34 120 A.2.7. Initialization Vector . . . . . . . . . . . . . . . . 34 121 A.2.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 34 122 A.2.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 35 123 A.2.10. Secured Input Value . . . . . . . . . . . . . . . . . 35 124 A.2.11. JWE Integrity Value . . . . . . . . . . . . . . . . . 36 125 A.2.12. Encoded JWE Integrity Value . . . . . . . . . . . . . 36 126 A.2.13. Complete Representation . . . . . . . . . . . . . . . 36 127 A.2.14. Validation . . . . . . . . . . . . . . . . . . . . . . 37 128 A.3. Example JWE using AES Key Wrap and AES GCM . . . . . . . . 37 129 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 37 130 A.3.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 38 131 A.3.3. Content Master Key (CMK) . . . . . . . . . . . . . . . 38 132 A.3.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 38 133 A.3.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 38 134 A.3.6. Initialization Vector . . . . . . . . . . . . . . . . 38 135 A.3.7. "Additional Authenticated Data" Parameter . . . . . . 39 136 A.3.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 39 137 A.3.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 39 138 A.3.10. Encoded JWE Integrity Value . . . . . . . . . . . . . 40 139 A.3.11. Complete Representation . . . . . . . . . . . . . . . 40 140 A.3.12. Validation . . . . . . . . . . . . . . . . . . . . . . 40 141 A.4. Example Key Derivation for "enc" value "A128CBC+HS256" . . 40 142 A.4.1. CEK Generation . . . . . . . . . . . . . . . . . . . . 41 143 A.4.2. CIK Generation . . . . . . . . . . . . . . . . . . . . 42 145 A.5. Example Key Derivation for "enc" value "A256CBC+HS512" . . 42 146 A.5.1. CEK Generation . . . . . . . . . . . . . . . . . . . . 43 147 A.5.2. CIK Generation . . . . . . . . . . . . . . . . . . . . 44 148 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 45 149 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . . 45 150 Appendix D. Document History . . . . . . . . . . . . . . . . . . 46 151 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 49 153 1. Introduction 155 JSON Web Encryption (JWE) is a compact encryption format intended for 156 space constrained environments such as HTTP Authorization headers and 157 URI query parameters. It represents this content using JavaScript 158 Object Notation (JSON) [RFC4627] based data structures. The JWE 159 cryptographic mechanisms encrypt and provide integrity protection for 160 arbitrary sequences of bytes. 162 Cryptographic algorithms and identifiers for use with this 163 specification are described in the separate JSON Web Algorithms (JWA) 164 [JWA] specification. Related digital signature and MAC capabilities 165 are described in the separate JSON Web Signature (JWS) [JWS] 166 specification. 168 1.1. Notational Conventions 170 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 171 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 172 document are to be interpreted as described in Key words for use in 173 RFCs to Indicate Requirement Levels [RFC2119]. 175 2. Terminology 177 JSON Web Encryption (JWE) A data structure representing an encrypted 178 message. The structure consists of five parts: the JWE Header, 179 the JWE Encrypted Key, the JWE Initialization Vector, the JWE 180 Ciphertext, and the JWE Integrity Value. 182 Plaintext The bytes to be encrypted -- a.k.a., the message. The 183 plaintext can contain an arbitrary sequence of bytes. 185 Ciphertext An encrypted representation of the Plaintext. 187 Content Encryption Key (CEK) A symmetric key used to encrypt the 188 Plaintext for the recipient to produce the Ciphertext. 190 Content Integrity Key (CIK) A key used with a MAC function to ensure 191 the integrity of the Ciphertext and the parameters used to create 192 it. 194 Content Master Key (CMK) A key from which the CEK and CIK are 195 derived. When key wrapping or key encryption are employed, the 196 CMK is randomly generated and encrypted to the recipient as the 197 JWE Encrypted Key. When direct encryption with a shared symmetric 198 key is employed, the CMK is the shared key. When key agreement 199 without key wrapping is employed, the CMK is the result of the key 200 agreement algorithm. 202 JWE Header A string representing a JSON object that describes the 203 encryption operations applied to create the JWE Encrypted Key, the 204 JWE Ciphertext, and the JWE Integrity Value. 206 JWE Encrypted Key When key wrapping or key encryption are employed, 207 the Content Master Key (CMK) is encrypted with the intended 208 recipient's key and the resulting encrypted content is recorded as 209 a byte array, which is referred to as the JWE Encrypted Key. 210 Otherwise, when direct encryption with a shared or agreed upon 211 symmetric key is employed, the JWE Encrypted Key is the empty byte 212 array. 214 JWE Initialization Vector A byte array containing the Initialization 215 Vector used when encrypting the Plaintext. 217 JWE Ciphertext A byte array containing the Ciphertext. 219 JWE Integrity Value A byte array containing a MAC value that ensures 220 the integrity of the Ciphertext and the parameters used to create 221 it. 223 Base64url Encoding The URL- and filename-safe Base64 encoding 224 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 225 safe) '=' padding characters omitted, as permitted by Section 3.2. 226 (See Appendix C of [JWS] for notes on implementing base64url 227 encoding without padding.) 229 Encoded JWE Header Base64url encoding of the bytes of the UTF-8 230 [RFC3629] representation of the JWE Header. 232 Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted 233 Key. 235 Encoded JWE Initialization Vector Base64url encoding of the JWE 236 Initialization Vector. 238 Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. 240 Encoded JWE Integrity Value Base64url encoding of the JWE Integrity 241 Value. 243 Header Parameter Name The name of a member of the JSON object 244 representing a JWE Header. 246 Header Parameter Value The value of a member of the JSON object 247 representing a JWE Header. 249 JWE Compact Serialization A representation of the JWE as the 250 concatenation of the Encoded JWE Header, the Encoded JWE Encrypted 251 Key, the Encoded JWE Initialization Vector, the Encoded JWE 252 Ciphertext, and the Encoded JWE Integrity Value in that order, 253 with the five strings being separated by four period ('.') 254 characters. 256 AEAD Algorithm An Authenticated Encryption with Associated Data 257 (AEAD) [RFC5116] encryption algorithm is one that provides an 258 integrated content integrity check. AES Galois/Counter Mode (GCM) 259 is one such algorithm. 261 Collision Resistant Namespace A namespace that allows names to be 262 allocated in a manner such that they are highly unlikely to 263 collide with other names. For instance, collision resistance can 264 be achieved through administrative delegation of portions of the 265 namespace or through use of collision-resistant name allocation 266 functions. Examples of Collision Resistant Namespaces include: 267 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 268 X.660 and X.670 Recommendation series, and Universally Unique 269 IDentifiers (UUIDs) [RFC4122]. When using an administratively 270 delegated namespace, the definer of a name needs to take 271 reasonable precautions to ensure they are in control of the 272 portion of the namespace they use to define the name. 274 StringOrURI A JSON string value, with the additional requirement 275 that while arbitrary string values MAY be used, any value 276 containing a ":" character MUST be a URI [RFC3986]. StringOrURI 277 values are compared as case-sensitive strings with no 278 transformations or canonicalizations applied. 280 3. JSON Web Encryption (JWE) Overview 282 JWE represents encrypted content using JSON data structures and 283 base64url encoding. The representation consists of five parts: the 284 JWE Header, the JWE Encrypted Key, the JWE Initialization Vector, the 285 JWE Ciphertext, and the JWE Integrity Value. In the Compact 286 Serialization, the five parts are base64url-encoded for transmission, 287 and represented as the concatenation of the encoded strings in that 288 order, with the five strings being separated by four period ('.') 289 characters. (A JSON Serialization for this information is defined in 290 the separate JSON Web Encryption JSON Serialization (JWE-JS) [JWE-JS] 291 specification.) 292 JWE utilizes encryption to ensure the confidentiality of the 293 Plaintext. JWE adds a content integrity check if not provided by the 294 underlying encryption algorithm. 296 3.1. Example JWE with an Integrated Integrity Check 298 This example encrypts the plaintext "Live long and prosper." to the 299 recipient using RSAES OAEP and AES GCM. The AES GCM algorithm has an 300 integrated integrity check. 302 The following example JWE Header declares that: 304 o the Content Master Key is encrypted to the recipient using the 305 RSAES OAEP algorithm to produce the JWE Encrypted Key and 307 o the Plaintext is encrypted using the AES GCM algorithm with a 256 308 bit key to produce the Ciphertext. 310 {"alg":"RSA-OAEP","enc":"A256GCM"} 312 Base64url encoding the bytes of the UTF-8 representation of the JWE 313 Header yields this Encoded JWE Header value: 315 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 317 The remaining steps to finish creating this JWE are: 319 o Generate a random Content Master Key (CMK) 321 o Encrypt the CMK with the recipient's public key using the RSAES 322 OAEP algorithm to produce the JWE Encrypted Key 324 o Base64url encode the JWE Encrypted Key to produce the Encoded JWE 325 Encrypted Key 327 o Generate a random JWE Initialization Vector 329 o Base64url encode the JWE Initialization Vector to produce the 330 Encoded JWE Initialization Vector 332 o Concatenate the Encoded JWE Header value, a period character 333 ('.'), the Encoded JWE Encrypted Key, a second period character 334 ('.'), and the Encoded JWE Initialization Vector to create the 335 "additional authenticated data" parameter for the AES GCM 336 algorithm 338 o Encrypt the Plaintext with AES GCM, using the CMK as the 339 encryption key, the JWE Initialization Vector, and the "additional 340 authenticated data" value above, requesting a 128 bit 341 "authentication tag" output 343 o Base64url encode the resulting Ciphertext to create the Encoded 344 JWE Ciphertext 346 o Base64url encode the resulting "authentication tag" to create the 347 Encoded JWE Integrity Value 349 o Assemble the final representation: The Compact Serialization of 350 this result is the concatenation of the Encoded JWE Header, the 351 Encoded JWE Encrypted Key, the Encoded JWE Initialization Vector, 352 the Encoded JWE Ciphertext, and the Encoded JWE Integrity Value in 353 that order, with the five strings being separated by four period 354 ('.') characters. 356 The final result in this example (with line breaks for display 357 purposes only) is: 359 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 360 M2XxpbORKezKSzzQL_95-GjiudRBTqn_omS8z9xgoRb7L0Jw5UsEbxmtyHn2T71m 361 rZLkjg4Mp8gbhYoltPkEOHvAopz25-vZ8C2e1cOaAo5WPcbSIuFcB4DjBOM3t0UA 362 O6JHkWLuAEYoe58lcxIQneyKdaYSLbV9cKqoUoFQpvKWYRHZbfszIyfsa18rmgTj 363 zrtLDTPnc09DSJE24aQ8w3i8RXEDthW9T1J6LsTH_vwHdwUgkI-tC2PNeGrnM-dN 364 SfzF3Y7-lwcGy0FsdXkPXytvDV7y4pZeeUiQ-0VdibIN2AjjfW60nfrPuOjepMFG 365 6BBBbR37pHcyzext9epOAQ. 366 48V1_ALb6US04U3b. 367 _e21tGGhac_peEFkLXr2dMPUZiUkrw. 368 7V5ZDko0v_mf2PAc4JMiUg 370 See Appendix A.1 for the complete details of computing this JWE. 372 3.2. Example JWE with a Separate Integrity Check 374 This example encrypts the plaintext "No matter where you go, there 375 you are." to the recipient using RSAES-PKCS1-V1_5 and AES CBC. AES 376 CBC does not have an integrated integrity check, so a separate 377 integrity check calculation is performed using HMAC SHA-256, with 378 separate encryption and integrity keys being derived from a master 379 key using the Concat KDF with the SHA-256 digest function. 381 The following example JWE Header (with line breaks for display 382 purposes only) declares that: 384 o the Content Master Key is encrypted to the recipient using the 385 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 387 o the Plaintext is encrypted using the AES CBC algorithm with a 128 388 bit key to produce the Ciphertext, with the integrity of the 389 Ciphertext and the parameters used to create it being secured 390 using the HMAC SHA-256 algorithm. 392 {"alg":"RSA1_5","enc":"A128CBC+HS256"} 394 Base64url encoding the bytes of the UTF-8 representation of the JWE 395 Header yields this Encoded JWE Header value: 397 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDK0hTMjU2In0 399 The remaining steps to finish creating this JWE are like the previous 400 example, but with an additional step to compute the separate 401 integrity value: 403 o Generate a random Content Master Key (CMK) 405 o Encrypt the CMK with the recipient's public key using the RSAES- 406 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key 408 o Base64url encode the JWE Encrypted Key to produce the Encoded JWE 409 Encrypted Key 411 o Generate a random JWE Initialization Vector 413 o Base64url encode the JWE Initialization Vector to produce the 414 Encoded JWE Initialization Vector 416 o Use the Concat key derivation function to derive Content 417 Encryption Key (CEK) and Content Integrity Key (CIK) values from 418 the CMK 420 o Encrypt the Plaintext with AES CBC using the CEK and JWE 421 Initialization Vector to produce the Ciphertext 423 o Base64url encode the resulting Ciphertext to create the Encoded 424 JWE Ciphertext 426 o Concatenate the Encoded JWE Header value, a period character 427 ('.'), the Encoded JWE Encrypted Key, a second period character 428 ('.'), the Encoded JWE Initialization Vector, a third period ('.') 429 character, and the Encoded JWE Ciphertext to create the value to 430 integrity protect 432 o Compute the HMAC SHA-256 of this value using the CIK to create the 433 JWE Integrity Value 435 o Base64url encode the resulting JWE Integrity Value to create the 436 Encoded JWE Integrity Value 438 o Assemble the final representation: The Compact Serialization of 439 this result is the concatenation of the Encoded JWE Header, the 440 Encoded JWE Encrypted Key, the Encoded JWE Initialization Vector, 441 the Encoded JWE Ciphertext, and the Encoded JWE Integrity Value in 442 that order, with the five strings being separated by four period 443 ('.') characters. 445 The final result in this example (with line breaks for display 446 purposes only) is: 448 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDK0hTMjU2In0. 449 O6AqXqgVlJJ4c4lp5sXZd7bpGHAw6ARkHUeXQxD1cAW4-X1x0qtj_AN0mukqEOl4 450 Y6UOwJXIJY9-G1ELK-RQWrKH_StR-AM9H7GpKmSEji8QYOcMOjr-u9H1Lt_pBEie 451 G802SxWz0rbFTXRcj4BWLxcpCtjUZ31AP-sc-L_eCZ5UNl0aSRNqFskuPkzRsFZR 452 DJqSSJeVOyJ7pZCQ83fli19Vgi_3R7XMUqluQuuc7ZHOWixi47jXlBTlWRZ5iFxa 453 S8G6J8wUrd4BKggAw3qX5XoIfXQVlQZE0Vmkq_zQSIo5LnFKyowooRcdsEuNh9B9 454 Mkyt0ZQElG-jGdtHWjZSOA. 455 AxY8DCtDaGlsbGljb3RoZQ. 456 1eBWFgcrz40wC88cgv8rPgu3EfmC1p4zT0kIxxfSF2zDJcQ-iEHk1jQM95xAdr5Z. 457 RBGhYzE8_cZLHjJqqHuLhzbgWgL_wV3LDSUrcbkOiIA 459 See Appendix A.2 for the complete details of computing this JWE. 461 4. JWE Header 463 The members of the JSON object represented by the JWE Header describe 464 the encryption applied to the Plaintext and optionally additional 465 properties of the JWE. The Header Parameter Names within this object 466 MUST be unique; JWEs with duplicate Header Parameter Names MUST be 467 rejected. Implementations MUST understand the entire contents of the 468 header; otherwise, the JWE MUST be rejected. 470 There are two ways of distinguishing whether a header is a JWS Header 471 or a JWE Header. The first is by examining the "alg" (algorithm) 472 header value. If the value represents a digital signature or MAC 473 algorithm, or is the value "none", it is for a JWS; if it represents 474 an encryption or key agreement algorithm, it is for a JWE. A second 475 method is determining whether an "enc" (encryption method) member 476 exists. If the "enc" member exists, it is a JWE; otherwise, it is a 477 JWS. Both methods will yield the same result for all legal input 478 values. 480 There are three classes of Header Parameter Names: Reserved Header 481 Parameter Names, Public Header Parameter Names, and Private Header 482 Parameter Names. 484 4.1. Reserved Header Parameter Names 486 The following header parameter names are reserved with meanings as 487 defined below. All the names are short because a core goal of JWE is 488 for the representations to be compact. 490 Additional reserved header parameter names MAY be defined via the 491 IANA JSON Web Signature and Encryption Header Parameters registry 492 [JWS]. As indicated by the common registry, JWSs and JWEs share a 493 common header parameter space; when a parameter is used by both 494 specifications, its usage must be compatible between the 495 specifications. 497 4.1.1. "alg" (Algorithm) Header Parameter 499 The "alg" (algorithm) header parameter identifies the cryptographic 500 algorithm used to encrypt or determine the value of the Content 501 Master Key (CMK). The algorithm specified by the "alg" value MUST be 502 supported by the implementation and there MUST be a key for use with 503 that algorithm associated with the intended recipient or the JWE MUST 504 be rejected. "alg" values SHOULD either be registered in the IANA 505 JSON Web Signature and Encryption Algorithms registry [JWA] or be a 506 URI that contains a Collision Resistant Namespace. The "alg" value 507 is a case sensitive string containing a StringOrURI value. This 508 header parameter is REQUIRED. 510 A list of defined "alg" values can be found in the IANA JSON Web 511 Signature and Encryption Algorithms registry [JWA]; the initial 512 contents of this registry are the values defined in Section 4.1 of 513 the JSON Web Algorithms (JWA) [JWA] specification. 515 4.1.2. "enc" (Encryption Method) Header Parameter 517 The "enc" (encryption method) header parameter identifies the 518 symmetric encryption algorithm used to encrypt the Plaintext to 519 produce the Ciphertext. The algorithm specified by the "enc" value 520 MUST be supported by the implementation or the JWE MUST be rejected. 521 "enc" values SHOULD either be registered in the IANA JSON Web 522 Signature and Encryption Algorithms registry [JWA] or be a URI that 523 contains a Collision Resistant Namespace. The "enc" value is a case 524 sensitive string containing a StringOrURI value. This header 525 parameter is REQUIRED. 527 A list of defined "enc" values can be found in the IANA JSON Web 528 Signature and Encryption Algorithms registry [JWA]; the initial 529 contents of this registry are the values defined in Section 4.2 of 530 the JSON Web Algorithms (JWA) [JWA] specification. 532 4.1.3. "epk" (Ephemeral Public Key) Header Parameter 534 The "epk" (ephemeral public key) value created by the originator for 535 the use in key agreement algorithms. This key is represented as a 536 JSON Web Key [JWK] value. This header parameter is OPTIONAL, 537 although its use is REQUIRED with some "alg" algorithms. 539 4.1.4. "zip" (Compression Algorithm) Header Parameter 541 The "zip" (compression algorithm) applied to the Plaintext before 542 encryption, if any. If present, the value of the "zip" header 543 parameter MUST be the case sensitive string "DEF". Compression is 544 performed with the DEFLATE [RFC1951] algorithm. If no "zip" 545 parameter is present, no compression is applied to the Plaintext 546 before encryption. This header parameter is OPTIONAL. 548 4.1.5. "jku" (JWK Set URL) Header Parameter 550 The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that 551 refers to a resource for a set of JSON-encoded public keys, one of 552 which corresponds to the key used to encrypt the JWE; this can be 553 used to determine the private key needed to decrypt the JWE. The 554 keys MUST be encoded as a JSON Web Key Set (JWK Set) [JWK]. The 555 protocol used to acquire the resource MUST provide integrity 556 protection; an HTTP GET request to retrieve the certificate MUST use 557 TLS [RFC2818] [RFC5246]; the identity of the server MUST be 558 validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. This 559 header parameter is OPTIONAL. 561 4.1.6. "jwk" (JSON Web Key) Header Parameter 563 The "jwk" (JSON Web Key) header parameter is a public key that 564 corresponds to the key used to encrypt the JWE; this can be used to 565 determine the private key needed to decrypt the JWE. This key is 566 represented as a JSON Web Key [JWK]. This header parameter is 567 OPTIONAL. 569 4.1.7. "x5u" (X.509 URL) Header Parameter 571 The "x5u" (X.509 URL) header parameter is a URI [RFC3986] that refers 572 to a resource for the X.509 public key certificate or certificate 573 chain [RFC5280] corresponding to the key used to encrypt the JWE; 574 this can be used to determine the private key needed to decrypt the 575 JWE. The identified resource MUST provide a representation of the 576 certificate or certificate chain that conforms to RFC 5280 [RFC5280] 577 in PEM encoded form [RFC1421]. The certificate containing the public 578 key of the entity that encrypted the JWE MUST be the first 579 certificate. This MAY be followed by additional certificates, with 580 each subsequent certificate being the one used to certify the 581 previous one. The protocol used to acquire the resource MUST provide 582 integrity protection; an HTTP GET request to retrieve the certificate 583 MUST use TLS [RFC2818] [RFC5246]; the identity of the server MUST be 584 validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. This 585 header parameter is OPTIONAL. 587 4.1.8. "x5t" (X.509 Certificate Thumbprint) Header Parameter 589 The "x5t" (X.509 Certificate Thumbprint) header parameter provides a 590 base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER 591 encoding of the X.509 certificate [RFC5280] corresponding to the key 592 used to encrypt the JWE; this can be used to determine the private 593 key needed to decrypt the JWE. This header parameter is OPTIONAL. 595 If, in the future, certificate thumbprints need to be computed using 596 hash functions other than SHA-1, it is suggested that additional 597 related header parameters be defined for that purpose. For example, 598 it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint 599 using SHA-256) header parameter could be defined by registering it in 600 the IANA JSON Web Signature and Encryption Header Parameters registry 601 [JWS]. 603 4.1.9. "x5c" (X.509 Certificate Chain) Header Parameter 605 The "x5c" (X.509 Certificate Chain) header parameter contains the 606 X.509 public key certificate or certificate chain [RFC5280] 607 corresponding to the key used to encrypt the JWE; this can be used to 608 determine the private key needed to decrypt the JWE. The certificate 609 or certificate chain is represented as an array of certificate value 610 strings. Each string is a base64 encoded ([RFC4648] Section 4 -- not 611 base64url encoded) DER [ITU.X690.1994] PKIX certificate value. The 612 certificate containing the public key of the entity that encrypted 613 the JWE MUST be the first certificate. This MAY be followed by 614 additional certificates, with each subsequent certificate being the 615 one used to certify the previous one. The recipient MUST verify the 616 certificate chain according to [RFC5280] and reject the JWE if any 617 validation failure occurs. This header parameter is OPTIONAL. 619 See Appendix B of [JWS] for an example "x5c" value. 621 4.1.10. "kid" (Key ID) Header Parameter 623 The "kid" (key ID) header parameter is a hint indicating which key 624 was used to encrypt the JWE; this can be used to determine the 625 private key needed to decrypt the JWE. This parameter allows 626 originators to explicitly signal a change of key to recipients. 627 Should the recipient be unable to locate a key corresponding to the 628 "kid" value, they SHOULD treat that condition as an error. The 629 interpretation of the "kid" value is unspecified. Its value MUST be 630 a string. This header parameter is OPTIONAL. 632 When used with a JWK, the "kid" value MAY be used to match a JWK 633 "kid" parameter value. 635 4.1.11. "typ" (Type) Header Parameter 637 The "typ" (type) header parameter is used to declare the type of this 638 object. The type value "JWE" MAY be used to indicate that this 639 object is a JWE. The "typ" value is a case sensitive string. This 640 header parameter is OPTIONAL. 642 MIME Media Type [RFC2046] values MAY be used as "typ" values. 644 "typ" values SHOULD either be registered in the IANA JSON Web 645 Signature and Encryption Type Values registry [JWS] or be a URI that 646 contains a Collision Resistant Namespace. 648 4.1.12. "cty" (Content Type) Header Parameter 650 The "cty" (content type) header parameter is used to declare the type 651 of the encrypted content (the Plaintext). The "cty" value is a case 652 sensitive string. This header parameter is OPTIONAL. 654 The values used for the "cty" header parameter come from the same 655 value space as the "typ" header parameter, with the same rules 656 applying. 658 4.1.13. "apu" (Agreement PartyUInfo) Header Parameter 660 The "apu" (agreement PartyUInfo) value for key agreement algorithms 661 using it (such as "ECDH-ES"), represented as a base64url encoded 662 string. This header parameter is OPTIONAL. 664 4.1.14. "apv" (Agreement PartyVInfo) Header Parameter 666 The "apv" (agreement PartyVInfo) value for key agreement algorithms 667 using it (such as "ECDH-ES"), represented as a base64url encoded 668 string. This header parameter is OPTIONAL. 670 4.1.15. "epu" (Encryption PartyUInfo) Header Parameter 672 The "epu" (encryption PartyUInfo) value for plaintext encryption 673 algorithms using it (such as "A128CBC+HS256"), represented as a 674 base64url encoded string. This header parameter is OPTIONAL. 676 4.1.16. "epv" (Encryption PartyVInfo) Header Parameter 678 The "epv" (encryption PartyVInfo) value for plaintext encryption 679 algorithms using it (such as "A128CBC+HS256"), represented as a 680 base64url encoded string. This header parameter is OPTIONAL. 682 4.2. Public Header Parameter Names 684 Additional header parameter names can be defined by those using JWEs. 685 However, in order to prevent collisions, any new header parameter 686 name SHOULD either be registered in the IANA JSON Web Signature and 687 Encryption Header Parameters registry [JWS] or be a URI that contains 688 a Collision Resistant Namespace. In each case, the definer of the 689 name or value needs to take reasonable precautions to make sure they 690 are in control of the part of the namespace they use to define the 691 header parameter name. 693 New header parameters should be introduced sparingly, as they can 694 result in non-interoperable JWEs. 696 4.3. Private Header Parameter Names 698 A producer and consumer of a JWE may agree to any header parameter 699 name that is not a Reserved Name Section 4.1 or a Public Name 700 Section 4.2. Unlike Public Names, these private names are subject to 701 collision and should be used with caution. 703 5. Message Encryption 705 The message encryption process is as follows. The order of the steps 706 is not significant in cases where there are no dependencies between 707 the inputs and outputs of the steps. 709 1. When key wrapping, key encryption, or key agreement with key 710 wrapping are employed, generate a random Content Master Key 711 (CMK). See RFC 4086 [RFC4086] for considerations on generating 712 random values. The CMK MUST have a length equal to that 713 required for the block encryption algorithm. 715 2. When key agreement is employed, use the key agreement algorithm 716 to compute the value of the agreed upon key. When key agreement 717 without key wrapping is employed, let the Content Master Key 718 (CMK) be the agreed upon key. When key agreement with key 719 wrapping is employed, the agreed upon key will be used to wrap 720 the CMK. 722 3. When key wrapping, key encryption, or key agreement with key 723 wrapping are employed, encrypt the CMK for the recipient (see 724 Section 7) and let the result be the JWE Encrypted Key. 725 Otherwise, when direct encryption with a shared or agreed upon 726 symmetric key is employed, let the JWE Encrypted Key be the 727 empty byte array. 729 4. When direct encryption with a shared symmetric key is employed, 730 let the Content Master Key (CMK) be the shared key. 732 5. Base64url encode the JWE Encrypted Key to create the Encoded JWE 733 Encrypted Key. 735 6. Generate a random JWE Initialization Vector of the correct size 736 for the block encryption algorithm (if required for the 737 algorithm); otherwise, let the JWE Initialization Vector be the 738 empty byte string. 740 7. Base64url encode the JWE Initialization Vector to create the 741 Encoded JWE Initialization Vector. 743 8. Compress the Plaintext if a "zip" parameter was included. 745 9. Serialize the (compressed) Plaintext into a byte sequence M. 747 10. Create a JWE Header containing the encryption parameters used. 748 Note that white space is explicitly allowed in the 749 representation and no canonicalization need be performed before 750 encoding. 752 11. Base64url encode the bytes of the UTF-8 representation of the 753 JWE Header to create the Encoded JWE Header. 755 12. Encrypt M using the CMK, the JWE Initialization Vector, and the 756 other parameters required for the specified block encryption 757 algorithm to create the JWE Ciphertext value and the JWE 758 Integrity Value. 760 13. Base64url encode the JWE Ciphertext to create the Encoded JWE 761 Ciphertext. 763 14. Base64url encode the JWE Integrity Value to create the Encoded 764 JWE Integrity Value. 766 15. The five encoded parts, taken together, are the result. 768 16. The Compact Serialization of this result is the concatenation of 769 the Encoded JWE Header, the Encoded JWE Encrypted Key, the 770 Encoded JWE Initialization Vector, the Encoded JWE Ciphertext, 771 and the Encoded JWE Integrity Value in that order, with the five 772 strings being separated by four period ('.') characters. 774 6. Message Decryption 776 The message decryption process is the reverse of the encryption 777 process. The order of the steps is not significant in cases where 778 there are no dependencies between the inputs and outputs of the 779 steps. If any of these steps fails, the JWE MUST be rejected. 781 1. Determine the Encoded JWE Header, the Encoded JWE Encrypted Key, 782 the Encoded JWE Initialization Vector, the Encoded JWE 783 Ciphertext, and the Encoded JWE Integrity Value values contained 784 in the JWE. When using the Compact Serialization, these five 785 values are represented in that order, separated by four period 786 ('.') characters. 788 2. The Encoded JWE Header, the Encoded JWE Encrypted Key, the 789 Encoded JWE Initialization Vector, the Encoded JWE Ciphertext, 790 and the Encoded JWE Integrity Value MUST be successfully 791 base64url decoded following the restriction that no padding 792 characters have been used. 794 3. The resulting JWE Header MUST be completely valid JSON syntax 795 conforming to RFC 4627 [RFC4627]. 797 4. The resulting JWE Header MUST be validated to only include 798 parameters and values whose syntax and semantics are both 799 understood and supported. 801 5. Verify that the JWE uses a key known to the recipient. 803 6. When key agreement is employed, use the key agreement algorithm 804 to compute the value of the agreed upon key. When key agreement 805 without key wrapping is employed, let the Content Master Key 806 (CMK) be the agreed upon key. When key agreement with key 807 wrapping is employed, the agreed upon key will be used to 808 decrypt the JWE Encrypted Key. 810 7. When key wrapping, key encryption, or key agreement with key 811 wrapping are employed, decrypt the JWE Encrypted Key to produce 812 the Content Master Key (CMK). The CMK MUST have a length equal 813 to that required for the block encryption algorithm. 815 8. When direct encryption with a shared symmetric key is employed, 816 let the Content Master Key (CMK) be the shared key. 818 9. Decrypt the JWE Ciphertext using the CMK, the JWE Initialization 819 Vector, and the other parameters required for the specified 820 block encryption algorithm, returning the decrypted plaintext 821 and verifying the JWE Integrity Value in the manner specified 822 for the algorithm. 824 10. Uncompress the decrypted plaintext if a "zip" parameter was 825 included. 827 11. Output the resulting Plaintext. 829 7. CMK Encryption 831 JWE supports three forms of Content Master Key (CMK) encryption: 833 o Asymmetric encryption under the recipient's public key. 835 o Symmetric encryption under a key shared between the sender and 836 receiver. 838 o Symmetric encryption under a key agreed upon between the sender 839 and receiver. 841 See the algorithms registered for "enc" usage in the IANA JSON Web 842 Signature and Encryption Algorithms registry [JWA] and Section 4.1 of 843 the JSON Web Algorithms (JWA) [JWA] specification for lists of 844 encryption algorithms that can be used for CMK encryption. 846 8. Encrypting JWEs with Cryptographic Algorithms 848 JWE uses cryptographic algorithms to encrypt the Plaintext and the 849 Content Encryption Key (CMK) and to provide integrity protection for 850 the JWE Header, JWE Encrypted Key, and JWE Ciphertext. The JSON Web 851 Algorithms (JWA) [JWA] specification specifies a set of cryptographic 852 algorithms and identifiers to be used with this specification and 853 defines registries for additional such algorithms. Specifically, 854 Section 4.1 specifies a set of "alg" (algorithm) header parameter 855 values and Section 4.2 specifies a set of "enc" (encryption method) 856 header parameter values intended for use this specification. It also 857 describes the semantics and operations that are specific to these 858 algorithms and algorithm families. 860 Public keys employed for encryption can be identified using the 861 Header Parameter methods described in Section 4.1 or can be 862 distributed using methods that are outside the scope of this 863 specification. 865 9. IANA Considerations 867 9.1. Registration of JWE Header Parameter Names 869 This specification registers the Header Parameter Names defined in 870 Section 4.1 in the IANA JSON Web Signature and Encryption Header 871 Parameters registry [JWS]. 873 9.1.1. Registry Contents 875 o Header Parameter Name: "alg" 876 o Change Controller: IETF 877 o Specification Document(s): Section 4.1.1 of [[ this document ]] 879 o Header Parameter Name: "enc" 880 o Change Controller: IETF 881 o Specification Document(s): Section 4.1.2 of [[ this document ]] 883 o Header Parameter Name: "epk" 884 o Change Controller: IETF 885 o Specification Document(s): Section 4.1.3 of [[ this document ]] 887 o Header Parameter Name: "zip" 888 o Change Controller: IETF 889 o Specification Document(s): Section 4.1.4 of [[ this document ]] 891 o Header Parameter Name: "jku" 892 o Change Controller: IETF 893 o Specification Document(s): Section 4.1.5 of [[ this document ]] 895 o Header Parameter Name: "jwk" 896 o Change Controller: IETF 897 o Specification document(s): Section 4.1.6 of [[ this document ]] 899 o Header Parameter Name: "x5u" 900 o Change Controller: IETF 901 o Specification Document(s): Section 4.1.7 of [[ this document ]] 903 o Header Parameter Name: "x5t" 904 o Change Controller: IETF 905 o Specification Document(s): Section 4.1.8 of [[ this document ]] 907 o Header Parameter Name: "x5c" 908 o Change Controller: IETF 909 o Specification Document(s): Section 4.1.9 of [[ this document ]] 910 o Header Parameter Name: "kid" 911 o Change Controller: IETF 912 o Specification Document(s): Section 4.1.10 of [[ this document ]] 914 o Header Parameter Name: "typ" 915 o Change Controller: IETF 916 o Specification Document(s): Section 4.1.11 of [[ this document ]] 918 o Header Parameter Name: "cty" 919 o Change Controller: IETF 920 o Specification Document(s): Section 4.1.12 of [[ this document ]] 922 o Header Parameter Name: "apu" 923 o Change Controller: IETF 924 o Specification Document(s): Section 4.1.13 of [[ this document ]] 926 o Header Parameter Name: "apv" 927 o Change Controller: IETF 928 o Specification Document(s): Section 4.1.14 of [[ this document ]] 930 o Header Parameter Name: "epu" 931 o Change Controller: IETF 932 o Specification Document(s): Section 4.1.15 of [[ this document ]] 934 o Header Parameter Name: "epv" 935 o Change Controller: IETF 936 o Specification Document(s): Section 4.1.16 of [[ this document ]] 938 9.2. JSON Web Signature and Encryption Type Values Registration 940 9.2.1. Registry Contents 942 This specification registers the "JWE" type value in the IANA JSON 943 Web Signature and Encryption Type Values registry [JWS]: 945 o "typ" Header Parameter Value: "JWE" 946 o Abbreviation for MIME Type: application/jwe 947 o Change Controller: IETF 948 o Specification Document(s): Section 4.1.11 of [[ this document ]] 950 9.3. Media Type Registration 952 9.3.1. Registry Contents 954 This specification registers the "application/jwe" Media Type 955 [RFC2046] in the MIME Media Type registry [RFC4288] to indicate that 956 the content is a JWE using the Compact Serialization. 958 o Type Name: application 959 o Subtype Name: jwe 960 o Required Parameters: n/a 961 o Optional Parameters: n/a 962 o Encoding considerations: JWE values are encoded as a series of 963 base64url encoded values (some of which may be the empty string) 964 separated by period ('.') characters 965 o Security Considerations: See the Security Considerations section 966 of this document 967 o Interoperability Considerations: n/a 968 o Published Specification: [[ this document ]] 969 o Applications that use this media type: OpenID Connect and other 970 applications using encrypted JWTs 971 o Additional Information: Magic number(s): n/a, File extension(s): 972 n/a, Macintosh file type code(s): n/a 973 o Person & email address to contact for further information: Michael 974 B. Jones, mbj@microsoft.com 975 o Intended Usage: COMMON 976 o Restrictions on Usage: none 977 o Author: Michael B. Jones, mbj@microsoft.com 978 o Change Controller: IETF 980 10. Security Considerations 982 All of the security issues faced by any cryptographic application 983 must be faced by a JWS/JWE/JWK agent. Among these issues are 984 protecting the user's private key, preventing various attacks, and 985 helping the user avoid mistakes such as inadvertently encrypting a 986 message for the wrong recipient. The entire list of security 987 considerations is beyond the scope of this document, but some 988 significant concerns are listed here. 990 All the security considerations in the JWS specification also apply 991 to this specification. Likewise, all the security considerations in 992 XML Encryption 1.1 [W3C.CR-xmlenc-core1-20120313] also apply to JWE, 993 other than those that are XML specific. 995 11. References 997 11.1. Normative References 999 [ITU.X690.1994] 1000 International Telecommunications Union, "Information 1001 Technology - ASN.1 encoding rules: Specification of Basic 1002 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1003 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1004 X.690, 1994. 1006 [JWA] Jones, M., "JSON Web Algorithms (JWA)", October 2012. 1008 [JWK] Jones, M., "JSON Web Key (JWK)", October 2012. 1010 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1011 Signature (JWS)", October 2012. 1013 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 1014 Mail: Part I: Message Encryption and Authentication 1015 Procedures", RFC 1421, February 1993. 1017 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1018 version 1.3", RFC 1951, May 1996. 1020 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1021 Extensions (MIME) Part Two: Media Types", RFC 2046, 1022 November 1996. 1024 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1025 Requirement Levels", BCP 14, RFC 2119, March 1997. 1027 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1029 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1030 10646", STD 63, RFC 3629, November 2003. 1032 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1033 Resource Identifier (URI): Generic Syntax", STD 66, 1034 RFC 3986, January 2005. 1036 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1037 Requirements for Security", BCP 106, RFC 4086, June 2005. 1039 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 1040 Registration Procedures", BCP 13, RFC 4288, December 2005. 1042 [RFC4627] Crockford, D., "The application/json Media Type for 1043 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1045 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1046 Encodings", RFC 4648, October 2006. 1048 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 1049 Encryption", RFC 5116, January 2008. 1051 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1052 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1054 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1055 Housley, R., and W. Polk, "Internet X.509 Public Key 1056 Infrastructure Certificate and Certificate Revocation List 1057 (CRL) Profile", RFC 5280, May 2008. 1059 [W3C.CR-xmlenc-core1-20120313] 1060 Eastlake, D., Reagle, J., Hirsch, F., and T. Roessler, 1061 "XML Encryption Syntax and Processing Version 1.1", World 1062 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1063 March 2012, 1064 . 1066 11.2. Informative References 1068 [I-D.rescorla-jsms] 1069 Rescorla, E. and J. Hildebrand, "JavaScript Message 1070 Security Format", draft-rescorla-jsms-00 (work in 1071 progress), March 2011. 1073 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1074 Encryption", September 2010. 1076 [JWE-JS] Jones, M., "JSON Web Encryption JSON Serialization 1077 (JWE-JS)", October 2012. 1079 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1080 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1081 July 2005. 1083 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1084 RFC 5652, September 2009. 1086 Appendix A. JWE Examples 1088 This section provides examples of JWE computations. 1090 A.1. Example JWE using RSAES OAEP and AES GCM 1092 This example encrypts the plaintext "Live long and prosper." to the 1093 recipient using RSAES OAEP and AES GCM. The AES GCM algorithm has an 1094 integrated integrity check. The representation of this plaintext is: 1096 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1097 112, 114, 111, 115, 112, 101, 114, 46] 1099 A.1.1. JWE Header 1101 The following example JWE Header declares that: 1103 o the Content Master Key is encrypted to the recipient using the 1104 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1106 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1107 bit key to produce the Ciphertext. 1109 {"alg":"RSA-OAEP","enc":"A256GCM"} 1111 A.1.2. Encoded JWE Header 1113 Base64url encoding the bytes of the UTF-8 representation of the JWE 1114 Header yields this Encoded JWE Header value: 1116 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1118 A.1.3. Content Master Key (CMK) 1120 Generate a 256 bit random Content Master Key (CMK). In this example, 1121 the value is: 1123 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1124 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1125 234, 64, 252] 1127 A.1.4. Key Encryption 1129 Encrypt the CMK with the recipient's public key using the RSAES OAEP 1130 algorithm to produce the JWE Encrypted Key. In this example, the RSA 1131 key parameters are: 1133 +-----------+-------------------------------------------------------+ 1134 | Parameter | Value | 1135 | Name | | 1136 +-----------+-------------------------------------------------------+ 1137 | Modulus | [161, 168, 84, 34, 133, 176, 208, 173, 46, 176, 163, | 1138 | | 110, 57, 30, 135, 227, 9, 31, 226, 128, 84, 92, 116, | 1139 | | 241, 70, 248, 27, 227, 193, 62, 5, 91, 241, 145, 224, | 1140 | | 205, 141, 176, 184, 133, 239, 43, 81, 103, 9, 161, | 1141 | | 153, 157, 179, 104, 123, 51, 189, 34, 152, 69, 97, | 1142 | | 69, 78, 93, 140, 131, 87, 182, 169, 101, 92, 142, 3, | 1143 | | 22, 167, 8, 212, 56, 35, 79, 210, 222, 192, 208, 252, | 1144 | | 49, 109, 138, 173, 253, 210, 166, 201, 63, 102, 74, | 1145 | | 5, 158, 41, 90, 144, 108, 160, 79, 10, 89, 222, 231, | 1146 | | 172, 31, 227, 197, 0, 19, 72, 81, 138, 78, 136, 221, | 1147 | | 121, 118, 196, 17, 146, 10, 244, 188, 72, 113, 55, | 1148 | | 221, 162, 217, 171, 27, 57, 233, 210, 101, 236, 154, | 1149 | | 199, 56, 138, 239, 101, 48, 198, 186, 202, 160, 76, | 1150 | | 111, 234, 71, 57, 183, 5, 211, 171, 136, 126, 64, 40, | 1151 | | 75, 58, 89, 244, 254, 107, 84, 103, 7, 236, 69, 163, | 1152 | | 18, 180, 251, 58, 153, 46, 151, 174, 12, 103, 197, | 1153 | | 181, 161, 162, 55, 250, 235, 123, 110, 17, 11, 158, | 1154 | | 24, 47, 133, 8, 199, 235, 107, 126, 130, 246, 73, | 1155 | | 195, 20, 108, 202, 176, 214, 187, 45, 146, 182, 118, | 1156 | | 54, 32, 200, 61, 201, 71, 243, 1, 255, 131, 84, 37, | 1157 | | 111, 211, 168, 228, 45, 192, 118, 27, 197, 235, 232, | 1158 | | 36, 10, 230, 248, 190, 82, 182, 140, 35, 204, 108, | 1159 | | 190, 253, 186, 186, 27] | 1160 | Exponent | [1, 0, 1] | 1161 | Private | [144, 183, 109, 34, 62, 134, 108, 57, 44, 252, 10, | 1162 | Exponent | 66, 73, 54, 16, 181, 233, 92, 54, 219, 101, 42, 35, | 1163 | | 178, 63, 51, 43, 92, 119, 136, 251, 41, 53, 23, 191, | 1164 | | 164, 164, 60, 88, 227, 229, 152, 228, 213, 149, 228, | 1165 | | 169, 237, 104, 71, 151, 75, 88, 252, 216, 77, 251, | 1166 | | 231, 28, 97, 88, 193, 215, 202, 248, 216, 121, 195, | 1167 | | 211, 245, 250, 112, 71, 243, 61, 129, 95, 39, 244, | 1168 | | 122, 225, 217, 169, 211, 165, 48, 253, 220, 59, 122, | 1169 | | 219, 42, 86, 223, 32, 236, 39, 48, 103, 78, 122, 216, | 1170 | | 187, 88, 176, 89, 24, 1, 42, 177, 24, 99, 142, 170, | 1171 | | 1, 146, 43, 3, 108, 64, 194, 121, 182, 95, 187, 134, | 1172 | | 71, 88, 96, 134, 74, 131, 167, 69, 106, 143, 121, 27, | 1173 | | 72, 44, 245, 95, 39, 194, 179, 175, 203, 122, 16, | 1174 | | 112, 183, 17, 200, 202, 31, 17, 138, 156, 184, 210, | 1175 | | 157, 184, 154, 131, 128, 110, 12, 85, 195, 122, 241, | 1176 | | 79, 251, 229, 183, 117, 21, 123, 133, 142, 220, 153, | 1177 | | 9, 59, 57, 105, 81, 255, 138, 77, 82, 54, 62, 216, | 1178 | | 38, 249, 208, 17, 197, 49, 45, 19, 232, 157, 251, | 1179 | | 131, 137, 175, 72, 126, 43, 229, 69, 179, 117, 82, | 1180 | | 157, 213, 83, 35, 57, 210, 197, 252, 171, 143, 194, | 1181 | | 11, 47, 163, 6, 253, 75, 252, 96, 11, 187, 84, 130, | 1182 | | 210, 7, 121, 78, 91, 79, 57, 251, 138, 132, 220, 60, | 1183 | | 224, 173, 56, 224, 201] | 1184 +-----------+-------------------------------------------------------+ 1186 The resulting JWE Encrypted Key value is: 1188 [51, 101, 241, 165, 179, 145, 41, 236, 202, 75, 60, 208, 47, 255, 1189 121, 248, 104, 226, 185, 212, 65, 78, 169, 255, 162, 100, 188, 207, 1190 220, 96, 161, 22, 251, 47, 66, 112, 229, 75, 4, 111, 25, 173, 200, 1191 121, 246, 79, 189, 102, 173, 146, 228, 142, 14, 12, 167, 200, 27, 1192 133, 138, 37, 180, 249, 4, 56, 123, 192, 162, 156, 246, 231, 235, 1193 217, 240, 45, 158, 213, 195, 154, 2, 142, 86, 61, 198, 210, 34, 225, 1194 92, 7, 128, 227, 4, 227, 55, 183, 69, 0, 59, 162, 71, 145, 98, 238, 1195 0, 70, 40, 123, 159, 37, 115, 18, 16, 157, 236, 138, 117, 166, 18, 1196 45, 181, 125, 112, 170, 168, 82, 129, 80, 166, 242, 150, 97, 17, 217, 1197 109, 251, 51, 35, 39, 236, 107, 95, 43, 154, 4, 227, 206, 187, 75, 1198 13, 51, 231, 115, 79, 67, 72, 145, 54, 225, 164, 60, 195, 120, 188, 1199 69, 113, 3, 182, 21, 189, 79, 82, 122, 46, 196, 199, 254, 252, 7, 1200 119, 5, 32, 144, 143, 173, 11, 99, 205, 120, 106, 231, 51, 231, 77, 1201 73, 252, 197, 221, 142, 254, 151, 7, 6, 203, 65, 108, 117, 121, 15, 1202 95, 43, 111, 13, 94, 242, 226, 150, 94, 121, 72, 144, 251, 69, 93, 1203 137, 178, 13, 216, 8, 227, 125, 110, 180, 157, 250, 207, 184, 232, 1204 222, 164, 193, 70, 232, 16, 65, 109, 29, 251, 164, 119, 50, 205, 236, 1205 109, 245, 234, 78, 1] 1207 A.1.5. Encoded JWE Encrypted Key 1209 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1210 Encrypted Key. This result (with line breaks for display purposes 1211 only) is: 1213 M2XxpbORKezKSzzQL_95-GjiudRBTqn_omS8z9xgoRb7L0Jw5UsEbxmtyHn2T71m 1214 rZLkjg4Mp8gbhYoltPkEOHvAopz25-vZ8C2e1cOaAo5WPcbSIuFcB4DjBOM3t0UA 1215 O6JHkWLuAEYoe58lcxIQneyKdaYSLbV9cKqoUoFQpvKWYRHZbfszIyfsa18rmgTj 1216 zrtLDTPnc09DSJE24aQ8w3i8RXEDthW9T1J6LsTH_vwHdwUgkI-tC2PNeGrnM-dN 1217 SfzF3Y7-lwcGy0FsdXkPXytvDV7y4pZeeUiQ-0VdibIN2AjjfW60nfrPuOjepMFG 1218 6BBBbR37pHcyzext9epOAQ 1220 A.1.6. Initialization Vector 1222 Generate a random 96 bit JWE Initialization Vector. In this example, 1223 the value is: 1225 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1227 Base64url encoding this value yields the Encoded JWE Initialization 1228 Vector value: 1230 48V1_ALb6US04U3b 1232 A.1.7. "Additional Authenticated Data" Parameter 1234 Concatenate the Encoded JWE Header value, a period character ('.'), 1235 the Encoded JWE Encrypted Key, a second period character ('.'), and 1236 the Encoded JWE Initialization Vector to create the "additional 1237 authenticated data" parameter for the AES GCM algorithm. This result 1238 (with line breaks for display purposes only) is: 1240 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1241 M2XxpbORKezKSzzQL_95-GjiudRBTqn_omS8z9xgoRb7L0Jw5UsEbxmtyHn2T71m 1242 rZLkjg4Mp8gbhYoltPkEOHvAopz25-vZ8C2e1cOaAo5WPcbSIuFcB4DjBOM3t0UA 1243 O6JHkWLuAEYoe58lcxIQneyKdaYSLbV9cKqoUoFQpvKWYRHZbfszIyfsa18rmgTj 1244 zrtLDTPnc09DSJE24aQ8w3i8RXEDthW9T1J6LsTH_vwHdwUgkI-tC2PNeGrnM-dN 1245 SfzF3Y7-lwcGy0FsdXkPXytvDV7y4pZeeUiQ-0VdibIN2AjjfW60nfrPuOjepMFG 1246 6BBBbR37pHcyzext9epOAQ. 1247 48V1_ALb6US04U3b 1249 The representation of this value is: 1251 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1252 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1253 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81, 46, 1254 77, 50, 88, 120, 112, 98, 79, 82, 75, 101, 122, 75, 83, 122, 122, 81, 1255 76, 95, 57, 53, 45, 71, 106, 105, 117, 100, 82, 66, 84, 113, 110, 95, 1256 111, 109, 83, 56, 122, 57, 120, 103, 111, 82, 98, 55, 76, 48, 74, 1257 119, 53, 85, 115, 69, 98, 120, 109, 116, 121, 72, 110, 50, 84, 55, 1258 49, 109, 114, 90, 76, 107, 106, 103, 52, 77, 112, 56, 103, 98, 104, 1259 89, 111, 108, 116, 80, 107, 69, 79, 72, 118, 65, 111, 112, 122, 50, 1260 53, 45, 118, 90, 56, 67, 50, 101, 49, 99, 79, 97, 65, 111, 53, 87, 1261 80, 99, 98, 83, 73, 117, 70, 99, 66, 52, 68, 106, 66, 79, 77, 51, 1262 116, 48, 85, 65, 79, 54, 74, 72, 107, 87, 76, 117, 65, 69, 89, 111, 1263 101, 53, 56, 108, 99, 120, 73, 81, 110, 101, 121, 75, 100, 97, 89, 1264 83, 76, 98, 86, 57, 99, 75, 113, 111, 85, 111, 70, 81, 112, 118, 75, 1265 87, 89, 82, 72, 90, 98, 102, 115, 122, 73, 121, 102, 115, 97, 49, 56, 1266 114, 109, 103, 84, 106, 122, 114, 116, 76, 68, 84, 80, 110, 99, 48, 1267 57, 68, 83, 74, 69, 50, 52, 97, 81, 56, 119, 51, 105, 56, 82, 88, 69, 1268 68, 116, 104, 87, 57, 84, 49, 74, 54, 76, 115, 84, 72, 95, 118, 119, 1269 72, 100, 119, 85, 103, 107, 73, 45, 116, 67, 50, 80, 78, 101, 71, 1270 114, 110, 77, 45, 100, 78, 83, 102, 122, 70, 51, 89, 55, 45, 108, 1271 119, 99, 71, 121, 48, 70, 115, 100, 88, 107, 80, 88, 121, 116, 118, 1272 68, 86, 55, 121, 52, 112, 90, 101, 101, 85, 105, 81, 45, 48, 86, 100, 1273 105, 98, 73, 78, 50, 65, 106, 106, 102, 87, 54, 48, 110, 102, 114, 1274 80, 117, 79, 106, 101, 112, 77, 70, 71, 54, 66, 66, 66, 98, 82, 51, 1275 55, 112, 72, 99, 121, 122, 101, 120, 116, 57, 101, 112, 79, 65, 81, 1276 46, 52, 56, 86, 49, 95, 65, 76, 98, 54, 85, 83, 48, 52, 85, 51, 98] 1278 A.1.8. Plaintext Encryption 1280 Encrypt the Plaintext with AES GCM using the CMK as the encryption 1281 key, the JWE Initialization Vector, and the "additional authenticated 1282 data" value above, requesting a 128 bit "authentication tag" output. 1283 The resulting Ciphertext is: 1285 [253, 237, 181, 180, 97, 161, 105, 207, 233, 120, 65, 100, 45, 122, 1286 246, 116, 195, 212, 102, 37, 36, 175] 1288 The resulting "authentication tag" value is: 1290 [237, 94, 89, 14, 74, 52, 191, 249, 159, 216, 240, 28, 224, 147, 34, 1291 82] 1293 A.1.9. Encoded JWE Ciphertext 1295 Base64url encode the resulting Ciphertext to create the Encoded JWE 1296 Ciphertext. This result is: 1298 _e21tGGhac_peEFkLXr2dMPUZiUkrw 1300 A.1.10. Encoded JWE Integrity Value 1302 Base64url encode the resulting "authentication tag" to create the 1303 Encoded JWE Integrity Value. This result is: 1305 7V5ZDko0v_mf2PAc4JMiUg 1307 A.1.11. Complete Representation 1309 Assemble the final representation: The Compact Serialization of this 1310 result is the concatenation of the Encoded JWE Header, the Encoded 1311 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1312 JWE Ciphertext, and the Encoded JWE Integrity Value in that order, 1313 with the five strings being separated by four period ('.') 1314 characters. 1316 The final result in this example (with line breaks for display 1317 purposes only) is: 1319 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1320 M2XxpbORKezKSzzQL_95-GjiudRBTqn_omS8z9xgoRb7L0Jw5UsEbxmtyHn2T71m 1321 rZLkjg4Mp8gbhYoltPkEOHvAopz25-vZ8C2e1cOaAo5WPcbSIuFcB4DjBOM3t0UA 1322 O6JHkWLuAEYoe58lcxIQneyKdaYSLbV9cKqoUoFQpvKWYRHZbfszIyfsa18rmgTj 1323 zrtLDTPnc09DSJE24aQ8w3i8RXEDthW9T1J6LsTH_vwHdwUgkI-tC2PNeGrnM-dN 1324 SfzF3Y7-lwcGy0FsdXkPXytvDV7y4pZeeUiQ-0VdibIN2AjjfW60nfrPuOjepMFG 1325 6BBBbR37pHcyzext9epOAQ. 1326 48V1_ALb6US04U3b. 1327 _e21tGGhac_peEFkLXr2dMPUZiUkrw. 1328 7V5ZDko0v_mf2PAc4JMiUg 1330 A.1.12. Validation 1332 This example illustrates the process of creating a JWE with an AEAD 1333 algorithm. These results can be used to validate JWE decryption 1334 implementations for these algorithms. Note that since the RSAES OAEP 1335 computation includes random values, the encryption results above will 1336 not be completely reproducible. However, since the AES GCM 1337 computation is deterministic, the JWE Encrypted Ciphertext values 1338 will be the same for all encryptions performed using these inputs. 1340 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES CBC 1342 This example encrypts the plaintext "No matter where you go, there 1343 you are." to the recipient using RSAES-PKCS1-V1_5 and AES CBC. AES 1344 CBC does not have an integrated integrity check, so a separate 1345 integrity check calculation is performed using HMAC SHA-256, with 1346 separate encryption and integrity keys being derived from a master 1347 key using the Concat KDF with the SHA-256 digest function. The 1348 representation of this plaintext is: 1350 [78, 111, 32, 109, 97, 116, 116, 101, 114, 32, 119, 104, 101, 114, 1351 101, 32, 121, 111, 117, 32, 103, 111, 44, 32, 116, 104, 101, 114, 1352 101, 32, 121, 111, 117, 32, 97, 114, 101, 46] 1354 A.2.1. JWE Header 1356 The following example JWE Header (with line breaks for display 1357 purposes only) declares that: 1359 o the Content Master Key is encrypted to the recipient using the 1360 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1362 o the Plaintext is encrypted using the AES CBC algorithm with a 128 1363 bit key to produce the Ciphertext, with the integrity of the 1364 Ciphertext and the parameters used to create it being secured with 1365 the HMAC SHA-256 algorithm. 1367 {"alg":"RSA1_5","enc":"A128CBC+HS256"} 1369 A.2.2. Encoded JWE Header 1371 Base64url encoding the bytes of the UTF-8 representation of the JWE 1372 Header yields this Encoded JWE Header value: 1374 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDK0hTMjU2In0 1376 A.2.3. Content Master Key (CMK) 1378 Generate a 256 bit random Content Master Key (CMK). In this example, 1379 the key value is: 1381 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1382 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1383 44, 207] 1385 A.2.4. Key Encryption 1387 Encrypt the CMK with the recipient's public key using the RSAES- 1388 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. In this 1389 example, the RSA key parameters are: 1391 +-----------+-------------------------------------------------------+ 1392 | Parameter | Value | 1393 | Name | | 1394 +-----------+-------------------------------------------------------+ 1395 | Modulus | [177, 119, 33, 13, 164, 30, 108, 121, 207, 136, 107, | 1396 | | 242, 12, 224, 19, 226, 198, 134, 17, 71, 173, 75, 42, | 1397 | | 61, 48, 162, 206, 161, 97, 108, 185, 234, 226, 219, | 1398 | | 118, 206, 118, 5, 169, 224, 60, 181, 90, 85, 51, 123, | 1399 | | 6, 224, 4, 122, 29, 230, 151, 12, 244, 127, 121, 25, | 1400 | | 4, 85, 220, 144, 215, 110, 130, 17, 68, 228, 129, | 1401 | | 138, 7, 130, 231, 40, 212, 214, 17, 179, 28, 124, | 1402 | | 151, 178, 207, 20, 14, 154, 222, 113, 176, 24, 198, | 1403 | | 73, 211, 113, 9, 33, 178, 80, 13, 25, 21, 25, 153, | 1404 | | 212, 206, 67, 154, 147, 70, 194, 192, 183, 160, 83, | 1405 | | 98, 236, 175, 85, 23, 97, 75, 199, 177, 73, 145, 50, | 1406 | | 253, 206, 32, 179, 254, 236, 190, 82, 73, 67, 129, | 1407 | | 253, 252, 220, 108, 136, 138, 11, 192, 1, 36, 239, | 1408 | | 228, 55, 81, 113, 17, 25, 140, 63, 239, 146, 3, 172, | 1409 | | 96, 60, 227, 233, 64, 255, 224, 173, 225, 228, 229, | 1410 | | 92, 112, 72, 99, 97, 26, 87, 187, 123, 46, 50, 90, | 1411 | | 202, 117, 73, 10, 153, 47, 224, 178, 163, 77, 48, 46, | 1412 | | 154, 33, 148, 34, 228, 33, 172, 216, 89, 46, 225, | 1413 | | 127, 68, 146, 234, 30, 147, 54, 146, 5, 133, 45, 78, | 1414 | | 254, 85, 55, 75, 213, 86, 194, 218, 215, 163, 189, | 1415 | | 194, 54, 6, 83, 36, 18, 153, 53, 7, 48, 89, 35, 66, | 1416 | | 144, 7, 65, 154, 13, 97, 75, 55, 230, 132, 3, 13, | 1417 | | 239, 71] | 1418 | Exponent | [1, 0, 1] | 1419 | Private | [84, 80, 150, 58, 165, 235, 242, 123, 217, 55, 38, | 1420 | Exponent | 154, 36, 181, 221, 156, 211, 215, 100, 164, 90, 88, | 1421 | | 40, 228, 83, 148, 54, 122, 4, 16, 165, 48, 76, 194, | 1422 | | 26, 107, 51, 53, 179, 165, 31, 18, 198, 173, 78, 61, | 1423 | | 56, 97, 252, 158, 140, 80, 63, 25, 223, 156, 36, 203, | 1424 | | 214, 252, 120, 67, 180, 167, 3, 82, 243, 25, 97, 214, | 1425 | | 83, 133, 69, 16, 104, 54, 160, 200, 41, 83, 164, 187, | 1426 | | 70, 153, 111, 234, 242, 158, 175, 28, 198, 48, 211, | 1427 | | 45, 148, 58, 23, 62, 227, 74, 52, 117, 42, 90, 41, | 1428 | | 249, 130, 154, 80, 119, 61, 26, 193, 40, 125, 10, | 1429 | | 152, 174, 227, 225, 205, 32, 62, 66, 6, 163, 100, 99, | 1430 | | 219, 19, 253, 25, 105, 80, 201, 29, 252, 157, 237, | 1431 | | 69, 1, 80, 171, 167, 20, 196, 156, 109, 249, 88, 0, | 1432 | | 3, 152, 38, 165, 72, 87, 6, 152, 71, 156, 214, 16, | 1433 | | 71, 30, 82, 51, 103, 76, 218, 63, 9, 84, 163, 249, | 1434 | | 91, 215, 44, 238, 85, 101, 240, 148, 1, 82, 224, 91, | 1435 | | 135, 105, 127, 84, 171, 181, 152, 210, 183, 126, 24, | 1436 | | 46, 196, 90, 173, 38, 245, 219, 186, 222, 27, 240, | 1437 | | 212, 194, 15, 66, 135, 226, 178, 190, 52, 245, 74, | 1438 | | 65, 224, 81, 100, 85, 25, 204, 165, 203, 187, 175, | 1439 | | 84, 100, 82, 15, 11, 23, 202, 151, 107, 54, 41, 207, | 1440 | | 3, 136, 229, 134, 131, 93, 139, 50, 182, 204, 93, | 1441 | | 130, 89] | 1442 +-----------+-------------------------------------------------------+ 1444 The resulting JWE Encrypted Key value is: 1446 [59, 160, 42, 94, 168, 21, 148, 146, 120, 115, 137, 105, 230, 197, 1447 217, 119, 182, 233, 24, 112, 48, 232, 4, 100, 29, 71, 151, 67, 16, 1448 245, 112, 5, 184, 249, 125, 113, 210, 171, 99, 252, 3, 116, 154, 233, 1449 42, 16, 233, 120, 99, 165, 14, 192, 149, 200, 37, 143, 126, 27, 81, 1450 11, 43, 228, 80, 90, 178, 135, 253, 43, 81, 248, 3, 61, 31, 177, 169, 1451 42, 100, 132, 142, 47, 16, 96, 231, 12, 58, 58, 254, 187, 209, 245, 1452 46, 223, 233, 4, 72, 158, 27, 205, 54, 75, 21, 179, 210, 182, 197, 1453 77, 116, 92, 143, 128, 86, 47, 23, 41, 10, 216, 212, 103, 125, 64, 1454 63, 235, 28, 248, 191, 222, 9, 158, 84, 54, 93, 26, 73, 19, 106, 22, 1455 201, 46, 62, 76, 209, 176, 86, 81, 12, 154, 146, 72, 151, 149, 59, 1456 34, 123, 165, 144, 144, 243, 119, 229, 139, 95, 85, 130, 47, 247, 71, 1457 181, 204, 82, 169, 110, 66, 235, 156, 237, 145, 206, 90, 44, 98, 227, 1458 184, 215, 148, 20, 229, 89, 22, 121, 136, 92, 90, 75, 193, 186, 39, 1459 204, 20, 173, 222, 1, 42, 8, 0, 195, 122, 151, 229, 122, 8, 125, 116, 1460 21, 149, 6, 68, 209, 89, 164, 171, 252, 208, 72, 138, 57, 46, 113, 1461 74, 202, 140, 40, 161, 23, 29, 176, 75, 141, 135, 208, 125, 50, 76, 1462 173, 209, 148, 4, 148, 111, 163, 25, 219, 71, 90, 54, 82, 56] 1464 A.2.5. Encoded JWE Encrypted Key 1466 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1467 Encrypted Key. This result (with line breaks for display purposes 1468 only) is: 1470 O6AqXqgVlJJ4c4lp5sXZd7bpGHAw6ARkHUeXQxD1cAW4-X1x0qtj_AN0mukqEOl4 1471 Y6UOwJXIJY9-G1ELK-RQWrKH_StR-AM9H7GpKmSEji8QYOcMOjr-u9H1Lt_pBEie 1472 G802SxWz0rbFTXRcj4BWLxcpCtjUZ31AP-sc-L_eCZ5UNl0aSRNqFskuPkzRsFZR 1473 DJqSSJeVOyJ7pZCQ83fli19Vgi_3R7XMUqluQuuc7ZHOWixi47jXlBTlWRZ5iFxa 1474 S8G6J8wUrd4BKggAw3qX5XoIfXQVlQZE0Vmkq_zQSIo5LnFKyowooRcdsEuNh9B9 1475 Mkyt0ZQElG-jGdtHWjZSOA 1477 A.2.6. Key Derivation 1479 Use the Concat key derivation function to derive Content Encryption 1480 Key (CEK) and Content Integrity Key (CIK) values from the CMK. The 1481 details of this derivation are shown in Appendix A.4. The resulting 1482 CEK value is: 1484 [37, 245, 125, 247, 113, 155, 238, 98, 228, 206, 62, 65, 81, 153, 79, 1485 91] 1487 The resulting CIK value is: 1489 [203, 194, 197, 180, 120, 46, 123, 202, 78, 12, 33, 116, 214, 247, 1490 128, 41, 175, 53, 181, 164, 224, 223, 56, 146, 179, 193, 18, 223, 1491 146, 85, 244, 127] 1493 A.2.7. Initialization Vector 1495 Generate a random 128 bit JWE Initialization Vector. In this 1496 example, the value is: 1498 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1499 101] 1501 Base64url encoding this value yields the Encoded JWE Initialization 1502 Vector value: 1504 AxY8DCtDaGlsbGljb3RoZQ 1506 A.2.8. Plaintext Encryption 1508 Encrypt the Plaintext with AES CBC using the CEK and the JWE 1509 Initialization Vector to produce the Ciphertext. The resulting 1510 Ciphertext is: 1512 [213, 224, 86, 22, 7, 43, 207, 141, 48, 11, 207, 28, 130, 255, 43, 1513 62, 11, 183, 17, 249, 130, 214, 158, 51, 79, 73, 8, 199, 23, 210, 23, 1514 108, 195, 37, 196, 62, 136, 65, 228, 214, 52, 12, 247, 156, 64, 118, 1515 190, 89] 1517 A.2.9. Encoded JWE Ciphertext 1519 Base64url encode the resulting Ciphertext to create the Encoded JWE 1520 Ciphertext. This result is: 1522 1eBWFgcrz40wC88cgv8rPgu3EfmC1p4zT0kIxxfSF2zDJcQ-iEHk1jQM95xAdr5Z 1524 A.2.10. Secured Input Value 1526 Concatenate the Encoded JWE Header value, a period character ('.'), 1527 the Encoded JWE Encrypted Key, a second period character, the Encoded 1528 JWE Initialization Vector, a third period ('.') character, and the 1529 Encoded JWE Ciphertext to create the value to integrity protect. 1530 This result (with line breaks for display purposes only) is: 1532 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDK0hTMjU2In0. 1533 O6AqXqgVlJJ4c4lp5sXZd7bpGHAw6ARkHUeXQxD1cAW4-X1x0qtj_AN0mukqEOl4 1534 Y6UOwJXIJY9-G1ELK-RQWrKH_StR-AM9H7GpKmSEji8QYOcMOjr-u9H1Lt_pBEie 1535 G802SxWz0rbFTXRcj4BWLxcpCtjUZ31AP-sc-L_eCZ5UNl0aSRNqFskuPkzRsFZR 1536 DJqSSJeVOyJ7pZCQ83fli19Vgi_3R7XMUqluQuuc7ZHOWixi47jXlBTlWRZ5iFxa 1537 S8G6J8wUrd4BKggAw3qX5XoIfXQVlQZE0Vmkq_zQSIo5LnFKyowooRcdsEuNh9B9 1538 Mkyt0ZQElG-jGdtHWjZSOA. 1539 AxY8DCtDaGlsbGljb3RoZQ. 1540 1eBWFgcrz40wC88cgv8rPgu3EfmC1p4zT0kIxxfSF2zDJcQ-iEHk1jQM95xAdr5Z 1542 The representation of this value is: 1544 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1545 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1546 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 75, 48, 104, 84, 77, 106, 85, 1547 50, 73, 110, 48, 46, 79, 54, 65, 113, 88, 113, 103, 86, 108, 74, 74, 1548 52, 99, 52, 108, 112, 53, 115, 88, 90, 100, 55, 98, 112, 71, 72, 65, 1549 119, 54, 65, 82, 107, 72, 85, 101, 88, 81, 120, 68, 49, 99, 65, 87, 1550 52, 45, 88, 49, 120, 48, 113, 116, 106, 95, 65, 78, 48, 109, 117, 1551 107, 113, 69, 79, 108, 52, 89, 54, 85, 79, 119, 74, 88, 73, 74, 89, 1552 57, 45, 71, 49, 69, 76, 75, 45, 82, 81, 87, 114, 75, 72, 95, 83, 116, 1553 82, 45, 65, 77, 57, 72, 55, 71, 112, 75, 109, 83, 69, 106, 105, 56, 1554 81, 89, 79, 99, 77, 79, 106, 114, 45, 117, 57, 72, 49, 76, 116, 95, 1555 112, 66, 69, 105, 101, 71, 56, 48, 50, 83, 120, 87, 122, 48, 114, 98, 1556 70, 84, 88, 82, 99, 106, 52, 66, 87, 76, 120, 99, 112, 67, 116, 106, 1557 85, 90, 51, 49, 65, 80, 45, 115, 99, 45, 76, 95, 101, 67, 90, 53, 85, 1558 78, 108, 48, 97, 83, 82, 78, 113, 70, 115, 107, 117, 80, 107, 122, 1559 82, 115, 70, 90, 82, 68, 74, 113, 83, 83, 74, 101, 86, 79, 121, 74, 1560 55, 112, 90, 67, 81, 56, 51, 102, 108, 105, 49, 57, 86, 103, 105, 95, 1561 51, 82, 55, 88, 77, 85, 113, 108, 117, 81, 117, 117, 99, 55, 90, 72, 1562 79, 87, 105, 120, 105, 52, 55, 106, 88, 108, 66, 84, 108, 87, 82, 90, 1563 53, 105, 70, 120, 97, 83, 56, 71, 54, 74, 56, 119, 85, 114, 100, 52, 1564 66, 75, 103, 103, 65, 119, 51, 113, 88, 53, 88, 111, 73, 102, 88, 81, 1565 86, 108, 81, 90, 69, 48, 86, 109, 107, 113, 95, 122, 81, 83, 73, 111, 1566 53, 76, 110, 70, 75, 121, 111, 119, 111, 111, 82, 99, 100, 115, 69, 1567 117, 78, 104, 57, 66, 57, 77, 107, 121, 116, 48, 90, 81, 69, 108, 71, 1568 45, 106, 71, 100, 116, 72, 87, 106, 90, 83, 79, 65, 46, 65, 120, 89, 1569 56, 68, 67, 116, 68, 97, 71, 108, 115, 98, 71, 108, 106, 98, 51, 82, 1570 111, 90, 81, 46, 49, 101, 66, 87, 70, 103, 99, 114, 122, 52, 48, 119, 1571 67, 56, 56, 99, 103, 118, 56, 114, 80, 103, 117, 51, 69, 102, 109, 1572 67, 49, 112, 52, 122, 84, 48, 107, 73, 120, 120, 102, 83, 70, 50, 1573 122, 68, 74, 99, 81, 45, 105, 69, 72, 107, 49, 106, 81, 77, 57, 53, 1574 120, 65, 100, 114, 53, 90] 1576 A.2.11. JWE Integrity Value 1578 Compute the HMAC SHA-256 of this value using the CIK to create the 1579 JWE Integrity Value. This result is: 1581 [68, 17, 161, 99, 49, 60, 253, 198, 75, 30, 50, 106, 168, 123, 139, 1582 135, 54, 224, 90, 2, 255, 193, 93, 203, 13, 37, 43, 113, 185, 14, 1583 136, 128] 1585 A.2.12. Encoded JWE Integrity Value 1587 Base64url encode the resulting JWE Integrity Value to create the 1588 Encoded JWE Integrity Value. This result is: 1590 RBGhYzE8_cZLHjJqqHuLhzbgWgL_wV3LDSUrcbkOiIA 1592 A.2.13. Complete Representation 1594 Assemble the final representation: The Compact Serialization of this 1595 result is the concatenation of the Encoded JWE Header, the Encoded 1596 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1597 JWE Ciphertext, and the Encoded JWE Integrity Value in that order, 1598 with the five strings being separated by four period ('.') 1599 characters. 1601 The final result in this example (with line breaks for display 1602 purposes only) is: 1604 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDK0hTMjU2In0. 1605 O6AqXqgVlJJ4c4lp5sXZd7bpGHAw6ARkHUeXQxD1cAW4-X1x0qtj_AN0mukqEOl4 1606 Y6UOwJXIJY9-G1ELK-RQWrKH_StR-AM9H7GpKmSEji8QYOcMOjr-u9H1Lt_pBEie 1607 G802SxWz0rbFTXRcj4BWLxcpCtjUZ31AP-sc-L_eCZ5UNl0aSRNqFskuPkzRsFZR 1608 DJqSSJeVOyJ7pZCQ83fli19Vgi_3R7XMUqluQuuc7ZHOWixi47jXlBTlWRZ5iFxa 1609 S8G6J8wUrd4BKggAw3qX5XoIfXQVlQZE0Vmkq_zQSIo5LnFKyowooRcdsEuNh9B9 1610 Mkyt0ZQElG-jGdtHWjZSOA. 1611 AxY8DCtDaGlsbGljb3RoZQ. 1612 1eBWFgcrz40wC88cgv8rPgu3EfmC1p4zT0kIxxfSF2zDJcQ-iEHk1jQM95xAdr5Z. 1613 RBGhYzE8_cZLHjJqqHuLhzbgWgL_wV3LDSUrcbkOiIA 1615 A.2.14. Validation 1617 This example illustrates the process of creating a JWE with a 1618 composite AEAD algorithm created from a non-AEAD algorithm by adding 1619 a separate integrity check calculation. These results can be used to 1620 validate JWE decryption implementations for these algorithms. Note 1621 that since the RSAES-PKCS1-V1_5 computation includes random values, 1622 the encryption results above will not be completely reproducible. 1623 However, since the AES CBC computation is deterministic, the JWE 1624 Encrypted Ciphertext values will be the same for all encryptions 1625 performed using these inputs. 1627 A.3. Example JWE using AES Key Wrap and AES GCM 1629 This example encrypts the plaintext "The true sign of intelligence is 1630 not knowledge but imagination." to the recipient using AES Key Wrap 1631 and AES GCM. The representation of this plaintext is: 1633 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1634 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1635 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1636 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1637 110, 97, 116, 105, 111, 110, 46] 1639 A.3.1. JWE Header 1641 The following example JWE Header declares that: 1643 o the Content Master Key is encrypted to the recipient using the AES 1644 Key Wrap algorithm with a 128 bit key to produce the JWE Encrypted 1645 Key and 1647 o the Plaintext is encrypted using the AES GCM algorithm with a 128 1648 bit key to produce the Ciphertext. 1650 {"alg":"A128KW","enc":"A128GCM"} 1652 A.3.2. Encoded JWE Header 1654 Base64url encoding the bytes of the UTF-8 representation of the JWE 1655 Header yields this Encoded JWE Header value: 1657 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4R0NNIn0 1659 A.3.3. Content Master Key (CMK) 1661 Generate a 128 bit random Content Master Key (CMK). In this example, 1662 the value is: 1664 [64, 154, 239, 170, 64, 40, 195, 99, 19, 84, 192, 142, 192, 238, 207, 1665 217] 1667 A.3.4. Key Encryption 1669 Encrypt the CMK with the shared symmetric key using the AES Key Wrap 1670 algorithm to produce the JWE Encrypted Key. In this example, the 1671 shared symmetric key value is: 1673 [25, 172, 32, 130, 225, 114, 26, 181, 138, 106, 254, 192, 95, 133, 1674 74, 82] 1676 The resulting JWE Encrypted Key value is: 1678 [164, 255, 251, 1, 64, 200, 65, 200, 34, 197, 81, 143, 43, 211, 240, 1679 38, 191, 161, 181, 117, 119, 68, 44, 80] 1681 A.3.5. Encoded JWE Encrypted Key 1683 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1684 Encrypted Key. This result is: 1686 pP_7AUDIQcgixVGPK9PwJr-htXV3RCxQ 1688 A.3.6. Initialization Vector 1690 Generate a random 96 bit JWE Initialization Vector. In this example, 1691 the value is: 1693 [253, 220, 80, 25, 166, 152, 178, 168, 97, 99, 67, 89] 1695 Base64url encoding this value yields the Encoded JWE Initialization 1696 Vector value: 1698 _dxQGaaYsqhhY0NZ 1700 A.3.7. "Additional Authenticated Data" Parameter 1702 Concatenate the Encoded JWE Header value, a period character ('.'), 1703 the Encoded JWE Encrypted Key, a second period character ('.'), and 1704 the Encoded JWE Initialization Vector to create the "additional 1705 authenticated data" parameter for the AES GCM algorithm. This result 1706 (with line breaks for display purposes only) is: 1708 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4R0NNIn0. 1709 pP_7AUDIQcgixVGPK9PwJr-htXV3RCxQ. 1710 _dxQGaaYsqhhY0NZ 1712 The representation of this value is: 1714 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1715 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1716 77, 84, 73, 52, 82, 48, 78, 78, 73, 110, 48, 46, 112, 80, 95, 55, 65, 1717 85, 68, 73, 81, 99, 103, 105, 120, 86, 71, 80, 75, 57, 80, 119, 74, 1718 114, 45, 104, 116, 88, 86, 51, 82, 67, 120, 81, 46, 95, 100, 120, 81, 1719 71, 97, 97, 89, 115, 113, 104, 104, 89, 48, 78, 90] 1721 A.3.8. Plaintext Encryption 1723 Encrypt the Plaintext with AES GCM using the CMK as the encryption 1724 key, the JWE Initialization Vector, and the "additional authenticated 1725 data" value above, requesting a 128 bit "authentication tag" output. 1726 The resulting Ciphertext is: 1728 [227, 12, 89, 132, 185, 16, 248, 93, 145, 87, 53, 130, 95, 115, 62, 1729 104, 138, 96, 109, 71, 124, 211, 165, 103, 202, 99, 21, 193, 4, 226, 1730 84, 229, 254, 106, 144, 241, 39, 86, 148, 132, 160, 104, 88, 232, 1731 228, 109, 85, 7, 86, 80, 134, 106, 166, 24, 92, 199, 210, 188, 153, 1732 187, 218, 69, 227] 1734 The resulting "authentication tag" value is: 1736 [154, 35, 80, 107, 37, 148, 81, 6, 103, 4, 60, 206, 171, 165, 113, 1737 67] 1739 A.3.9. Encoded JWE Ciphertext 1741 Base64url encode the resulting Ciphertext to create the Encoded JWE 1742 Ciphertext. This result (with line breaks for display purposes only) 1743 is: 1745 4wxZhLkQ-F2RVzWCX3M-aIpgbUd806VnymMVwQTiVOX-apDxJ1aUhKBoWOjkbVUH 1746 VlCGaqYYXMfSvJm72kXj 1748 A.3.10. Encoded JWE Integrity Value 1750 Base64url encode the resulting "authentication tag" to create the 1751 Encoded JWE Integrity Value. This result is: 1753 miNQayWUUQZnBDzOq6VxQw 1755 A.3.11. Complete Representation 1757 Assemble the final representation: The Compact Serialization of this 1758 result is the concatenation of the Encoded JWE Header, the Encoded 1759 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1760 JWE Ciphertext, and the Encoded JWE Integrity Value in that order, 1761 with the five strings being separated by four period ('.') 1762 characters. 1764 The final result in this example (with line breaks for display 1765 purposes only) is: 1767 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4R0NNIn0. 1768 pP_7AUDIQcgixVGPK9PwJr-htXV3RCxQ. 1769 _dxQGaaYsqhhY0NZ. 1770 4wxZhLkQ-F2RVzWCX3M-aIpgbUd806VnymMVwQTiVOX-apDxJ1aUhKBoWOjkbVUH 1771 VlCGaqYYXMfSvJm72kXj. 1772 miNQayWUUQZnBDzOq6VxQw 1774 A.3.12. Validation 1776 This example illustrates the process of creating a JWE with symmetric 1777 key wrap and an AEAD algorithm. These results can be used to 1778 validate JWE decryption implementations for these algorithms. Also, 1779 since both the AES Key Wrap and AES GCM computations are 1780 deterministic, the resulting JWE value will be the same for all 1781 encryptions performed using these inputs. Since the computation is 1782 reproducible, these results can also be used to validate JWE 1783 encryption implementations for these algorithms. 1785 A.4. Example Key Derivation for "enc" value "A128CBC+HS256" 1787 This example uses the Concat KDF to derive the Content Encryption Key 1788 (CEK) and Content Integrity Key (CIK) from the Content Master Key 1789 (CMK) in the manner described in Section 4.8.1 of [JWA]. In this 1790 example, a 256 bit CMK is used to derive a 128 bit CEK and a 256 bit 1791 CIK. 1793 The CMK value used is: 1795 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1796 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1797 44, 207] 1799 A.4.1. CEK Generation 1801 These values are concatenated to produce the round 1 hash input: 1803 o the round number 1 as a 32 bit big endian integer ([0, 0, 0, 1]), 1805 o the CMK value (as above), 1807 o the output bit size 128 as a 32 bit big endian number ([0, 0, 0, 1808 128]), 1810 o the bytes of the UTF-8 representation of the "enc" value 1811 "A128CBC+HS256" -- [65, 49, 50, 56, 67, 66, 67, 43, 72, 83, 50, 1812 53, 54], 1814 o (no bytes are included for the "epu" (encryption PartyUInfo) and 1815 "epv" (encryption PartyVInfo) parameters because they are absent, 1816 but if present, the base64url decoded values of them would have 1817 been included here), 1819 o the bytes of the ASCII representation of the label "Encryption" -- 1820 [69, 110, 99, 114, 121, 112, 116, 105, 111, 110]. 1822 Thus the round 1 hash input is: 1824 [0, 0, 0, 1, 4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 1825 63, 170, 106, 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 1826 240, 143, 156, 44, 207, 0, 0, 0, 128, 65, 49, 50, 56, 67, 66, 67, 43, 1827 72, 83, 50, 53, 54, 69, 110, 99, 114, 121, 112, 116, 105, 111, 110] 1829 The SHA-256 hash of this value, which is the round 1 hash output, is: 1831 [37, 245, 125, 247, 113, 155, 238, 98, 228, 206, 62, 65, 81, 153, 79, 1832 91, 225, 37, 250, 101, 198, 63, 51, 182, 5, 242, 241, 169, 162, 232, 1833 103, 155] 1835 Given that 128 bits are needed for the CEK and the hash has produced 1836 256 bits, the CEK value is the first 128 bits of that value: 1838 [37, 245, 125, 247, 113, 155, 238, 98, 228, 206, 62, 65, 81, 153, 79, 1839 91] 1841 A.4.2. CIK Generation 1843 These values are concatenated to produce the round 1 hash input: 1845 o the round number 1 as a 32 bit big endian integer ([0, 0, 0, 1]), 1847 o the CMK value (as above), 1849 o the output bit size 256 as a 32 bit big endian number ([0, 0, 1, 1850 0]), 1852 o the bytes of the UTF-8 representation of the "enc" value 1853 "A128CBC+HS256" -- [65, 49, 50, 56, 67, 66, 67, 43, 72, 83, 50, 1854 53, 54], 1856 o (no bytes are included for the "epu" (encryption PartyUInfo) and 1857 "epv" (encryption PartyVInfo) parameters because they are absent, 1858 but if present, the base64url decoded values of them would have 1859 been included here), 1861 o the bytes of the ASCII representation of the label "Integrity" -- 1862 [73, 110, 116, 101, 103, 114, 105, 116, 121]. 1864 Thus the round 1 hash input is: 1866 [0, 0, 0, 1, 4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 1867 63, 170, 106, 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 1868 240, 143, 156, 44, 207, 0, 0, 1, 0, 65, 49, 50, 56, 67, 66, 67, 43, 1869 72, 83, 50, 53, 54, 73, 110, 116, 101, 103, 114, 105, 116, 121] 1871 The SHA-256 hash of this value, which is the round 1 hash output, is: 1873 [203, 194, 197, 180, 120, 46, 123, 202, 78, 12, 33, 116, 214, 247, 1874 128, 41, 175, 53, 181, 164, 224, 223, 56, 146, 179, 193, 18, 223, 1875 146, 85, 244, 127] 1877 Given that 256 bits are needed for the CIK and the hash has produced 1878 256 bits, the CIK value is that same value: 1880 [203, 194, 197, 180, 120, 46, 123, 202, 78, 12, 33, 116, 214, 247, 1881 128, 41, 175, 53, 181, 164, 224, 223, 56, 146, 179, 193, 18, 223, 1882 146, 85, 244, 127] 1884 A.5. Example Key Derivation for "enc" value "A256CBC+HS512" 1886 This example uses the Concat KDF to derive the Content Encryption Key 1887 (CEK) and Content Integrity Key (CIK) from the Content Master Key 1888 (CMK) in the manner described in Section 4.8.1 of [JWA]. In this 1889 example, a 512 bit CMK is used to derive a 256 bit CEK and a 512 bit 1890 CIK. 1892 The CMK value used is: 1894 [148, 116, 199, 126, 2, 117, 233, 76, 150, 149, 89, 193, 61, 34, 239, 1895 226, 109, 71, 59, 160, 192, 140, 150, 235, 106, 204, 49, 176, 68, 1896 119, 13, 34, 49, 19, 41, 69, 5, 20, 252, 145, 104, 129, 137, 138, 67, 1897 23, 153, 83, 81, 234, 82, 247, 48, 211, 41, 130, 35, 124, 45, 156, 1898 249, 7, 225, 168] 1900 A.5.1. CEK Generation 1902 These values are concatenated to produce the round 1 hash input: 1904 o the round number 1 as a 32 bit big endian integer ([0, 0, 0, 1]), 1906 o the CMK value (as above), 1908 o the output bit size 256 as a 32 bit big endian number ([0, 0, 1, 1909 0]), 1911 o the bytes of the UTF-8 representation of the "enc" value 1912 "A256CBC+HS512" -- [65, 50, 53, 54, 67, 66, 67, 43, 72, 83, 53, 1913 49, 50], 1915 o (no bytes are included for the "epu" (encryption PartyUInfo) and 1916 "epv" (encryption PartyVInfo) parameters because they are absent, 1917 but if present, the base64url decoded values of them would have 1918 been included here), 1920 o the bytes of the ASCII representation of the label "Encryption" -- 1921 [69, 110, 99, 114, 121, 112, 116, 105, 111, 110]. 1923 Thus the round 1 hash input is: 1925 [0, 0, 0, 1, 148, 116, 199, 126, 2, 117, 233, 76, 150, 149, 89, 193, 1926 61, 34, 239, 226, 109, 71, 59, 160, 192, 140, 150, 235, 106, 204, 49, 1927 176, 68, 119, 13, 34, 49, 19, 41, 69, 5, 20, 252, 145, 104, 129, 137, 1928 138, 67, 23, 153, 83, 81, 234, 82, 247, 48, 211, 41, 130, 35, 124, 1929 45, 156, 249, 7, 225, 168, 0, 0, 1, 0, 65, 50, 53, 54, 67, 66, 67, 1930 43, 72, 83, 53, 49, 50, 69, 110, 99, 114, 121, 112, 116, 105, 111, 1931 110] 1933 The SHA-512 hash of this value, which is the round 1 hash output, is: 1935 [95, 112, 19, 252, 0, 97, 200, 188, 108, 84, 27, 116, 192, 169, 42, 1936 165, 25, 246, 115, 235, 226, 198, 148, 211, 94, 143, 240, 226, 89, 1937 226, 79, 13, 178, 80, 124, 251, 55, 114, 30, 115, 179, 64, 107, 213, 1938 222, 225, 12, 169, 245, 116, 231, 83, 227, 233, 20, 164, 249, 148, 1939 62, 92, 43, 5, 1, 97] 1941 Given that 256 bits are needed for the CEK and the hash has produced 1942 512 bits, the CEK value is the first 256 bits of that value: 1944 [95, 112, 19, 252, 0, 97, 200, 188, 108, 84, 27, 116, 192, 169, 42, 1945 165, 25, 246, 115, 235, 226, 198, 148, 211, 94, 143, 240, 226, 89, 1946 226, 79, 13] 1948 A.5.2. CIK Generation 1950 These values are concatenated to produce the round 1 hash input: 1952 o the round number 1 as a 32 bit big endian integer ([0, 0, 0, 1]), 1954 o the CMK value (as above), 1956 o the output bit size 512 as a 32 bit big endian number ([0, 0, 2, 1957 0]), 1959 o the bytes of the UTF-8 representation of the "enc" value 1960 "A256CBC+HS512" -- [65, 50, 53, 54, 67, 66, 67, 43, 72, 83, 53, 1961 49, 50], 1963 o (no bytes are included for the "epu" (encryption PartyUInfo) and 1964 "epv" (encryption PartyVInfo) parameters because they are absent, 1965 but if present, the base64url decoded values of them would have 1966 been included here), 1968 o the bytes of the ASCII representation of the label "Integrity" -- 1969 [73, 110, 116, 101, 103, 114, 105, 116, 121]. 1971 Thus the round 1 hash input is: 1973 [0, 0, 0, 1, 148, 116, 199, 126, 2, 117, 233, 76, 150, 149, 89, 193, 1974 61, 34, 239, 226, 109, 71, 59, 160, 192, 140, 150, 235, 106, 204, 49, 1975 176, 68, 119, 13, 34, 49, 19, 41, 69, 5, 20, 252, 145, 104, 129, 137, 1976 138, 67, 23, 153, 83, 81, 234, 82, 247, 48, 211, 41, 130, 35, 124, 1977 45, 156, 249, 7, 225, 168, 0, 0, 2, 0, 65, 50, 53, 54, 67, 66, 67, 1978 43, 72, 83, 53, 49, 50, 73, 110, 116, 101, 103, 114, 105, 116, 121] 1980 The SHA-512 hash of this value, which is the round 1 hash output, is: 1982 [203, 188, 104, 71, 177, 60, 21, 10, 255, 157, 56, 214, 254, 87, 32, 1983 115, 194, 36, 117, 162, 226, 93, 50, 220, 191, 219, 41, 56, 80, 197, 1984 18, 173, 250, 145, 215, 178, 235, 51, 251, 122, 212, 193, 48, 227, 1985 126, 89, 253, 101, 143, 252, 124, 157, 147, 200, 175, 164, 253, 92, 1986 204, 122, 218, 77, 105, 146] 1988 Given that 512 bits are needed for the CIK and the hash has produced 1989 512 bits, the CIK value is that same value: 1991 [203, 188, 104, 71, 177, 60, 21, 10, 255, 157, 56, 214, 254, 87, 32, 1992 115, 194, 36, 117, 162, 226, 93, 50, 220, 191, 219, 41, 56, 80, 197, 1993 18, 173, 250, 145, 215, 178, 235, 51, 251, 122, 212, 193, 48, 227, 1994 126, 89, 253, 101, 143, 252, 124, 157, 147, 200, 175, 164, 253, 92, 1995 204, 122, 218, 77, 105, 146] 1997 Appendix B. Acknowledgements 1999 Solutions for encrypting JSON content were also explored by JSON 2000 Simple Encryption [JSE] and JavaScript Message Security Format 2001 [I-D.rescorla-jsms], both of which significantly influenced this 2002 draft. This draft attempts to explicitly reuse as many of the 2003 relevant concepts from XML Encryption 1.1 2004 [W3C.CR-xmlenc-core1-20120313] and RFC 5652 [RFC5652] as possible, 2005 while utilizing simple compact JSON-based data structures. 2007 Special thanks are due to John Bradley and Nat Sakimura for the 2008 discussions that helped inform the content of this specification and 2009 to Eric Rescorla and Joe Hildebrand for allowing the reuse of text 2010 from [I-D.rescorla-jsms] in this document. 2012 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2013 Jay for validating the examples in this specification. 2015 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2016 Sean Turner and Stephen Farrell served as Security area directors 2017 during the creation of this specification. 2019 Appendix C. Open Issues 2021 [[ to be removed by the RFC editor before publication as an RFC ]] 2023 The following items remain to be considered or done in this draft: 2025 o Should we define optional nonce, timestamp, and/or uninterpreted 2026 string header parameter(s)? 2028 Appendix D. Document History 2030 [[ to be removed by the RFC editor before publication as an RFC ]] 2032 -06 2034 o Removed the "int" and "kdf" parameters and defined the new 2035 composite AEAD algorithms "A128CBC+HS256" and "A256CBC+HS512" to 2036 replace the former uses of AES CBC, which required the use of 2037 separate integrity and key derivation functions. 2039 o Included additional values in the Concat KDF calculation -- the 2040 desired output size and the algorithm value, and optionally 2041 PartyUInfo and PartyVInfo values. Added the optional header 2042 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2043 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2044 PartyVInfo). Updated the KDF examples accordingly. 2046 o Promoted Initialization Vector from being a header parameter to 2047 being a top-level JWE element. This saves approximately 16 bytes 2048 in the compact serialization, which is a significant savings for 2049 some use cases. Promoting the Initialization Vector out of the 2050 header also avoids repeating this shared value in the JSON 2051 serialization. 2053 o Changed "x5c" (X.509 Certificate Chain) representation from being 2054 a single string to being an array of strings, each containing a 2055 single base64 encoded DER certificate value, representing elements 2056 of the certificate chain. 2058 o Added an AES Key Wrap example. 2060 o Reordered the encryption steps so CMK creation is first, when 2061 required. 2063 o Correct statements in examples about which algorithms produce 2064 reproducible results. 2066 -05 2068 o Support both direct encryption using a shared or agreed upon 2069 symmetric key, and the use of a shared or agreed upon symmetric 2070 key to key wrap the CMK. 2072 o Added statement that "StringOrURI values are compared as case- 2073 sensitive strings with no transformations or canonicalizations 2074 applied". 2076 o Updated open issues. 2078 o Indented artwork elements to better distinguish them from the body 2079 text. 2081 -04 2083 o Refer to the registries as the primary sources of defined values 2084 and then secondarily reference the sections defining the initial 2085 contents of the registries. 2087 o Normatively reference XML Encryption 1.1 2088 [W3C.CR-xmlenc-core1-20120313] for its security considerations. 2090 o Reference draft-jones-jose-jwe-json-serialization instead of 2091 draft-jones-json-web-encryption-json-serialization. 2093 o Described additional open issues. 2095 o Applied editorial suggestions. 2097 -03 2099 o Added the "kdf" (key derivation function) header parameter to 2100 provide crypto agility for key derivation. The default KDF 2101 remains the Concat KDF with the SHA-256 digest function. 2103 o Reordered encryption steps so that the Encoded JWE Header is 2104 always created before it is needed as an input to the AEAD 2105 "additional authenticated data" parameter. 2107 o Added the "cty" (content type) header parameter for declaring type 2108 information about the secured content, as opposed to the "typ" 2109 (type) header parameter, which declares type information about 2110 this object. 2112 o Moved description of how to determine whether a header is for a 2113 JWS or a JWE from the JWT spec to the JWE spec. 2115 o Added complete encryption examples for both AEAD and non-AEAD 2116 algorithms. 2118 o Added complete key derivation examples. 2120 o Added "Collision Resistant Namespace" to the terminology section. 2122 o Reference ITU.X690.1994 for DER encoding. 2124 o Added Registry Contents sections to populate registry values. 2126 o Numerous editorial improvements. 2128 -02 2130 o When using AEAD algorithms (such as AES GCM), use the "additional 2131 authenticated data" parameter to provide integrity for the header, 2132 encrypted key, and ciphertext and use the resulting 2133 "authentication tag" value as the JWE Integrity Value. 2135 o Defined KDF output key sizes. 2137 o Generalized text to allow key agreement to be employed as an 2138 alternative to key wrapping or key encryption. 2140 o Changed compression algorithm from gzip to DEFLATE. 2142 o Clarified that it is an error when a "kid" value is included and 2143 no matching key is found. 2145 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2146 rejected. 2148 o Clarified the relationship between "typ" header parameter values 2149 and MIME types. 2151 o Registered application/jwe MIME type and "JWE" typ header 2152 parameter value. 2154 o Simplified JWK terminology to get replace the "JWK Key Object" and 2155 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2156 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2157 between single keys and sets of keys. As part of this change, the 2158 header parameter name for a public key value was changed from 2159 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2161 o Added suggestion on defining additional header parameters such as 2162 "x5t#S256" in the future for certificate thumbprints using hash 2163 algorithms other than SHA-1. 2165 o Specify RFC 2818 server identity validation, rather than RFC 6125 2166 (paralleling the same decision in the OAuth specs). 2168 o Generalized language to refer to Message Authentication Codes 2169 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2170 unless in a context specific to HMAC algorithms. 2172 o Reformatted to give each header parameter its own section heading. 2174 -01 2176 o Added an integrity check for non-AEAD algorithms. 2178 o Added "jpk" and "x5c" header parameters for including JWK public 2179 keys and X.509 certificate chains directly in the header. 2181 o Clarified that this specification is defining the JWE Compact 2182 Serialization. Referenced the new JWE-JS spec, which defines the 2183 JWE JSON Serialization. 2185 o Added text "New header parameters should be introduced sparingly 2186 since an implementation that does not understand a parameter MUST 2187 reject the JWE". 2189 o Clarified that the order of the encryption and decryption steps is 2190 not significant in cases where there are no dependencies between 2191 the inputs and outputs of the steps. 2193 o Made other editorial improvements suggested by JOSE working group 2194 participants. 2196 -00 2198 o Created the initial IETF draft based upon 2199 draft-jones-json-web-encryption-02 with no normative changes. 2201 o Changed terminology to no longer call both digital signatures and 2202 HMACs "signatures". 2204 Authors' Addresses 2206 Michael B. Jones 2207 Microsoft 2209 Email: mbj@microsoft.com 2210 URI: http://self-issued.info/ 2212 Eric Rescorla 2213 RTFM, Inc. 2215 Email: ekr@rtfm.com 2216 Joe Hildebrand 2217 Cisco Systems, Inc. 2219 Email: jhildebr@cisco.com