idnits 2.17.1 draft-ietf-jose-json-web-encryption-14.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 == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The "crit" (critical) header parameter indicates that extensions to [[ this specification ]] are being used that MUST be understood and processed. Its value is an array listing the header parameter names defined by those extensions that are used in the JWE Header. If any of the listed extension header parameters are not understood and supported by the receiver, it MUST reject the JWE. Senders MUST NOT include header parameter names defined by [[ this specification ]] or by [JWA] for use with JWE, duplicate names, or names that do not occur as header parameter names within the JWE Header in the "crit" list. Senders MUST not use the empty list "[]" as the "crit" value. Recipients MAY reject the JWE if the critical list contains any header parameter names defined by [[ this specification ]] or by [JWA] for use with JWE, or any other constraints on its use are violated. This header parameter MUST be integrity protected, and therefore MUST occur only with the JWE Protected Header, when used. Use of this header parameter is OPTIONAL. This header parameter MUST be understood by implementations. -- The document date (July 29, 2013) is 3923 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '227' on line 1399 -- Looks like a reference, but probably isn't: '197' on line 1399 -- Looks like a reference, but probably isn't: '117' on line 1399 -- Looks like a reference, but probably isn't: '252' on line 1399 -- Looks like a reference, but probably isn't: '2' on line 1399 -- Looks like a reference, but probably isn't: '219' on line 1399 -- Looks like a reference, but probably isn't: '233' on line 1399 -- Looks like a reference, but probably isn't: '68' on line 1399 -- Looks like a reference, but probably isn't: '180' on line 1399 -- Looks like a reference, but probably isn't: '225' on line 1399 -- Looks like a reference, but probably isn't: '77' on line 1399 -- Looks like a reference, but probably isn't: '0' on line 2018 -- Looks like a reference, but probably isn't: '1' on line 2018 -- Looks like a reference, but probably isn't: '152' on line 2018 -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMAScript' -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X690.1994' ** 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 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) == Outdated reference: A later version (-05) exists of draft-mcgrew-aead-aes-cbc-hmac-sha2-01 Summary: 5 errors (**), 0 flaws (~~), 3 warnings (==), 18 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track E. Rescorla 5 Expires: January 30, 2014 RTFM 6 J. Hildebrand 7 Cisco 8 July 29, 2013 10 JSON Web Encryption (JWE) 11 draft-ietf-jose-json-web-encryption-14 13 Abstract 15 JSON Web Encryption (JWE) is a means of representing encrypted 16 content using JavaScript Object Notation (JSON) based data 17 structures. Cryptographic algorithms and identifiers for use with 18 this specification are described in the separate JSON Web Algorithms 19 (JWA) specification. Related digital signature and MAC capabilities 20 are described in the separate JSON Web Signature (JWS) specification. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on January 30, 2014. 39 Copyright Notice 41 Copyright (c) 2013 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 . . . . . . . . . . . . . . 8 60 3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 9 61 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10 62 4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 11 63 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 11 64 4.1.2. "enc" (Encryption Method) Header Parameter . . . . . . 12 65 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 12 66 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 12 67 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 12 68 4.1.6. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 13 69 4.1.7. "x5t" (X.509 Certificate Thumbprint) Header 70 Parameter . . . . . . . . . . . . . . . . . . . . . . 13 71 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 13 72 4.1.9. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14 73 4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 14 74 4.1.11. "cty" (Content Type) Header Parameter . . . . . . . . 14 75 4.1.12. "crit" (Critical) Header Parameter . . . . . . . . . . 15 76 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15 77 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 16 78 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 16 79 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 16 80 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 18 81 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20 82 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20 83 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 20 84 7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 21 85 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21 86 8. Distinguishing Between JWS and JWE Objects . . . . . . . . . . 24 87 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 88 9.1. Registration of JWE Header Parameter Names . . . . . . . . 24 89 9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25 90 10. Security Considerations . . . . . . . . . . . . . . . . . . . 26 91 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 92 11.1. Normative References . . . . . . . . . . . . . . . . . . . 26 93 11.2. Informative References . . . . . . . . . . . . . . . . . . 28 94 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 29 95 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 29 96 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 29 97 A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 29 98 A.1.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 29 99 A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 30 100 A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 30 101 A.1.6. Initialization Vector . . . . . . . . . . . . . . . . 31 102 A.1.7. Additional Authenticated Data . . . . . . . . . . . . 31 103 A.1.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 31 104 A.1.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 32 105 A.1.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 32 106 A.1.11. Complete Representation . . . . . . . . . . . . . . . 32 107 A.1.12. Validation . . . . . . . . . . . . . . . . . . . . . . 32 108 A.2. Example JWE using RSAES-PKCS1-V1_5 and 109 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 33 110 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 33 111 A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 33 112 A.2.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 33 113 A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 33 114 A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 34 115 A.2.6. Initialization Vector . . . . . . . . . . . . . . . . 35 116 A.2.7. Additional Authenticated Data . . . . . . . . . . . . 35 117 A.2.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 35 118 A.2.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 35 119 A.2.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 36 120 A.2.11. Complete Representation . . . . . . . . . . . . . . . 36 121 A.2.12. Validation . . . . . . . . . . . . . . . . . . . . . . 36 122 A.3. Example JWE using AES Key Wrap and 123 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 36 124 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 37 125 A.3.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 37 126 A.3.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 37 127 A.3.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 37 128 A.3.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 38 129 A.3.6. Initialization Vector . . . . . . . . . . . . . . . . 38 130 A.3.7. Additional Authenticated Data . . . . . . . . . . . . 38 131 A.3.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 38 132 A.3.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 39 133 A.3.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 39 134 A.3.11. Complete Representation . . . . . . . . . . . . . . . 39 135 A.3.12. Validation . . . . . . . . . . . . . . . . . . . . . . 39 136 A.4. Example JWE Using JWE JSON Serialization . . . . . . . . . 39 137 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 40 138 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 40 139 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 40 140 A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 41 141 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 41 142 A.4.6. Plaintext Encryption . . . . . . . . . . . . . . . . . 41 143 A.4.7. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 41 144 A.4.8. Encoded JWE Authentication Tag . . . . . . . . . . . . 42 145 A.4.9. Complete JWE JSON Serialization Representation . . . . 42 146 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 42 147 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 43 148 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 43 149 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 43 150 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 44 151 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 44 152 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 44 153 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 44 154 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 45 155 Appendix D. Document History . . . . . . . . . . . . . . . . . . 45 156 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 52 158 1. Introduction 160 JSON Web Encryption (JWE) is a means of representing encrypted 161 content using JavaScript Object Notation (JSON) [RFC4627] based data 162 structures. The JWE cryptographic mechanisms encrypt and provide 163 integrity protection for arbitrary sequences of octets. 165 Two closely related representations for JWE objects are defined. The 166 JWE Compact Serialization is a compact, URL-safe representation 167 intended for space constrained environments such as HTTP 168 Authorization headers and URI query parameters. The JWE JSON 169 Serialization represents JWE objects as JSON objects and enables the 170 same content to be encrypted to multiple parties. Both share the 171 same cryptographic underpinnings. 173 Cryptographic algorithms and identifiers for use with this 174 specification are described in the separate JSON Web Algorithms (JWA) 175 [JWA] specification. Related digital signature and MAC capabilities 176 are described in the separate JSON Web Signature (JWS) [JWS] 177 specification. 179 1.1. Notational Conventions 181 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 182 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 183 document are to be interpreted as described in Key words for use in 184 RFCs to Indicate Requirement Levels [RFC2119]. 186 2. Terminology 188 JSON Web Encryption (JWE) A data structure representing an encrypted 189 message. The structure represents five values: the JWE Header, 190 the JWE Encrypted Key, the JWE Initialization Vector, the JWE 191 Ciphertext, and the JWE Authentication Tag. 193 Authenticated Encryption with Associated Data (AEAD) An AEAD 194 algorithm is one that encrypts the Plaintext, allows Additional 195 Authenticated Data to be specified, and provides an integrated 196 content integrity check over the Ciphertext and Additional 197 Authenticated Data. AEAD algorithms accept two inputs, the 198 Plaintext and the Additional Authenticated Data value, and produce 199 two outputs, the Ciphertext and the Authentication Tag value. AES 200 Galois/Counter Mode (GCM) is one such algorithm. 202 Plaintext The sequence of octets to be encrypted -- a.k.a., the 203 message. The plaintext can contain an arbitrary sequence of 204 octets. 206 Ciphertext An encrypted representation of the Plaintext. 208 Additional Authenticated Data (AAD) An input to an AEAD operation 209 that is integrity protected but not encrypted. 211 Authentication Tag An output of an AEAD operation that ensures the 212 integrity of the Ciphertext and the Additional Authenticated Data. 213 Note that some algorithms may not use an Authentication Tag, in 214 which case this value is the empty octet sequence. 216 Content Encryption Key (CEK) A symmetric key for the AEAD algorithm 217 used to encrypt the Plaintext for the recipient to produce the 218 Ciphertext and the Authentication Tag. 220 JSON Text Object A UTF-8 [RFC3629] encoded text string representing 221 a JSON object; the syntax of JSON objects is defined in Section 222 2.2 of [RFC4627]. 224 JWE Header A JSON Text Object (or JSON Text Objects, when using the 225 JWE JSON Serialization) that describes the encryption operations 226 applied to create the JWE Encrypted Key, the JWE Ciphertext, and 227 the JWE Authentication Tag. The members of the JWE Header 228 object(s) are Header Parameters. 230 JWE Encrypted Key The result of encrypting the Content Encryption 231 Key (CEK) with the intended recipient's key using the specified 232 algorithm. Note that for some algorithms, the JWE Encrypted Key 233 value is specified as being the empty octet sequence. 235 JWE Initialization Vector A sequence of octets containing the 236 Initialization Vector used when encrypting the Plaintext. Note 237 that some algorithms may not use an Initialization Vector, in 238 which case this value is the empty octet sequence. 240 JWE Ciphertext A sequence of octets containing the Ciphertext for a 241 JWE. 243 JWE Authentication Tag A sequence of octets containing the 244 Authentication Tag for a JWE. 246 JWE Protected Header A JSON Text Object that contains the portion of 247 the JWE Header that is integrity protected. For the JWE Compact 248 Serialization, this comprises the entire JWE Header. For the JWE 249 JSON Serialization, this is one component of the JWE Header. 251 Header Parameter A name/value pair that is member of the JWE Header. 253 Header Parameter Name The name of a member of the JWE Header. 255 Header Parameter Value The value of a member of the JWE Header. 257 Base64url Encoding The URL- and filename-safe Base64 encoding 258 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 259 safe) '=' padding characters omitted, as permitted by Section 3.2. 260 (See Appendix C of [JWS] for notes on implementing base64url 261 encoding without padding.) 263 Encoded JWE Header Base64url encoding of the JWE Protected Header. 265 Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted 266 Key. 268 Encoded JWE Initialization Vector Base64url encoding of the JWE 269 Initialization Vector. 271 Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. 273 Encoded JWE Authentication Tag Base64url encoding of the JWE 274 Authentication Tag. 276 JWE Compact Serialization A representation of the JWE as the 277 concatenation of the Encoded JWE Header, the Encoded JWE Encrypted 278 Key, the Encoded JWE Initialization Vector, the Encoded JWE 279 Ciphertext, and the Encoded JWE Authentication Tag in that order, 280 with the five strings being separated by four period ('.') 281 characters. This representation is compact and URL-safe. 283 JWE JSON Serialization A representation of the JWE as a JSON 284 structure containing JWE Header, Encoded JWE Encrypted Key, 285 Encoded JWE Initialization Vector, Encoded JWE Ciphertext, and 286 Encoded JWE Authentication Tag values. Unlike the JWE Compact 287 Serialization, the JWE JSON Serialization enables the same content 288 to be encrypted to multiple parties. This representation is 289 neither compact nor URL-safe. 291 Collision Resistant Namespace A namespace that allows names to be 292 allocated in a manner such that they are highly unlikely to 293 collide with other names. For instance, collision resistance can 294 be achieved through administrative delegation of portions of the 295 namespace or through use of collision-resistant name allocation 296 functions. Examples of Collision Resistant Namespaces include: 297 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 298 X.660 and X.670 Recommendation series, and Universally Unique 299 IDentifiers (UUIDs) [RFC4122]. When using an administratively 300 delegated namespace, the definer of a name needs to take 301 reasonable precautions to ensure they are in control of the 302 portion of the namespace they use to define the name. 304 StringOrURI A JSON string value, with the additional requirement 305 that while arbitrary string values MAY be used, any value 306 containing a ":" character MUST be a URI [RFC3986]. StringOrURI 307 values are compared as case-sensitive strings with no 308 transformations or canonicalizations applied. 310 Key Management Mode A method of determining the Content Encryption 311 Key (CEK) value to use. Each algorithm used for determining the 312 CEK value uses a specific Key Management Mode. Key Management 313 Modes employed by this specification are Key Encryption, Key 314 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 315 and Direct Encryption. 317 Key Encryption A Key Management Mode in which the Content Encryption 318 Key (CEK) value is encrypted to the intended recipient using an 319 asymmetric encryption algorithm. 321 Key Wrapping A Key Management Mode in which the Content Encryption 322 Key (CEK) value is encrypted to the intended recipient using a 323 symmetric key wrapping algorithm. 325 Direct Key Agreement A Key Management Mode in which a key agreement 326 algorithm is used to agree upon the Content Encryption Key (CEK) 327 value. 329 Key Agreement with Key Wrapping A Key Management Mode in which a key 330 agreement algorithm is used to agree upon a symmetric key used to 331 encrypt the Content Encryption Key (CEK) value to the intended 332 recipient using a symmetric key wrapping algorithm. 334 Direct Encryption A Key Management Mode in which the Content 335 Encryption Key (CEK) value used is the secret symmetric key value 336 shared between the parties. 338 3. JSON Web Encryption (JWE) Overview 340 JWE represents encrypted content using JSON data structures and 341 base64url encoding. Five values are represented in a JWE: the JWE 342 Header, the JWE Encrypted Key, the JWE Initialization Vector, the JWE 343 Ciphertext, and the JWE Authentication Tag. In the Compact 344 Serialization, the five values are base64url-encoded for 345 transmission, and represented as the concatenation of the encoded 346 strings in that order, with the five strings being separated by four 347 period ('.') characters. A JSON Serialization for this information 348 is also defined in Section 7.2. 350 JWE utilizes authenticated encryption to ensure the confidentiality 351 and integrity of the Plaintext and the integrity of the JWE Protected 352 Header. 354 3.1. Example JWE 356 This example encrypts the plaintext "The true sign of intelligence is 357 not knowledge but imagination." to the recipient using RSAES OAEP for 358 key encryption and AES GCM for content encryption. 360 The following example JWE Header declares that: 362 o the Content Encryption Key is encrypted to the recipient using the 363 RSAES OAEP algorithm to produce the JWE Encrypted Key and 365 o the Plaintext is encrypted using the AES GCM algorithm with a 256 366 bit key to produce the Ciphertext. 368 {"alg":"RSA-OAEP","enc":"A256GCM"} 370 Base64url encoding the octets of the UTF-8 representation of the JWE 371 Header yields this Encoded JWE Header value: 373 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 375 The remaining steps to finish creating this JWE are: 377 o Generate a random Content Encryption Key (CEK). 379 o Encrypt the CEK with the recipient's public key using the RSAES 380 OAEP algorithm to produce the JWE Encrypted Key. 382 o Base64url encode the JWE Encrypted Key to produce the Encoded JWE 383 Encrypted Key. 385 o Generate a random JWE Initialization Vector. 387 o Base64url encode the JWE Initialization Vector to produce the 388 Encoded JWE Initialization Vector. 390 o Let the Additional Authenticated Data encryption parameter be the 391 octets of the ASCII representation of the Encoded JWE Header 392 value. 394 o Encrypt the Plaintext with AES GCM using the CEK as the encryption 395 key, the JWE Initialization Vector, and the Additional 396 Authenticated Data value, requesting a 128 bit Authentication Tag 397 output. 399 o Base64url encode the Ciphertext to create the Encoded JWE 400 Ciphertext. 402 o Base64url encode the Authentication Tag to create the Encoded JWE 403 Authentication Tag. 405 o Assemble the final representation: The Compact Serialization of 406 this result is the concatenation of the Encoded JWE Header, the 407 Encoded JWE Encrypted Key, the Encoded JWE Initialization Vector, 408 the Encoded JWE Ciphertext, and the Encoded JWE Authentication Tag 409 in that order, with the five strings being separated by four 410 period ('.') characters. 412 The final result in this example (with line breaks for display 413 purposes only) is: 415 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 416 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 417 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 418 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 419 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 420 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 421 6UklfCpIMfIjf7iGdXKHzg. 422 48V1_ALb6US04U3b. 423 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 424 SdiwkIr3ajwQzaBtQD_A. 425 XFBoMYUZodetZdvTiFvSkQ 427 See Appendix A.1 for the complete details of computing this JWE. See 428 Appendix A for additional examples. 430 4. JWE Header 432 The members of the JSON object(s) representing the JWE Header 433 describe the encryption applied to the Plaintext and optionally 434 additional properties of the JWE. The Header Parameter Names within 435 the JWE Header MUST be unique; recipients MUST either reject JWEs 436 with duplicate Header Parameter Names or use a JSON parser that 437 returns only the lexically last duplicate member name, as specified 438 in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. 440 Implementations are required to understand the specific header 441 parameters defined by this specification that are designated as "MUST 442 be understood" and process them in the manner defined in this 443 specification. All other header parameters defined by this 444 specification that are not so designated MUST be ignored when not 445 understood. Unless listed as a critical header parameter, per 446 Section 4.1.12, all header parameters not defined by this 447 specification MUST be ignored when not understood. 449 There are three classes of Header Parameter Names: Reserved Header 450 Parameter Names, Public Header Parameter Names, and Private Header 451 Parameter Names. 453 4.1. Reserved Header Parameter Names 455 The following Header Parameter Names are reserved with meanings as 456 defined below. All the names are short because a core goal of this 457 specification is for the resulting representations using the JWE 458 Compact Serialization to be compact. 460 Additional reserved Header Parameter Names can be defined via the 461 IANA JSON Web Signature and Encryption Header Parameters registry 462 [JWS]. As indicated by the common registry, JWSs and JWEs share a 463 common header parameter space; when a parameter is used by both 464 specifications, its usage must be compatible between the 465 specifications. 467 4.1.1. "alg" (Algorithm) Header Parameter 469 The "alg" (algorithm) header parameter identifies a cryptographic 470 algorithm used to encrypt or determine the value of the Content 471 Encryption Key (CEK). The recipient MUST reject the JWE if the "alg" 472 value does not represent a supported algorithm, or if the recipient 473 does not have a key that can be used with that algorithm. "alg" 474 values SHOULD either be registered in the IANA JSON Web Signature and 475 Encryption Algorithms registry [JWA] or be a value that contains a 476 Collision Resistant Namespace. The "alg" value is a case sensitive 477 string containing a StringOrURI value. Use of this header parameter 478 is REQUIRED. This header parameter MUST be understood by 479 implementations. 481 A list of defined "alg" values can be found in the IANA JSON Web 482 Signature and Encryption Algorithms registry [JWA]; the initial 483 contents of this registry are the values defined in Section 4.1 of 484 the JSON Web Algorithms (JWA) [JWA] specification. 486 4.1.2. "enc" (Encryption Method) Header Parameter 488 The "enc" (encryption method) header parameter identifies the content 489 encryption algorithm used to encrypt the Plaintext to produce the 490 Ciphertext. This algorithm MUST be an AEAD algorithm with a 491 specified key length. The recipient MUST reject the JWE if the "enc" 492 value does not represent a supported algorithm. "enc" values SHOULD 493 either be registered in the IANA JSON Web Signature and Encryption 494 Algorithms registry [JWA] or be a value that contains a Collision 495 Resistant Namespace. The "enc" value is a case sensitive string 496 containing a StringOrURI value. Use of this header parameter is 497 REQUIRED. This header parameter MUST be understood by 498 implementations. 500 A list of defined "enc" values can be found in the IANA JSON Web 501 Signature and Encryption Algorithms registry [JWA]; the initial 502 contents of this registry are the values defined in Section 4.2 of 503 the JSON Web Algorithms (JWA) [JWA] specification. 505 4.1.3. "zip" (Compression Algorithm) Header Parameter 507 The "zip" (compression algorithm) applied to the Plaintext before 508 encryption, if any. If present, the value of the "zip" header 509 parameter MUST be the case sensitive string "DEF". Compression is 510 performed with the DEFLATE [RFC1951] algorithm. If no "zip" 511 parameter is present, no compression is applied to the Plaintext 512 before encryption. This header parameter MUST be integrity 513 protected, and therefore MUST occur only with the JWE Protected 514 Header, when used. Use of this header parameter is OPTIONAL. This 515 header parameter MUST be understood by implementations. 517 4.1.4. "jku" (JWK Set URL) Header Parameter 519 The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that 520 refers to a resource for a set of JSON-encoded public keys, one of 521 which is the key to which the JWE was encrypted; this can be used to 522 determine the private key needed to decrypt the JWE. The keys MUST 523 be encoded as a JSON Web Key Set (JWK Set) [JWK]. The protocol used 524 to acquire the resource MUST provide integrity protection; an HTTP 525 GET request to retrieve the JWK Set MUST use TLS [RFC2818] [RFC5246]; 526 the identity of the server MUST be validated, as per Section 3.1 of 527 HTTP Over TLS [RFC2818]. Use of this header parameter is OPTIONAL. 529 4.1.5. "jwk" (JSON Web Key) Header Parameter 531 The "jwk" (JSON Web Key) header parameter is the public key to which 532 the JWE was encrypted; this can be used to determine the private key 533 needed to decrypt the JWE. This key is represented as a JSON Web Key 535 [JWK]. Use of this header parameter is OPTIONAL. 537 4.1.6. "x5u" (X.509 URL) Header Parameter 539 The "x5u" (X.509 URL) header parameter is a URI [RFC3986] that refers 540 to a resource for the X.509 public key certificate or certificate 541 chain [RFC5280] containing the key to which the JWE was encrypted; 542 this can be used to determine the private key needed to decrypt the 543 JWE. The identified resource MUST provide a representation of the 544 certificate or certificate chain that conforms to RFC 5280 [RFC5280] 545 in PEM encoded form [RFC1421]. The certificate containing the public 546 key to which the JWE was encrypted MUST be the first certificate. 547 This MAY be followed by additional certificates, with each subsequent 548 certificate being the one used to certify the previous one. The 549 protocol used to acquire the resource MUST provide integrity 550 protection; an HTTP GET request to retrieve the certificate MUST use 551 TLS [RFC2818] [RFC5246]; the identity of the server MUST be 552 validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. Use of 553 this header parameter is OPTIONAL. 555 4.1.7. "x5t" (X.509 Certificate Thumbprint) Header Parameter 557 The "x5t" (X.509 Certificate Thumbprint) header parameter is a 558 base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER 559 encoding of the X.509 certificate [RFC5280] containing the key to 560 which the JWE was encrypted; this can be used to determine the 561 private key needed to decrypt the JWE. Use of this header parameter 562 is OPTIONAL. 564 If, in the future, certificate thumbprints need to be computed using 565 hash functions other than SHA-1, it is suggested that additional 566 related header parameters be defined for that purpose. For example, 567 it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint 568 using SHA-256) header parameter could be defined by registering it in 569 the IANA JSON Web Signature and Encryption Header Parameters registry 570 [JWS]. 572 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 574 The "x5c" (X.509 Certificate Chain) header parameter contains the 575 X.509 public key certificate or certificate chain [RFC5280] 576 containing the key to which the JWE was encrypted; this can be used 577 to determine the private key needed to decrypt the JWE. The 578 certificate or certificate chain is represented as a JSON array of 579 certificate value strings. Each string in the array is a base64 580 encoded ([RFC4648] Section 4 -- not base64url encoded) DER 581 [ITU.X690.1994] PKIX certificate value. The certificate containing 582 the public key to which the JWE was encrypted MUST be the first 583 certificate. This MAY be followed by additional certificates, with 584 each subsequent certificate being the one used to certify the 585 previous one. Use of this header parameter is OPTIONAL. 587 See Appendix B of [JWS] for an example "x5c" value. 589 4.1.9. "kid" (Key ID) Header Parameter 591 The "kid" (key ID) header parameter is a hint indicating which key to 592 which the JWE was encrypted; this can be used to determine the 593 private key needed to decrypt the JWE. This parameter allows 594 originators to explicitly signal a change of key to recipients. 595 Should the recipient be unable to locate a key corresponding to the 596 "kid" value, they SHOULD treat that condition as an error. The 597 interpretation of the "kid" value is unspecified. Its value MUST be 598 a string. Use of this header parameter is OPTIONAL. 600 When used with a JWK, the "kid" value can be used to match a JWK 601 "kid" parameter value. 603 4.1.10. "typ" (Type) Header Parameter 605 The "typ" (type) header parameter MAY be used to declare the type of 606 this complete JWE object in an application-specific manner in 607 contexts where this is useful to the application. This parameter has 608 no effect upon the JWE processing. The type value "JOSE" MAY be used 609 by applications to indicate that this object is a JWS or JWE using 610 the JWS Compact Serialization or the JWE Compact Serialization. The 611 type value "JOSE+JSON" MAY be used by applications to indicate that 612 this object is a JWS or JWE using the JWS JSON Serialization or the 613 JWE JSON Serialization. Other type values MAY be used, and if not 614 understood, SHOULD be ignored. The "typ" value is a case sensitive 615 string. Use of this header parameter is OPTIONAL. 617 MIME Media Type [RFC2046] values MAY be used as "typ" values. 619 "typ" values SHOULD either be registered in the IANA JSON Web 620 Signature and Encryption Type Values registry [JWS] or be a value 621 that contains a Collision Resistant Namespace. 623 4.1.11. "cty" (Content Type) Header Parameter 625 The "cty" (content type) header parameter MAY be used to declare the 626 type of the encrypted content (the Plaintext) in an application- 627 specific manner in contexts where this is useful to the application. 628 This parameter has no effect upon the JWE processing. Content type 629 values that are not understood SHOULD be ignored. The "cty" value is 630 a case sensitive string. Use of this header parameter is OPTIONAL. 632 The values used for the "cty" header parameter come from the same 633 value space as the "typ" header parameter, with the same rules 634 applying. 636 4.1.12. "crit" (Critical) Header Parameter 638 The "crit" (critical) header parameter indicates that extensions to 639 [[ this specification ]] are being used that MUST be understood and 640 processed. Its value is an array listing the header parameter names 641 defined by those extensions that are used in the JWE Header. If any 642 of the listed extension header parameters are not understood and 643 supported by the receiver, it MUST reject the JWE. Senders MUST NOT 644 include header parameter names defined by [[ this specification ]] or 645 by [JWA] for use with JWE, duplicate names, or names that do not 646 occur as header parameter names within the JWE Header in the "crit" 647 list. Senders MUST not use the empty list "[]" as the "crit" value. 648 Recipients MAY reject the JWE if the critical list contains any 649 header parameter names defined by [[ this specification ]] or by 650 [JWA] for use with JWE, or any other constraints on its use are 651 violated. This header parameter MUST be integrity protected, and 652 therefore MUST occur only with the JWE Protected Header, when used. 653 Use of this header parameter is OPTIONAL. This header parameter MUST 654 be understood by implementations. 656 An example use, along with a hypothetical "exp" (expiration-time) 657 field is: 659 {"alg":"RSA-OAEP", 660 "enc":"A256GCM", 661 "crit":["exp"], 662 "exp":1363284000 663 } 665 4.2. Public Header Parameter Names 667 Additional Header Parameter Names can be defined by those using JWEs. 668 However, in order to prevent collisions, any new Header Parameter 669 Name SHOULD either be registered in the IANA JSON Web Signature and 670 Encryption Header Parameters registry [JWS] or be a Public Name: a 671 value that contains a Collision Resistant Namespace. In each case, 672 the definer of the name or value needs to take reasonable precautions 673 to make sure they are in control of the part of the namespace they 674 use to define the Header Parameter Name. 676 New header parameters should be introduced sparingly, as they can 677 result in non-interoperable JWEs. 679 4.3. Private Header Parameter Names 681 A producer and consumer of a JWE may agree to use Header Parameter 682 Names that are Private Names: names that are not Reserved Names 683 Section 4.1 or Public Names Section 4.2. Unlike Public Names, 684 Private Names are subject to collision and should be used with 685 caution. 687 5. Producing and Consuming JWEs 689 5.1. Message Encryption 691 The message encryption process is as follows. The order of the steps 692 is not significant in cases where there are no dependencies between 693 the inputs and outputs of the steps. 695 1. Determine the Key Management Mode employed by the algorithm used 696 to determine the Content Encryption Key (CEK) value. (This is 697 the algorithm recorded in the "alg" (algorithm) header parameter 698 of the resulting JWE.) 700 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 701 Wrapping are employed, generate a random Content Encryption Key 702 (CEK) value. See RFC 4086 [RFC4086] for considerations on 703 generating random values. The CEK MUST have a length equal to 704 that required for the content encryption algorithm. 706 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 707 employed, use the key agreement algorithm to compute the value 708 of the agreed upon key. When Direct Key Agreement is employed, 709 let the Content Encryption Key (CEK) be the agreed upon key. 710 When Key Agreement with Key Wrapping is employed, the agreed 711 upon key will be used to wrap the CEK. 713 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 714 Wrapping are employed, encrypt the CEK to the recipient and let 715 the result be the JWE Encrypted Key. 717 5. Otherwise, when Direct Key Agreement or Direct Encryption are 718 employed, let the JWE Encrypted Key be the empty octet sequence. 720 6. When Direct Encryption is employed, let the Content Encryption 721 Key (CEK) be the shared symmetric key. 723 7. Base64url encode the JWE Encrypted Key to create the Encoded JWE 724 Encrypted Key. 726 8. If the JWE JSON Serialization is being used, repeat this process 727 for each recipient. 729 9. Generate a random JWE Initialization Vector of the correct size 730 for the content encryption algorithm (if required for the 731 algorithm); otherwise, let the JWE Initialization Vector be the 732 empty octet sequence. 734 10. Base64url encode the JWE Initialization Vector to create the 735 Encoded JWE Initialization Vector. 737 11. Compress the Plaintext if a "zip" parameter was included. 739 12. Serialize the (compressed) Plaintext into an octet sequence M. 741 13. Create a JWE Header containing the encryption parameters used. 742 Note that white space is explicitly allowed in the 743 representation and no canonicalization need be performed before 744 encoding. 746 14. Base64url encode the octets of the UTF-8 representation of the 747 JWE Protected Header to create the Encoded JWE Header. If the 748 JWE Protected Header is not present (which can only happen when 749 using the JWE JSON Serialization and no "protected" member is 750 present), let the Encoded JWE Header be the empty string. 752 15. Let the Additional Authenticated Data encryption parameter be 753 the octets of the ASCII representation of the Encoded JWE Header 754 value. 756 16. Encrypt M using the CEK, the JWE Initialization Vector, and the 757 Additional Authenticated Data value using the specified content 758 encryption algorithm to create the JWE Ciphertext value and the 759 JWE Authentication Tag (which is the Authentication Tag output 760 from the encryption operation). 762 17. Base64url encode the JWE Ciphertext to create the Encoded JWE 763 Ciphertext. 765 18. Base64url encode the JWE Authentication Tag to create the 766 Encoded JWE Authentication Tag. 768 19. The five encoded parts are result values used in both the JWE 769 Compact Serialization and the JWE JSON Serialization 770 representations. 772 20. Create the desired serialized output. The JWE Compact 773 Serialization of this result is the concatenation of the Encoded 774 JWE Header, the Encoded JWE Encrypted Key, the Encoded JWE 775 Initialization Vector, the Encoded JWE Ciphertext, and the 776 Encoded JWE Authentication Tag in that order, with the five 777 strings being separated by four period ('.') characters. The 778 JWE JSON Serialization is described in Section 7.2. 780 5.2. Message Decryption 782 The message decryption process is the reverse of the encryption 783 process. The order of the steps is not significant in cases where 784 there are no dependencies between the inputs and outputs of the 785 steps. If any of these steps fails, the JWE MUST be rejected. 787 1. Parse the serialized input to determine the values of the JWE 788 Header, the Encoded JWE Encrypted Key, the Encoded JWE 789 Initialization Vector, the Encoded JWE Ciphertext, and the 790 Encoded JWE Authentication Tag. When using the JWE Compact 791 Serialization, the Encoded JWE Header, the Encoded JWE Encrypted 792 Key, the Encoded JWE Initialization Vector, the Encoded JWE 793 Ciphertext, and the Encoded JWE Authentication Tag are 794 represented as text strings in that order, separated by four 795 period ('.') characters. The JWE JSON Serialization is 796 described in Section 7.2. 798 2. The Encoded JWE Header, the Encoded JWE Encrypted Key, the 799 Encoded JWE Initialization Vector, the Encoded JWE Ciphertext, 800 and the Encoded JWE Authentication Tag MUST be successfully 801 base64url decoded following the restriction that no padding 802 characters have been used. 804 3. The resulting JWE Protected Header MUST be a completely valid 805 JSON object conforming to RFC 4627 [RFC4627]. 807 4. If using the JWE Compact Serialization, let the JWE Header be 808 the JWE Protected Header; otherwise, when using the JWE JSON 809 Serialization, let the JWE Header be the union of the members of 810 the JWE Protected Header, the members of the "unprotected" 811 value, and the members of the corresponding "header" value, all 812 of which must be completely valid JSON objects. 814 5. The resulting JWE Header MUST NOT contain duplicate Header 815 Parameter Names. When using the JWE JSON Serialization, this 816 restriction includes that the same Header Parameter Name also 817 MUST NOT occur in distinct JSON Text Object values that together 818 comprise the JWE Header. 820 6. The resulting JWE Header MUST be validated to only include 821 parameters and values whose syntax and semantics are both 822 understood and supported or that are specified as being ignored 823 when not understood. 825 7. Determine the Key Management Mode employed by the algorithm 826 specified by the "alg" (algorithm) header parameter. 828 8. Verify that the JWE uses a key known to the recipient. 830 9. When Direct Key Agreement or Key Agreement with Key Wrapping are 831 employed, use the key agreement algorithm to compute the value 832 of the agreed upon key. When Direct Key Agreement is employed, 833 let the Content Encryption Key (CEK) be the agreed upon key. 834 When Key Agreement with Key Wrapping is employed, the agreed 835 upon key will be used to decrypt the JWE Encrypted Key. 837 10. When Key Wrapping, Key Encryption, or Key Agreement with Key 838 Wrapping are employed, decrypt the JWE Encrypted Key to produce 839 the Content Encryption Key (CEK). The CEK MUST have a length 840 equal to that required for the content encryption algorithm. 841 Note that when there are multiple recipients, each recipient 842 will only be able decrypt any JWE Encrypted Key values that were 843 encrypted to a key in that recipient's possession. It is 844 therefore normal to only be able to decrypt one of the per- 845 recipient JWE Encrypted Key values to obtain the CEK value. To 846 mitigate the attacks described in RFC 3218 [RFC3218], the 847 recipient MUST NOT distinguish between format, padding, and 848 length errors of encrypted keys. It is strongly recommended, in 849 the event of receiving an improperly formatted key, that the 850 receiver substitute a randomly generated CEK and proceed to the 851 next step, to mitigate timing attacks. 853 11. Otherwise, when Direct Key Agreement or Direct Encryption are 854 employed, verify that the JWE Encrypted Key value is empty octet 855 sequence. 857 12. When Direct Encryption is employed, let the Content Encryption 858 Key (CEK) be the shared symmetric key. 860 13. If the JWE JSON Serialization is being used, repeat this process 861 for each recipient contained in the representation until the CEK 862 value has been determined. 864 14. Let the Additional Authenticated Data encryption parameter be 865 the octets of the ASCII representation of the Encoded JWE Header 866 value. However if a top-level "aad" member is present when 867 using the JWE JSON Serialization, instead let the Additional 868 Authenticated Data encryption parameter be the octets of the 869 ASCII representation of the concatenation of the Encoded JWE 870 Header value, a period ('.') character, and the "aad" field 871 value. 873 15. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 874 Vector, the Additional Authenticated Data value, and the JWE 875 Authentication Tag (which is the Authentication Tag input to the 876 calculation) using the specified content encryption algorithm, 877 returning the decrypted plaintext and verifying the JWE 878 Authentication Tag in the manner specified for the algorithm, 879 rejecting the input without emitting any decrypted output if the 880 JWE Authentication Tag is incorrect. 882 16. Uncompress the decrypted plaintext if a "zip" parameter was 883 included. 885 17. Output the resulting Plaintext. 887 5.3. String Comparison Rules 889 Processing a JWE inevitably requires comparing known strings to 890 values in JSON objects. For example, in checking what the encryption 891 method is, the Unicode string encoding "enc" will be checked against 892 the member names in the JWE Header to see if there is a matching 893 Header Parameter Name. 895 Comparisons between JSON strings and other Unicode strings MUST be 896 performed by comparing Unicode code points without normalization as 897 specified in the String Comparison Rules in Section 5.3 of [JWS]. 899 6. Key Identification 901 It is necessary for the recipient of a JWE to be able to determine 902 the key that was employed for the encryption operation. The key 903 employed can be identified using the Header Parameter methods 904 described in Section 4.1 or can be identified using methods that are 905 outside the scope of this specification. Specifically, the Header 906 Parameters "jku", "jwk", "x5u", "x5t", "x5c", and "kid" can be used 907 to identify the key used. The sender SHOULD include sufficient 908 information in the Header Parameters to identify the key used, unless 909 the application uses another means or convention to determine the key 910 used. Recipients MUST reject the input when the key used cannot be 911 determined. 913 7. Serializations 915 JWE objects use one of two serializations, the JWE Compact 916 Serialization or the JWE JSON Serialization. The JWE Compact 917 Serialization is mandatory to implement. Implementation of the JWE 918 JSON Serialization is OPTIONAL. 920 7.1. JWE Compact Serialization 922 The JWE Compact Serialization represents encrypted content as a 923 compact URL-safe string. This string is the concatenation of the 924 Encoded JWE Header, the Encoded JWE Encrypted Key, the Encoded JWE 925 Initialization Vector, the Encoded JWE Ciphertext, and the Encoded 926 JWE Authentication Tag in that order, with the five strings being 927 separated by four period ('.') characters. Only one recipient is 928 supported by the JWE Compact Serialization. 930 7.2. JWE JSON Serialization 932 The JWE JSON Serialization represents encrypted content as a JSON 933 object. Unlike the JWE Compact Serialization, content using the JWE 934 JSON Serialization can be encrypted to more than one recipient. 936 The representation is closely related to that used in the JWE Compact 937 Serialization, with the following differences for the JWE JSON 938 Serialization: 940 o Values in the JWE JSON Serialization are represented as members of 941 a JSON object, rather than as base64url encoded strings separated 942 by period ('.') characters. (However binary values and values 943 that are integrity protected are still base64url encoded.) 945 o The Encoded JWE Header value, if non-empty, is stored in the 946 "protected" member. 948 o The Encoded JWE Initialization Vector value, if non-empty, is 949 stored in the "iv" member. 951 o The Encoded JWE Ciphertext value is stored in the "ciphertext" 952 member. 954 o The Encoded JWE Authentication Tag value, if non-empty, is stored 955 in the "tag" member. 957 o The JWE can be encrypted to multiple recipients, rather than just 958 one. A JSON array in the "recipients" member is used to hold 959 values that are specific to a particular recipient, with one array 960 element per recipient represented. These array elements are JSON 961 objects. 963 o Each Encoded JWE Encrypted Key value, if non-empty, is stored in 964 the "encrypted_key" member of a JSON object that is an element of 965 the "recipients" array. 967 o Some header parameter values, such as the "alg" value and 968 parameters used for selecting keys, can also differ for different 969 recipient computations. Per-recipient header parameter values, if 970 present, are stored in the "header" members of the same JSON 971 objects that are elements of the "recipients" array. 973 o Some header parameters, including the "alg" parameter, can be 974 shared among all recipient computations. These header parameters 975 are stored in either of two top-level member(s) of the JSON 976 object: the "protected" member and the "unprotected" member. The 977 values of these members, if present, are JSON Text Objects 978 containing Header Parameters. 980 o Not all header parameters are integrity protected. The shared 981 header parameters in the "protected" member are integrity 982 protected, and are base64url encoded. The per-recipient header 983 parameters in the "header" array element members and the shared 984 header parameters in the "unprotected" member are not integrity 985 protected. These JSON Text Objects containing header parameters 986 that are not integrity protected are not base64url encoded. 988 o The header parameter values used when creating or validating per- 989 recipient Ciphertext and Authentication Tag values are the union 990 of the three sets of header parameter values that may be present: 991 (1) the per-recipient values in the "header" member of the 992 recipient's array element, (2) the shared integrity-protected 993 values in the "protected" member, and (3) the shared non- 994 integrity-protected values in the "unprotected" member. The union 995 of these sets of header parameters comprises the JWE Header. The 996 header parameter names in the three locations MUST be disjoint. 998 o An "aad" (Additional Authenticated Data) member can be included to 999 supply a base64url encoded value to be integrity protected but not 1000 encrypted. (Note that this can also be achieved when using either 1001 serialization by including the AAD value as a protected header 1002 parameter value, but at the cost of the value being double 1003 base64url encoded.) 1005 o The "recipients" array MUST always be present, even if the array 1006 elements contain only the empty JSON object "{}" (which can happen 1007 when all header parameter values are shared between all recipients 1008 and when no encrypted key is used, such as when doing Direct 1009 Encryption). 1011 The syntax of a JWE using the JWE JSON Serialization is as follows: 1013 {"protected":", 1014 "unprotected":", 1015 "recipients":[ 1016 {"header":"", 1017 "encrypted_key":""}, 1018 ... 1019 {"header":"", 1020 "encrypted_key":""}], 1021 "aad":"", 1022 "iv":"", 1023 "ciphertext":"", 1024 "tag":"" 1025 } 1027 Of these members, only the "ciphertext" member MUST be present. The 1028 "iv", "tag", and "encrypted_key" members MUST be present when 1029 corresponding JWE Initialization Vector, JWE Authentication Tag, and 1030 JWE Encrypted Key values are non-empty. The "recipients" member MUST 1031 be present when any "header" or "encrypted_key" members are needed 1032 for recipients. At least one of the "header", "protected", and 1033 "unprotected" members MUST be present so that "alg" and "enc" header 1034 parameter values are conveyed for each recipient computation. 1036 The contents of the Encoded JWE Encrypted Key, Encoded JWE 1037 Initialization Vector, Encoded JWE Ciphertext, and Encoded JWE 1038 Authentication Tag values are exactly as defined in the rest of this 1039 specification. They are interpreted and validated in the same 1040 manner, with each corresponding Encoded JWE Encrypted Key, Encoded 1041 JWE Initialization Vector, Encoded JWE Ciphertext, Encoded JWE 1042 Authentication Tag, and set of header parameter values being created 1043 and validated together. The JWE Header values used are the union of 1044 the header parameters in the "protected", "unprotected", and 1045 corresponding "header" members, as described earlier. 1047 Each JWE Encrypted Key value is computed using the parameters of the 1048 corresponding JWE Header value in the same manner as for the JWE 1049 Compact Serialization. This has the desirable property that each 1050 Encoded JWE Encrypted Key value in the "recipients" array is 1051 identical to the value that would have been computed for the same 1052 parameter in the JWE Compact Serialization. Likewise, the JWE 1053 Ciphertext and JWE Authentication Tag values match those produced for 1054 the JWE Compact Serialization, provided that the Encoded JWE Header 1055 value (which represents the integrity-protected header parameter 1056 values) matches that used in the JWE Compact Serialization. 1058 All recipients use the same JWE Protected Header, JWE Initialization 1059 Vector, JWE Ciphertext, and JWE Authentication Tag values, resulting 1060 in potentially significant space savings if the message is large. 1061 Therefore, all header parameters that specify the treatment of the 1062 Plaintext value MUST be the same for all recipients. This primarily 1063 means that the "enc" (encryption method) header parameter value in 1064 the JWE Header for each recipient and any parameters of that 1065 algorithm MUST be the same. 1067 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1068 Serialization. 1070 8. Distinguishing Between JWS and JWE Objects 1072 There are several ways of distinguishing whether an object is a JWS 1073 or JWE object. All these methods will yield the same result for all 1074 legal input values. 1076 o If the object is using the JWS Compact Serialization or the JWE 1077 Compact Serialization, the number of base64url encoded segments 1078 separated by period ('.') characters differs for JWSs and JWEs. 1079 JWSs have three segments separated by two period ('.') characters. 1080 JWEs have five segments separated by four period ('.') characters. 1082 o If the object is using the JWS JSON Serialization or the JWE JSON 1083 Serialization, the members used will be different. JWSs have a 1084 "signatures" member and JWEs do not. JWEs have a "recipients" 1085 member and JWSs do not. 1087 o A JWS Header can be distinguished from a JWE header by examining 1088 the "alg" (algorithm) header parameter value. If the value 1089 represents a digital signature or MAC algorithm, or is the value 1090 "none", it is for a JWS; if it represents a Key Encryption, Key 1091 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 1092 or Direct Encryption algorithm, it is for a JWE. 1094 o A JWS Header can also be distinguished from a JWE header by 1095 determining whether an "enc" (encryption method) member exists. 1096 If the "enc" member exists, it is a JWE; otherwise, it is a JWS. 1098 9. IANA Considerations 1100 9.1. Registration of JWE Header Parameter Names 1102 This specification registers the Header Parameter Names defined in 1103 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1104 Parameters registry [JWS]. 1106 9.1.1. Registry Contents 1108 o Header Parameter Name: "alg" 1109 o Header Parameter Usage Location(s): JWE 1110 o Change Controller: IETF 1111 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1113 o Header Parameter Name: "enc" 1114 o Header Parameter Usage Location(s): JWE 1115 o Change Controller: IETF 1116 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1118 o Header Parameter Name: "zip" 1119 o Header Parameter Usage Location(s): JWE 1120 o Change Controller: IETF 1121 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1123 o Header Parameter Name: "jku" 1124 o Header Parameter Usage Location(s): JWE 1125 o Change Controller: IETF 1126 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1128 o Header Parameter Name: "jwk" 1129 o Header Parameter Usage Location(s): JWE 1130 o Change Controller: IETF 1131 o Specification document(s): Section 4.1.5 of [[ this document ]] 1133 o Header Parameter Name: "x5u" 1134 o Header Parameter Usage Location(s): JWE 1135 o Change Controller: IETF 1136 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1138 o Header Parameter Name: "x5t" 1139 o Header Parameter Usage Location(s): JWE 1140 o Change Controller: IETF 1141 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1143 o Header Parameter Name: "x5c" 1144 o Header Parameter Usage Location(s): JWE 1145 o Change Controller: IETF 1146 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1148 o Header Parameter Name: "kid" 1149 o Header Parameter Usage Location(s): JWE 1150 o Change Controller: IETF 1151 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1152 o Header Parameter Name: "typ" 1153 o Header Parameter Usage Location(s): JWE 1154 o Change Controller: IETF 1155 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1157 o Header Parameter Name: "cty" 1158 o Header Parameter Usage Location(s): JWE 1159 o Change Controller: IETF 1160 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1162 o Header Parameter Name: "crit" 1163 o Header Parameter Usage Location(s): JWE 1164 o Change Controller: IETF 1165 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1167 10. Security Considerations 1169 All of the security issues faced by any cryptographic application 1170 must be faced by a JWS/JWE/JWK agent. Among these issues are 1171 protecting the user's private and symmetric keys, preventing various 1172 attacks, and helping the user avoid mistakes such as inadvertently 1173 encrypting a message for the wrong recipient. The entire list of 1174 security considerations is beyond the scope of this document. 1176 All the security considerations in the JWS specification also apply 1177 to this specification. Likewise, all the security considerations in 1178 XML Encryption 1.1 [W3C.CR-xmlenc-core1-20120313] also apply, other 1179 than those that are XML specific. 1181 When decrypting, particular care must be taken not to allow the JWE 1182 recipient to be used as an oracle for decrypting messages. RFC 3218 1183 [RFC3218] should be consulted for specific countermeasures to attacks 1184 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1185 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1186 formatting error that can be detected and used to recover the CEK 1187 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1188 particularly important to report all formatting errors to the CEK, 1189 Additional Authenticated Data, or ciphertext as a single error when 1190 the JWE is rejected. 1192 11. References 1194 11.1. Normative References 1196 [ECMAScript] 1197 Ecma International, "ECMAScript Language Specification, 1198 5.1 Edition", ECMA 262, June 2011. 1200 [ITU.X690.1994] 1201 International Telecommunications Union, "Information 1202 Technology - ASN.1 encoding rules: Specification of Basic 1203 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1204 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1205 X.690, 1994. 1207 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1208 draft-ietf-jose-json-web-algorithms (work in progress), 1209 July 2013. 1211 [JWK] Jones, M., "JSON Web Key (JWK)", 1212 draft-ietf-jose-json-web-key (work in progress), 1213 July 2013. 1215 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1216 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1217 in progress), July 2013. 1219 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 1220 Mail: Part I: Message Encryption and Authentication 1221 Procedures", RFC 1421, February 1993. 1223 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1224 version 1.3", RFC 1951, May 1996. 1226 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1227 Extensions (MIME) Part Two: Media Types", RFC 2046, 1228 November 1996. 1230 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1231 Requirement Levels", BCP 14, RFC 2119, March 1997. 1233 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1235 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1236 10646", STD 63, RFC 3629, November 2003. 1238 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1239 Resource Identifier (URI): Generic Syntax", STD 66, 1240 RFC 3986, January 2005. 1242 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1243 Requirements for Security", BCP 106, RFC 4086, June 2005. 1245 [RFC4627] Crockford, D., "The application/json Media Type for 1246 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1248 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1249 Encodings", RFC 4648, October 2006. 1251 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1252 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1254 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1255 Housley, R., and W. Polk, "Internet X.509 Public Key 1256 Infrastructure Certificate and Certificate Revocation List 1257 (CRL) Profile", RFC 5280, May 2008. 1259 [W3C.CR-xmlenc-core1-20120313] 1260 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 1261 "XML Encryption Syntax and Processing Version 1.1", World 1262 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1263 March 2012, 1264 . 1266 11.2. Informative References 1268 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1269 McGrew, D. and K. Paterson, "Authenticated Encryption with 1270 AES-CBC and HMAC-SHA", 1271 draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), 1272 October 2012. 1274 [I-D.rescorla-jsms] 1275 Rescorla, E. and J. Hildebrand, "JavaScript Message 1276 Security Format", draft-rescorla-jsms-00 (work in 1277 progress), March 2011. 1279 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1280 Encryption", September 2010. 1282 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1283 Cryptographic Message Syntax", RFC 3218, January 2002. 1285 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1286 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1287 July 2005. 1289 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1290 RFC 5652, September 2009. 1292 Appendix A. JWE Examples 1294 This section provides examples of JWE computations. 1296 A.1. Example JWE using RSAES OAEP and AES GCM 1298 This example encrypts the plaintext "The true sign of intelligence is 1299 not knowledge but imagination." to the recipient using RSAES OAEP for 1300 key encryption and AES GCM for content encryption. The 1301 representation of this plaintext is: 1303 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1304 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1305 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1306 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1307 110, 97, 116, 105, 111, 110, 46] 1309 A.1.1. JWE Header 1311 The following example JWE Header declares that: 1313 o the Content Encryption Key is encrypted to the recipient using the 1314 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1316 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1317 bit key to produce the Ciphertext. 1319 {"alg":"RSA-OAEP","enc":"A256GCM"} 1321 A.1.2. Encoded JWE Header 1323 Base64url encoding the octets of the UTF-8 representation of the JWE 1324 Header yields this Encoded JWE Header value: 1326 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1328 A.1.3. Content Encryption Key (CEK) 1330 Generate a 256 bit random Content Encryption Key (CEK). In this 1331 example, the value is: 1333 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1334 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1335 234, 64, 252] 1337 A.1.4. Key Encryption 1339 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1340 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1341 key represented in JSON Web Key [JWK] format below (with line breaks 1342 for display purposes only): 1344 {"kty":"RSA", 1345 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1346 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1347 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1348 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1349 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1350 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1351 "e":"AQAB", 1352 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1353 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1354 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1355 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1356 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1357 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ" 1358 } 1360 The resulting JWE Encrypted Key value is: 1362 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1363 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1364 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1365 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1366 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1367 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1368 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1369 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1370 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1371 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1372 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1373 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1374 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1375 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1376 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1377 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1378 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1379 117, 114, 135, 206] 1381 A.1.5. Encoded JWE Encrypted Key 1383 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1384 Encrypted Key. This result (with line breaks for display purposes 1385 only) is: 1387 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1388 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1389 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1390 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1391 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1392 6UklfCpIMfIjf7iGdXKHzg 1394 A.1.6. Initialization Vector 1396 Generate a random 96 bit JWE Initialization Vector. In this example, 1397 the value is: 1399 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1401 Base64url encoding this value yields this Encoded JWE Initialization 1402 Vector value: 1404 48V1_ALb6US04U3b 1406 A.1.7. Additional Authenticated Data 1408 Let the Additional Authenticated Data encryption parameter be the 1409 octets of the ASCII representation of the Encoded JWE Header value. 1410 This AAD value is: 1412 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1413 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1414 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1416 A.1.8. Plaintext Encryption 1418 Encrypt the Plaintext with AES GCM using the CEK as the encryption 1419 key, the JWE Initialization Vector, and the Additional Authenticated 1420 Data value above, requesting a 128 bit Authentication Tag output. 1421 The resulting Ciphertext is: 1423 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1424 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1425 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1426 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1427 160, 109, 64, 63, 192] 1429 The resulting Authentication Tag value is: 1431 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1432 210, 145] 1434 A.1.9. Encoded JWE Ciphertext 1436 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1437 This result (with line breaks for display purposes only) is: 1439 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1440 SdiwkIr3ajwQzaBtQD_A 1442 A.1.10. Encoded JWE Authentication Tag 1444 Base64url encode the Authentication Tag to create the Encoded JWE 1445 Authentication Tag. This result is: 1447 XFBoMYUZodetZdvTiFvSkQ 1449 A.1.11. Complete Representation 1451 Assemble the final representation: The Compact Serialization of this 1452 result is the concatenation of the Encoded JWE Header, the Encoded 1453 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1454 JWE Ciphertext, and the Encoded JWE Authentication Tag in that order, 1455 with the five strings being separated by four period ('.') 1456 characters. 1458 The final result in this example (with line breaks for display 1459 purposes only) is: 1461 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1462 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1463 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1464 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1465 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1466 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1467 6UklfCpIMfIjf7iGdXKHzg. 1468 48V1_ALb6US04U3b. 1469 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1470 SdiwkIr3ajwQzaBtQD_A. 1471 XFBoMYUZodetZdvTiFvSkQ 1473 A.1.12. Validation 1475 This example illustrates the process of creating a JWE with RSAES 1476 OAEP for key encryption and AES GCM for content encryption. These 1477 results can be used to validate JWE decryption implementations for 1478 these algorithms. Note that since the RSAES OAEP computation 1479 includes random values, the encryption results above will not be 1480 completely reproducible. However, since the AES GCM computation is 1481 deterministic, the JWE Encrypted Ciphertext values will be the same 1482 for all encryptions performed using these inputs. 1484 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1486 This example encrypts the plaintext "Live long and prosper." to the 1487 recipient using RSAES-PKCS1-V1_5 for key encryption and 1488 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1489 of this plaintext is: 1491 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1492 112, 114, 111, 115, 112, 101, 114, 46] 1494 A.2.1. JWE Header 1496 The following example JWE Header (with line breaks for display 1497 purposes only) declares that: 1499 o the Content Encryption Key is encrypted to the recipient using the 1500 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1502 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1503 algorithm to produce the Ciphertext. 1505 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1507 A.2.2. Encoded JWE Header 1509 Base64url encoding the octets of the UTF-8 representation of the JWE 1510 Header yields this Encoded JWE Header value: 1512 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1514 A.2.3. Content Encryption Key (CEK) 1516 Generate a 256 bit random Content Encryption Key (CEK). In this 1517 example, the key value is: 1519 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1520 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1521 44, 207] 1523 A.2.4. Key Encryption 1525 Encrypt the CEK with the recipient's public key using the RSAES- 1526 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1527 uses the RSA key represented in JSON Web Key [JWK] format below (with 1528 line breaks for display purposes only): 1530 {"kty":"RSA", 1531 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1532 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1533 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1534 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1535 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1536 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1537 "e":"AQAB", 1538 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1539 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1540 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1541 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1542 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1543 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1544 } 1546 The resulting JWE Encrypted Key value is: 1548 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1549 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1550 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1551 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1552 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1553 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1554 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1555 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1556 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1557 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1558 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1559 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1560 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1561 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1562 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1563 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1564 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1565 146, 114, 165, 204, 71, 136, 41, 252] 1567 A.2.5. Encoded JWE Encrypted Key 1569 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1570 Encrypted Key. This result (with line breaks for display purposes 1571 only) is: 1573 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1574 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1575 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1576 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1577 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1578 -B3oWh2TbqmScqXMR4gp_A 1580 A.2.6. Initialization Vector 1582 Generate a random 128 bit JWE Initialization Vector. In this 1583 example, the value is: 1585 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1586 101] 1588 Base64url encoding this value yields this Encoded JWE Initialization 1589 Vector value: 1591 AxY8DCtDaGlsbGljb3RoZQ 1593 A.2.7. Additional Authenticated Data 1595 Let the Additional Authenticated Data encryption parameter be the 1596 octets of the ASCII representation of the Encoded JWE Header value. 1597 This AAD value is: 1599 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1600 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1601 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1602 50, 73, 110, 48] 1604 A.2.8. Plaintext Encryption 1606 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1607 the encryption key, the JWE Initialization Vector, and the Additional 1608 Authenticated Data value above. The steps for doing this using the 1609 values from Appendix A.3 are detailed in Appendix B. The resulting 1610 Ciphertext is: 1612 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1613 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1614 112, 56, 102] 1616 The resulting Authentication Tag value is: 1618 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1619 191] 1621 A.2.9. Encoded JWE Ciphertext 1623 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1624 This result is: 1626 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1628 A.2.10. Encoded JWE Authentication Tag 1630 Base64url encode the Authentication Tag to create the Encoded JWE 1631 Authentication Tag. This result is: 1633 9hH0vgRfYgPnAHOd8stkvw 1635 A.2.11. Complete Representation 1637 Assemble the final representation: The Compact Serialization of this 1638 result is the concatenation of the Encoded JWE Header, the Encoded 1639 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1640 JWE Ciphertext, and the Encoded JWE Authentication Tag in that order, 1641 with the five strings being separated by four period ('.') 1642 characters. 1644 The final result in this example (with line breaks for display 1645 purposes only) is: 1647 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1648 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1649 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1650 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1651 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1652 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1653 -B3oWh2TbqmScqXMR4gp_A. 1654 AxY8DCtDaGlsbGljb3RoZQ. 1655 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1656 9hH0vgRfYgPnAHOd8stkvw 1658 A.2.12. Validation 1660 This example illustrates the process of creating a JWE with RSAES- 1661 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1662 encryption. These results can be used to validate JWE decryption 1663 implementations for these algorithms. Note that since the RSAES- 1664 PKCS1-V1_5 computation includes random values, the encryption results 1665 above will not be completely reproducible. However, since the AES 1666 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1667 will be the same for all encryptions performed using these inputs. 1669 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1671 This example encrypts the plaintext "Live long and prosper." to the 1672 recipient using AES Key Wrap for key encryption and AES GCM for 1673 content encryption. The representation of this plaintext is: 1675 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1676 112, 114, 111, 115, 112, 101, 114, 46] 1678 A.3.1. JWE Header 1680 The following example JWE Header declares that: 1682 o the Content Encryption Key is encrypted to the recipient using the 1683 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1684 Encrypted Key and 1686 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1687 algorithm to produce the Ciphertext. 1689 {"alg":"A128KW","enc":"A128CBC-HS256"} 1691 A.3.2. Encoded JWE Header 1693 Base64url encoding the octets of the UTF-8 representation of the JWE 1694 Header yields this Encoded JWE Header value: 1696 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1698 A.3.3. Content Encryption Key (CEK) 1700 Generate a 256 bit random Content Encryption Key (CEK). In this 1701 example, the value is: 1703 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1704 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1705 44, 207] 1707 A.3.4. Key Encryption 1709 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1710 algorithm to produce the JWE Encrypted Key. This example uses the 1711 symmetric key represented in JSON Web Key [JWK] format below: 1713 {"kty":"oct", 1714 "k":"GawgguFyGrWKav7AX4VKUg" 1715 } 1717 The resulting JWE Encrypted Key value is: 1719 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1720 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1721 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1723 A.3.5. Encoded JWE Encrypted Key 1725 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1726 Encrypted Key. This result is: 1728 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1730 A.3.6. Initialization Vector 1732 Generate a random 128 bit JWE Initialization Vector. In this 1733 example, the value is: 1735 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1736 101] 1738 Base64url encoding this value yields this Encoded JWE Initialization 1739 Vector value: 1741 AxY8DCtDaGlsbGljb3RoZQ 1743 A.3.7. Additional Authenticated Data 1745 Let the Additional Authenticated Data encryption parameter be the 1746 octets of the ASCII representation of the Encoded JWE Header value. 1747 This AAD value is: 1749 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1750 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1751 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1752 110, 48] 1754 A.3.8. Plaintext Encryption 1756 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1757 the encryption key, the JWE Initialization Vector, and the Additional 1758 Authenticated Data value above. The steps for doing this using the 1759 values from this example are detailed in Appendix B. The resulting 1760 Ciphertext is: 1762 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1763 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1764 112, 56, 102] 1766 The resulting Authentication Tag value is: 1768 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1769 194, 85] 1771 A.3.9. Encoded JWE Ciphertext 1773 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1774 This result is: 1776 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1778 A.3.10. Encoded JWE Authentication Tag 1780 Base64url encode the Authentication Tag to create the Encoded JWE 1781 Authentication Tag. This result is: 1783 U0m_YmjN04DJvceFICbCVQ 1785 A.3.11. Complete Representation 1787 Assemble the final representation: The Compact Serialization of this 1788 result is the concatenation of the Encoded JWE Header, the Encoded 1789 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1790 JWE Ciphertext, and the Encoded JWE Authentication Tag in that order, 1791 with the five strings being separated by four period ('.') 1792 characters. 1794 The final result in this example (with line breaks for display 1795 purposes only) is: 1797 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1798 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1799 AxY8DCtDaGlsbGljb3RoZQ. 1800 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1801 U0m_YmjN04DJvceFICbCVQ 1803 A.3.12. Validation 1805 This example illustrates the process of creating a JWE with AES Key 1806 Wrap for key encryption and AES GCM for content encryption. These 1807 results can be used to validate JWE decryption implementations for 1808 these algorithms. Also, since both the AES Key Wrap and AES GCM 1809 computations are deterministic, the resulting JWE value will be the 1810 same for all encryptions performed using these inputs. Since the 1811 computation is reproducible, these results can also be used to 1812 validate JWE encryption implementations for these algorithms. 1814 A.4. Example JWE Using JWE JSON Serialization 1816 This section contains an example using the JWE JSON Serialization. 1817 This example demonstrates the capability for encrypting the same 1818 plaintext to multiple recipients. 1820 Two recipients are present in this example. The algorithm and key 1821 used for the first recipient are the same as that used in 1822 Appendix A.2. The algorithm and key used for the second recipient 1823 are the same as that used in Appendix A.3. The resulting JWE 1824 Encrypted Key values are therefore the same; those computations are 1825 not repeated here. 1827 The Plaintext, the Content Encryption Key (CEK), Initialization 1828 Vector, and JWE Protected Header are shared by all recipients (which 1829 must be the case, since the Ciphertext and Authentication Tag are 1830 also shared). 1832 A.4.1. JWE Per-Recipient Unprotected Headers 1834 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1835 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1836 encrypt the CEK. Key ID values are supplied for both keys. The two 1837 per-recipient header values used to represent these algorithms and 1838 Key IDs are: 1840 {"alg":"RSA1_5","kid":"2011-04-29"} 1842 and: 1844 {"alg":"A128KW","kid":"7"} 1846 A.4.2. JWE Protected Header 1848 The Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1849 algorithm to produce the common JWE Ciphertext and JWE Authentication 1850 Tag values. The JWE Protected Header value representing this is: 1852 {"enc":"A128CBC-HS256"} 1854 Base64url encoding the octets of the UTF-8 representation of the JWE 1855 Protected Header yields this Encoded JWE Protected Header value: 1857 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1859 A.4.3. JWE Unprotected Header 1861 This JWE uses the "jku" header parameter to reference a JWK Set. This 1862 is represented in the following JWE Unprotected Header value as: 1864 {"jku":"https://server.example.com/keys.jwks"} 1866 A.4.4. Complete JWE Header Values 1868 Combining the per-recipient, protected, and unprotected header values 1869 supplied, the JWE Header values used for the first and second 1870 recipient respectively are: 1872 {"alg":"RSA1_5", 1873 "kid":"2011-04-29", 1874 "enc":"A128CBC-HS256", 1875 "jku":"https://server.example.com/keys.jwks"} 1877 and: 1879 {"alg":"A128KW", 1880 "kid":"7", 1881 "enc":"A128CBC-HS256", 1882 "jku":"https://server.example.com/keys.jwks"} 1884 A.4.5. Additional Authenticated Data 1886 Let the Additional Authenticated Data encryption parameter be the 1887 octets of the ASCII representation of the Encoded JWE Protected 1888 Header value. This AAD value is: 1890 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1891 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1893 A.4.6. Plaintext Encryption 1895 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1896 the encryption key, the JWE Initialization Vector, and the Additional 1897 Authenticated Data value above. The steps for doing this using the 1898 values from Appendix A.3 are detailed in Appendix B. The resulting 1899 Ciphertext is: 1901 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1902 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1903 112, 56, 102] 1905 The resulting Authentication Tag value is: 1907 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1908 207] 1910 A.4.7. Encoded JWE Ciphertext 1912 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1913 This result is: 1915 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1917 A.4.8. Encoded JWE Authentication Tag 1919 Base64url encode the Authentication Tag to create the Encoded JWE 1920 Authentication Tag. This result is: 1922 Mz-VPPyU4RlcuYv1IwIvzw 1924 A.4.9. Complete JWE JSON Serialization Representation 1926 The complete JSON Web Encryption JSON Serialization for these values 1927 is as follows (with line breaks for display purposes only): 1929 {"protected": 1930 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1931 "unprotected": 1932 {"jku":"https://server.example.com/keys.jwks"}, 1933 "recipients":[ 1934 {"header": 1935 {"alg":"RSA1_5"}, 1936 "encrypted_key": 1937 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1938 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1939 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 1940 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 1941 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 1942 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 1943 {"header": 1944 {"alg":"A128KW"}, 1945 "encrypted_key": 1946 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1947 "iv": 1948 "AxY8DCtDaGlsbGljb3RoZQ", 1949 "ciphertext": 1950 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1951 "tag": 1952 "Mz-VPPyU4RlcuYv1IwIvzw" 1953 } 1955 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 1957 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 1958 authenticated encryption computation using the values from the 1959 example in Appendix A.3. As described where this algorithm is 1960 defined in Sections 4.8 and 4.8.3 of JWA, the AES_CBC_HMAC_SHA2 1961 family of algorithms are implemented using Advanced Encryption 1962 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #5 1963 padding to perform the encryption and an HMAC SHA-2 function to 1964 perform the integrity calculation - in this case, HMAC SHA-256. 1966 B.1. Extract MAC_KEY and ENC_KEY from Key 1968 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example is: 1970 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1971 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1972 44, 207] 1974 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 1975 which is: 1977 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1978 206] 1980 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 1981 is: 1983 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 1984 207] 1986 Note that the MAC key comes before the encryption key in the input 1987 key K; this is in the opposite order of the algorithm names in the 1988 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 1990 B.2. Encrypt Plaintext to Create Ciphertext 1992 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 1993 using PKCS #5 padding using the ENC_KEY above. The Plaintext in this 1994 example is: 1996 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1997 112, 114, 111, 115, 112, 101, 114, 46] 1999 The encryption result is as follows, which is the Ciphertext output: 2001 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 2002 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 2003 112, 56, 102] 2005 B.3. 64 Bit Big Endian Representation of AAD Length 2007 The Additional Authenticated Data (AAD) in this example is: 2009 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2010 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2011 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2012 110, 48] 2014 This AAD is 51 bytes long, which is 408 bits long. The octet string 2015 AL, which is the number of bits in AAD expressed as a big endian 64 2016 bit unsigned integer is: 2018 [0, 0, 0, 0, 0, 0, 1, 152] 2020 B.4. Initialization Vector Value 2022 The Initialization Vector value used in this example is: 2024 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 2025 101] 2027 B.5. Create Input to HMAC Computation 2029 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 2030 the AL value. The result of this concatenation is: 2032 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2033 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2034 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2035 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 2036 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 2037 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 2038 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 2040 B.6. Compute HMAC Value 2042 Compute the HMAC SHA-256 of the concatenated value above. This 2043 result M is: 2045 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2046 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 2047 86, 229, 116] 2049 B.7. Truncate HMAC Value to Create Authentication Tag 2051 Use the first half (128 bits) of the HMAC output M as the 2052 Authentication Tag output T. This truncated value is: 2054 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2055 194, 85] 2057 Appendix C. Acknowledgements 2059 Solutions for encrypting JSON content were also explored by JSON 2060 Simple Encryption [JSE] and JavaScript Message Security Format 2061 [I-D.rescorla-jsms], both of which significantly influenced this 2062 draft. This draft attempts to explicitly reuse as many of the 2063 relevant concepts from XML Encryption 1.1 2064 [W3C.CR-xmlenc-core1-20120313] and RFC 5652 [RFC5652] as possible, 2065 while utilizing simple, compact JSON-based data structures. 2067 Special thanks are due to John Bradley and Nat Sakimura for the 2068 discussions that helped inform the content of this specification and 2069 to Eric Rescorla and Joe Hildebrand for allowing the reuse of text 2070 from [I-D.rescorla-jsms] in this document. 2072 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2073 Jay for validating the examples in this specification. 2075 This specification is the work of the JOSE Working Group, which 2076 includes dozens of active and dedicated participants. In particular, 2077 the following individuals contributed ideas, feedback, and wording 2078 that influenced this specification: 2080 Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick 2081 Hardt, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Tony 2082 Nadalin, Axel Nennker, Emmanuel Raviart, Nat Sakimura, Jim Schaad, 2083 Hannes Tschofenig, and Sean Turner. 2085 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2086 Sean Turner and Stephen Farrell served as Security area directors 2087 during the creation of this specification. 2089 Appendix D. Document History 2091 [[ to be removed by the RFC editor before publication as an RFC ]] 2093 -14 2095 o Clarified that the "protected", "unprotected", "header", "iv", 2096 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2097 JSON Serialization when their values would be empty. Stated that 2098 the "recipients" array must always be present. 2100 -13 2102 o Added an "aad" (Additional Authenticated Data) member for the JWE 2103 JSON Serialization, enabling Additional Authenticated Data to be 2104 supplied that is not double base64url encoded, addressing issue 2105 #29. 2107 -12 2109 o Clarified that the "typ" and "cty" header parameters are used in 2110 an application-specific manner and have no effect upon the JWE 2111 processing. 2113 o Replaced the MIME types "application/jwe+json" and 2114 "application/jwe" with "application/jose+json" and 2115 "application/jose". 2117 o Stated that recipients MUST either reject JWEs with duplicate 2118 Header Parameter Names or use a JSON parser that returns only the 2119 lexically last duplicate member name. 2121 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2122 be with the algorithm descriptions that use them. 2124 o Added a Serializations section with parallel treatment of the JWE 2125 Compact Serialization and the JWE JSON Serialization and also 2126 moved the former Implementation Considerations content there. 2128 o Restored use of the term "AEAD". 2130 o Changed terminology from "block encryption" to "content 2131 encryption". 2133 -11 2135 o Added Key Identification section. 2137 o Removed the Encrypted Key value from the AAD computation since it 2138 is already effectively integrity protected by the encryption 2139 process. The AAD value now only contains the representation of 2140 the JWE Encrypted Header. 2142 o For the JWE JSON Serialization, enable header parameter values to 2143 be specified in any of three parameters: the "protected" member 2144 that is integrity protected and shared among all recipients, the 2145 "unprotected" member that is not integrity protected and shared 2146 among all recipients, and the "header" member that is not 2147 integrity protected and specific to a particular recipient. (This 2148 does not affect the JWE Compact Serialization, in which all header 2149 parameter values are in a single integrity protected JWE Header 2150 value.) 2152 o Shortened the names "authentication_tag" to "tag" and 2153 "initialization_vector" to "iv" in the JWE JSON Serialization, 2154 addressing issue #20. 2156 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2158 o Removed suggested compact serialization for multiple recipients. 2160 o Changed the MIME type name "application/jwe-js" to 2161 "application/jwe+json", addressing issue #22. 2163 o Tightened the description of the "crit" (critical) header 2164 parameter. 2166 -10 2168 o Changed the JWE processing rules for multiple recipients so that a 2169 single AAD value contains the header parameters and encrypted key 2170 values for all the recipients, enabling AES GCM to be safely used 2171 for multiple recipients. 2173 o Added an appendix suggesting a possible compact serialization for 2174 JWEs with multiple recipients. 2176 -09 2178 o Added JWE JSON Serialization, as specified by 2179 draft-jones-jose-jwe-json-serialization-04. 2181 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2182 parameter value. 2184 o Defined that the default action for header parameters that are not 2185 understood is to ignore them unless specifically designated as 2186 "MUST be understood" or included in the new "crit" (critical) 2187 header parameter list. This addressed issue #6. 2189 o Corrected "x5c" description. This addressed issue #12. 2191 o Changed from using the term "byte" to "octet" when referring to 8 2192 bit values. 2194 o Added Key Management Mode definitions to terminology section and 2195 used the defined terms to provide clearer key management 2196 instructions. This addressed issue #5. 2198 o Added text about preventing the recipient from behaving as an 2199 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2201 o Changed from using the term "Integrity Value" to "Authentication 2202 Tag". 2204 o Changed member name from "integrity_value" to "authentication_tag" 2205 in the JWE JSON Serialization. 2207 o Removed Initialization Vector from the AAD value since it is 2208 already integrity protected by all of the authenticated encryption 2209 algorithms specified in the JWA specification. 2211 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2212 and "A256CBC-HS512". The new algorithms perform the same 2213 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2214 but with the Initialization Vector and Authentication Tag values 2215 remaining separate from the Ciphertext value in the output 2216 representation. Also deleted the header parameters "epu" 2217 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2218 they are no longer used. 2220 -08 2222 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2223 since the term AEAD in the RFC 5116 sense implied the use of a 2224 particular data representation, rather than just referring to the 2225 class of algorithms that perform authenticated encryption with 2226 associated data. 2228 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2229 Tschofenig. Many of these simplified the terminology used. 2231 o Clarified statements of the form "This header parameter is 2232 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2234 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2235 Web Signature and Encryption Header Parameters registry. 2237 o Added seriesInfo information to Internet Draft references. 2239 -07 2241 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2243 o Updated values for example AES CBC calculations. 2245 o Made several local editorial changes to clean up loose ends left 2246 over from to the decision to only support block encryption methods 2247 providing integrity. One of these changes was to explicitly state 2248 that the "enc" (encryption method) algorithm must be an 2249 Authenticated Encryption algorithm with a specified key length. 2251 -06 2253 o Removed the "int" and "kdf" parameters and defined the new 2254 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2255 "A256CBC+HS512" to replace the former uses of AES CBC, which 2256 required the use of separate integrity and key derivation 2257 functions. 2259 o Included additional values in the Concat KDF calculation -- the 2260 desired output size and the algorithm value, and optionally 2261 PartyUInfo and PartyVInfo values. Added the optional header 2262 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2263 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2264 PartyVInfo). Updated the KDF examples accordingly. 2266 o Promoted Initialization Vector from being a header parameter to 2267 being a top-level JWE element. This saves approximately 16 bytes 2268 in the compact serialization, which is a significant savings for 2269 some use cases. Promoting the Initialization Vector out of the 2270 header also avoids repeating this shared value in the JSON 2271 serialization. 2273 o Changed "x5c" (X.509 Certificate Chain) representation from being 2274 a single string to being an array of strings, each containing a 2275 single base64 encoded DER certificate value, representing elements 2276 of the certificate chain. 2278 o Added an AES Key Wrap example. 2280 o Reordered the encryption steps so CMK creation is first, when 2281 required. 2283 o Correct statements in examples about which algorithms produce 2284 reproducible results. 2286 -05 2288 o Support both direct encryption using a shared or agreed upon 2289 symmetric key, and the use of a shared or agreed upon symmetric 2290 key to key wrap the CMK. 2292 o Added statement that "StringOrURI values are compared as case- 2293 sensitive strings with no transformations or canonicalizations 2294 applied". 2296 o Updated open issues. 2298 o Indented artwork elements to better distinguish them from the body 2299 text. 2301 -04 2303 o Refer to the registries as the primary sources of defined values 2304 and then secondarily reference the sections defining the initial 2305 contents of the registries. 2307 o Normatively reference XML Encryption 1.1 2308 [W3C.CR-xmlenc-core1-20120313] for its security considerations. 2310 o Reference draft-jones-jose-jwe-json-serialization instead of 2311 draft-jones-json-web-encryption-json-serialization. 2313 o Described additional open issues. 2315 o Applied editorial suggestions. 2317 -03 2319 o Added the "kdf" (key derivation function) header parameter to 2320 provide crypto agility for key derivation. The default KDF 2321 remains the Concat KDF with the SHA-256 digest function. 2323 o Reordered encryption steps so that the Encoded JWE Header is 2324 always created before it is needed as an input to the 2325 Authenticated Encryption "additional authenticated data" 2326 parameter. 2328 o Added the "cty" (content type) header parameter for declaring type 2329 information about the secured content, as opposed to the "typ" 2330 (type) header parameter, which declares type information about 2331 this object. 2333 o Moved description of how to determine whether a header is for a 2334 JWS or a JWE from the JWT spec to the JWE spec. 2336 o Added complete encryption examples for both Authenticated 2337 Encryption and non-Authenticated Encryption algorithms. 2339 o Added complete key derivation examples. 2341 o Added "Collision Resistant Namespace" to the terminology section. 2343 o Reference ITU.X690.1994 for DER encoding. 2345 o Added Registry Contents sections to populate registry values. 2347 o Numerous editorial improvements. 2349 -02 2351 o When using Authenticated Encryption algorithms (such as AES GCM), 2352 use the "additional authenticated data" parameter to provide 2353 integrity for the header, encrypted key, and ciphertext and use 2354 the resulting "authentication tag" value as the JWE Authentication 2355 Tag. 2357 o Defined KDF output key sizes. 2359 o Generalized text to allow key agreement to be employed as an 2360 alternative to key wrapping or key encryption. 2362 o Changed compression algorithm from gzip to DEFLATE. 2364 o Clarified that it is an error when a "kid" value is included and 2365 no matching key is found. 2367 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2368 rejected. 2370 o Clarified the relationship between "typ" header parameter values 2371 and MIME types. 2373 o Registered application/jwe MIME type and "JWE" typ header 2374 parameter value. 2376 o Simplified JWK terminology to get replace the "JWK Key Object" and 2377 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2378 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2379 between single keys and sets of keys. As part of this change, the 2380 Header Parameter Name for a public key value was changed from 2381 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2383 o Added suggestion on defining additional header parameters such as 2384 "x5t#S256" in the future for certificate thumbprints using hash 2385 algorithms other than SHA-1. 2387 o Specify RFC 2818 server identity validation, rather than RFC 6125 2388 (paralleling the same decision in the OAuth specs). 2390 o Generalized language to refer to Message Authentication Codes 2391 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2392 unless in a context specific to HMAC algorithms. 2394 o Reformatted to give each header parameter its own section heading. 2396 -01 2398 o Added an integrity check for non-Authenticated Encryption 2399 algorithms. 2401 o Added "jpk" and "x5c" header parameters for including JWK public 2402 keys and X.509 certificate chains directly in the header. 2404 o Clarified that this specification is defining the JWE Compact 2405 Serialization. Referenced the new JWE-JS spec, which defines the 2406 JWE JSON Serialization. 2408 o Added text "New header parameters should be introduced sparingly 2409 since an implementation that does not understand a parameter MUST 2410 reject the JWE". 2412 o Clarified that the order of the encryption and decryption steps is 2413 not significant in cases where there are no dependencies between 2414 the inputs and outputs of the steps. 2416 o Made other editorial improvements suggested by JOSE working group 2417 participants. 2419 -00 2421 o Created the initial IETF draft based upon 2422 draft-jones-json-web-encryption-02 with no normative changes. 2424 o Changed terminology to no longer call both digital signatures and 2425 HMACs "signatures". 2427 Authors' Addresses 2429 Michael B. Jones 2430 Microsoft 2432 Email: mbj@microsoft.com 2433 URI: http://self-issued.info/ 2434 Eric Rescorla 2435 RTFM, Inc. 2437 Email: ekr@rtfm.com 2439 Joe Hildebrand 2440 Cisco Systems, Inc. 2442 Email: jhildebr@cisco.com