idnits 2.17.1 draft-ietf-jose-json-web-encryption-16.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 and processed by implementations. -- The document date (September 15, 2013) is 3875 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 1434 -- Looks like a reference, but probably isn't: '197' on line 1434 -- Looks like a reference, but probably isn't: '117' on line 1434 -- Looks like a reference, but probably isn't: '252' on line 1434 -- Looks like a reference, but probably isn't: '2' on line 1434 -- Looks like a reference, but probably isn't: '219' on line 1434 -- Looks like a reference, but probably isn't: '233' on line 1434 -- Looks like a reference, but probably isn't: '68' on line 1434 -- Looks like a reference, but probably isn't: '180' on line 1434 -- Looks like a reference, but probably isn't: '225' on line 1434 -- Looks like a reference, but probably isn't: '77' on line 1434 -- Looks like a reference, but probably isn't: '0' on line 2053 -- Looks like a reference, but probably isn't: '1' on line 2053 -- Looks like a reference, but probably isn't: '152' on line 2053 -- 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: March 19, 2014 RTFM 6 J. Hildebrand 7 Cisco 8 September 15, 2013 10 JSON Web Encryption (JWE) 11 draft-ietf-jose-json-web-encryption-16 13 Abstract 15 JSON Web Encryption (JWE) represents encrypted content using 16 JavaScript Object Notation (JSON) based data structures. 17 Cryptographic algorithms and identifiers for use with this 18 specification are described in the separate JSON Web Algorithms (JWA) 19 specification and IANA registries defined by that specification. 20 Related digital signature and MAC capabilities are described in the 21 separate JSON Web Signature (JWS) specification. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on March 19, 2014. 40 Copyright Notice 42 Copyright (c) 2013 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 9 61 3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 9 62 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11 63 4.1. Registered Header Parameter Names . . . . . . . . . . . . 11 64 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 11 65 4.1.2. "enc" (Encryption Method) Header Parameter . . . . . . 12 66 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 12 67 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 12 68 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 13 69 4.1.6. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 13 70 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header 71 Parameter . . . . . . . . . . . . . . . . . . . . . . 13 72 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 14 73 4.1.9. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14 74 4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 14 75 4.1.11. "cty" (Content Type) Header Parameter . . . . . . . . 15 76 4.1.12. "crit" (Critical) Header Parameter . . . . . . . . . . 15 77 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 16 78 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 16 79 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 16 80 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 16 81 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 18 82 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 21 83 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 21 84 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 21 85 7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 21 86 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 22 87 8. Distinguishing Between JWS and JWE Objects . . . . . . . . . . 25 88 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 89 9.1. JWE Header Parameter Names Registration . . . . . . . . . 25 90 9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 26 91 10. Security Considerations . . . . . . . . . . . . . . . . . . . 27 92 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 93 11.1. Normative References . . . . . . . . . . . . . . . . . . . 27 94 11.2. Informative References . . . . . . . . . . . . . . . . . . 29 95 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 30 96 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 30 97 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 30 98 A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 30 99 A.1.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 30 100 A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 31 101 A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 31 102 A.1.6. Initialization Vector . . . . . . . . . . . . . . . . 32 103 A.1.7. Additional Authenticated Data . . . . . . . . . . . . 32 104 A.1.8. Content Encryption . . . . . . . . . . . . . . . . . . 32 105 A.1.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 33 106 A.1.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 33 107 A.1.11. Complete Representation . . . . . . . . . . . . . . . 33 108 A.1.12. Validation . . . . . . . . . . . . . . . . . . . . . . 33 109 A.2. Example JWE using RSAES-PKCS1-V1_5 and 110 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 34 111 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 34 112 A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 34 113 A.2.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 34 114 A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 34 115 A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 35 116 A.2.6. Initialization Vector . . . . . . . . . . . . . . . . 36 117 A.2.7. Additional Authenticated Data . . . . . . . . . . . . 36 118 A.2.8. Content Encryption . . . . . . . . . . . . . . . . . . 36 119 A.2.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 36 120 A.2.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 37 121 A.2.11. Complete Representation . . . . . . . . . . . . . . . 37 122 A.2.12. Validation . . . . . . . . . . . . . . . . . . . . . . 37 123 A.3. Example JWE using AES Key Wrap and 124 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 37 125 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 38 126 A.3.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 38 127 A.3.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 38 128 A.3.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 38 129 A.3.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 39 130 A.3.6. Initialization Vector . . . . . . . . . . . . . . . . 39 131 A.3.7. Additional Authenticated Data . . . . . . . . . . . . 39 132 A.3.8. Content Encryption . . . . . . . . . . . . . . . . . . 39 133 A.3.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 40 134 A.3.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 40 135 A.3.11. Complete Representation . . . . . . . . . . . . . . . 40 136 A.3.12. Validation . . . . . . . . . . . . . . . . . . . . . . 40 137 A.4. Example JWE Using JWE JSON Serialization . . . . . . . . . 40 138 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 41 139 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 41 140 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 41 141 A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 42 142 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 42 143 A.4.6. Content Encryption . . . . . . . . . . . . . . . . . . 42 144 A.4.7. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 42 145 A.4.8. Encoded JWE Authentication Tag . . . . . . . . . . . . 43 146 A.4.9. Complete JWE JSON Serialization Representation . . . . 43 147 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 43 148 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 44 149 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 44 150 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 44 151 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 45 152 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 45 153 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 45 154 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 45 155 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 46 156 Appendix D. Document History . . . . . . . . . . . . . . . . . . 46 157 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 54 159 1. Introduction 161 JSON Web Encryption (JWE) represents encrypted content using 162 JavaScript Object Notation (JSON) [RFC4627] based data structures. 163 The JWE cryptographic mechanisms encrypt and provide integrity 164 protection for an arbitrary sequence of octets. 166 Two closely related serializations for JWE objects are defined. The 167 JWE Compact Serialization is a compact, URL-safe representation 168 intended for space constrained environments such as HTTP 169 Authorization headers and URI query parameters. The JWE JSON 170 Serialization represents JWE objects as JSON objects and enables the 171 same content to be encrypted to multiple parties. Both share the 172 same cryptographic underpinnings. 174 Cryptographic algorithms and identifiers for use with this 175 specification are described in the separate JSON Web Algorithms (JWA) 176 [JWA] specification and IANA registries defined by that 177 specification. Related digital signature and MAC capabilities are 178 described in the separate JSON Web Signature (JWS) [JWS] 179 specification. 181 Names defined by this specification are short because a core goal is 182 for the resulting representations to be compact. 184 1.1. Notational Conventions 186 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 187 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 188 document are to be interpreted as described in Key words for use in 189 RFCs to Indicate Requirement Levels [RFC2119]. If these words are 190 used without being spelled in uppercase then they are to be 191 interpreted with their normal natural language meanings. 193 2. Terminology 195 JSON Web Encryption (JWE) A data structure representing an encrypted 196 message. The structure represents five values: the JWE Header, 197 the JWE Encrypted Key, the JWE Initialization Vector, the JWE 198 Ciphertext, and the JWE Authentication Tag. 200 Authenticated Encryption with Associated Data (AEAD) An AEAD 201 algorithm is one that encrypts the Plaintext, allows Additional 202 Authenticated Data to be specified, and provides an integrated 203 content integrity check over the Ciphertext and Additional 204 Authenticated Data. AEAD algorithms accept two inputs, the 205 Plaintext and the Additional Authenticated Data value, and produce 206 two outputs, the Ciphertext and the Authentication Tag value. AES 207 Galois/Counter Mode (GCM) is one such algorithm. 209 Plaintext The sequence of octets to be encrypted -- a.k.a., the 210 message. The plaintext can contain an arbitrary sequence of 211 octets. 213 Ciphertext An encrypted representation of the Plaintext. 215 Additional Authenticated Data (AAD) An input to an AEAD operation 216 that is integrity protected but not encrypted. 218 Authentication Tag An output of an AEAD operation that ensures the 219 integrity of the Ciphertext and the Additional Authenticated Data. 220 Note that some algorithms may not use an Authentication Tag, in 221 which case this value is the empty octet sequence. 223 Content Encryption Key (CEK) A symmetric key for the AEAD algorithm 224 used to encrypt the Plaintext for the recipient to produce the 225 Ciphertext and the Authentication Tag. 227 JSON Text Object A UTF-8 [RFC3629] encoded text string representing 228 a JSON object; the syntax of JSON objects is defined in Section 229 2.2 of [RFC4627]. 231 JWE Header A JSON Text Object (or JSON Text Objects, when using the 232 JWE JSON Serialization) that describes the encryption operations 233 applied to create the JWE Encrypted Key, the JWE Ciphertext, and 234 the JWE Authentication Tag. The members of the JWE Header 235 object(s) are Header Parameters. 237 JWE Encrypted Key The result of encrypting the Content Encryption 238 Key (CEK) with the intended recipient's key using the specified 239 algorithm. Note that for some algorithms, the JWE Encrypted Key 240 value is specified as being the empty octet sequence. 242 JWE Initialization Vector A sequence of octets containing the 243 Initialization Vector used when encrypting the Plaintext. Note 244 that some algorithms may not use an Initialization Vector, in 245 which case this value is the empty octet sequence. 247 JWE Ciphertext A sequence of octets containing the Ciphertext for a 248 JWE. 250 JWE Authentication Tag A sequence of octets containing the 251 Authentication Tag for a JWE. 253 JWE Protected Header A JSON Text Object that contains the portion of 254 the JWE Header that is integrity protected. For the JWE Compact 255 Serialization, this comprises the entire JWE Header. For the JWE 256 JSON Serialization, this is one component of the JWE Header. 258 Header Parameter A name/value pair that is member of the JWE Header. 260 Header Parameter Name The name of a member of the JWE Header. 262 Header Parameter Value The value of a member of the JWE Header. 264 Base64url Encoding Base64 encoding using the URL- and filename-safe 265 character set defined in Section 5 of RFC 4648 [RFC4648], with all 266 trailing '=' characters omitted (as permitted by Section 3.2). 267 (See Appendix C of [JWS] for notes on implementing base64url 268 encoding without padding.) 270 Encoded JWE Header Base64url encoding of the JWE Protected Header. 272 Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted 273 Key. 275 Encoded JWE Initialization Vector Base64url encoding of the JWE 276 Initialization Vector. 278 Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. 280 Encoded JWE Authentication Tag Base64url encoding of the JWE 281 Authentication Tag. 283 JWE Compact Serialization A representation of the JWE as the 284 concatenation of the Encoded JWE Header, the Encoded JWE Encrypted 285 Key, the Encoded JWE Initialization Vector, the Encoded JWE 286 Ciphertext, and the Encoded JWE Authentication Tag in that order, 287 with the five strings being separated by four period ('.') 288 characters. This representation is compact and URL-safe. 290 JWE JSON Serialization A representation of the JWE as a JSON 291 structure containing JWE Header, Encoded JWE Encrypted Key, 292 Encoded JWE Initialization Vector, Encoded JWE Ciphertext, and 293 Encoded JWE Authentication Tag values. Unlike the JWE Compact 294 Serialization, the JWE JSON Serialization enables the same content 295 to be encrypted to multiple parties. This representation is 296 neither compact nor URL-safe. 298 Collision Resistant Name A name in a namespace that enables names to 299 be allocated in a manner such that they are highly unlikely to 300 collide with other names. Examples of collision resistant 301 namespaces include: Domain Names, Object Identifiers (OIDs) as 302 defined in the ITU-T X.660 and X.670 Recommendation series, and 303 Universally Unique IDentifiers (UUIDs) [RFC4122]. When using an 304 administratively delegated namespace, the definer of a name needs 305 to take reasonable precautions to ensure they are in control of 306 the portion of the namespace they use to define the name. 308 StringOrURI A JSON string value, with the additional requirement 309 that while arbitrary string values MAY be used, any value 310 containing a ":" character MUST be a URI [RFC3986]. StringOrURI 311 values are compared as case-sensitive strings with no 312 transformations or canonicalizations applied. 314 Key Management Mode A method of determining the Content Encryption 315 Key (CEK) value to use. Each algorithm used for determining the 316 CEK value uses a specific Key Management Mode. Key Management 317 Modes employed by this specification are Key Encryption, Key 318 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 319 and Direct Encryption. 321 Key Encryption A Key Management Mode in which the Content Encryption 322 Key (CEK) value is encrypted to the intended recipient using an 323 asymmetric encryption algorithm. 325 Key Wrapping A Key Management Mode in which the Content Encryption 326 Key (CEK) value is encrypted to the intended recipient using a 327 symmetric key wrapping algorithm. 329 Direct Key Agreement A Key Management Mode in which a key agreement 330 algorithm is used to agree upon the Content Encryption Key (CEK) 331 value. 333 Key Agreement with Key Wrapping A Key Management Mode in which a key 334 agreement algorithm is used to agree upon a symmetric key used to 335 encrypt the Content Encryption Key (CEK) value to the intended 336 recipient using a symmetric key wrapping algorithm. 338 Direct Encryption A Key Management Mode in which the Content 339 Encryption Key (CEK) value used is the secret symmetric key value 340 shared between the parties. 342 3. JSON Web Encryption (JWE) Overview 344 JWE represents encrypted content using JSON data structures and 345 base64url encoding. Five values are represented in a JWE: the JWE 346 Header, the JWE Encrypted Key, the JWE Initialization Vector, the JWE 347 Ciphertext, and the JWE Authentication Tag. In the Compact 348 Serialization, the five values are base64url-encoded for 349 transmission, and represented as the concatenation of the encoded 350 strings in that order, with the five strings being separated by four 351 period ('.') characters. A JSON Serialization for this information 352 is also defined in Section 7.2. 354 JWE utilizes authenticated encryption to ensure the confidentiality 355 and integrity of the Plaintext and the integrity of the JWE Protected 356 Header. 358 3.1. Example JWE 360 This example encrypts the plaintext "The true sign of intelligence is 361 not knowledge but imagination." to the recipient using RSAES OAEP for 362 key encryption and AES GCM for content encryption. 364 The following example JWE Header declares that: 366 o the Content Encryption Key is encrypted to the recipient using the 367 RSAES OAEP algorithm to produce the JWE Encrypted Key and 369 o the Plaintext is encrypted using the AES GCM algorithm with a 256 370 bit key to produce the Ciphertext. 372 {"alg":"RSA-OAEP","enc":"A256GCM"} 374 Base64url encoding the octets of the UTF-8 representation of the JWE 375 Header yields this Encoded JWE Header value: 377 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 379 The remaining steps to finish creating this JWE are: 381 o Generate a random Content Encryption Key (CEK). 383 o Encrypt the CEK with the recipient's public key using the RSAES 384 OAEP algorithm to produce the JWE Encrypted Key. 386 o Base64url encode the JWE Encrypted Key to produce the Encoded JWE 387 Encrypted Key. 389 o Generate a random JWE Initialization Vector. 391 o Base64url encode the JWE Initialization Vector to produce the 392 Encoded JWE Initialization Vector. 394 o Let the Additional Authenticated Data encryption parameter be the 395 octets of the ASCII representation of the Encoded JWE Header 396 value. 398 o Encrypt the Plaintext with AES GCM using the CEK as the encryption 399 key, the JWE Initialization Vector, and the Additional 400 Authenticated Data value, requesting a 128 bit Authentication Tag 401 output. 403 o Base64url encode the Ciphertext to create the Encoded JWE 404 Ciphertext. 406 o Base64url encode the Authentication Tag to create the Encoded JWE 407 Authentication Tag. 409 o Assemble the final representation: The Compact Serialization of 410 this result is the concatenation of the Encoded JWE Header, the 411 Encoded JWE Encrypted Key, the Encoded JWE Initialization Vector, 412 the Encoded JWE Ciphertext, and the Encoded JWE Authentication Tag 413 in that order, with the five strings being separated by four 414 period ('.') characters. 416 The final result in this example (with line breaks for display 417 purposes only) is: 419 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 420 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 421 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 422 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 423 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 424 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 425 6UklfCpIMfIjf7iGdXKHzg. 426 48V1_ALb6US04U3b. 427 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 428 SdiwkIr3ajwQzaBtQD_A. 429 XFBoMYUZodetZdvTiFvSkQ 431 See Appendix A.1 for the complete details of computing this JWE. See 432 Appendix A for additional examples. 434 4. JWE Header 436 The members of the JSON object(s) representing the JWE Header 437 describe the encryption applied to the Plaintext and optionally 438 additional properties of the JWE. The Header Parameter Names within 439 the JWE Header MUST be unique; recipients MUST either reject JWEs 440 with duplicate Header Parameter Names or use a JSON parser that 441 returns only the lexically last duplicate member name, as specified 442 in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. 444 Implementations are required to understand the specific header 445 parameters defined by this specification that are designated as "MUST 446 be understood" and process them in the manner defined in this 447 specification. All other header parameters defined by this 448 specification that are not so designated MUST be ignored when not 449 understood. Unless listed as a critical header parameter, per 450 Section 4.1.12, all header parameters not defined by this 451 specification MUST be ignored when not understood. 453 There are three classes of Header Parameter Names: Registered Header 454 Parameter Names, Public Header Parameter Names, and Private Header 455 Parameter Names. 457 4.1. Registered Header Parameter Names 459 The following Header Parameter Names are registered in the IANA JSON 460 Web Signature and Encryption Header Parameters registry defined in 461 [JWS], with meanings as defined below. 463 As indicated by the common registry, JWSs and JWEs share a common 464 header parameter space; when a parameter is used by both 465 specifications, its usage must be compatible between the 466 specifications. 468 4.1.1. "alg" (Algorithm) Header Parameter 470 The "alg" (algorithm) header parameter identifies the cryptographic 471 algorithm used to encrypt or determine the value of the Content 472 Encryption Key (CEK). The encrypted content is not usable if the 473 "alg" value does not represent a supported algorithm, or if the 474 recipient does not have a key that can be used with that algorithm. 475 "alg" values SHOULD either be registered in the IANA JSON Web 476 Signature and Encryption Algorithms registry defined in [JWA] or be a 477 value that contains a Collision Resistant Name. The "alg" value is a 478 case sensitive string containing a StringOrURI value. Use of this 479 header parameter is REQUIRED. This header parameter MUST be 480 understood and processed by implementations. 482 A list of defined "alg" values can be found in the IANA JSON Web 483 Signature and Encryption Algorithms registry defined in [JWA]; the 484 initial contents of this registry are the values defined in Section 485 4.1 of the JSON Web Algorithms (JWA) [JWA] specification. 487 4.1.2. "enc" (Encryption Method) Header Parameter 489 The "enc" (encryption method) header parameter identifies the content 490 encryption algorithm used to encrypt the Plaintext to produce the 491 Ciphertext. This algorithm MUST be an AEAD algorithm with a 492 specified key length. The recipient MUST reject the JWE if the "enc" 493 value does not represent a supported algorithm. "enc" values SHOULD 494 either be registered in the IANA JSON Web Signature and Encryption 495 Algorithms registry defined in [JWA] or be a value that contains a 496 Collision Resistant Name. The "enc" value is a case sensitive string 497 containing a StringOrURI value. Use of this header parameter is 498 REQUIRED. This header parameter MUST be understood and processed by 499 implementations. 501 A list of defined "enc" values can be found in the IANA JSON Web 502 Signature and Encryption Algorithms registry defined in [JWA]; the 503 initial contents of this registry are the values defined in Section 504 4.2 of the JSON Web Algorithms (JWA) [JWA] specification. 506 4.1.3. "zip" (Compression Algorithm) Header Parameter 508 The "zip" (compression algorithm) applied to the Plaintext before 509 encryption, if any. The "zip" value defined by this specification 510 is: 512 o "DEF" - Compression with the DEFLATE [RFC1951] algorithm 514 Other values MAY be used. Compression algorithm values can be 515 registered in the IANA JSON Web Encryption Compression Algorithm 516 registry defined in [JWA]. The "zip" value is a case sensitive 517 string. If no "zip" parameter is present, no compression is applied 518 to the Plaintext before encryption. This header parameter MUST be 519 integrity protected, and therefore MUST occur only within the JWE 520 Protected Header, when used. Use of this header parameter is 521 OPTIONAL. This header parameter MUST be understood and processed by 522 implementations. 524 4.1.4. "jku" (JWK Set URL) Header Parameter 526 The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that 527 refers to a resource for a set of JSON-encoded public keys, one of 528 which is the key to which the JWE was encrypted; this can be used to 529 determine the private key needed to decrypt the JWE. The keys MUST 530 be encoded as a JSON Web Key Set (JWK Set) [JWK]. The protocol used 531 to acquire the resource MUST provide integrity protection; an HTTP 532 GET request to retrieve the JWK Set MUST use TLS [RFC2818] [RFC5246]; 533 the identity of the server MUST be validated, as per Section 3.1 of 534 HTTP Over TLS [RFC2818]. Use of this header parameter is OPTIONAL. 536 4.1.5. "jwk" (JSON Web Key) Header Parameter 538 The "jwk" (JSON Web Key) header parameter is the public key to which 539 the JWE was encrypted; this can be used to determine the private key 540 needed to decrypt the JWE. This key is represented as a JSON Web Key 541 [JWK]. Use of this header parameter is OPTIONAL. 543 4.1.6. "x5u" (X.509 URL) Header Parameter 545 The "x5u" (X.509 URL) header parameter is a URI [RFC3986] that refers 546 to a resource for the X.509 public key certificate or certificate 547 chain [RFC5280] containing the key to which the JWE was encrypted; 548 this can be used to determine the private key needed to decrypt the 549 JWE. The identified resource MUST provide a representation of the 550 certificate or certificate chain that conforms to RFC 5280 [RFC5280] 551 in PEM encoded form [RFC1421]. The certificate containing the public 552 key to which the JWE was encrypted MUST be the first certificate. 553 This MAY be followed by additional certificates, with each subsequent 554 certificate being the one used to certify the previous one. The 555 protocol used to acquire the resource MUST provide integrity 556 protection; an HTTP GET request to retrieve the certificate MUST use 557 TLS [RFC2818] [RFC5246]; the identity of the server MUST be 558 validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. Use of 559 this header parameter is OPTIONAL. 561 4.1.7. "x5t" (X.509 Certificate SHA-1 Thumbprint) Header Parameter 563 The "x5t" (X.509 Certificate SHA-1 Thumbprint) header parameter is a 564 base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER 565 encoding of the X.509 certificate [RFC5280] containing the key to 566 which the JWE was encrypted; this can be used to determine the 567 private key needed to decrypt the JWE. Use of this header parameter 568 is OPTIONAL. 570 If, in the future, certificate thumbprints need to be computed using 571 hash functions other than SHA-1, it is suggested that additional 572 related header parameters be defined for that purpose. For example, 573 it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint 574 using SHA-256) header parameter could be defined by registering it in 575 the IANA JSON Web Signature and Encryption Header Parameters registry 576 defined in [JWS]. 578 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 580 The "x5c" (X.509 Certificate Chain) header parameter contains the 581 X.509 public key certificate or certificate chain [RFC5280] 582 containing the key to which the JWE was encrypted; this can be used 583 to determine the private key needed to decrypt the JWE. The 584 certificate or certificate chain is represented as a JSON array of 585 certificate value strings. Each string in the array is a base64 586 encoded ([RFC4648] Section 4 -- not base64url encoded) DER 587 [ITU.X690.1994] PKIX certificate value. The certificate containing 588 the public key to which the JWE was encrypted MUST be the first 589 certificate. This MAY be followed by additional certificates, with 590 each subsequent certificate being the one used to certify the 591 previous one. Use of this header parameter is OPTIONAL. 593 See Appendix B of [JWS] for an example "x5c" value. 595 4.1.9. "kid" (Key ID) Header Parameter 597 The "kid" (key ID) header parameter is a hint indicating which key to 598 which the JWE was encrypted; this can be used to determine the 599 private key needed to decrypt the JWE. This parameter allows 600 originators to explicitly signal a change of key to recipients. 601 Should the recipient be unable to locate a key corresponding to the 602 "kid" value, they SHOULD treat that condition as an error. The 603 interpretation of the "kid" value is unspecified. Its value MUST be 604 a string. Use of this header parameter is OPTIONAL. 606 When used with a JWK, the "kid" value can be used to match a JWK 607 "kid" parameter value. 609 4.1.10. "typ" (Type) Header Parameter 611 The "typ" (type) header parameter is used to declare the type of this 612 complete JWE object in an application-specific manner in contexts 613 where this is useful to the application. This parameter has no 614 effect upon the JWE processing. The type value "JOSE" can be used by 615 applications to indicate that this object is a JWS or JWE using the 616 JWS Compact Serialization or the JWE Compact Serialization. The type 617 value "JOSE+JSON" can be used by applications to indicate that this 618 object is a JWS or JWE using the JWS JSON Serialization or the JWE 619 JSON Serialization. Other type values can also be used by 620 applications. The "typ" value is a case sensitive string. Use of 621 this header parameter is OPTIONAL. 623 MIME Media Type [RFC2046] values MAY be used as "typ" values. When 624 MIME Media Type values are used, it is RECOMMENDED that they be 625 spelled using the exact character case used in the MIME Media Types 626 registry [IANA.MediaTypes], since this field is case sensitive, 627 whereas MIME Media Type values are case insensitive. 629 "typ" values SHOULD either be registered in the IANA JSON Web 630 Signature and Encryption Type Values registry defined in [JWS] or be 631 a value that contains a Collision Resistant Name. 633 4.1.11. "cty" (Content Type) Header Parameter 635 The "cty" (content type) header parameter is used to declare the type 636 of the encrypted content (the Plaintext) in an application-specific 637 manner in contexts where this is useful to the application. This 638 parameter has no effect upon the JWE processing. The "cty" value is 639 a case sensitive string. Use of this header parameter is OPTIONAL. 641 The values used for the "cty" header parameter come from the same 642 value space as the "typ" header parameter, with the same rules 643 applying. 645 4.1.12. "crit" (Critical) Header Parameter 647 The "crit" (critical) header parameter indicates that extensions to 648 [[ this specification ]] are being used that MUST be understood and 649 processed. Its value is an array listing the header parameter names 650 defined by those extensions that are used in the JWE Header. If any 651 of the listed extension header parameters are not understood and 652 supported by the receiver, it MUST reject the JWE. Senders MUST NOT 653 include header parameter names defined by [[ this specification ]] or 654 by [JWA] for use with JWE, duplicate names, or names that do not 655 occur as header parameter names within the JWE Header in the "crit" 656 list. Senders MUST not use the empty list "[]" as the "crit" value. 657 Recipients MAY reject the JWE if the critical list contains any 658 header parameter names defined by [[ this specification ]] or by 659 [JWA] for use with JWE, or any other constraints on its use are 660 violated. This header parameter MUST be integrity protected, and 661 therefore MUST occur only with the JWE Protected Header, when used. 662 Use of this header parameter is OPTIONAL. This header parameter MUST 663 be understood and processed by implementations. 665 An example use, along with a hypothetical "exp" (expiration-time) 666 field is: 668 {"alg":"RSA-OAEP", 669 "enc":"A256GCM", 670 "crit":["exp"], 671 "exp":1363284000 672 } 674 4.2. Public Header Parameter Names 676 Additional Header Parameter Names can be defined by those using JWEs. 677 However, in order to prevent collisions, any new Header Parameter 678 Name SHOULD either be registered in the IANA JSON Web Signature and 679 Encryption Header Parameters registry defined in [JWS] or be a Public 680 Name: a value that contains a Collision Resistant Name. In each 681 case, the definer of the name or value needs to take reasonable 682 precautions to make sure they are in control of the part of the 683 namespace they use to define the Header Parameter Name. 685 New header parameters should be introduced sparingly, as they can 686 result in non-interoperable JWEs. 688 4.3. Private Header Parameter Names 690 A producer and consumer of a JWE may agree to use Header Parameter 691 Names that are Private Names: names that are not Registered Header 692 Parameter Names Section 4.1 or Public Header Parameter Names 693 Section 4.2. Unlike Public Header Parameter Names, Private Header 694 Parameter Names are subject to collision and should be used with 695 caution. 697 5. Producing and Consuming JWEs 699 5.1. Message Encryption 701 The message encryption process is as follows. The order of the steps 702 is not significant in cases where there are no dependencies between 703 the inputs and outputs of the steps. 705 1. Determine the Key Management Mode employed by the algorithm used 706 to determine the Content Encryption Key (CEK) value. (This is 707 the algorithm recorded in the "alg" (algorithm) header parameter 708 of the resulting JWE.) 710 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 711 Wrapping are employed, generate a random Content Encryption Key 712 (CEK) value. See RFC 4086 [RFC4086] for considerations on 713 generating random values. The CEK MUST have a length equal to 714 that required for the content encryption algorithm. 716 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 717 employed, use the key agreement algorithm to compute the value 718 of the agreed upon key. When Direct Key Agreement is employed, 719 let the Content Encryption Key (CEK) be the agreed upon key. 720 When Key Agreement with Key Wrapping is employed, the agreed 721 upon key will be used to wrap the CEK. 723 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 724 Wrapping are employed, encrypt the CEK to the recipient and let 725 the result be the JWE Encrypted Key. 727 5. Otherwise, when Direct Key Agreement or Direct Encryption are 728 employed, let the JWE Encrypted Key be the empty octet sequence. 730 6. When Direct Encryption is employed, let the Content Encryption 731 Key (CEK) be the shared symmetric key. 733 7. Base64url encode the JWE Encrypted Key to create the Encoded JWE 734 Encrypted Key. 736 8. If the JWE JSON Serialization is being used, repeat this process 737 for each recipient. 739 9. Generate a random JWE Initialization Vector of the correct size 740 for the content encryption algorithm (if required for the 741 algorithm); otherwise, let the JWE Initialization Vector be the 742 empty octet sequence. 744 10. Base64url encode the JWE Initialization Vector to create the 745 Encoded JWE Initialization Vector. 747 11. Compress the Plaintext if a "zip" parameter was included. 749 12. Serialize the (compressed) Plaintext into an octet sequence M. 751 13. Create a JWE Header containing the encryption parameters used. 752 Note that white space is explicitly allowed in the 753 representation and no canonicalization need be performed before 754 encoding. 756 14. Base64url encode the octets of the UTF-8 representation of the 757 JWE Protected Header to create the Encoded JWE Header. If the 758 JWE Protected Header is not present (which can only happen when 759 using the JWE JSON Serialization and no "protected" member is 760 present), let the Encoded JWE Header be the empty string. 762 15. Let the Additional Authenticated Data encryption parameter be 763 the octets of the ASCII representation of the Encoded JWE Header 764 value. However if a top-level "aad" member is present when 765 using the JWE JSON Serialization, instead let the Additional 766 Authenticated Data encryption parameter be the octets of the 767 ASCII representation of the concatenation of the Encoded JWE 768 Header value, a period ('.') character, and the "aad" field 769 value. 771 16. Encrypt M using the CEK, the JWE Initialization Vector, and the 772 Additional Authenticated Data value using the specified content 773 encryption algorithm to create the JWE Ciphertext value and the 774 JWE Authentication Tag (which is the Authentication Tag output 775 from the encryption operation). 777 17. Base64url encode the JWE Ciphertext to create the Encoded JWE 778 Ciphertext. 780 18. Base64url encode the JWE Authentication Tag to create the 781 Encoded JWE Authentication Tag. 783 19. The five encoded parts are result values used in both the JWE 784 Compact Serialization and the JWE JSON Serialization 785 representations. 787 20. Create the desired serialized output. The JWE Compact 788 Serialization of this result is the concatenation of the Encoded 789 JWE Header, the Encoded JWE Encrypted Key, the Encoded JWE 790 Initialization Vector, the Encoded JWE Ciphertext, and the 791 Encoded JWE Authentication Tag in that order, with the five 792 strings being separated by four period ('.') characters. The 793 JWE JSON Serialization is described in Section 7.2. 795 5.2. Message Decryption 797 The message decryption process is the reverse of the encryption 798 process. The order of the steps is not significant in cases where 799 there are no dependencies between the inputs and outputs of the 800 steps. If any of these steps fails, the encrypted content cannot be 801 validated. 803 It is an application decision which recipients' encrypted content 804 must successfully validate for the JWE to be accepted. In some 805 cases, encrypted content for all recipients must successfully 806 validate or the JWE will be rejected. In other cases, only the 807 encrypted content for a single recipient needs to be successfully 808 validated. However, in all cases, the encrypted content for at least 809 one recipient MUST successfully validate or the JWE MUST be rejected. 811 1. Parse the serialized input to determine the values of the JWE 812 Header, the Encoded JWE Encrypted Key, the Encoded JWE 813 Initialization Vector, the Encoded JWE Ciphertext, and the 814 Encoded JWE Authentication Tag. When using the JWE Compact 815 Serialization, the Encoded JWE Header, the Encoded JWE Encrypted 816 Key, the Encoded JWE Initialization Vector, the Encoded JWE 817 Ciphertext, and the Encoded JWE Authentication Tag are 818 represented as text strings in that order, separated by four 819 period ('.') characters. The JWE JSON Serialization is 820 described in Section 7.2. 822 2. The Encoded JWE Header, the Encoded JWE Encrypted Key, the 823 Encoded JWE Initialization Vector, the Encoded JWE Ciphertext, 824 and the Encoded JWE Authentication Tag MUST be successfully 825 base64url decoded following the restriction that no padding 826 characters have been used. 828 3. The resulting JWE Protected Header MUST be a completely valid 829 JSON object conforming to RFC 4627 [RFC4627]. 831 4. If using the JWE Compact Serialization, let the JWE Header be 832 the JWE Protected Header; otherwise, when using the JWE JSON 833 Serialization, let the JWE Header be the union of the members of 834 the JWE Protected Header, the members of the "unprotected" 835 value, and the members of the corresponding "header" value, all 836 of which must be completely valid JSON objects. 838 5. The resulting JWE Header MUST NOT contain duplicate Header 839 Parameter Names. When using the JWE JSON Serialization, this 840 restriction includes that the same Header Parameter Name also 841 MUST NOT occur in distinct JSON Text Object values that together 842 comprise the JWE Header. 844 6. The resulting JWE Header MUST be validated to only include 845 parameters and values whose syntax and semantics are both 846 understood and supported or that are specified as being ignored 847 when not understood. 849 7. Determine the Key Management Mode employed by the algorithm 850 specified by the "alg" (algorithm) header parameter. 852 8. Verify that the JWE uses a key known to the recipient. 854 9. When Direct Key Agreement or Key Agreement with Key Wrapping are 855 employed, use the key agreement algorithm to compute the value 856 of the agreed upon key. When Direct Key Agreement is employed, 857 let the Content Encryption Key (CEK) be the agreed upon key. 858 When Key Agreement with Key Wrapping is employed, the agreed 859 upon key will be used to decrypt the JWE Encrypted Key. 861 10. When Key Wrapping, Key Encryption, or Key Agreement with Key 862 Wrapping are employed, decrypt the JWE Encrypted Key to produce 863 the Content Encryption Key (CEK). The CEK MUST have a length 864 equal to that required for the content encryption algorithm. 866 Note that when there are multiple recipients, each recipient 867 will only be able decrypt any JWE Encrypted Key values that were 868 encrypted to a key in that recipient's possession. It is 869 therefore normal to only be able to decrypt one of the per- 870 recipient JWE Encrypted Key values to obtain the CEK value. To 871 mitigate the attacks described in RFC 3218 [RFC3218], the 872 recipient MUST NOT distinguish between format, padding, and 873 length errors of encrypted keys. It is strongly recommended, in 874 the event of receiving an improperly formatted key, that the 875 receiver substitute a randomly generated CEK and proceed to the 876 next step, to mitigate timing attacks. 878 11. Otherwise, when Direct Key Agreement or Direct Encryption are 879 employed, verify that the JWE Encrypted Key value is empty octet 880 sequence. 882 12. When Direct Encryption is employed, let the Content Encryption 883 Key (CEK) be the shared symmetric key. 885 13. If the JWE JSON Serialization is being used, repeat this process 886 for each recipient contained in the representation until the CEK 887 value has been determined. 889 14. Let the Additional Authenticated Data encryption parameter be 890 the octets of the ASCII representation of the Encoded JWE Header 891 value. However if a top-level "aad" member is present when 892 using the JWE JSON Serialization, instead let the Additional 893 Authenticated Data encryption parameter be the octets of the 894 ASCII representation of the concatenation of the Encoded JWE 895 Header value, a period ('.') character, and the "aad" field 896 value. 898 15. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 899 Vector, the Additional Authenticated Data value, and the JWE 900 Authentication Tag (which is the Authentication Tag input to the 901 calculation) using the specified content encryption algorithm, 902 returning the decrypted plaintext and verifying the JWE 903 Authentication Tag in the manner specified for the algorithm, 904 rejecting the input without emitting any decrypted output if the 905 JWE Authentication Tag is incorrect. 907 16. Uncompress the decrypted plaintext if a "zip" parameter was 908 included. 910 17. Output the resulting Plaintext. 912 5.3. String Comparison Rules 914 Processing a JWE inevitably requires comparing known strings to 915 values in JSON objects. For example, in checking what the encryption 916 method is, the Unicode string encoding "enc" will be checked against 917 the member names in the JWE Header to see if there is a matching 918 Header Parameter Name. 920 Comparisons between JSON strings and other Unicode strings MUST be 921 performed by comparing Unicode code points without normalization as 922 specified in the String Comparison Rules in Section 5.3 of [JWS]. 924 6. Key Identification 926 It is necessary for the recipient of a JWE to be able to determine 927 the key that was employed for the encryption operation. The key 928 employed can be identified using the Header Parameter methods 929 described in Section 4.1 or can be identified using methods that are 930 outside the scope of this specification. Specifically, the Header 931 Parameters "jku", "jwk", "x5u", "x5t", "x5c", and "kid" can be used 932 to identify the key used. These header parameters MUST be integrity 933 protected if the information that they convey is to be utilized in a 934 trust decision. 936 The sender SHOULD include sufficient information in the Header 937 Parameters to identify the key used, unless the application uses 938 another means or convention to determine the key used. Validation of 939 the encrypted content fails when the key used cannot be determined. 941 The means of exchanging any shared symmetric keys used is outside the 942 scope of this specification. 944 7. Serializations 946 JWE objects use one of two serializations, the JWE Compact 947 Serialization or the JWE JSON Serialization. The JWE Compact 948 Serialization is mandatory to implement. Implementation of the JWE 949 JSON Serialization is OPTIONAL. 951 7.1. JWE Compact Serialization 953 The JWE Compact Serialization represents encrypted content as a 954 compact URL-safe string. This string is the concatenation of the 955 Encoded JWE Header, the Encoded JWE Encrypted Key, the Encoded JWE 956 Initialization Vector, the Encoded JWE Ciphertext, and the Encoded 957 JWE Authentication Tag in that order, with the five strings being 958 separated by four period ('.') characters. Only one recipient is 959 supported by the JWE Compact Serialization. 961 7.2. JWE JSON Serialization 963 The JWE JSON Serialization represents encrypted content as a JSON 964 object. Unlike the JWE Compact Serialization, content using the JWE 965 JSON Serialization can be encrypted to more than one recipient. 967 The representation is closely related to that used in the JWE Compact 968 Serialization, with the following differences for the JWE JSON 969 Serialization: 971 o Values in the JWE JSON Serialization are represented as members of 972 a JSON object, rather than as base64url encoded strings separated 973 by period ('.') characters. (However binary values and values 974 that are integrity protected are still base64url encoded.) 976 o The Encoded JWE Header value, if non-empty, is stored in the 977 "protected" member. 979 o The Encoded JWE Initialization Vector value, if non-empty, is 980 stored in the "iv" member. 982 o The Encoded JWE Ciphertext value is stored in the "ciphertext" 983 member. 985 o The Encoded JWE Authentication Tag value, if non-empty, is stored 986 in the "tag" member. 988 o The JWE can be encrypted to multiple recipients, rather than just 989 one. A JSON array in the "recipients" member is used to hold 990 values that are specific to a particular recipient, with one array 991 element per recipient represented. These array elements are JSON 992 objects. 994 o Each Encoded JWE Encrypted Key value, if non-empty, is stored in 995 the "encrypted_key" member of a JSON object that is an element of 996 the "recipients" array. 998 o Some header parameter values, such as the "alg" value and 999 parameters used for selecting keys, can also differ for different 1000 recipient computations. Per-recipient header parameter values, if 1001 present, are stored in the "header" members of the same JSON 1002 objects that are elements of the "recipients" array. 1004 o Some header parameters, including the "alg" parameter, can be 1005 shared among all recipient computations. These header parameters 1006 are stored in either of two top-level member(s) of the JSON 1007 object: the "protected" member and the "unprotected" member. The 1008 values of these members, if present, are JSON Text Objects 1009 containing Header Parameters. 1011 o Not all header parameters are integrity protected. The shared 1012 header parameters in the "protected" member are integrity 1013 protected, and are base64url encoded. The per-recipient header 1014 parameters in the "header" array element members and the shared 1015 header parameters in the "unprotected" member are not integrity 1016 protected. These JSON Text Objects containing header parameters 1017 that are not integrity protected are not base64url encoded. 1019 o The header parameter values used when creating or validating per- 1020 recipient Ciphertext and Authentication Tag values are the union 1021 of the three sets of header parameter values that may be present: 1022 (1) the per-recipient values in the "header" member of the 1023 recipient's array element, (2) the shared integrity-protected 1024 values in the "protected" member, and (3) the shared non- 1025 integrity-protected values in the "unprotected" member. The union 1026 of these sets of header parameters comprises the JWE Header. The 1027 header parameter names in the three locations MUST be disjoint. 1029 o An "aad" (Additional Authenticated Data) member can be included to 1030 supply a base64url encoded value to be integrity protected but not 1031 encrypted. (Note that this can also be achieved when using either 1032 serialization by including the AAD value as a protected header 1033 parameter value, but at the cost of the value being double 1034 base64url encoded.) 1036 o The "recipients" array MUST always be present, even if the array 1037 elements contain only the empty JSON object "{}" (which can happen 1038 when all header parameter values are shared between all recipients 1039 and when no encrypted key is used, such as when doing Direct 1040 Encryption). 1042 The syntax of a JWE using the JWE JSON Serialization is as follows: 1044 {"protected":", 1045 "unprotected":", 1046 "recipients":[ 1047 {"header":"", 1048 "encrypted_key":""}, 1049 ... 1050 {"header":"", 1051 "encrypted_key":""}], 1052 "aad":"", 1053 "iv":"", 1054 "ciphertext":"", 1055 "tag":"" 1056 } 1058 Of these members, only the "ciphertext" member MUST be present. The 1059 "iv", "tag", and "encrypted_key" members MUST be present when 1060 corresponding JWE Initialization Vector, JWE Authentication Tag, and 1061 JWE Encrypted Key values are non-empty. The "recipients" member MUST 1062 be present when any "header" or "encrypted_key" members are needed 1063 for recipients. At least one of the "header", "protected", and 1064 "unprotected" members MUST be present so that "alg" and "enc" header 1065 parameter values are conveyed for each recipient computation. 1067 The contents of the Encoded JWE Encrypted Key, Encoded JWE 1068 Initialization Vector, Encoded JWE Ciphertext, and Encoded JWE 1069 Authentication Tag values are exactly as defined in the rest of this 1070 specification. They are interpreted and validated in the same 1071 manner, with each corresponding Encoded JWE Encrypted Key, Encoded 1072 JWE Initialization Vector, Encoded JWE Ciphertext, Encoded JWE 1073 Authentication Tag, and set of header parameter values being created 1074 and validated together. The JWE Header values used are the union of 1075 the header parameters in the "protected", "unprotected", and 1076 corresponding "header" members, as described earlier. 1078 Each JWE Encrypted Key value is computed using the parameters of the 1079 corresponding JWE Header value in the same manner as for the JWE 1080 Compact Serialization. This has the desirable property that each 1081 Encoded JWE Encrypted Key value in the "recipients" array is 1082 identical to the value that would have been computed for the same 1083 parameter in the JWE Compact Serialization. Likewise, the JWE 1084 Ciphertext and JWE Authentication Tag values match those produced for 1085 the JWE Compact Serialization, provided that the Encoded JWE Header 1086 value (which represents the integrity-protected header parameter 1087 values) matches that used in the JWE Compact Serialization. 1089 All recipients use the same JWE Protected Header, JWE Initialization 1090 Vector, JWE Ciphertext, and JWE Authentication Tag values, resulting 1091 in potentially significant space savings if the message is large. 1092 Therefore, all header parameters that specify the treatment of the 1093 Plaintext value MUST be the same for all recipients. This primarily 1094 means that the "enc" (encryption method) header parameter value in 1095 the JWE Header for each recipient and any parameters of that 1096 algorithm MUST be the same. 1098 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1099 Serialization. 1101 8. Distinguishing Between JWS and JWE Objects 1103 There are several ways of distinguishing whether an object is a JWS 1104 or JWE object. All these methods will yield the same result for all 1105 legal input values. 1107 o If the object is using the JWS Compact Serialization or the JWE 1108 Compact Serialization, the number of base64url encoded segments 1109 separated by period ('.') characters differs for JWSs and JWEs. 1110 JWSs have three segments separated by two period ('.') characters. 1111 JWEs have five segments separated by four period ('.') characters. 1113 o If the object is using the JWS JSON Serialization or the JWE JSON 1114 Serialization, the members used will be different. JWSs have a 1115 "signatures" member and JWEs do not. JWEs have a "recipients" 1116 member and JWSs do not. 1118 o A JWS Header can be distinguished from a JWE header by examining 1119 the "alg" (algorithm) header parameter value. If the value 1120 represents a digital signature or MAC algorithm, or is the value 1121 "none", it is for a JWS; if it represents a Key Encryption, Key 1122 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 1123 or Direct Encryption algorithm, it is for a JWE. 1125 o A JWS Header can also be distinguished from a JWE header by 1126 determining whether an "enc" (encryption method) member exists. 1127 If the "enc" member exists, it is a JWE; otherwise, it is a JWS. 1129 9. IANA Considerations 1131 9.1. JWE Header Parameter Names Registration 1133 This specification registers the Header Parameter Names defined in 1134 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1135 Parameters registry defined in [JWS]. 1137 9.1.1. Registry Contents 1139 o Header Parameter Name: "alg" 1140 o Header Parameter Usage Location(s): JWE 1141 o Change Controller: IESG 1142 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1144 o Header Parameter Name: "enc" 1145 o Header Parameter Usage Location(s): JWE 1146 o Change Controller: IESG 1147 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1149 o Header Parameter Name: "zip" 1150 o Header Parameter Usage Location(s): JWE 1151 o Change Controller: IESG 1152 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1154 o Header Parameter Name: "jku" 1155 o Header Parameter Usage Location(s): JWE 1156 o Change Controller: IESG 1157 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1159 o Header Parameter Name: "jwk" 1160 o Header Parameter Usage Location(s): JWE 1161 o Change Controller: IESG 1162 o Specification document(s): Section 4.1.5 of [[ this document ]] 1164 o Header Parameter Name: "x5u" 1165 o Header Parameter Usage Location(s): JWE 1166 o Change Controller: IESG 1167 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1169 o Header Parameter Name: "x5t" 1170 o Header Parameter Usage Location(s): JWE 1171 o Change Controller: IESG 1172 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1174 o Header Parameter Name: "x5c" 1175 o Header Parameter Usage Location(s): JWE 1176 o Change Controller: IESG 1177 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1179 o Header Parameter Name: "kid" 1180 o Header Parameter Usage Location(s): JWE 1181 o Change Controller: IESG 1182 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1183 o Header Parameter Name: "typ" 1184 o Header Parameter Usage Location(s): JWE 1185 o Change Controller: IESG 1186 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1188 o Header Parameter Name: "cty" 1189 o Header Parameter Usage Location(s): JWE 1190 o Change Controller: IESG 1191 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1193 o Header Parameter Name: "crit" 1194 o Header Parameter Usage Location(s): JWE 1195 o Change Controller: IESG 1196 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1198 10. Security Considerations 1200 All of the security issues faced by any cryptographic application 1201 must be faced by a JWS/JWE/JWK agent. Among these issues are 1202 protecting the user's private and symmetric keys, preventing various 1203 attacks, and helping the user avoid mistakes such as inadvertently 1204 encrypting a message for the wrong recipient. The entire list of 1205 security considerations is beyond the scope of this document. 1207 All the security considerations in the JWS specification also apply 1208 to this specification. Likewise, all the security considerations in 1209 XML Encryption 1.1 [W3C.CR-xmlenc-core1-20120313] also apply, other 1210 than those that are XML specific. 1212 When decrypting, particular care must be taken not to allow the JWE 1213 recipient to be used as an oracle for decrypting messages. RFC 3218 1214 [RFC3218] should be consulted for specific countermeasures to attacks 1215 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1216 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1217 formatting error that can be detected and used to recover the CEK 1218 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1219 particularly important to report all formatting errors to the CEK, 1220 Additional Authenticated Data, or ciphertext as a single error when 1221 the encrypted content is rejected. 1223 11. References 1225 11.1. Normative References 1227 [ECMAScript] 1228 Ecma International, "ECMAScript Language Specification, 1229 5.1 Edition", ECMA 262, June 2011. 1231 [IANA.MediaTypes] 1232 Internet Assigned Numbers Authority (IANA), "MIME Media 1233 Types", 2005. 1235 [ITU.X690.1994] 1236 International Telecommunications Union, "Information 1237 Technology - ASN.1 encoding rules: Specification of Basic 1238 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1239 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1240 X.690, 1994. 1242 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1243 draft-ietf-jose-json-web-algorithms (work in progress), 1244 September 2013. 1246 [JWK] Jones, M., "JSON Web Key (JWK)", 1247 draft-ietf-jose-json-web-key (work in progress), 1248 September 2013. 1250 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1251 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1252 in progress), September 2013. 1254 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 1255 Mail: Part I: Message Encryption and Authentication 1256 Procedures", RFC 1421, February 1993. 1258 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1259 version 1.3", RFC 1951, May 1996. 1261 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1262 Extensions (MIME) Part Two: Media Types", RFC 2046, 1263 November 1996. 1265 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1266 Requirement Levels", BCP 14, RFC 2119, March 1997. 1268 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1270 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1271 10646", STD 63, RFC 3629, November 2003. 1273 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1274 Resource Identifier (URI): Generic Syntax", STD 66, 1275 RFC 3986, January 2005. 1277 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1278 Requirements for Security", BCP 106, RFC 4086, June 2005. 1280 [RFC4627] Crockford, D., "The application/json Media Type for 1281 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1283 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1284 Encodings", RFC 4648, October 2006. 1286 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1287 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1289 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1290 Housley, R., and W. Polk, "Internet X.509 Public Key 1291 Infrastructure Certificate and Certificate Revocation List 1292 (CRL) Profile", RFC 5280, May 2008. 1294 [W3C.CR-xmlenc-core1-20120313] 1295 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 1296 "XML Encryption Syntax and Processing Version 1.1", World 1297 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1298 March 2012, 1299 . 1301 11.2. Informative References 1303 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1304 McGrew, D. and K. Paterson, "Authenticated Encryption with 1305 AES-CBC and HMAC-SHA", 1306 draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), 1307 October 2012. 1309 [I-D.rescorla-jsms] 1310 Rescorla, E. and J. Hildebrand, "JavaScript Message 1311 Security Format", draft-rescorla-jsms-00 (work in 1312 progress), March 2011. 1314 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1315 Encryption", September 2010. 1317 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1318 Cryptographic Message Syntax", RFC 3218, January 2002. 1320 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1321 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1322 July 2005. 1324 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1325 RFC 5652, September 2009. 1327 Appendix A. JWE Examples 1329 This section provides examples of JWE computations. 1331 A.1. Example JWE using RSAES OAEP and AES GCM 1333 This example encrypts the plaintext "The true sign of intelligence is 1334 not knowledge but imagination." to the recipient using RSAES OAEP for 1335 key encryption and AES GCM for content encryption. The 1336 representation of this plaintext is: 1338 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1339 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1340 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1341 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1342 110, 97, 116, 105, 111, 110, 46] 1344 A.1.1. JWE Header 1346 The following example JWE Header declares that: 1348 o the Content Encryption Key is encrypted to the recipient using the 1349 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1351 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1352 bit key to produce the Ciphertext. 1354 {"alg":"RSA-OAEP","enc":"A256GCM"} 1356 A.1.2. Encoded JWE Header 1358 Base64url encoding the octets of the UTF-8 representation of the JWE 1359 Header yields this Encoded JWE Header value: 1361 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1363 A.1.3. Content Encryption Key (CEK) 1365 Generate a 256 bit random Content Encryption Key (CEK). In this 1366 example, the value is: 1368 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1369 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1370 234, 64, 252] 1372 A.1.4. Key Encryption 1374 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1375 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1376 key represented in JSON Web Key [JWK] format below (with line breaks 1377 for display purposes only): 1379 {"kty":"RSA", 1380 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1381 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1382 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1383 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1384 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1385 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1386 "e":"AQAB", 1387 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1388 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1389 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1390 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1391 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1392 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ" 1393 } 1395 The resulting JWE Encrypted Key value is: 1397 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1398 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1399 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1400 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1401 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1402 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1403 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1404 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1405 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1406 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1407 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1408 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1409 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1410 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1411 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1412 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1413 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1414 117, 114, 135, 206] 1416 A.1.5. Encoded JWE Encrypted Key 1418 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1419 Encrypted Key. This result (with line breaks for display purposes 1420 only) is: 1422 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1423 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1424 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1425 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1426 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1427 6UklfCpIMfIjf7iGdXKHzg 1429 A.1.6. Initialization Vector 1431 Generate a random 96 bit JWE Initialization Vector. In this example, 1432 the value is: 1434 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1436 Base64url encoding this value yields this Encoded JWE Initialization 1437 Vector value: 1439 48V1_ALb6US04U3b 1441 A.1.7. Additional Authenticated Data 1443 Let the Additional Authenticated Data encryption parameter be the 1444 octets of the ASCII representation of the Encoded JWE Header value. 1445 This AAD value is: 1447 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1448 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1449 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1451 A.1.8. Content Encryption 1453 Encrypt the Plaintext with AES GCM using the CEK as the encryption 1454 key, the JWE Initialization Vector, and the Additional Authenticated 1455 Data value above, requesting a 128 bit Authentication Tag output. 1456 The resulting Ciphertext is: 1458 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1459 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1460 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1461 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1462 160, 109, 64, 63, 192] 1464 The resulting Authentication Tag value is: 1466 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1467 210, 145] 1469 A.1.9. Encoded JWE Ciphertext 1471 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1472 This result (with line breaks for display purposes only) is: 1474 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1475 SdiwkIr3ajwQzaBtQD_A 1477 A.1.10. Encoded JWE Authentication Tag 1479 Base64url encode the Authentication Tag to create the Encoded JWE 1480 Authentication Tag. This result is: 1482 XFBoMYUZodetZdvTiFvSkQ 1484 A.1.11. Complete Representation 1486 Assemble the final representation: The Compact Serialization of this 1487 result is the concatenation of the Encoded JWE Header, the Encoded 1488 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1489 JWE Ciphertext, and the Encoded JWE Authentication Tag in that order, 1490 with the five strings being separated by four period ('.') 1491 characters. 1493 The final result in this example (with line breaks for display 1494 purposes only) is: 1496 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1497 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1498 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1499 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1500 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1501 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1502 6UklfCpIMfIjf7iGdXKHzg. 1503 48V1_ALb6US04U3b. 1504 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1505 SdiwkIr3ajwQzaBtQD_A. 1506 XFBoMYUZodetZdvTiFvSkQ 1508 A.1.12. Validation 1510 This example illustrates the process of creating a JWE with RSAES 1511 OAEP for key encryption and AES GCM for content encryption. These 1512 results can be used to validate JWE decryption implementations for 1513 these algorithms. Note that since the RSAES OAEP computation 1514 includes random values, the encryption results above will not be 1515 completely reproducible. However, since the AES GCM computation is 1516 deterministic, the JWE Encrypted Ciphertext values will be the same 1517 for all encryptions performed using these inputs. 1519 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1521 This example encrypts the plaintext "Live long and prosper." to the 1522 recipient using RSAES-PKCS1-V1_5 for key encryption and 1523 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1524 of this plaintext is: 1526 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1527 112, 114, 111, 115, 112, 101, 114, 46] 1529 A.2.1. JWE Header 1531 The following example JWE Header (with line breaks for display 1532 purposes only) declares that: 1534 o the Content Encryption Key is encrypted to the recipient using the 1535 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1537 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1538 algorithm to produce the Ciphertext. 1540 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1542 A.2.2. Encoded JWE Header 1544 Base64url encoding the octets of the UTF-8 representation of the JWE 1545 Header yields this Encoded JWE Header value: 1547 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1549 A.2.3. Content Encryption Key (CEK) 1551 Generate a 256 bit random Content Encryption Key (CEK). In this 1552 example, the key value is: 1554 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1555 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1556 44, 207] 1558 A.2.4. Key Encryption 1560 Encrypt the CEK with the recipient's public key using the RSAES- 1561 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1562 uses the RSA key represented in JSON Web Key [JWK] format below (with 1563 line breaks for display purposes only): 1565 {"kty":"RSA", 1566 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1567 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1568 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1569 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1570 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1571 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1572 "e":"AQAB", 1573 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1574 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1575 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1576 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1577 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1578 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1579 } 1581 The resulting JWE Encrypted Key value is: 1583 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1584 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1585 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1586 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1587 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1588 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1589 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1590 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1591 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1592 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1593 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1594 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1595 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1596 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1597 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1598 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1599 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1600 146, 114, 165, 204, 71, 136, 41, 252] 1602 A.2.5. Encoded JWE Encrypted Key 1604 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1605 Encrypted Key. This result (with line breaks for display purposes 1606 only) is: 1608 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1609 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1610 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1611 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1612 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1613 -B3oWh2TbqmScqXMR4gp_A 1615 A.2.6. Initialization Vector 1617 Generate a random 128 bit JWE Initialization Vector. In this 1618 example, the value is: 1620 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1621 101] 1623 Base64url encoding this value yields this Encoded JWE Initialization 1624 Vector value: 1626 AxY8DCtDaGlsbGljb3RoZQ 1628 A.2.7. Additional Authenticated Data 1630 Let the Additional Authenticated Data encryption parameter be the 1631 octets of the ASCII representation of the Encoded JWE Header value. 1632 This AAD value is: 1634 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1635 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1636 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1637 50, 73, 110, 48] 1639 A.2.8. Content Encryption 1641 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1642 the encryption key, the JWE Initialization Vector, and the Additional 1643 Authenticated Data value above. The steps for doing this using the 1644 values from Appendix A.3 are detailed in Appendix B. The resulting 1645 Ciphertext is: 1647 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1648 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1649 112, 56, 102] 1651 The resulting Authentication Tag value is: 1653 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1654 191] 1656 A.2.9. Encoded JWE Ciphertext 1658 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1659 This result is: 1661 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1663 A.2.10. Encoded JWE Authentication Tag 1665 Base64url encode the Authentication Tag to create the Encoded JWE 1666 Authentication Tag. This result is: 1668 9hH0vgRfYgPnAHOd8stkvw 1670 A.2.11. Complete Representation 1672 Assemble the final representation: The Compact Serialization of this 1673 result is the concatenation of the Encoded JWE Header, the Encoded 1674 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1675 JWE Ciphertext, and the Encoded JWE Authentication Tag in that order, 1676 with the five strings being separated by four period ('.') 1677 characters. 1679 The final result in this example (with line breaks for display 1680 purposes only) is: 1682 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1683 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1684 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1685 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1686 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1687 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1688 -B3oWh2TbqmScqXMR4gp_A. 1689 AxY8DCtDaGlsbGljb3RoZQ. 1690 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1691 9hH0vgRfYgPnAHOd8stkvw 1693 A.2.12. Validation 1695 This example illustrates the process of creating a JWE with RSAES- 1696 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1697 encryption. These results can be used to validate JWE decryption 1698 implementations for these algorithms. Note that since the RSAES- 1699 PKCS1-V1_5 computation includes random values, the encryption results 1700 above will not be completely reproducible. However, since the AES 1701 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1702 will be the same for all encryptions performed using these inputs. 1704 A.3. Example JWE using AES Key Wrap and AES_128_CBC_HMAC_SHA_256 1706 This example encrypts the plaintext "Live long and prosper." to the 1707 recipient using AES Key Wrap for key encryption and AES GCM for 1708 content encryption. The representation of this plaintext is: 1710 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1711 112, 114, 111, 115, 112, 101, 114, 46] 1713 A.3.1. JWE Header 1715 The following example JWE Header declares that: 1717 o the Content Encryption Key is encrypted to the recipient using the 1718 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1719 Encrypted Key and 1721 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1722 algorithm to produce the Ciphertext. 1724 {"alg":"A128KW","enc":"A128CBC-HS256"} 1726 A.3.2. Encoded JWE Header 1728 Base64url encoding the octets of the UTF-8 representation of the JWE 1729 Header yields this Encoded JWE Header value: 1731 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1733 A.3.3. Content Encryption Key (CEK) 1735 Generate a 256 bit random Content Encryption Key (CEK). In this 1736 example, the value is: 1738 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1739 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1740 44, 207] 1742 A.3.4. Key Encryption 1744 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1745 algorithm to produce the JWE Encrypted Key. This example uses the 1746 symmetric key represented in JSON Web Key [JWK] format below: 1748 {"kty":"oct", 1749 "k":"GawgguFyGrWKav7AX4VKUg" 1750 } 1752 The resulting JWE Encrypted Key value is: 1754 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1755 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1756 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1758 A.3.5. Encoded JWE Encrypted Key 1760 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1761 Encrypted Key. This result is: 1763 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1765 A.3.6. Initialization Vector 1767 Generate a random 128 bit JWE Initialization Vector. In this 1768 example, the value is: 1770 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1771 101] 1773 Base64url encoding this value yields this Encoded JWE Initialization 1774 Vector value: 1776 AxY8DCtDaGlsbGljb3RoZQ 1778 A.3.7. Additional Authenticated Data 1780 Let the Additional Authenticated Data encryption parameter be the 1781 octets of the ASCII representation of the Encoded JWE Header value. 1782 This AAD value is: 1784 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1785 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1786 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1787 110, 48] 1789 A.3.8. Content Encryption 1791 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1792 the encryption key, the JWE Initialization Vector, and the Additional 1793 Authenticated Data value above. The steps for doing this using the 1794 values from this example are detailed in Appendix B. The resulting 1795 Ciphertext is: 1797 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1798 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1799 112, 56, 102] 1801 The resulting Authentication Tag value is: 1803 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1804 194, 85] 1806 A.3.9. Encoded JWE Ciphertext 1808 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1809 This result is: 1811 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1813 A.3.10. Encoded JWE Authentication Tag 1815 Base64url encode the Authentication Tag to create the Encoded JWE 1816 Authentication Tag. This result is: 1818 U0m_YmjN04DJvceFICbCVQ 1820 A.3.11. Complete Representation 1822 Assemble the final representation: The Compact Serialization of this 1823 result is the concatenation of the Encoded JWE Header, the Encoded 1824 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1825 JWE Ciphertext, and the Encoded JWE Authentication Tag in that order, 1826 with the five strings being separated by four period ('.') 1827 characters. 1829 The final result in this example (with line breaks for display 1830 purposes only) is: 1832 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1833 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1834 AxY8DCtDaGlsbGljb3RoZQ. 1835 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1836 U0m_YmjN04DJvceFICbCVQ 1838 A.3.12. Validation 1840 This example illustrates the process of creating a JWE with AES Key 1841 Wrap for key encryption and AES GCM for content encryption. These 1842 results can be used to validate JWE decryption implementations for 1843 these algorithms. Also, since both the AES Key Wrap and AES GCM 1844 computations are deterministic, the resulting JWE value will be the 1845 same for all encryptions performed using these inputs. Since the 1846 computation is reproducible, these results can also be used to 1847 validate JWE encryption implementations for these algorithms. 1849 A.4. Example JWE Using JWE JSON Serialization 1851 This section contains an example using the JWE JSON Serialization. 1852 This example demonstrates the capability for encrypting the same 1853 plaintext to multiple recipients. 1855 Two recipients are present in this example. The algorithm and key 1856 used for the first recipient are the same as that used in 1857 Appendix A.2. The algorithm and key used for the second recipient 1858 are the same as that used in Appendix A.3. The resulting JWE 1859 Encrypted Key values are therefore the same; those computations are 1860 not repeated here. 1862 The Plaintext, the Content Encryption Key (CEK), Initialization 1863 Vector, and JWE Protected Header are shared by all recipients (which 1864 must be the case, since the Ciphertext and Authentication Tag are 1865 also shared). 1867 A.4.1. JWE Per-Recipient Unprotected Headers 1869 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1870 the Content Encryption Key (CEK). The second uses AES Key Wrap to 1871 encrypt the CEK. Key ID values are supplied for both keys. The two 1872 per-recipient header values used to represent these algorithms and 1873 Key IDs are: 1875 {"alg":"RSA1_5","kid":"2011-04-29"} 1877 and 1879 {"alg":"A128KW","kid":"7"} 1881 A.4.2. JWE Protected Header 1883 The Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1884 algorithm to produce the common JWE Ciphertext and JWE Authentication 1885 Tag values. The JWE Protected Header value representing this is: 1887 {"enc":"A128CBC-HS256"} 1889 Base64url encoding the octets of the UTF-8 representation of the JWE 1890 Protected Header yields this Encoded JWE Protected Header value: 1892 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1894 A.4.3. JWE Unprotected Header 1896 This JWE uses the "jku" header parameter to reference a JWK Set. This 1897 is represented in the following JWE Unprotected Header value as: 1899 {"jku":"https://server.example.com/keys.jwks"} 1901 A.4.4. Complete JWE Header Values 1903 Combining the per-recipient, protected, and unprotected header values 1904 supplied, the JWE Header values used for the first and second 1905 recipient respectively are: 1907 {"alg":"RSA1_5", 1908 "kid":"2011-04-29", 1909 "enc":"A128CBC-HS256", 1910 "jku":"https://server.example.com/keys.jwks"} 1912 and 1914 {"alg":"A128KW", 1915 "kid":"7", 1916 "enc":"A128CBC-HS256", 1917 "jku":"https://server.example.com/keys.jwks"} 1919 A.4.5. Additional Authenticated Data 1921 Let the Additional Authenticated Data encryption parameter be the 1922 octets of the ASCII representation of the Encoded JWE Protected 1923 Header value. This AAD value is: 1925 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1926 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1928 A.4.6. Content Encryption 1930 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1931 the encryption key, the JWE Initialization Vector, and the Additional 1932 Authenticated Data value above. The steps for doing this using the 1933 values from Appendix A.3 are detailed in Appendix B. The resulting 1934 Ciphertext is: 1936 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1937 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1938 112, 56, 102] 1940 The resulting Authentication Tag value is: 1942 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1943 207] 1945 A.4.7. Encoded JWE Ciphertext 1947 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1948 This result is: 1950 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1952 A.4.8. Encoded JWE Authentication Tag 1954 Base64url encode the Authentication Tag to create the Encoded JWE 1955 Authentication Tag. This result is: 1957 Mz-VPPyU4RlcuYv1IwIvzw 1959 A.4.9. Complete JWE JSON Serialization Representation 1961 The complete JSON Web Encryption JSON Serialization for these values 1962 is as follows (with line breaks for display purposes only): 1964 {"protected": 1965 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1966 "unprotected": 1967 {"jku":"https://server.example.com/keys.jwks"}, 1968 "recipients":[ 1969 {"header": 1970 {"alg":"RSA1_5"}, 1971 "encrypted_key": 1972 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1973 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1974 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 1975 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 1976 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 1977 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 1978 {"header": 1979 {"alg":"A128KW"}, 1980 "encrypted_key": 1981 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1982 "iv": 1983 "AxY8DCtDaGlsbGljb3RoZQ", 1984 "ciphertext": 1985 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1986 "tag": 1987 "Mz-VPPyU4RlcuYv1IwIvzw" 1988 } 1990 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 1992 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 1993 authenticated encryption computation using the values from the 1994 example in Appendix A.3. As described where this algorithm is 1995 defined in Sections 4.8 and 4.8.3 of JWA, the AES_CBC_HMAC_SHA2 1996 family of algorithms are implemented using Advanced Encryption 1997 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #5 1998 padding to perform the encryption and an HMAC SHA-2 function to 1999 perform the integrity calculation - in this case, HMAC SHA-256. 2001 B.1. Extract MAC_KEY and ENC_KEY from Key 2003 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example is: 2005 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 2006 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 2007 44, 207] 2009 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 2010 which is: 2012 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 2013 206] 2015 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 2016 is: 2018 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 2019 207] 2021 Note that the MAC key comes before the encryption key in the input 2022 key K; this is in the opposite order of the algorithm names in the 2023 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 2025 B.2. Encrypt Plaintext to Create Ciphertext 2027 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 2028 using PKCS #5 padding using the ENC_KEY above. The Plaintext in this 2029 example is: 2031 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 2032 112, 114, 111, 115, 112, 101, 114, 46] 2034 The encryption result is as follows, which is the Ciphertext output: 2036 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 2037 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 2038 112, 56, 102] 2040 B.3. 64 Bit Big Endian Representation of AAD Length 2042 The Additional Authenticated Data (AAD) in this example is: 2044 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2045 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2046 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2047 110, 48] 2049 This AAD is 51 bytes long, which is 408 bits long. The octet string 2050 AL, which is the number of bits in AAD expressed as a big endian 64 2051 bit unsigned integer is: 2053 [0, 0, 0, 0, 0, 0, 1, 152] 2055 B.4. Initialization Vector Value 2057 The Initialization Vector value used in this example is: 2059 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 2060 101] 2062 B.5. Create Input to HMAC Computation 2064 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 2065 the AL value. The result of this concatenation is: 2067 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2068 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2069 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2070 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 2071 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 2072 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 2073 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 2075 B.6. Compute HMAC Value 2077 Compute the HMAC SHA-256 of the concatenated value above. This 2078 result M is: 2080 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2081 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 2082 86, 229, 116] 2084 B.7. Truncate HMAC Value to Create Authentication Tag 2086 Use the first half (128 bits) of the HMAC output M as the 2087 Authentication Tag output T. This truncated value is: 2089 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2090 194, 85] 2092 Appendix C. Acknowledgements 2094 Solutions for encrypting JSON content were also explored by JSON 2095 Simple Encryption [JSE] and JavaScript Message Security Format 2096 [I-D.rescorla-jsms], both of which significantly influenced this 2097 draft. This draft attempts to explicitly reuse as many of the 2098 relevant concepts from XML Encryption 1.1 2099 [W3C.CR-xmlenc-core1-20120313] and RFC 5652 [RFC5652] as possible, 2100 while utilizing simple, compact JSON-based data structures. 2102 Special thanks are due to John Bradley and Nat Sakimura for the 2103 discussions that helped inform the content of this specification and 2104 to Eric Rescorla and Joe Hildebrand for allowing the reuse of text 2105 from [I-D.rescorla-jsms] in this document. 2107 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2108 Jay for validating the examples in this specification. 2110 This specification is the work of the JOSE Working Group, which 2111 includes dozens of active and dedicated participants. In particular, 2112 the following individuals contributed ideas, feedback, and wording 2113 that influenced this specification: 2115 Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick 2116 Hardt, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Tony 2117 Nadalin, Axel Nennker, Emmanuel Raviart, Nat Sakimura, Jim Schaad, 2118 Hannes Tschofenig, and Sean Turner. 2120 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2121 Sean Turner and Stephen Farrell served as Security area directors 2122 during the creation of this specification. 2124 Appendix D. Document History 2126 [[ to be removed by the RFC Editor before publication as an RFC ]] 2128 -16 2130 o Changes to address editorial and minor issues #163, #168, #169, 2131 #170, #172, and #173. 2133 -15 2135 o Clarified that it is an application decision which recipients' 2136 encrypted content must successfully validate for the JWE to be 2137 accepted, addressing issue #35. 2139 o Changes to address editorial issues #34, #164, and #169. 2141 -14 2143 o Clarified that the "protected", "unprotected", "header", "iv", 2144 "tag", and "encrypted_key" parameters are to be omitted in the JWE 2145 JSON Serialization when their values would be empty. Stated that 2146 the "recipients" array must always be present. 2148 -13 2150 o Added an "aad" (Additional Authenticated Data) member for the JWE 2151 JSON Serialization, enabling Additional Authenticated Data to be 2152 supplied that is not double base64url encoded, addressing issue 2153 #29. 2155 -12 2157 o Clarified that the "typ" and "cty" header parameters are used in 2158 an application-specific manner and have no effect upon the JWE 2159 processing. 2161 o Replaced the MIME types "application/jwe+json" and 2162 "application/jwe" with "application/jose+json" and 2163 "application/jose". 2165 o Stated that recipients MUST either reject JWEs with duplicate 2166 Header Parameter Names or use a JSON parser that returns only the 2167 lexically last duplicate member name. 2169 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2170 be with the algorithm descriptions that use them. 2172 o Added a Serializations section with parallel treatment of the JWE 2173 Compact Serialization and the JWE JSON Serialization and also 2174 moved the former Implementation Considerations content there. 2176 o Restored use of the term "AEAD". 2178 o Changed terminology from "block encryption" to "content 2179 encryption". 2181 -11 2183 o Added Key Identification section. 2185 o Removed the Encrypted Key value from the AAD computation since it 2186 is already effectively integrity protected by the encryption 2187 process. The AAD value now only contains the representation of 2188 the JWE Encrypted Header. 2190 o For the JWE JSON Serialization, enable header parameter values to 2191 be specified in any of three parameters: the "protected" member 2192 that is integrity protected and shared among all recipients, the 2193 "unprotected" member that is not integrity protected and shared 2194 among all recipients, and the "header" member that is not 2195 integrity protected and specific to a particular recipient. (This 2196 does not affect the JWE Compact Serialization, in which all header 2197 parameter values are in a single integrity protected JWE Header 2198 value.) 2200 o Shortened the names "authentication_tag" to "tag" and 2201 "initialization_vector" to "iv" in the JWE JSON Serialization, 2202 addressing issue #20. 2204 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2206 o Removed suggested compact serialization for multiple recipients. 2208 o Changed the MIME type name "application/jwe-js" to 2209 "application/jwe+json", addressing issue #22. 2211 o Tightened the description of the "crit" (critical) header 2212 parameter. 2214 -10 2216 o Changed the JWE processing rules for multiple recipients so that a 2217 single AAD value contains the header parameters and encrypted key 2218 values for all the recipients, enabling AES GCM to be safely used 2219 for multiple recipients. 2221 o Added an appendix suggesting a possible compact serialization for 2222 JWEs with multiple recipients. 2224 -09 2226 o Added JWE JSON Serialization, as specified by 2227 draft-jones-jose-jwe-json-serialization-04. 2229 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2230 parameter value. 2232 o Defined that the default action for header parameters that are not 2233 understood is to ignore them unless specifically designated as 2234 "MUST be understood" or included in the new "crit" (critical) 2235 header parameter list. This addressed issue #6. 2237 o Corrected "x5c" description. This addressed issue #12. 2239 o Changed from using the term "byte" to "octet" when referring to 8 2240 bit values. 2242 o Added Key Management Mode definitions to terminology section and 2243 used the defined terms to provide clearer key management 2244 instructions. This addressed issue #5. 2246 o Added text about preventing the recipient from behaving as an 2247 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2249 o Changed from using the term "Integrity Value" to "Authentication 2250 Tag". 2252 o Changed member name from "integrity_value" to "authentication_tag" 2253 in the JWE JSON Serialization. 2255 o Removed Initialization Vector from the AAD value since it is 2256 already integrity protected by all of the authenticated encryption 2257 algorithms specified in the JWA specification. 2259 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2260 and "A256CBC-HS512". The new algorithms perform the same 2261 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2262 but with the Initialization Vector and Authentication Tag values 2263 remaining separate from the Ciphertext value in the output 2264 representation. Also deleted the header parameters "epu" 2265 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2266 they are no longer used. 2268 -08 2270 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2271 since the term AEAD in the RFC 5116 sense implied the use of a 2272 particular data representation, rather than just referring to the 2273 class of algorithms that perform authenticated encryption with 2274 associated data. 2276 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2277 Tschofenig. Many of these simplified the terminology used. 2279 o Clarified statements of the form "This header parameter is 2280 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2282 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2283 Web Signature and Encryption Header Parameters registry. 2285 o Added seriesInfo information to Internet Draft references. 2287 -07 2289 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2291 o Updated values for example AES CBC calculations. 2293 o Made several local editorial changes to clean up loose ends left 2294 over from to the decision to only support block encryption methods 2295 providing integrity. One of these changes was to explicitly state 2296 that the "enc" (encryption method) algorithm must be an 2297 Authenticated Encryption algorithm with a specified key length. 2299 -06 2301 o Removed the "int" and "kdf" parameters and defined the new 2302 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2303 "A256CBC+HS512" to replace the former uses of AES CBC, which 2304 required the use of separate integrity and key derivation 2305 functions. 2307 o Included additional values in the Concat KDF calculation -- the 2308 desired output size and the algorithm value, and optionally 2309 PartyUInfo and PartyVInfo values. Added the optional header 2310 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2311 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2312 PartyVInfo). Updated the KDF examples accordingly. 2314 o Promoted Initialization Vector from being a header parameter to 2315 being a top-level JWE element. This saves approximately 16 bytes 2316 in the compact serialization, which is a significant savings for 2317 some use cases. Promoting the Initialization Vector out of the 2318 header also avoids repeating this shared value in the JSON 2319 serialization. 2321 o Changed "x5c" (X.509 Certificate Chain) representation from being 2322 a single string to being an array of strings, each containing a 2323 single base64 encoded DER certificate value, representing elements 2324 of the certificate chain. 2326 o Added an AES Key Wrap example. 2328 o Reordered the encryption steps so CMK creation is first, when 2329 required. 2331 o Correct statements in examples about which algorithms produce 2332 reproducible results. 2334 -05 2336 o Support both direct encryption using a shared or agreed upon 2337 symmetric key, and the use of a shared or agreed upon symmetric 2338 key to key wrap the CMK. 2340 o Added statement that "StringOrURI values are compared as case- 2341 sensitive strings with no transformations or canonicalizations 2342 applied". 2344 o Updated open issues. 2346 o Indented artwork elements to better distinguish them from the body 2347 text. 2349 -04 2351 o Refer to the registries as the primary sources of defined values 2352 and then secondarily reference the sections defining the initial 2353 contents of the registries. 2355 o Normatively reference XML Encryption 1.1 2356 [W3C.CR-xmlenc-core1-20120313] for its security considerations. 2358 o Reference draft-jones-jose-jwe-json-serialization instead of 2359 draft-jones-json-web-encryption-json-serialization. 2361 o Described additional open issues. 2363 o Applied editorial suggestions. 2365 -03 2367 o Added the "kdf" (key derivation function) header parameter to 2368 provide crypto agility for key derivation. The default KDF 2369 remains the Concat KDF with the SHA-256 digest function. 2371 o Reordered encryption steps so that the Encoded JWE Header is 2372 always created before it is needed as an input to the 2373 Authenticated Encryption "additional authenticated data" 2374 parameter. 2376 o Added the "cty" (content type) header parameter for declaring type 2377 information about the secured content, as opposed to the "typ" 2378 (type) header parameter, which declares type information about 2379 this object. 2381 o Moved description of how to determine whether a header is for a 2382 JWS or a JWE from the JWT spec to the JWE spec. 2384 o Added complete encryption examples for both Authenticated 2385 Encryption and non-Authenticated Encryption algorithms. 2387 o Added complete key derivation examples. 2389 o Added "Collision Resistant Namespace" to the terminology section. 2391 o Reference ITU.X690.1994 for DER encoding. 2393 o Added Registry Contents sections to populate registry values. 2395 o Numerous editorial improvements. 2397 -02 2399 o When using Authenticated Encryption algorithms (such as AES GCM), 2400 use the "additional authenticated data" parameter to provide 2401 integrity for the header, encrypted key, and ciphertext and use 2402 the resulting "authentication tag" value as the JWE Authentication 2403 Tag. 2405 o Defined KDF output key sizes. 2407 o Generalized text to allow key agreement to be employed as an 2408 alternative to key wrapping or key encryption. 2410 o Changed compression algorithm from gzip to DEFLATE. 2412 o Clarified that it is an error when a "kid" value is included and 2413 no matching key is found. 2415 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2416 rejected. 2418 o Clarified the relationship between "typ" header parameter values 2419 and MIME types. 2421 o Registered application/jwe MIME type and "JWE" typ header 2422 parameter value. 2424 o Simplified JWK terminology to get replace the "JWK Key Object" and 2425 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2426 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2427 between single keys and sets of keys. As part of this change, the 2428 Header Parameter Name for a public key value was changed from 2429 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2431 o Added suggestion on defining additional header parameters such as 2432 "x5t#S256" in the future for certificate thumbprints using hash 2433 algorithms other than SHA-1. 2435 o Specify RFC 2818 server identity validation, rather than RFC 6125 2436 (paralleling the same decision in the OAuth specs). 2438 o Generalized language to refer to Message Authentication Codes 2439 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2440 unless in a context specific to HMAC algorithms. 2442 o Reformatted to give each header parameter its own section heading. 2444 -01 2446 o Added an integrity check for non-Authenticated Encryption 2447 algorithms. 2449 o Added "jpk" and "x5c" header parameters for including JWK public 2450 keys and X.509 certificate chains directly in the header. 2452 o Clarified that this specification is defining the JWE Compact 2453 Serialization. Referenced the new JWE-JS spec, which defines the 2454 JWE JSON Serialization. 2456 o Added text "New header parameters should be introduced sparingly 2457 since an implementation that does not understand a parameter MUST 2458 reject the JWE". 2460 o Clarified that the order of the encryption and decryption steps is 2461 not significant in cases where there are no dependencies between 2462 the inputs and outputs of the steps. 2464 o Made other editorial improvements suggested by JOSE working group 2465 participants. 2467 -00 2469 o Created the initial IETF draft based upon 2470 draft-jones-json-web-encryption-02 with no normative changes. 2472 o Changed terminology to no longer call both digital signatures and 2473 HMACs "signatures". 2475 Authors' Addresses 2477 Michael B. Jones 2478 Microsoft 2480 Email: mbj@microsoft.com 2481 URI: http://self-issued.info/ 2483 Eric Rescorla 2484 RTFM, Inc. 2486 Email: ekr@rtfm.com 2488 Joe Hildebrand 2489 Cisco Systems, Inc. 2491 Email: jhildebr@cisco.com