idnits 2.17.1 draft-ietf-jose-json-web-encryption-11.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 ]], 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 any other constraints on its use are violated. This header parameter MUST be integrity protected, and therefore MUST occur only with the JWE Protected Header, when used. Use of this header parameter is OPTIONAL. This header parameter MUST be understood by implementations. -- The document date (May 28, 2013) is 3987 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 2168 -- Looks like a reference, but probably isn't: '0' on line 2168 -- Looks like a reference, but probably isn't: '227' on line 1518 -- Looks like a reference, but probably isn't: '197' on line 1518 -- Looks like a reference, but probably isn't: '117' on line 1518 -- Looks like a reference, but probably isn't: '252' on line 1518 -- Looks like a reference, but probably isn't: '2' on line 1518 -- Looks like a reference, but probably isn't: '219' on line 1518 -- Looks like a reference, but probably isn't: '233' on line 1518 -- Looks like a reference, but probably isn't: '68' on line 1518 -- Looks like a reference, but probably isn't: '180' on line 1518 -- Looks like a reference, but probably isn't: '225' on line 1518 -- Looks like a reference, but probably isn't: '77' on line 1518 -- Looks like a reference, but probably isn't: '152' on line 2168 -- 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 4288 (Obsoleted by RFC 6838) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) == Outdated reference: A later version (-05) exists of draft-mcgrew-aead-aes-cbc-hmac-sha2-01 Summary: 6 errors (**), 0 flaws (~~), 3 warnings (==), 16 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: November 29, 2013 RTFM 6 J. Hildebrand 7 Cisco 8 May 28, 2013 10 JSON Web Encryption (JWE) 11 draft-ietf-jose-json-web-encryption-11 13 Abstract 15 JSON Web Encryption (JWE) is a means of representing encrypted 16 content using JavaScript Object Notation (JSON) based data 17 structures. Cryptographic algorithms and identifiers for use with 18 this specification are described in the separate JSON Web Algorithms 19 (JWA) specification. Related digital signature and MAC capabilities 20 are described in the separate JSON Web Signature (JWS) specification. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on November 29, 2013. 39 Copyright Notice 41 Copyright (c) 2013 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 58 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 8 60 3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 9 61 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10 62 4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 11 63 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 11 64 4.1.2. "enc" (Encryption Method) Header Parameter . . . . . . 12 65 4.1.3. "epk" (Ephemeral Public Key) Header Parameter . . . . 12 66 4.1.4. "zip" (Compression Algorithm) Header Parameter . . . . 12 67 4.1.5. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 13 68 4.1.6. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 13 69 4.1.7. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 13 70 4.1.8. "x5t" (X.509 Certificate Thumbprint) Header 71 Parameter . . . . . . . . . . . . . . . . . . . . . . 13 72 4.1.9. "x5c" (X.509 Certificate Chain) Header Parameter . . . 14 73 4.1.10. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14 74 4.1.11. "typ" (Type) Header Parameter . . . . . . . . . . . . 14 75 4.1.12. "cty" (Content Type) Header Parameter . . . . . . . . 15 76 4.1.13. "apu" (Agreement PartyUInfo) Header Parameter . . . . 15 77 4.1.14. "crit" (Critical) Header Parameter . . . . . . . . . . 15 78 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 16 79 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 16 80 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 16 81 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 16 82 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 18 83 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20 84 6. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 21 85 6.1. CEK Encryption . . . . . . . . . . . . . . . . . . . . . . 21 86 7. Key Identification . . . . . . . . . . . . . . . . . . . . . . 21 87 8. JWE JSON Serialization . . . . . . . . . . . . . . . . . . . . 22 88 9. Implementation Considerations . . . . . . . . . . . . . . . . 24 89 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 90 10.1. Registration of JWE Header Parameter Names . . . . . . . . 24 91 10.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 25 92 10.2. JSON Web Signature and Encryption Type Values 93 Registration . . . . . . . . . . . . . . . . . . . . . . . 26 94 10.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 26 95 10.3. Media Type Registration . . . . . . . . . . . . . . . . . 26 96 10.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 27 97 11. Security Considerations . . . . . . . . . . . . . . . . . . . 28 98 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 99 12.1. Normative References . . . . . . . . . . . . . . . . . . . 28 100 12.2. Informative References . . . . . . . . . . . . . . . . . . 30 101 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 30 102 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 30 103 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 31 104 A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 31 105 A.1.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 31 106 A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 31 107 A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 34 108 A.1.6. Initialization Vector . . . . . . . . . . . . . . . . 34 109 A.1.7. Additional Authenticated Data . . . . . . . . . . . . 34 110 A.1.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 34 111 A.1.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 35 112 A.1.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 35 113 A.1.11. Complete Representation . . . . . . . . . . . . . . . 35 114 A.1.12. Validation . . . . . . . . . . . . . . . . . . . . . . 36 115 A.2. Example JWE using RSAES-PKCS1-V1_5 and 116 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 36 117 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 36 118 A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 36 119 A.2.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 36 120 A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 37 121 A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 39 122 A.2.6. Initialization Vector . . . . . . . . . . . . . . . . 39 123 A.2.7. Additional Authenticated Data . . . . . . . . . . . . 39 124 A.2.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 39 125 A.2.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 40 126 A.2.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 40 127 A.2.11. Complete Representation . . . . . . . . . . . . . . . 40 128 A.2.12. Validation . . . . . . . . . . . . . . . . . . . . . . 40 129 A.3. Example JWE using AES Key Wrap and AES GCM . . . . . . . . 41 130 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 41 131 A.3.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 41 132 A.3.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 41 133 A.3.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 41 134 A.3.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 42 135 A.3.6. Initialization Vector . . . . . . . . . . . . . . . . 42 136 A.3.7. Additional Authenticated Data . . . . . . . . . . . . 42 137 A.3.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 42 138 A.3.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 43 139 A.3.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 43 140 A.3.11. Complete Representation . . . . . . . . . . . . . . . 43 141 A.3.12. Validation . . . . . . . . . . . . . . . . . . . . . . 43 142 A.4. Example JWE Using JWE JSON Serialization . . . . . . . . . 44 143 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 44 144 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 44 145 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 45 146 A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 45 147 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 45 148 A.4.6. Plaintext Encryption . . . . . . . . . . . . . . . . . 45 149 A.4.7. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 46 150 A.4.8. Encoded JWE Authentication Tag . . . . . . . . . . . . 46 151 A.4.9. Complete JWE JSON Serialization Representation . . . . 46 152 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 47 153 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 47 154 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 47 155 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 48 156 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 48 157 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 48 158 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 48 159 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 49 160 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 49 161 Appendix D. Document History . . . . . . . . . . . . . . . . . . 49 162 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 56 164 1. Introduction 166 JSON Web Encryption (JWE) is a means of representing encrypted 167 content using JavaScript Object Notation (JSON) [RFC4627] based data 168 structures. The JWE cryptographic mechanisms encrypt and provide 169 integrity protection for arbitrary sequences of octets. 171 Two closely related representations for JWE objects are defined. The 172 JWE Compact Serialization is a compact, URL-safe representation 173 intended for space constrained environments such as HTTP 174 Authorization headers and URI query parameters. The JWE JSON 175 Serialization represents JWE objects as JSON objects and enables the 176 same content to be encrypted to multiple parties. Both share the 177 same cryptographic underpinnings. 179 Cryptographic algorithms and identifiers for use with this 180 specification are described in the separate JSON Web Algorithms (JWA) 181 [JWA] specification. Related digital signature and MAC capabilities 182 are described in the separate JSON Web Signature (JWS) [JWS] 183 specification. 185 1.1. Notational Conventions 187 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 188 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 189 document are to be interpreted as described in Key words for use in 190 RFCs to Indicate Requirement Levels [RFC2119]. 192 2. Terminology 194 JSON Web Encryption (JWE) A data structure representing an encrypted 195 message. The structure represents five values: the JWE Header, 196 the JWE Encrypted Key, the JWE Initialization Vector, the JWE 197 Ciphertext, and the JWE Authentication Tag. 199 Authenticated Encryption An Authenticated Encryption algorithm is 200 one that provides an integrated content integrity check. 201 Authenticated Encryption algorithms accept two inputs, the 202 Plaintext and the Additional Authenticated Data value, and produce 203 two outputs, the Ciphertext and the Authentication Tag value. AES 204 Galois/Counter Mode (GCM) is one such algorithm. 206 Plaintext The sequence of octets to be encrypted -- a.k.a., the 207 message. The plaintext can contain an arbitrary sequence of 208 octets. 210 Ciphertext An encrypted representation of the Plaintext. 212 Additional Authenticated Data (AAD) An input to an Authenticated 213 Encryption operation that is integrity protected but not 214 encrypted. 216 Authentication Tag An output of an Authenticated Encryption 217 operation that ensures the integrity of the Ciphertext and the 218 Additional Authenticated Data. Note that some algorithms may not 219 use an Authentication Tag, in which case this value is the empty 220 octet sequence. 222 Content Encryption Key (CEK) A symmetric key for the Authenticated 223 Encryption algorithm used to encrypt the Plaintext for the 224 recipient to produce the Ciphertext and the Authentication Tag. 226 JSON Text Object A UTF-8 [RFC3629] encoded text string representing 227 a JSON object; the syntax of JSON objects is defined in Section 228 2.2 of [RFC4627]. 230 JWE Header A JSON Text Object (or JSON Text Objects, when using the 231 JWE JSON Serialization) that describes the encryption operations 232 applied to create the JWE Encrypted Key, the JWE Ciphertext, and 233 the JWE Authentication Tag. The members of the JWE Header 234 object(s) are Header Parameters. 236 JWE Encrypted Key The result of encrypting the Content Encryption 237 Key (CEK) with the intended recipient's key using the specified 238 algorithm. Note that for some algorithms, the JWE Encrypted Key 239 value is specified as being the empty octet sequence. 241 JWE Initialization Vector A sequence of octets containing the 242 Initialization Vector used when encrypting the Plaintext. Note 243 that some algorithms may not use an Initialization Vector, in 244 which case this value is the empty octet sequence. 246 JWE Ciphertext A sequence of octets containing the Ciphertext for a 247 JWE. 249 JWE Authentication Tag A sequence of octets containing the 250 Authentication Tag for a JWE. 252 JWE Protected Header A JSON Text Object that contains the portion of 253 the JWE Header that is integrity protected. For the JWE Compact 254 Serialization, this comprises the entire JWE Header. For the JWE 255 JSON Serialization, this is one component of the JWE Header. 257 Header Parameter A name/value pair that is member of the JWE Header. 259 Header Parameter Name The name of a member of the JWE Header. 261 Header Parameter Value The value of a member of the JWE Header. 263 Base64url Encoding The URL- and filename-safe Base64 encoding 264 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 265 safe) '=' padding characters omitted, as permitted by Section 3.2. 266 (See Appendix C of [JWS] for notes on implementing base64url 267 encoding without padding.) 269 Encoded JWE Header Base64url encoding of the JWE Protected Header. 271 Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted 272 Key. 274 Encoded JWE Initialization Vector Base64url encoding of the JWE 275 Initialization Vector. 277 Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. 279 Encoded JWE Authentication Tag Base64url encoding of the JWE 280 Authentication Tag. 282 JWE Compact Serialization A representation of the JWE as the 283 concatenation of the Encoded JWE Header, the Encoded JWE Encrypted 284 Key, the Encoded JWE Initialization Vector, the Encoded JWE 285 Ciphertext, and the Encoded JWE Authentication Tag in that order, 286 with the five strings being separated by four period ('.') 287 characters. This representation is compact and URL-safe. 289 JWE JSON Serialization A representation of the JWE as a JSON 290 structure containing JWE Header, Encoded JWE Encrypted Key, 291 Encoded JWE Initialization Vector, Encoded JWE Ciphertext, and 292 Encoded JWE Authentication Tag values. Unlike the JWE Compact 293 Serialization, the JWE JSON Serialization enables the same content 294 to be encrypted to multiple parties. This representation is 295 neither compact nor URL-safe. 297 Collision Resistant Namespace A namespace that allows names to be 298 allocated in a manner such that they are highly unlikely to 299 collide with other names. For instance, collision resistance can 300 be achieved through administrative delegation of portions of the 301 namespace or through use of collision-resistant name allocation 302 functions. Examples of Collision Resistant Namespaces include: 303 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 304 X.660 and X.670 Recommendation series, and Universally Unique 305 IDentifiers (UUIDs) [RFC4122]. When using an administratively 306 delegated namespace, the definer of a name needs to take 307 reasonable precautions to ensure they are in control of the 308 portion of the namespace they use to define the name. 310 StringOrURI A JSON string value, with the additional requirement 311 that while arbitrary string values MAY be used, any value 312 containing a ":" character MUST be a URI [RFC3986]. StringOrURI 313 values are compared as case-sensitive strings with no 314 transformations or canonicalizations applied. 316 Key Management Mode A method of determining the Content Encryption 317 Key (CEK) value to use. Each algorithm used for determining the 318 CEK value uses a specific Key Management Mode. Key Management 319 Modes employed by this specification are Key Encryption, Key 320 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 321 and Direct Encryption. 323 Key Encryption A Key Management Mode in which the Content Encryption 324 Key (CEK) value is encrypted to the intended recipient using an 325 asymmetric encryption algorithm. 327 Key Wrapping A Key Management Mode in which the Content Encryption 328 Key (CEK) value is encrypted to the intended recipient using a 329 symmetric key wrapping algorithm. 331 Direct Key Agreement A Key Management Mode in which a key agreement 332 algorithm is used to agree upon the Content Encryption Key (CEK) 333 value. 335 Key Agreement with Key Wrapping A Key Management Mode in which a key 336 agreement algorithm is used to agree upon a symmetric key used to 337 encrypt the Content Encryption Key (CEK) value to the intended 338 recipient using a symmetric key wrapping algorithm. 340 Direct Encryption A Key Management Mode in which the Content 341 Encryption Key (CEK) value used is the secret symmetric key value 342 shared between the parties. 344 3. JSON Web Encryption (JWE) Overview 346 JWE represents encrypted content using JSON data structures and 347 base64url encoding. Five values are represented in a JWE: the JWE 348 Header, the JWE Encrypted Key, the JWE Initialization Vector, the JWE 349 Ciphertext, and the JWE Authentication Tag. In the Compact 350 Serialization, the five values are base64url-encoded for 351 transmission, and represented as the concatenation of the encoded 352 strings in that order, with the five strings being separated by four 353 period ('.') characters. A JSON Serialization for this information 354 is also defined in Section 8. 356 JWE utilizes authenticated encryption to ensure the confidentiality 357 and integrity of the Plaintext and the integrity of the JWE Protected 358 Header. 360 3.1. Example JWE 362 This example encrypts the plaintext "The true sign of intelligence is 363 not knowledge but imagination." to the recipient using RSAES OAEP and 364 AES GCM. 366 The following example JWE Header declares that: 368 o the Content Encryption Key is encrypted to the recipient using the 369 RSAES OAEP algorithm to produce the JWE Encrypted Key and 371 o the Plaintext is encrypted using the AES GCM algorithm with a 256 372 bit key to produce the Ciphertext. 374 {"alg":"RSA-OAEP","enc":"A256GCM"} 376 Base64url encoding the octets of the UTF-8 representation of the JWE 377 Header yields this Encoded JWE Header value: 379 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 381 The remaining steps to finish creating this JWE are: 383 o Generate a random Content Encryption Key (CEK). 385 o Encrypt the CEK with the recipient's public key using the RSAES 386 OAEP algorithm to produce the JWE Encrypted Key. 388 o Base64url encode the JWE Encrypted Key to produce the Encoded JWE 389 Encrypted Key. 391 o Generate a random JWE Initialization Vector. 393 o Base64url encode the JWE Initialization Vector to produce the 394 Encoded JWE Initialization Vector. 396 o Let the Additional Authenticated Data encryption parameter be the 397 octets of the ASCII representation of the Encoded JWE Header 398 value. 400 o Encrypt the Plaintext with AES GCM using the CEK as the encryption 401 key, the JWE Initialization Vector, and the Additional 402 Authenticated Data value, requesting a 128 bit Authentication Tag 403 output. 405 o Base64url encode the Ciphertext to create the Encoded JWE 406 Ciphertext. 408 o Base64url encode the Authentication Tag to create the Encoded JWE 409 Authentication Tag. 411 o Assemble the final representation: The Compact Serialization of 412 this result is the concatenation of the Encoded JWE Header, the 413 Encoded JWE Encrypted Key, the Encoded JWE Initialization Vector, 414 the Encoded JWE Ciphertext, and the Encoded JWE Authentication Tag 415 in that order, with the five strings being separated by four 416 period ('.') characters. 418 The final result in this example (with line breaks for display 419 purposes only) is: 421 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 422 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 423 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 424 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 425 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 426 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 427 6UklfCpIMfIjf7iGdXKHzg. 428 48V1_ALb6US04U3b. 429 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 430 SdiwkIr3ajwQzaBtQD_A. 431 XFBoMYUZodetZdvTiFvSkQ 433 See Appendix A.1 for the complete details of computing this JWE. See 434 Appendix A for additional examples. 436 4. JWE Header 438 The members of the JSON object(s) represented by the JWE Header 439 describe the encryption applied to the Plaintext and optionally 440 additional properties of the JWE. The Header Parameter Names within 441 the JWE Header MUST be unique; JWEs with duplicate Header Parameter 442 Names MUST be rejected. 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.14, all other header parameters MUST be ignored when not 451 understood. 453 There are two ways of distinguishing whether a header is a JWS Header 454 or a JWE Header. The first is by examining the "alg" (algorithm) 455 header parameter value. If the value represents a digital signature 456 or MAC algorithm, or is the value "none", it is for a JWS; if it 457 represents a Key Encryption, Key Wrapping, Direct Key Agreement, Key 458 Agreement with Key Wrapping, or Direct Encryption algorithm, it is 459 for a JWE. A second method is determining whether an "enc" 460 (encryption method) member exists. If the "enc" member exists, it is 461 a JWE; otherwise, it is a JWS. Both methods will yield the same 462 result for all legal input values. 464 There are three classes of Header Parameter Names: Reserved Header 465 Parameter Names, Public Header Parameter Names, and Private Header 466 Parameter Names. 468 4.1. Reserved Header Parameter Names 470 The following Header Parameter Names are reserved with meanings as 471 defined below. All the names are short because a core goal of this 472 specification is for the resulting representations using the JWE 473 Compact Serialization to be compact. 475 Additional reserved Header Parameter Names can be defined via the 476 IANA JSON Web Signature and Encryption Header Parameters registry 477 [JWS]. As indicated by the common registry, JWSs and JWEs share a 478 common header parameter space; when a parameter is used by both 479 specifications, its usage must be compatible between the 480 specifications. 482 4.1.1. "alg" (Algorithm) Header Parameter 484 The "alg" (algorithm) header parameter identifies the cryptographic 485 algorithm used to encrypt or determine the value of the Content 486 Encryption Key (CEK). The algorithm specified by the "alg" value 487 MUST be supported by the implementation and there MUST be a key for 488 use with that algorithm associated with the intended recipient or the 489 JWE MUST be rejected. "alg" values SHOULD either be registered in the 490 IANA JSON Web Signature and Encryption Algorithms registry [JWA] or 491 be a value that contains a Collision Resistant Namespace. The "alg" 492 value is a case sensitive string containing a StringOrURI value. Use 493 of this header parameter is REQUIRED. This header parameter MUST be 494 understood by implementations. 496 A list of defined "alg" values can be found in the IANA JSON Web 497 Signature and Encryption Algorithms registry [JWA]; the initial 498 contents of this registry are the values defined in Section 4.1 of 499 the JSON Web Algorithms (JWA) [JWA] specification. 501 4.1.2. "enc" (Encryption Method) Header Parameter 503 The "enc" (encryption method) header parameter identifies the block 504 encryption algorithm used to encrypt the Plaintext to produce the 505 Ciphertext. This algorithm MUST be an Authenticated Encryption 506 algorithm with a specified key length. The algorithm specified by 507 the "enc" value MUST be supported by the implementation or the JWE 508 MUST be rejected. "enc" values SHOULD either be registered in the 509 IANA JSON Web Signature and Encryption Algorithms registry [JWA] or 510 be a value that contains a Collision Resistant Namespace. The "enc" 511 value is a case sensitive string containing a StringOrURI value. Use 512 of this header parameter is REQUIRED. This header parameter MUST be 513 understood by implementations. 515 A list of defined "enc" values can be found in the IANA JSON Web 516 Signature and Encryption Algorithms registry [JWA]; the initial 517 contents of this registry are the values defined in Section 4.2 of 518 the JSON Web Algorithms (JWA) [JWA] specification. 520 4.1.3. "epk" (Ephemeral Public Key) Header Parameter 522 The "epk" (ephemeral public key) value created by the originator for 523 the use in key agreement algorithms. This key is represented as a 524 JSON Web Key [JWK] value. When the "alg" value used identifies an 525 algorithm for which "epk" is a parameter, this parameter MUST be 526 present if REQUIRED by the algorithm and this header parameter MUST 527 be understood by implementations; otherwise, this parameter MUST be 528 omitted. 530 4.1.4. "zip" (Compression Algorithm) Header Parameter 532 The "zip" (compression algorithm) applied to the Plaintext before 533 encryption, if any. If present, the value of the "zip" header 534 parameter MUST be the case sensitive string "DEF". Compression is 535 performed with the DEFLATE [RFC1951] algorithm. If no "zip" 536 parameter is present, no compression is applied to the Plaintext 537 before encryption. This header parameter MUST be integrity 538 protected, and therefore MUST occur only with the JWE Protected 539 Header, when used. Use of this header parameter is OPTIONAL. This 540 header parameter MUST be understood by implementations. 542 4.1.5. "jku" (JWK Set URL) Header Parameter 544 The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that 545 refers to a resource for a set of JSON-encoded public keys, one of 546 which is the key to which the JWE was encrypted; this can be used to 547 determine the private key needed to decrypt the JWE. The keys MUST 548 be encoded as a JSON Web Key Set (JWK Set) [JWK]. The protocol used 549 to acquire the resource MUST provide integrity protection; an HTTP 550 GET request to retrieve the certificate MUST use TLS [RFC2818] 551 [RFC5246]; the identity of the server MUST be validated, as per 552 Section 3.1 of HTTP Over TLS [RFC2818]. Use of this header parameter 553 is OPTIONAL. 555 4.1.6. "jwk" (JSON Web Key) Header Parameter 557 The "jwk" (JSON Web Key) header parameter is the public key to which 558 the JWE was encrypted; this can be used to determine the private key 559 needed to decrypt the JWE. This key is represented as a JSON Web Key 560 [JWK]. Use of this header parameter is OPTIONAL. 562 4.1.7. "x5u" (X.509 URL) Header Parameter 564 The "x5u" (X.509 URL) header parameter is a URI [RFC3986] that refers 565 to a resource for the X.509 public key certificate or certificate 566 chain [RFC5280] containing the key to which the JWE was encrypted; 567 this can be used to determine the private key needed to decrypt the 568 JWE. The identified resource MUST provide a representation of the 569 certificate or certificate chain that conforms to RFC 5280 [RFC5280] 570 in PEM encoded form [RFC1421]. The certificate containing the public 571 key to which the JWE was encrypted MUST be the first certificate. 572 This MAY be followed by additional certificates, with each subsequent 573 certificate being the one used to certify the previous one. The 574 protocol used to acquire the resource MUST provide integrity 575 protection; an HTTP GET request to retrieve the certificate MUST use 576 TLS [RFC2818] [RFC5246]; the identity of the server MUST be 577 validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. Use of 578 this header parameter is OPTIONAL. 580 4.1.8. "x5t" (X.509 Certificate Thumbprint) Header Parameter 582 The "x5t" (X.509 Certificate Thumbprint) header parameter is a 583 base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER 584 encoding of the X.509 certificate [RFC5280] containing the key to 585 which the JWE was encrypted; this can be used to determine the 586 private key needed to decrypt the JWE. Use of this header parameter 587 is OPTIONAL. 589 If, in the future, certificate thumbprints need to be computed using 590 hash functions other than SHA-1, it is suggested that additional 591 related header parameters be defined for that purpose. For example, 592 it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint 593 using SHA-256) header parameter could be defined by registering it in 594 the IANA JSON Web Signature and Encryption Header Parameters registry 595 [JWS]. 597 4.1.9. "x5c" (X.509 Certificate Chain) Header Parameter 599 The "x5c" (X.509 Certificate Chain) header parameter contains the 600 X.509 public key certificate or certificate chain [RFC5280] 601 containing the key to which the JWE was encrypted; this can be used 602 to determine the private key needed to decrypt the JWE. The 603 certificate or certificate chain is represented as a JSON array of 604 certificate value strings. Each string in the array is a base64 605 encoded ([RFC4648] Section 4 -- not base64url encoded) DER 606 [ITU.X690.1994] PKIX certificate value. The certificate containing 607 the public key to which the JWE was encrypted MUST be the first 608 certificate. This MAY be followed by additional certificates, with 609 each subsequent certificate being the one used to certify the 610 previous one. Use of this header parameter is OPTIONAL. 612 See Appendix B of [JWS] for an example "x5c" value. 614 4.1.10. "kid" (Key ID) Header Parameter 616 The "kid" (key ID) header parameter is a hint indicating which key to 617 which the JWE was encrypted; this can be used to determine the 618 private key needed to decrypt the JWE. This parameter allows 619 originators to explicitly signal a change of key to recipients. 620 Should the recipient be unable to locate a key corresponding to the 621 "kid" value, they SHOULD treat that condition as an error. The 622 interpretation of the "kid" value is unspecified. Its value MUST be 623 a string. Use of this header parameter is OPTIONAL. 625 When used with a JWK, the "kid" value can be used to match a JWK 626 "kid" parameter value. 628 4.1.11. "typ" (Type) Header Parameter 630 The "typ" (type) header parameter is used to declare the type of this 631 object. The type value "JWE" is used to indicate that this object is 632 a JWE using the JWE Compact Serialization. The type value "JWE+JSON" 633 is used to indicate that this object is a JWE using the JWE JSON 634 Serialization. Other type values MAY be used, and if not understood, 635 SHOULD be ignored. The "typ" value is a case sensitive string. Use 636 of this header parameter is OPTIONAL. 638 MIME Media Type [RFC2046] values MAY be used as "typ" values. 640 "typ" values SHOULD either be registered in the IANA JSON Web 641 Signature and Encryption Type Values registry [JWS] or be a value 642 that contains a Collision Resistant Namespace. 644 4.1.12. "cty" (Content Type) Header Parameter 646 The "cty" (content type) header parameter is used to declare the type 647 of the encrypted content (the Plaintext). For example, the JSON Web 648 Token (JWT) [JWT] specification uses the "cty" value "JWT" to 649 indicate that the Plaintext is a JSON Web Token (JWT). Content type 650 values that are not understood SHOULD be ignored. The "cty" value is 651 a case sensitive string. Use of this header parameter is OPTIONAL. 653 The values used for the "cty" header parameter come from the same 654 value space as the "typ" header parameter, with the same rules 655 applying. 657 4.1.13. "apu" (Agreement PartyUInfo) Header Parameter 659 The "apu" (agreement PartyUInfo) value for key agreement algorithms 660 using it (such as "ECDH-ES"), represented as a base64url encoded 661 string. Use of this header parameter is OPTIONAL. When the "alg" 662 value used identifies an algorithm for which "apu" is a parameter, 663 this header parameter MUST be understood by implementations; 664 otherwise, this parameter MUST be omitted. 666 4.1.14. "crit" (Critical) Header Parameter 668 The "crit" (critical) header parameter indicates that extensions to 669 [[ this specification ]] are being used that MUST be understood and 670 processed. Its value is an array listing the header parameter names 671 defined by those extensions that are used in the JWE Header. If any 672 of the listed extension header parameters are not understood and 673 supported by the receiver, it MUST reject the JWE. Senders MUST NOT 674 include header parameter names defined by [[ this specification ]], 675 duplicate names, or names that do not occur as header parameter names 676 within the JWE Header in the "crit" list. Senders MUST not use the 677 empty list "[]" as the "crit" value. Recipients MAY reject the JWE 678 if the critical list contains any header parameter names defined by 679 [[ this specification ]] or any other constraints on its use are 680 violated. This header parameter MUST be integrity protected, and 681 therefore MUST occur only with the JWE Protected Header, when used. 682 Use of this header parameter is OPTIONAL. This header parameter MUST 683 be understood by implementations. 685 An example use, along with a hypothetical "exp" (expiration-time) 686 field is: 688 {"alg":"RSA-OAEP", 689 "enc":"A256GCM", 690 "crit":["exp"], 691 "exp":1363284000 692 } 694 4.2. Public Header Parameter Names 696 Additional Header Parameter Names can be defined by those using JWEs. 697 However, in order to prevent collisions, any new Header Parameter 698 Name SHOULD either be registered in the IANA JSON Web Signature and 699 Encryption Header Parameters registry [JWS] or be a Public Name: a 700 value that contains a Collision Resistant Namespace. In each case, 701 the definer of the name or value needs to take reasonable precautions 702 to make sure they are in control of the part of the namespace they 703 use to define the Header Parameter Name. 705 New header parameters should be introduced sparingly, as they can 706 result in non-interoperable JWEs. 708 4.3. Private Header Parameter Names 710 A producer and consumer of a JWE may agree to use Header Parameter 711 Names that are Private Names: names that are not Reserved Names 712 Section 4.1 or Public Names Section 4.2. Unlike Public Names, 713 Private Names are subject to collision and should be used with 714 caution. 716 5. Producing and Consuming JWEs 718 5.1. Message Encryption 720 The message encryption process is as follows. The order of the steps 721 is not significant in cases where there are no dependencies between 722 the inputs and outputs of the steps. 724 1. Determine the Key Management Mode employed by the algorithm used 725 to determine the Content Encryption Key (CEK) value. (This is 726 the algorithm recorded in the "alg" (algorithm) header parameter 727 of the resulting JWE.) 729 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 730 Wrapping are employed, generate a random Content Encryption Key 731 (CEK) value. See RFC 4086 [RFC4086] for considerations on 732 generating random values. The CEK MUST have a length equal to 733 that required for the block encryption algorithm. 735 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 736 employed, use the key agreement algorithm to compute the value 737 of the agreed upon key. When Direct Key Agreement is employed, 738 let the Content Encryption Key (CEK) be the agreed upon key. 739 When Key Agreement with Key Wrapping is employed, the agreed 740 upon key will be used to wrap the CEK. 742 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 743 Wrapping are employed, encrypt the CEK to the recipient (see 744 Section 6.1) and let the result be the JWE Encrypted Key. 746 5. Otherwise, when Direct Key Agreement or Direct Encryption are 747 employed, let the JWE Encrypted Key be the empty octet sequence. 749 6. When Direct Encryption is employed, let the Content Encryption 750 Key (CEK) be the shared symmetric key. 752 7. Base64url encode the JWE Encrypted Key to create the Encoded JWE 753 Encrypted Key. 755 8. If the JWE JSON Serialization is being used, repeat this process 756 for each recipient. 758 9. Generate a random JWE Initialization Vector of the correct size 759 for the block encryption algorithm (if required for the 760 algorithm); otherwise, let the JWE Initialization Vector be the 761 empty octet sequence. 763 10. Base64url encode the JWE Initialization Vector to create the 764 Encoded JWE Initialization Vector. 766 11. Compress the Plaintext if a "zip" parameter was included. 768 12. Serialize the (compressed) Plaintext into an octet sequence M. 770 13. Create a JWE Header containing the encryption parameters used. 771 Note that white space is explicitly allowed in the 772 representation and no canonicalization need be performed before 773 encoding. 775 14. Base64url encode the octets of the UTF-8 representation of the 776 JWE Protected Header to create the Encoded JWE Header. If the 777 JWE Protected Header is not present (which can only happen when 778 using the JWE JSON Serialization), let the Encoded JWE Header be 779 the empty string. 781 15. Let the Additional Authenticated Data encryption parameter be 782 the octets of the ASCII representation of the Encoded JWE Header 783 value. 785 16. Encrypt M using the CEK, the JWE Initialization Vector, and the 786 Additional Authenticated Data value using the specified block 787 encryption algorithm to create the JWE Ciphertext value and the 788 JWE Authentication Tag (which is the Authentication Tag output 789 from the encryption operation). 791 17. Base64url encode the JWE Ciphertext to create the Encoded JWE 792 Ciphertext. 794 18. Base64url encode the JWE Authentication Tag to create the 795 Encoded JWE Authentication Tag. 797 19. The five encoded parts are result values used in both the JWE 798 Compact Serialization and the JWE JSON Serialization 799 representations. 801 20. Create the desired serialized output. The JWE Compact 802 Serialization of this result is the concatenation of the Encoded 803 JWE Header, the Encoded JWE Encrypted Key, the Encoded JWE 804 Initialization Vector, the Encoded JWE Ciphertext, and the 805 Encoded JWE Authentication Tag in that order, with the five 806 strings being separated by four period ('.') characters. The 807 JWE JSON Serialization is described in Section 8. 809 5.2. Message Decryption 811 The message decryption process is the reverse of the encryption 812 process. The order of the steps is not significant in cases where 813 there are no dependencies between the inputs and outputs of the 814 steps. If any of these steps fails, the JWE MUST be rejected. 816 1. Parse the serialized input to determine the values of the JWE 817 Header, the Encoded JWE Encrypted Key, the Encoded JWE 818 Initialization Vector, the Encoded JWE Ciphertext, and the 819 Encoded JWE Authentication Tag. When using the JWE Compact 820 Serialization, the Encoded JWE Header, the Encoded JWE Encrypted 821 Key, the Encoded JWE Initialization Vector, the Encoded JWE 822 Ciphertext, and the Encoded JWE Authentication Tag are 823 represented as text strings in that order, separated by four 824 period ('.') characters. The JWE JSON Serialization is 825 described in Section 8. 827 2. The Encoded JWE Header, the Encoded JWE Encrypted Key, the 828 Encoded JWE Initialization Vector, the Encoded JWE Ciphertext, 829 and the Encoded JWE Authentication Tag MUST be successfully 830 base64url decoded following the restriction that no padding 831 characters have been used. 833 3. The resulting JWE Protected Header MUST be a completely valid 834 JSON object conforming to RFC 4627 [RFC4627]. 836 4. If using the JWE Compact Serialization, let the JWE Header be 837 the JWE Protected Header; otherwise, when using the JWE JSON 838 Serialization, let the JWE Header be the union of the members of 839 the JWE Protected Header, the members of the "unprotected" 840 value, and the members of the corresponding "header" value, all 841 of which must be completely valid JSON objects. 843 5. The resulting JWE Header MUST NOT contain duplicate Header 844 Parameter Names. When using the JWE JSON Serialization, this 845 restriction includes that the same Header Parameter Name also 846 MUST NOT occur in distinct JSON Text Object values that together 847 comprise the JWE Header. 849 6. The resulting JWE Header MUST be validated to only include 850 parameters and values whose syntax and semantics are both 851 understood and supported or that are specified as being ignored 852 when not understood. 854 7. Determine the Key Management Mode employed by the algorithm 855 specified by the "alg" (algorithm) header parameter. 857 8. Verify that the JWE uses a key known to the recipient. 859 9. When Direct Key Agreement or Key Agreement with Key Wrapping are 860 employed, use the key agreement algorithm to compute the value 861 of the agreed upon key. When Direct Key Agreement is employed, 862 let the Content Encryption Key (CEK) be the agreed upon key. 863 When Key Agreement with Key Wrapping is employed, the agreed 864 upon key will be used to decrypt the JWE Encrypted Key. 866 10. When Key Wrapping, Key Encryption, or Key Agreement with Key 867 Wrapping are employed, decrypt the JWE Encrypted Key to produce 868 the Content Encryption Key (CEK). The CEK MUST have a length 869 equal to that required for the block encryption algorithm. Note 870 that when there are multiple recipients, each recipient will 871 only be able decrypt any JWE Encrypted Key values that were 872 encrypted to a key in that recipient's possession. It is 873 therefore normal to only be able to decrypt one of the per- 874 recipient JWE Encrypted Key values to obtain the CEK value. To 875 mitigate against attacks described in RFC 3218 [RFC3218], the 876 recipient MUST NOT distinguish between format, padding, and 877 length errors of encrypted keys. It is strongly recommended, in 878 the event of receiving an improperly formatted key, that the 879 receiver substitute a randomly generated CEK and proceed to the 880 next step, to mitigate timing attacks. 882 11. Otherwise, when Direct Key Agreement or Direct Encryption are 883 employed, verify that the JWE Encrypted Key value is empty octet 884 sequence. 886 12. When Direct Encryption is employed, let the Content Encryption 887 Key (CEK) be the shared symmetric key. 889 13. If the JWE JSON Serialization is being used, repeat this process 890 for each recipient contained in the representation until the CEK 891 value has been determined. 893 14. Let the Additional Authenticated Data encryption parameter be 894 the octets of the ASCII representation of the Encoded JWE Header 895 value. 897 15. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 898 Vector, the Additional Authenticated Data value, and the JWE 899 Authentication Tag (which is the Authentication Tag input to the 900 calculation) using the specified block encryption algorithm, 901 returning the decrypted plaintext and verifying the JWE 902 Authentication Tag in the manner specified for the algorithm, 903 rejecting the input without emitting any decrypted output if the 904 JWE Authentication Tag is incorrect. 906 16. Uncompress the decrypted plaintext if a "zip" parameter was 907 included. 909 17. Output the resulting Plaintext. 911 5.3. String Comparison Rules 913 Processing a JWE inevitably requires comparing known strings to 914 values in JSON objects. For example, in checking what the encryption 915 method is, the Unicode string encoding "enc" will be checked against 916 the member names in the JWE Header to see if there is a matching 917 Header Parameter Name. 919 Comparisons between JSON strings and other Unicode strings MUST be 920 performed by comparing Unicode code points without normalization as 921 specified in the String Comparison Rules in Section 5.3 of [JWS]. 923 6. Cryptographic Algorithms 925 JWE uses cryptographic algorithms to encrypt the Plaintext and the 926 Content Encryption Key (CEK) and to provide integrity protection for 927 the JWE Protected Header and JWE Ciphertext. The JSON Web Algorithms 928 (JWA) [JWA] specification specifies a set of cryptographic algorithms 929 and identifiers to be used with this specification and defines 930 registries for additional such algorithms. Specifically, Section 4.1 931 specifies a set of "alg" (algorithm) header parameter values and 932 Section 4.2 specifies a set of "enc" (encryption method) header 933 parameter values intended for use this specification. It also 934 describes the semantics and operations that are specific to these 935 algorithms. 937 6.1. CEK Encryption 939 JWE supports three forms of Content Encryption Key (CEK) encryption: 941 o Asymmetric encryption under the recipient's public key. 943 o Symmetric encryption under a key shared between the sender and 944 receiver. 946 o Symmetric encryption under a key agreed upon between the sender 947 and receiver. 949 See the algorithms registered for "enc" usage in the IANA JSON Web 950 Signature and Encryption Algorithms registry [JWA] and Section 4.1 of 951 the JSON Web Algorithms (JWA) [JWA] specification for lists of 952 encryption algorithms that can be used for CEK encryption. 954 7. Key Identification 956 It is necessary for the recipient of a JWE to be able to determine 957 the key that was employed for the encryption operation. The key 958 employed can be identified using the Header Parameter methods 959 described in Section 4.1 or can be identified using methods that are 960 outside the scope of this specification. Specifically, the Header 961 Parameters "jku", "jwk", "x5u", "x5t", "x5c", and "kid" can be used 962 to identify the key used. The sender SHOULD include sufficient 963 information in the Header Parameters to identify the key used, unless 964 the application uses another means or convention to determine the key 965 used. Recipients MUST reject the input when the key used cannot be 966 determined. 968 8. JWE JSON Serialization 970 The JWE JSON Serialization represents encrypted content as a JSON 971 object. Unlike the JWE Compact Serialization, content using the JWE 972 JSON Serialization can be encrypted to more than one recipient. 974 The representation is closely related to that used in the JWE Compact 975 Serialization, with the following differences for the JWE JSON 976 Serialization: 978 o Values in the JWE JSON Serialization are represented as members of 979 a JSON object, rather than as base64url encoded strings separated 980 by period ('.') characters. (However binary values and values 981 that are integrity protected are still base64url encoded.) 983 o The Encoded JWE Header value, if non-empty, is stored in the 984 "protected" member. 986 o The Encoded JWE Initialization Vector value is stored in the "iv" 987 member. 989 o The Encoded JWE Ciphertext value is stored in the "ciphertext" 990 member. 992 o The Encoded JWE Authentication Tag value is stored in the "tag" 993 member. 995 o The JWE can be encrypted to multiple recipients, rather than just 996 one. A JSON array in the "recipients" member is used to hold 997 values that are specific to a particular recipient, with one array 998 element per recipient represented. These array elements are JSON 999 objects. 1001 o Each Encoded JWE Encrypted Key value is stored in the 1002 "encrypted_key" member of a JSON object that is an element of the 1003 "recipients" array. 1005 o Some header parameter values, such as the "alg" value and 1006 parameters used for selecting keys, can also differ for different 1007 recipient computations. Per-recipient header parameter values are 1008 stored in the "header" members of the same JSON objects that are 1009 elements of the "recipients" array. 1011 o Some header parameters, including the "alg" parameter, can be 1012 shared among all recipient computations. These header parameters 1013 are stored in either of two top-level member(s) of the JSON 1014 object: the "protected" member and the "unprotected" member. The 1015 values of these members are JSON Text Objects containing Header 1016 Parameters. 1018 o Not all header parameters are integrity protected. The shared 1019 header parameters in the "protected" member are integrity 1020 protected, and are base64url encoded. The per-recipient header 1021 parameters in the "header" array element members and the shared 1022 header parameters in the "unprotected" member are not integrity 1023 protected. These JSON Text Objects containing header parameters 1024 that are not integrity protected are not base64url encoded. 1026 o The header parameter values used when creating or validating per- 1027 recipient Ciphertext and Authentication Tag values are the union 1028 of the three sets of header parameter values that may be present: 1029 (1) the per-recipient values in the "header" member of the 1030 recipient's array element, (2) the shared integrity-protected 1031 values in the "protected" member, and (3) the shared non- 1032 integrity-protected values in the "unprotected" member. The union 1033 of these sets of header parameters comprises the JWE Header. The 1034 header parameter names in the three locations MUST be disjoint. 1036 The syntax of a JWE using the JWE JSON Serialization is as follows: 1038 {"protected":", 1039 "unprotected":", 1040 "recipients":[ 1041 {"header":"", 1042 "encrypted_key":""}, 1043 ... 1044 {"header":"", 1045 "encrypted_key":""}], 1046 "iv":"", 1047 "ciphertext":"", 1048 "tag":"" 1049 } 1051 Of these members, only the "ciphertext" member MUST be present. The 1052 "iv", "tag", and "encrypted_key" members MUST be present when 1053 corresponding JWE Initialization Vector, JWE Authentication Tag, and 1054 JWE Encrypted Key values are non-empty. The "recipients" member MUST 1055 be present when any "header" or "encrypted_key" members are needed 1056 for recipients. At least one of the "header", "protected", and 1057 "unprotected" members MUST be present so that "alg" and "enc" header 1058 parameter values are conveyed for each recipient computation. 1060 The contents of the Encoded JWE Encrypted Key, Encoded JWE 1061 Initialization Vector, Encoded JWE Ciphertext, and Encoded JWE 1062 Authentication Tag values are exactly as defined in the rest of this 1063 specification. They are interpreted and validated in the same 1064 manner, with each corresponding Encoded JWE Encrypted Key, Encoded 1065 JWE Initialization Vector, Encoded JWE Ciphertext, Encoded JWE 1066 Authentication Tag, and set of header parameter values being created 1067 and validated together. The JWE Header values used are the union of 1068 the header parameters in the "protected", "unprotected", and 1069 corresponding "header" members, as described earlier. 1071 Each JWE Encrypted Key value is computed using the parameters of the 1072 corresponding JWE Header value in the same manner as for the JWE 1073 Compact Serialization. This has the desirable property that each 1074 Encoded JWE Encrypted Key value in the "recipients" array is 1075 identical to the value that would have been computed for the same 1076 parameter in the JWE Compact Serialization. Likewise, the JWE 1077 Ciphertext and JWE Authentication Tag values match those produced for 1078 the JWE Compact Serialization, provided that the Encoded JWE Header 1079 value (which represents the integrity-protected header parameter 1080 values) matches that used in the JWE Compact Serialization. 1082 All recipients use the same JWE Protected Header, JWE Initialization 1083 Vector, JWE Ciphertext, and JWE Authentication Tag values, resulting 1084 in potentially significant space savings if the message is large. 1085 Therefore, all header parameters that specify the treatment of the 1086 Plaintext value MUST be the same for all recipients. This primarily 1087 means that the "enc" (encryption method) header parameter value in 1088 the JWE Header for each recipient and any parameters of that 1089 algorithm MUST be the same. 1091 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1092 Serialization. 1094 9. Implementation Considerations 1096 The JWE Compact Serialization is mandatory to implement. 1097 Implementation of the JWE JSON Serialization is OPTIONAL. 1099 10. IANA Considerations 1101 10.1. Registration of JWE Header Parameter Names 1103 This specification registers the Header Parameter Names defined in 1104 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1105 Parameters registry [JWS]. 1107 10.1.1. Registry Contents 1109 o Header Parameter Name: "alg" 1110 o Header Parameter Usage Location(s): JWE 1111 o Change Controller: IETF 1112 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1114 o Header Parameter Name: "enc" 1115 o Header Parameter Usage Location(s): JWE 1116 o Change Controller: IETF 1117 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1119 o Header Parameter Name: "epk" 1120 o Header Parameter Usage Location(s): JWE 1121 o Change Controller: IETF 1122 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1124 o Header Parameter Name: "zip" 1125 o Header Parameter Usage Location(s): JWE 1126 o Change Controller: IETF 1127 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1129 o Header Parameter Name: "jku" 1130 o Header Parameter Usage Location(s): JWE 1131 o Change Controller: IETF 1132 o Specification Document(s): Section 4.1.5 of [[ this document ]] 1134 o Header Parameter Name: "jwk" 1135 o Header Parameter Usage Location(s): JWE 1136 o Change Controller: IETF 1137 o Specification document(s): Section 4.1.6 of [[ this document ]] 1139 o Header Parameter Name: "x5u" 1140 o Header Parameter Usage Location(s): JWE 1141 o Change Controller: IETF 1142 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1144 o Header Parameter Name: "x5t" 1145 o Header Parameter Usage Location(s): JWE 1146 o Change Controller: IETF 1147 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1149 o Header Parameter Name: "x5c" 1150 o Header Parameter Usage Location(s): JWE 1151 o Change Controller: IETF 1152 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1153 o Header Parameter Name: "kid" 1154 o Header Parameter Usage Location(s): JWE 1155 o Change Controller: IETF 1156 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1158 o Header Parameter Name: "typ" 1159 o Header Parameter Usage Location(s): JWE 1160 o Change Controller: IETF 1161 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1163 o Header Parameter Name: "cty" 1164 o Header Parameter Usage Location(s): JWE 1165 o Change Controller: IETF 1166 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1168 o Header Parameter Name: "apu" 1169 o Header Parameter Usage Location(s): JWE 1170 o Change Controller: IETF 1171 o Specification Document(s): Section 4.1.13 of [[ this document ]] 1173 o Header Parameter Name: "crit" 1174 o Header Parameter Usage Location(s): JWS 1175 o Change Controller: IETF 1176 o Specification Document(s): Section 4.1.14 of [[ this document ]] 1178 10.2. JSON Web Signature and Encryption Type Values Registration 1180 10.2.1. Registry Contents 1182 This specification registers the "JWE" and "JWE+JSON" type values in 1183 the IANA JSON Web Signature and Encryption Type Values registry 1184 [JWS]: 1186 o "typ" Header Parameter Value: "JWE" 1187 o Abbreviation for MIME Type: application/jwe 1188 o Change Controller: IETF 1189 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1191 o "typ" Header Parameter Value: "JWE+JSON" 1192 o Abbreviation for MIME Type: application/jwe+json 1193 o Change Controller: IETF 1194 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1196 10.3. Media Type Registration 1197 10.3.1. Registry Contents 1199 This specification registers the "application/jwe" and 1200 "application/jwe+json" Media Types [RFC2046] in the MIME Media Type 1201 registry [RFC4288] to indicate, respectively, that the content is a 1202 JWE using the JWE Compact Serialization or a JWE using the JWE JSON 1203 Serialization. 1205 o Type Name: application 1206 o Subtype Name: jwe 1207 o Required Parameters: n/a 1208 o Optional Parameters: n/a 1209 o Encoding considerations: JWE values are encoded as a series of 1210 base64url encoded values (some of which may be the empty string) 1211 separated by period ('.') characters 1212 o Security Considerations: See the Security Considerations section 1213 of [[ this document ]] 1214 o Interoperability Considerations: n/a 1215 o Published Specification: [[ this document ]] 1216 o Applications that use this media type: OpenID Connect and other 1217 applications using encrypted JWTs 1218 o Additional Information: Magic number(s): n/a, File extension(s): 1219 n/a, Macintosh file type code(s): n/a 1220 o Person & email address to contact for further information: Michael 1221 B. Jones, mbj@microsoft.com 1222 o Intended Usage: COMMON 1223 o Restrictions on Usage: none 1224 o Author: Michael B. Jones, mbj@microsoft.com 1225 o Change Controller: IETF 1227 o Type Name: application 1228 o Subtype Name: jwe+json 1229 o Required Parameters: n/a 1230 o Optional Parameters: n/a 1231 o Encoding considerations: application/jwe+json values are 1232 represented as a JSON Object; UTF-8 encoding SHOULD be employed 1233 for the JSON object. 1234 o Security Considerations: See the Security Considerations section 1235 of [[ this document ]] 1236 o Interoperability Considerations: n/a 1237 o Published Specification: [[ this document ]] 1238 o Applications that use this media type: TBD 1239 o Additional Information: Magic number(s): n/a, File extension(s): 1240 n/a, Macintosh file type code(s): n/a 1241 o Person & email address to contact for further information: Michael 1242 B. Jones, mbj@microsoft.com 1244 o Intended Usage: COMMON 1245 o Restrictions on Usage: none 1246 o Author: Michael B. Jones, mbj@microsoft.com 1247 o Change Controller: IETF 1249 11. Security Considerations 1251 All of the security issues faced by any cryptographic application 1252 must be faced by a JWS/JWE/JWK agent. Among these issues are 1253 protecting the user's private and symmetric keys, preventing various 1254 attacks, and helping the user avoid mistakes such as inadvertently 1255 encrypting a message for the wrong recipient. The entire list of 1256 security considerations is beyond the scope of this document. 1258 All the security considerations in the JWS specification also apply 1259 to this specification. Likewise, all the security considerations in 1260 XML Encryption 1.1 [W3C.CR-xmlenc-core1-20120313] also apply, other 1261 than those that are XML specific. 1263 When decrypting, particular care must be taken not to allow the JWE 1264 recipient to be used as an oracle for decrypting messages. RFC 3218 1265 [RFC3218] should be consulted for specific countermeasures to attacks 1266 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1267 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1268 formatting error that can be detected and used to recover the CEK 1269 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1270 particularly important to report all formatting errors to the CEK, 1271 Additional Authenticated Data, or ciphertext as a single error when 1272 the JWE is rejected. 1274 12. References 1276 12.1. Normative References 1278 [ITU.X690.1994] 1279 International Telecommunications Union, "Information 1280 Technology - ASN.1 encoding rules: Specification of Basic 1281 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1282 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1283 X.690, 1994. 1285 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1286 draft-ietf-jose-json-web-algorithms (work in progress), 1287 May 2013. 1289 [JWK] Jones, M., "JSON Web Key (JWK)", 1290 draft-ietf-jose-json-web-key (work in progress), May 2013. 1292 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1293 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1294 in progress), May 2013. 1296 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 1297 Mail: Part I: Message Encryption and Authentication 1298 Procedures", RFC 1421, February 1993. 1300 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1301 version 1.3", RFC 1951, May 1996. 1303 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1304 Extensions (MIME) Part Two: Media Types", RFC 2046, 1305 November 1996. 1307 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1308 Requirement Levels", BCP 14, RFC 2119, March 1997. 1310 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1312 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1313 10646", STD 63, RFC 3629, November 2003. 1315 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1316 Resource Identifier (URI): Generic Syntax", STD 66, 1317 RFC 3986, January 2005. 1319 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1320 Requirements for Security", BCP 106, RFC 4086, June 2005. 1322 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 1323 Registration Procedures", RFC 4288, December 2005. 1325 [RFC4627] Crockford, D., "The application/json Media Type for 1326 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1328 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1329 Encodings", RFC 4648, October 2006. 1331 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1332 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1334 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1335 Housley, R., and W. Polk, "Internet X.509 Public Key 1336 Infrastructure Certificate and Certificate Revocation List 1337 (CRL) Profile", RFC 5280, May 2008. 1339 [W3C.CR-xmlenc-core1-20120313] 1340 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 1341 "XML Encryption Syntax and Processing Version 1.1", World 1342 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1343 March 2012, 1344 . 1346 12.2. Informative References 1348 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1349 McGrew, D. and K. Paterson, "Authenticated Encryption with 1350 AES-CBC and HMAC-SHA", 1351 draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), 1352 October 2012. 1354 [I-D.rescorla-jsms] 1355 Rescorla, E. and J. Hildebrand, "JavaScript Message 1356 Security Format", draft-rescorla-jsms-00 (work in 1357 progress), March 2011. 1359 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1360 Encryption", September 2010. 1362 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1363 (JWT)", draft-ietf-oauth-json-web-token (work in 1364 progress), May 2013. 1366 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1367 Cryptographic Message Syntax", RFC 3218, January 2002. 1369 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1370 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1371 July 2005. 1373 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1374 RFC 5652, September 2009. 1376 Appendix A. JWE Examples 1378 This section provides examples of JWE computations. 1380 A.1. Example JWE using RSAES OAEP and AES GCM 1382 This example encrypts the plaintext "The true sign of intelligence is 1383 not knowledge but imagination." to the recipient using RSAES OAEP and 1384 AES GCM. The representation of this plaintext is: 1386 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1387 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1388 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1389 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1390 110, 97, 116, 105, 111, 110, 46] 1392 A.1.1. JWE Header 1394 The following example JWE Header declares that: 1396 o the Content Encryption Key is encrypted to the recipient using the 1397 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1399 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1400 bit key to produce the Ciphertext. 1402 {"alg":"RSA-OAEP","enc":"A256GCM"} 1404 A.1.2. Encoded JWE Header 1406 Base64url encoding the octets of the UTF-8 representation of the JWE 1407 Header yields this Encoded JWE Header value: 1409 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1411 A.1.3. Content Encryption Key (CEK) 1413 Generate a 256 bit random Content Encryption Key (CEK). In this 1414 example, the value is: 1416 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1417 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1418 234, 64, 252] 1420 A.1.4. Key Encryption 1422 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1423 algorithm to produce the JWE Encrypted Key. In this example, the RSA 1424 key parameters are: 1426 +-----------+-------------------------------------------------------+ 1427 | Parameter | Value | 1428 | Name | | 1429 +-----------+-------------------------------------------------------+ 1430 | Modulus | [161, 168, 84, 34, 133, 176, 208, 173, 46, 176, 163, | 1431 | | 110, 57, 30, 135, 227, 9, 31, 226, 128, 84, 92, 116, | 1432 | | 241, 70, 248, 27, 227, 193, 62, 5, 91, 241, 145, 224, | 1433 | | 205, 141, 176, 184, 133, 239, 43, 81, 103, 9, 161, | 1434 | | 153, 157, 179, 104, 123, 51, 189, 34, 152, 69, 97, | 1435 | | 69, 78, 93, 140, 131, 87, 182, 169, 101, 92, 142, 3, | 1436 | | 22, 167, 8, 212, 56, 35, 79, 210, 222, 192, 208, 252, | 1437 | | 49, 109, 138, 173, 253, 210, 166, 201, 63, 102, 74, | 1438 | | 5, 158, 41, 90, 144, 108, 160, 79, 10, 89, 222, 231, | 1439 | | 172, 31, 227, 197, 0, 19, 72, 81, 138, 78, 136, 221, | 1440 | | 121, 118, 196, 17, 146, 10, 244, 188, 72, 113, 55, | 1441 | | 221, 162, 217, 171, 27, 57, 233, 210, 101, 236, 154, | 1442 | | 199, 56, 138, 239, 101, 48, 198, 186, 202, 160, 76, | 1443 | | 111, 234, 71, 57, 183, 5, 211, 171, 136, 126, 64, 40, | 1444 | | 75, 58, 89, 244, 254, 107, 84, 103, 7, 236, 69, 163, | 1445 | | 18, 180, 251, 58, 153, 46, 151, 174, 12, 103, 197, | 1446 | | 181, 161, 162, 55, 250, 235, 123, 110, 17, 11, 158, | 1447 | | 24, 47, 133, 8, 199, 235, 107, 126, 130, 246, 73, | 1448 | | 195, 20, 108, 202, 176, 214, 187, 45, 146, 182, 118, | 1449 | | 54, 32, 200, 61, 201, 71, 243, 1, 255, 131, 84, 37, | 1450 | | 111, 211, 168, 228, 45, 192, 118, 27, 197, 235, 232, | 1451 | | 36, 10, 230, 248, 190, 82, 182, 140, 35, 204, 108, | 1452 | | 190, 253, 186, 186, 27] | 1453 | Exponent | [1, 0, 1] | 1454 | Private | [144, 183, 109, 34, 62, 134, 108, 57, 44, 252, 10, | 1455 | Exponent | 66, 73, 54, 16, 181, 233, 92, 54, 219, 101, 42, 35, | 1456 | | 178, 63, 51, 43, 92, 119, 136, 251, 41, 53, 23, 191, | 1457 | | 164, 164, 60, 88, 227, 229, 152, 228, 213, 149, 228, | 1458 | | 169, 237, 104, 71, 151, 75, 88, 252, 216, 77, 251, | 1459 | | 231, 28, 97, 88, 193, 215, 202, 248, 216, 121, 195, | 1460 | | 211, 245, 250, 112, 71, 243, 61, 129, 95, 39, 244, | 1461 | | 122, 225, 217, 169, 211, 165, 48, 253, 220, 59, 122, | 1462 | | 219, 42, 86, 223, 32, 236, 39, 48, 103, 78, 122, 216, | 1463 | | 187, 88, 176, 89, 24, 1, 42, 177, 24, 99, 142, 170, | 1464 | | 1, 146, 43, 3, 108, 64, 194, 121, 182, 95, 187, 134, | 1465 | | 71, 88, 96, 134, 74, 131, 167, 69, 106, 143, 121, 27, | 1466 | | 72, 44, 245, 95, 39, 194, 179, 175, 203, 122, 16, | 1467 | | 112, 183, 17, 200, 202, 31, 17, 138, 156, 184, 210, | 1468 | | 157, 184, 154, 131, 128, 110, 12, 85, 195, 122, 241, | 1469 | | 79, 251, 229, 183, 117, 21, 123, 133, 142, 220, 153, | 1470 | | 9, 59, 57, 105, 81, 255, 138, 77, 82, 54, 62, 216, | 1471 | | 38, 249, 208, 17, 197, 49, 45, 19, 232, 157, 251, | 1472 | | 131, 137, 175, 72, 126, 43, 229, 69, 179, 117, 82, | 1473 | | 157, 213, 83, 35, 57, 210, 197, 252, 171, 143, 194, | 1474 | | 11, 47, 163, 6, 253, 75, 252, 96, 11, 187, 84, 130, | 1475 | | 210, 7, 121, 78, 91, 79, 57, 251, 138, 132, 220, 60, | 1476 | | 224, 173, 56, 224, 201] | 1477 +-----------+-------------------------------------------------------+ 1479 The resulting JWE Encrypted Key value is: 1481 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1482 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1483 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1484 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1485 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1486 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1487 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1488 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1489 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1490 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1491 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1492 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1493 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1494 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1495 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1496 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1497 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1498 117, 114, 135, 206] 1500 A.1.5. Encoded JWE Encrypted Key 1502 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1503 Encrypted Key. This result (with line breaks for display purposes 1504 only) is: 1506 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1507 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1508 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1509 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1510 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1511 6UklfCpIMfIjf7iGdXKHzg 1513 A.1.6. Initialization Vector 1515 Generate a random 96 bit JWE Initialization Vector. In this example, 1516 the value is: 1518 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1520 Base64url encoding this value yields the Encoded JWE Initialization 1521 Vector value: 1523 48V1_ALb6US04U3b 1525 A.1.7. Additional Authenticated Data 1527 Let the Additional Authenticated Data encryption parameter be the 1528 octets of the ASCII representation of the Encoded JWE Header value. 1529 This AAD value is: 1531 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1532 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1533 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1535 A.1.8. Plaintext Encryption 1537 Encrypt the Plaintext with AES GCM using the CEK as the encryption 1538 key, the JWE Initialization Vector, and the Additional Authenticated 1539 Data value above, requesting a 128 bit Authentication Tag output. 1540 The resulting Ciphertext is: 1542 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1543 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1544 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1545 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1546 160, 109, 64, 63, 192] 1547 The resulting Authentication Tag value is: 1549 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1550 210, 145] 1552 A.1.9. Encoded JWE Ciphertext 1554 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1555 This result (with line breaks for display purposes only) is: 1557 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1558 SdiwkIr3ajwQzaBtQD_A 1560 A.1.10. Encoded JWE Authentication Tag 1562 Base64url encode the Authentication Tag to create the Encoded JWE 1563 Authentication Tag. This result is: 1565 XFBoMYUZodetZdvTiFvSkQ 1567 A.1.11. Complete Representation 1569 Assemble the final representation: The Compact Serialization of this 1570 result is the concatenation of the Encoded JWE Header, the Encoded 1571 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1572 JWE Ciphertext, and the Encoded JWE Authentication Tag in that order, 1573 with the five strings being separated by four period ('.') 1574 characters. 1576 The final result in this example (with line breaks for display 1577 purposes only) is: 1579 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1580 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1581 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1582 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1583 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1584 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1585 6UklfCpIMfIjf7iGdXKHzg. 1586 48V1_ALb6US04U3b. 1587 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1588 SdiwkIr3ajwQzaBtQD_A. 1589 XFBoMYUZodetZdvTiFvSkQ 1591 A.1.12. Validation 1593 This example illustrates the process of creating a JWE with RSA OAEP 1594 and AES GCM. These results can be used to validate JWE decryption 1595 implementations for these algorithms. Note that since the RSAES OAEP 1596 computation includes random values, the encryption results above will 1597 not be completely reproducible. However, since the AES GCM 1598 computation is deterministic, the JWE Encrypted Ciphertext values 1599 will be the same for all encryptions performed using these inputs. 1601 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1603 This example encrypts the plaintext "Live long and prosper." to the 1604 recipient using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256. The 1605 representation of this plaintext is: 1607 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1608 112, 114, 111, 115, 112, 101, 114, 46] 1610 A.2.1. JWE Header 1612 The following example JWE Header (with line breaks for display 1613 purposes only) declares that: 1615 o the Content Encryption Key is encrypted to the recipient using the 1616 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1618 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1619 algorithm to produce the Ciphertext. 1621 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1623 A.2.2. Encoded JWE Header 1625 Base64url encoding the octets of the UTF-8 representation of the JWE 1626 Header yields this Encoded JWE Header value: 1628 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1630 A.2.3. Content Encryption Key (CEK) 1632 Generate a 256 bit random Content Encryption Key (CEK). In this 1633 example, the key value is: 1635 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1636 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1637 44, 207] 1639 A.2.4. Key Encryption 1641 Encrypt the CEK with the recipient's public key using the RSAES- 1642 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. In this 1643 example, the RSA key parameters are: 1645 +-----------+-------------------------------------------------------+ 1646 | Parameter | Value | 1647 | Name | | 1648 +-----------+-------------------------------------------------------+ 1649 | Modulus | [177, 119, 33, 13, 164, 30, 108, 121, 207, 136, 107, | 1650 | | 242, 12, 224, 19, 226, 198, 134, 17, 71, 173, 75, 42, | 1651 | | 61, 48, 162, 206, 161, 97, 108, 185, 234, 226, 219, | 1652 | | 118, 206, 118, 5, 169, 224, 60, 181, 90, 85, 51, 123, | 1653 | | 6, 224, 4, 122, 29, 230, 151, 12, 244, 127, 121, 25, | 1654 | | 4, 85, 220, 144, 215, 110, 130, 17, 68, 228, 129, | 1655 | | 138, 7, 130, 231, 40, 212, 214, 17, 179, 28, 124, | 1656 | | 151, 178, 207, 20, 14, 154, 222, 113, 176, 24, 198, | 1657 | | 73, 211, 113, 9, 33, 178, 80, 13, 25, 21, 25, 153, | 1658 | | 212, 206, 67, 154, 147, 70, 194, 192, 183, 160, 83, | 1659 | | 98, 236, 175, 85, 23, 97, 75, 199, 177, 73, 145, 50, | 1660 | | 253, 206, 32, 179, 254, 236, 190, 82, 73, 67, 129, | 1661 | | 253, 252, 220, 108, 136, 138, 11, 192, 1, 36, 239, | 1662 | | 228, 55, 81, 113, 17, 25, 140, 63, 239, 146, 3, 172, | 1663 | | 96, 60, 227, 233, 64, 255, 224, 173, 225, 228, 229, | 1664 | | 92, 112, 72, 99, 97, 26, 87, 187, 123, 46, 50, 90, | 1665 | | 202, 117, 73, 10, 153, 47, 224, 178, 163, 77, 48, 46, | 1666 | | 154, 33, 148, 34, 228, 33, 172, 216, 89, 46, 225, | 1667 | | 127, 68, 146, 234, 30, 147, 54, 146, 5, 133, 45, 78, | 1668 | | 254, 85, 55, 75, 213, 86, 194, 218, 215, 163, 189, | 1669 | | 194, 54, 6, 83, 36, 18, 153, 53, 7, 48, 89, 35, 66, | 1670 | | 144, 7, 65, 154, 13, 97, 75, 55, 230, 132, 3, 13, | 1671 | | 239, 71] | 1672 | Exponent | [1, 0, 1] | 1673 | Private | [84, 80, 150, 58, 165, 235, 242, 123, 217, 55, 38, | 1674 | Exponent | 154, 36, 181, 221, 156, 211, 215, 100, 164, 90, 88, | 1675 | | 40, 228, 83, 148, 54, 122, 4, 16, 165, 48, 76, 194, | 1676 | | 26, 107, 51, 53, 179, 165, 31, 18, 198, 173, 78, 61, | 1677 | | 56, 97, 252, 158, 140, 80, 63, 25, 223, 156, 36, 203, | 1678 | | 214, 252, 120, 67, 180, 167, 3, 82, 243, 25, 97, 214, | 1679 | | 83, 133, 69, 16, 104, 54, 160, 200, 41, 83, 164, 187, | 1680 | | 70, 153, 111, 234, 242, 158, 175, 28, 198, 48, 211, | 1681 | | 45, 148, 58, 23, 62, 227, 74, 52, 117, 42, 90, 41, | 1682 | | 249, 130, 154, 80, 119, 61, 26, 193, 40, 125, 10, | 1683 | | 152, 174, 227, 225, 205, 32, 62, 66, 6, 163, 100, 99, | 1684 | | 219, 19, 253, 25, 105, 80, 201, 29, 252, 157, 237, | 1685 | | 69, 1, 80, 171, 167, 20, 196, 156, 109, 249, 88, 0, | 1686 | | 3, 152, 38, 165, 72, 87, 6, 152, 71, 156, 214, 16, | 1687 | | 71, 30, 82, 51, 103, 76, 218, 63, 9, 84, 163, 249, | 1688 | | 91, 215, 44, 238, 85, 101, 240, 148, 1, 82, 224, 91, | 1689 | | 135, 105, 127, 84, 171, 181, 152, 210, 183, 126, 24, | 1690 | | 46, 196, 90, 173, 38, 245, 219, 186, 222, 27, 240, | 1691 | | 212, 194, 15, 66, 135, 226, 178, 190, 52, 245, 74, | 1692 | | 65, 224, 81, 100, 85, 25, 204, 165, 203, 187, 175, | 1693 | | 84, 100, 82, 15, 11, 23, 202, 151, 107, 54, 41, 207, | 1694 | | 3, 136, 229, 134, 131, 93, 139, 50, 182, 204, 93, | 1695 | | 130, 89] | 1696 +-----------+-------------------------------------------------------+ 1698 The resulting JWE Encrypted Key value is: 1700 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1701 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1702 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1703 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1704 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1705 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1706 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1707 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1708 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1709 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1710 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1711 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1712 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1713 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1714 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1715 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1716 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1717 146, 114, 165, 204, 71, 136, 41, 252] 1719 A.2.5. Encoded JWE Encrypted Key 1721 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1722 Encrypted Key. This result (with line breaks for display purposes 1723 only) is: 1725 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1726 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1727 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1728 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1729 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1730 -B3oWh2TbqmScqXMR4gp_A 1732 A.2.6. Initialization Vector 1734 Generate a random 128 bit JWE Initialization Vector. In this 1735 example, the value is: 1737 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1738 101] 1740 Base64url encoding this value yields the Encoded JWE Initialization 1741 Vector value: 1743 AxY8DCtDaGlsbGljb3RoZQ 1745 A.2.7. Additional Authenticated Data 1747 Let the Additional Authenticated Data encryption parameter be the 1748 octets of the ASCII representation of the Encoded JWE Header value. 1749 This AAD value is: 1751 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1752 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1753 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1754 50, 73, 110, 48] 1756 A.2.8. Plaintext Encryption 1758 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1759 the encryption key, the JWE Initialization Vector, and the Additional 1760 Authenticated Data value above. The steps for doing this using the 1761 values from Appendix A.3 are detailed in Appendix B. The resulting 1762 Ciphertext is: 1764 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1765 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1766 112, 56, 102] 1767 The resulting Authentication Tag value is: 1769 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1770 191] 1772 A.2.9. Encoded JWE Ciphertext 1774 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1775 This result is: 1777 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1779 A.2.10. Encoded JWE Authentication Tag 1781 Base64url encode the Authentication Tag to create the Encoded JWE 1782 Authentication Tag. This result is: 1784 9hH0vgRfYgPnAHOd8stkvw 1786 A.2.11. Complete Representation 1788 Assemble the final representation: The Compact Serialization of this 1789 result is the concatenation of the Encoded JWE Header, the Encoded 1790 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1791 JWE Ciphertext, and the Encoded JWE Authentication Tag in that order, 1792 with the five strings being separated by four period ('.') 1793 characters. 1795 The final result in this example (with line breaks for display 1796 purposes only) is: 1798 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1799 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1800 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1801 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1802 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1803 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1804 -B3oWh2TbqmScqXMR4gp_A. 1805 AxY8DCtDaGlsbGljb3RoZQ. 1806 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1807 9hH0vgRfYgPnAHOd8stkvw 1809 A.2.12. Validation 1811 This example illustrates the process of creating a JWE with RSAES- 1812 PKCS1-V1_5 and AES_CBC_HMAC_SHA2. These results can be used to 1813 validate JWE decryption implementations for these algorithms. Note 1814 that since the RSAES-PKCS1-V1_5 computation includes random values, 1815 the encryption results above will not be completely reproducible. 1816 However, since the AES CBC computation is deterministic, the JWE 1817 Encrypted Ciphertext values will be the same for all encryptions 1818 performed using these inputs. 1820 A.3. Example JWE using AES Key Wrap and AES GCM 1822 This example encrypts the plaintext "Live long and prosper." to the 1823 recipient using AES Key Wrap and AES GCM. The representation of this 1824 plaintext is: 1826 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1827 112, 114, 111, 115, 112, 101, 114, 46] 1829 A.3.1. JWE Header 1831 The following example JWE Header declares that: 1833 o the Content Encryption Key is encrypted to the recipient using the 1834 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1835 Encrypted Key and 1837 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1838 algorithm to produce the Ciphertext. 1840 {"alg":"A128KW","enc":"A128CBC-HS256"} 1842 A.3.2. Encoded JWE Header 1844 Base64url encoding the octets of the UTF-8 representation of the JWE 1845 Header yields this Encoded JWE Header value: 1847 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1849 A.3.3. Content Encryption Key (CEK) 1851 Generate a 256 bit random Content Encryption Key (CEK). In this 1852 example, the value is: 1854 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1855 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1856 44, 207] 1858 A.3.4. Key Encryption 1860 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1861 algorithm to produce the JWE Encrypted Key. In this example, the 1862 shared symmetric key value is: 1864 [25, 172, 32, 130, 225, 114, 26, 181, 138, 106, 254, 192, 95, 133, 1865 74, 82] 1867 The resulting JWE Encrypted Key value is: 1869 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1870 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1871 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1873 A.3.5. Encoded JWE Encrypted Key 1875 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1876 Encrypted Key. This result is: 1878 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1880 A.3.6. Initialization Vector 1882 Generate a random 128 bit JWE Initialization Vector. In this 1883 example, the value is: 1885 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1886 101] 1888 Base64url encoding this value yields the Encoded JWE Initialization 1889 Vector value: 1891 AxY8DCtDaGlsbGljb3RoZQ 1893 A.3.7. Additional Authenticated Data 1895 Let the Additional Authenticated Data encryption parameter be the 1896 octets of the ASCII representation of the Encoded JWE Header value. 1897 This AAD value is: 1899 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1900 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1901 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1902 110, 48] 1904 A.3.8. Plaintext Encryption 1906 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1907 the encryption key, the JWE Initialization Vector, and the Additional 1908 Authenticated Data value above. The steps for doing this using the 1909 values from this example are detailed in Appendix B. The resulting 1910 Ciphertext is: 1912 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1913 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1914 112, 56, 102] 1916 The resulting Authentication Tag value is: 1918 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1919 194, 85] 1921 A.3.9. Encoded JWE Ciphertext 1923 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1924 This result is: 1926 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1928 A.3.10. Encoded JWE Authentication Tag 1930 Base64url encode the Authentication Tag to create the Encoded JWE 1931 Authentication Tag. This result is: 1933 U0m_YmjN04DJvceFICbCVQ 1935 A.3.11. Complete Representation 1937 Assemble the final representation: The Compact Serialization of this 1938 result is the concatenation of the Encoded JWE Header, the Encoded 1939 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1940 JWE Ciphertext, and the Encoded JWE Authentication Tag in that order, 1941 with the five strings being separated by four period ('.') 1942 characters. 1944 The final result in this example (with line breaks for display 1945 purposes only) is: 1947 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1948 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1949 AxY8DCtDaGlsbGljb3RoZQ. 1950 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1951 U0m_YmjN04DJvceFICbCVQ 1953 A.3.12. Validation 1955 This example illustrates the process of creating a JWE with symmetric 1956 key wrap and AES_CBC_HMAC_SHA2. These results can be used to 1957 validate JWE decryption implementations for these algorithms. Also, 1958 since both the AES Key Wrap and AES GCM computations are 1959 deterministic, the resulting JWE value will be the same for all 1960 encryptions performed using these inputs. Since the computation is 1961 reproducible, these results can also be used to validate JWE 1962 encryption implementations for these algorithms. 1964 A.4. Example JWE Using JWE JSON Serialization 1966 This section contains an example using the JWE JSON Serialization. 1967 This example demonstrates the capability for encrypting the same 1968 plaintext to multiple recipients. 1970 Two recipients are present in this example. The algorithm and key 1971 used for the first recipient are the same as that used in 1972 Appendix A.2. The algorithm and key used for the second recipient 1973 are the same as that used in Appendix A.3. The resulting JWE 1974 Encrypted Key values are therefore the same; those computations are 1975 not repeated here. 1977 The Plaintext, the Content Encryption Key (CEK), Initialization 1978 Vector, and JWE Protected Header are shared by all recipients (which 1979 must be the case, since the Ciphertext and Authentication Tag are 1980 also shared). 1982 A.4.1. JWE Per-Recipient Unprotected Headers 1984 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1985 the Content Encryption Key (CEK). The second uses RSAES OAEP to 1986 encrypt the CEK. Key ID values are supplied for both keys. The two 1987 per-recipient header values used to represent these algorithms and 1988 Key IDs are: 1990 {"alg":"RSA1_5","kid":"2011-04-29"} 1992 and: 1994 {"alg":"A128KW","kid":"7"} 1996 A.4.2. JWE Protected Header 1998 The Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1999 algorithm to produce the common JWE Ciphertext and JWE Authentication 2000 Tag values. The JWE Protected Header value representing this is: 2002 {"enc":"A128CBC-HS256"} 2004 Base64url encoding the octets of the UTF-8 representation of the JWE 2005 Protected Header yields this Encoded JWE Protected Header value: 2007 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 2009 A.4.3. JWE Unprotected Header 2011 This JWE uses the "jku" header parameter to reference a JWK Set. This 2012 is represented in the following JWE Unprotected Header value as: 2014 {"jku":"https://server.example.com/keys.jwks"} 2016 A.4.4. Complete JWE Header Values 2018 Combining the per-recipient, protected, and unprotected header values 2019 supplied, the JWE Header values used for the first and second 2020 recipient respectively are: 2022 {"alg":"RSA1_5", 2023 "kid":"2011-04-29", 2024 "enc":"A128CBC-HS256", 2025 "jku":"https://server.example.com/keys.jwks"} 2027 and: 2029 {"alg":"A128KW", 2030 "kid":"7", 2031 "enc":"A128CBC-HS256", 2032 "jku":"https://server.example.com/keys.jwks"} 2034 A.4.5. Additional Authenticated Data 2036 Let the Additional Authenticated Data encryption parameter be the 2037 octets of the ASCII representation of the Encoded JWE Protected 2038 Header value. This AAD value is: 2040 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 2041 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 2043 A.4.6. Plaintext Encryption 2045 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 2046 the encryption key, the JWE Initialization Vector, and the Additional 2047 Authenticated Data value above. The steps for doing this using the 2048 values from Appendix A.3 are detailed in Appendix B. The resulting 2049 Ciphertext is: 2051 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 2052 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 2053 112, 56, 102] 2054 The resulting Authentication Tag value is: 2056 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 2057 207] 2059 A.4.7. Encoded JWE Ciphertext 2061 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 2062 This result is: 2064 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 2066 A.4.8. Encoded JWE Authentication Tag 2068 Base64url encode the Authentication Tag to create the Encoded JWE 2069 Authentication Tag. This result is: 2071 Mz-VPPyU4RlcuYv1IwIvzw 2073 A.4.9. Complete JWE JSON Serialization Representation 2075 The complete JSON Web Encryption JSON Serialization for these values 2076 is as follows (with line breaks for display purposes only): 2078 {"protected": 2079 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 2080 "unprotected": 2081 {"jku":"https://server.example.com/keys.jwks"}, 2082 "recipients":[ 2083 {"header": 2084 {"alg":"RSA1_5"}, 2085 "encrypted_key": 2086 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 2087 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 2088 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 2089 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 2090 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 2091 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 2092 {"header": 2093 {"alg":"A128KW"}, 2094 "encrypted_key": 2095 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 2096 "iv": 2097 "AxY8DCtDaGlsbGljb3RoZQ", 2098 "ciphertext": 2099 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 2100 "tag": 2101 "Mz-VPPyU4RlcuYv1IwIvzw" 2103 } 2105 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 2107 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 2108 authenticated encryption computation using the values from the 2109 example in Appendix A.3. As described where this algorithm is 2110 defined in Sections 4.8 and 4.8.3 of JWA, the AES_CBC_HMAC_SHA2 2111 family of algorithms are implemented using Advanced Encryption 2112 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #5 2113 padding to perform the encryption and an HMAC SHA-2 function to 2114 perform the integrity calculation - in this case, HMAC SHA-256. 2116 B.1. Extract MAC_KEY and ENC_KEY from Key 2118 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example is: 2120 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 2121 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 2122 44, 207] 2124 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 2125 which is: 2127 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 2128 206] 2130 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 2131 is: 2133 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 2134 207] 2136 Note that the MAC key comes before the encryption key in the input 2137 key K; this is in the opposite order of the algorithm names in the 2138 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 2140 B.2. Encrypt Plaintext to Create Ciphertext 2142 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 2143 using PKCS #5 padding using the ENC_KEY above. The Plaintext in this 2144 example is: 2146 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 2147 112, 114, 111, 115, 112, 101, 114, 46] 2149 The encryption result is as follows, which is the Ciphertext output: 2151 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 2152 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 2153 112, 56, 102] 2155 B.3. 64 Bit Big Endian Representation of AAD Length 2157 The Additional Authenticated Data (AAD) in this example is: 2159 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2160 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2161 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2162 110, 48] 2164 This AAD is 51 bytes long, which is 408 bits long. The octet string 2165 AL, which is the number of bits in AAD expressed as a big endian 64 2166 bit unsigned integer is: 2168 [0, 0, 0, 0, 0, 0, 1, 152] 2170 B.4. Initialization Vector Value 2172 The Initialization Vector value used in this example is: 2174 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 2175 101] 2177 B.5. Create Input to HMAC Computation 2179 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 2180 the AL value. The result of this concatenation is: 2182 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2183 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2184 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2185 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 2186 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 2187 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 2188 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 2190 B.6. Compute HMAC Value 2192 Compute the HMAC SHA-256 of the concatenated value above. This 2193 result M is: 2195 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2196 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 2197 86, 229, 116] 2199 B.7. Truncate HMAC Value to Create Authentication Tag 2201 Use the first half (128 bits) of the HMAC output M as the 2202 Authentication Tag output T. This truncated value is: 2204 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2205 194, 85] 2207 Appendix C. Acknowledgements 2209 Solutions for encrypting JSON content were also explored by JSON 2210 Simple Encryption [JSE] and JavaScript Message Security Format 2211 [I-D.rescorla-jsms], both of which significantly influenced this 2212 draft. This draft attempts to explicitly reuse as many of the 2213 relevant concepts from XML Encryption 1.1 2214 [W3C.CR-xmlenc-core1-20120313] and RFC 5652 [RFC5652] as possible, 2215 while utilizing simple compact JSON-based data structures. 2217 Special thanks are due to John Bradley and Nat Sakimura for the 2218 discussions that helped inform the content of this specification and 2219 to Eric Rescorla and Joe Hildebrand for allowing the reuse of text 2220 from [I-D.rescorla-jsms] in this document. 2222 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2223 Jay for validating the examples in this specification. 2225 This specification is the work of the JOSE Working Group, which 2226 includes dozens of active and dedicated participants. In particular, 2227 the following individuals contributed ideas, feedback, and wording 2228 that influenced this specification: 2230 Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick 2231 Hardt, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Tony 2232 Nadalin, Axel Nennker, Emmanuel Raviart, Nat Sakimura, Jim Schaad, 2233 Hannes Tschofenig, and Sean Turner. 2235 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2236 Sean Turner and Stephen Farrell served as Security area directors 2237 during the creation of this specification. 2239 Appendix D. Document History 2241 [[ to be removed by the RFC editor before publication as an RFC ]] 2243 -11 2244 o Added Key Identification section. 2246 o Removed the Encrypted Key value from the AAD computation since it 2247 is already effectively integrity protected by the encryption 2248 process. The AAD value now only contains the representation of 2249 the JWE Encrypted Header. 2251 o For the JWE JSON Serialization, enable header parameter values to 2252 be specified in any of three parameters: the "protected" member 2253 that is integrity protected and shared among all recipients, the 2254 "unprotected" member that is not integrity protected and shared 2255 among all recipients, and the "header" member that is not 2256 integrity protected and specific to a particular recipient. (This 2257 does not affect the JWE Compact Serialization, in which all header 2258 parameter values are in a single integrity protected JWE Header 2259 value.) 2261 o Shortened the names "authentication_tag" to "tag" and 2262 "initialization_vector" to "iv" in the JWE JSON Serialization, 2263 addressing issue #20. 2265 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2267 o Removed suggested compact serialization for multiple recipients. 2269 o Changed the MIME type name "application/jwe-js" to 2270 "application/jwe+json", addressing issue #22. 2272 o Tightened the description of the "crit" (critical) header 2273 parameter. 2275 -10 2277 o Changed the JWE processing rules for multiple recipients so that a 2278 single AAD value contains the header parameters and encrypted key 2279 values for all the recipients, enabling AES GCM to be safely used 2280 for multiple recipients. 2282 o Added an appendix suggesting a possible compact serialization for 2283 JWEs with multiple recipients. 2285 -09 2287 o Added JWE JSON Serialization, as specified by 2288 draft-jones-jose-jwe-json-serialization-04. 2290 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2291 parameter value. 2293 o Defined that the default action for header parameters that are not 2294 understood is to ignore them unless specifically designated as 2295 "MUST be understood" or included in the new "crit" (critical) 2296 header parameter list. This addressed issue #6. 2298 o Corrected "x5c" description. This addressed issue #12. 2300 o Changed from using the term "byte" to "octet" when referring to 8 2301 bit values. 2303 o Added Key Management Mode definitions to terminology section and 2304 used the defined terms to provide clearer key management 2305 instructions. This addressed issue #5. 2307 o Added text about preventing the recipient from behaving as an 2308 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2310 o Changed from using the term "Integrity Value" to "Authentication 2311 Tag". 2313 o Changed member name from "integrity_value" to "authentication_tag" 2314 in the JWE JSON Serialization. 2316 o Removed Initialization Vector from the AAD value since it is 2317 already integrity protected by all of the authenticated encryption 2318 algorithms specified in the JWA specification. 2320 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2321 and "A256CBC-HS512". The new algorithms perform the same 2322 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2323 but with the Initialization Vector and Authentication Tag values 2324 remaining separate from the Ciphertext value in the output 2325 representation. Also deleted the header parameters "epu" 2326 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2327 they are no longer used. 2329 -08 2331 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2332 since the term AEAD in the RFC 5116 sense implied the use of a 2333 particular data representation, rather than just referring to the 2334 class of algorithms that perform authenticated encryption with 2335 associated data. 2337 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2338 Tschofenig. Many of these simplified the terminology used. 2340 o Clarified statements of the form "This header parameter is 2341 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2343 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2344 Web Signature and Encryption Header Parameters registry. 2346 o Added seriesInfo information to Internet Draft references. 2348 -07 2350 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2352 o Updated values for example AES CBC calculations. 2354 o Made several local editorial changes to clean up loose ends left 2355 over from to the decision to only support block encryption methods 2356 providing integrity. One of these changes was to explicitly state 2357 that the "enc" (encryption method) algorithm must be an 2358 Authenticated Encryption algorithm with a specified key length. 2360 -06 2362 o Removed the "int" and "kdf" parameters and defined the new 2363 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2364 "A256CBC+HS512" to replace the former uses of AES CBC, which 2365 required the use of separate integrity and key derivation 2366 functions. 2368 o Included additional values in the Concat KDF calculation -- the 2369 desired output size and the algorithm value, and optionally 2370 PartyUInfo and PartyVInfo values. Added the optional header 2371 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2372 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2373 PartyVInfo). Updated the KDF examples accordingly. 2375 o Promoted Initialization Vector from being a header parameter to 2376 being a top-level JWE element. This saves approximately 16 bytes 2377 in the compact serialization, which is a significant savings for 2378 some use cases. Promoting the Initialization Vector out of the 2379 header also avoids repeating this shared value in the JSON 2380 serialization. 2382 o Changed "x5c" (X.509 Certificate Chain) representation from being 2383 a single string to being an array of strings, each containing a 2384 single base64 encoded DER certificate value, representing elements 2385 of the certificate chain. 2387 o Added an AES Key Wrap example. 2389 o Reordered the encryption steps so CMK creation is first, when 2390 required. 2392 o Correct statements in examples about which algorithms produce 2393 reproducible results. 2395 -05 2397 o Support both direct encryption using a shared or agreed upon 2398 symmetric key, and the use of a shared or agreed upon symmetric 2399 key to key wrap the CMK. 2401 o Added statement that "StringOrURI values are compared as case- 2402 sensitive strings with no transformations or canonicalizations 2403 applied". 2405 o Updated open issues. 2407 o Indented artwork elements to better distinguish them from the body 2408 text. 2410 -04 2412 o Refer to the registries as the primary sources of defined values 2413 and then secondarily reference the sections defining the initial 2414 contents of the registries. 2416 o Normatively reference XML Encryption 1.1 2417 [W3C.CR-xmlenc-core1-20120313] for its security considerations. 2419 o Reference draft-jones-jose-jwe-json-serialization instead of 2420 draft-jones-json-web-encryption-json-serialization. 2422 o Described additional open issues. 2424 o Applied editorial suggestions. 2426 -03 2428 o Added the "kdf" (key derivation function) header parameter to 2429 provide crypto agility for key derivation. The default KDF 2430 remains the Concat KDF with the SHA-256 digest function. 2432 o Reordered encryption steps so that the Encoded JWE Header is 2433 always created before it is needed as an input to the 2434 Authenticated Encryption "additional authenticated data" 2435 parameter. 2437 o Added the "cty" (content type) header parameter for declaring type 2438 information about the secured content, as opposed to the "typ" 2439 (type) header parameter, which declares type information about 2440 this object. 2442 o Moved description of how to determine whether a header is for a 2443 JWS or a JWE from the JWT spec to the JWE spec. 2445 o Added complete encryption examples for both Authenticated 2446 Encryption and non-Authenticated Encryption algorithms. 2448 o Added complete key derivation examples. 2450 o Added "Collision Resistant Namespace" to the terminology section. 2452 o Reference ITU.X690.1994 for DER encoding. 2454 o Added Registry Contents sections to populate registry values. 2456 o Numerous editorial improvements. 2458 -02 2460 o When using Authenticated Encryption algorithms (such as AES GCM), 2461 use the "additional authenticated data" parameter to provide 2462 integrity for the header, encrypted key, and ciphertext and use 2463 the resulting "authentication tag" value as the JWE Authentication 2464 Tag. 2466 o Defined KDF output key sizes. 2468 o Generalized text to allow key agreement to be employed as an 2469 alternative to key wrapping or key encryption. 2471 o Changed compression algorithm from gzip to DEFLATE. 2473 o Clarified that it is an error when a "kid" value is included and 2474 no matching key is found. 2476 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2477 rejected. 2479 o Clarified the relationship between "typ" header parameter values 2480 and MIME types. 2482 o Registered application/jwe MIME type and "JWE" typ header 2483 parameter value. 2485 o Simplified JWK terminology to get replace the "JWK Key Object" and 2486 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2487 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2488 between single keys and sets of keys. As part of this change, the 2489 Header Parameter Name for a public key value was changed from 2490 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2492 o Added suggestion on defining additional header parameters such as 2493 "x5t#S256" in the future for certificate thumbprints using hash 2494 algorithms other than SHA-1. 2496 o Specify RFC 2818 server identity validation, rather than RFC 6125 2497 (paralleling the same decision in the OAuth specs). 2499 o Generalized language to refer to Message Authentication Codes 2500 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2501 unless in a context specific to HMAC algorithms. 2503 o Reformatted to give each header parameter its own section heading. 2505 -01 2507 o Added an integrity check for non-Authenticated Encryption 2508 algorithms. 2510 o Added "jpk" and "x5c" header parameters for including JWK public 2511 keys and X.509 certificate chains directly in the header. 2513 o Clarified that this specification is defining the JWE Compact 2514 Serialization. Referenced the new JWE-JS spec, which defines the 2515 JWE JSON Serialization. 2517 o Added text "New header parameters should be introduced sparingly 2518 since an implementation that does not understand a parameter MUST 2519 reject the JWE". 2521 o Clarified that the order of the encryption and decryption steps is 2522 not significant in cases where there are no dependencies between 2523 the inputs and outputs of the steps. 2525 o Made other editorial improvements suggested by JOSE working group 2526 participants. 2528 -00 2529 o Created the initial IETF draft based upon 2530 draft-jones-json-web-encryption-02 with no normative changes. 2532 o Changed terminology to no longer call both digital signatures and 2533 HMACs "signatures". 2535 Authors' Addresses 2537 Michael B. Jones 2538 Microsoft 2540 Email: mbj@microsoft.com 2541 URI: http://self-issued.info/ 2543 Eric Rescorla 2544 RTFM, Inc. 2546 Email: ekr@rtfm.com 2548 Joe Hildebrand 2549 Cisco Systems, Inc. 2551 Email: jhildebr@cisco.com