idnits 2.17.1 draft-ietf-jose-json-web-encryption-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The "crit" (critical) header parameter indicates that extensions to [[ this specification ]] are being used that MUST be understood and processed. Its value is an array listing the header parameter names defined by those extensions that are used in the JWE Header. If any of the listed extension header parameters are not understood and supported by the receiver, it MUST reject the JWE. Senders MUST NOT include header parameter names defined by [[ this specification ]] or by [JWA] for use with JWE, duplicate names, or names that do not occur as header parameter names within the JWE Header in the "crit" list. Senders MUST not use the empty list "[]" as the "crit" value. Recipients MAY reject the JWE if the critical list contains any header parameter names defined by [[ this specification ]] or by [JWA] for use with JWE, or any other constraints on its use are violated. This header parameter MUST be integrity protected, and therefore MUST occur only with the JWE Protected Header, when used. Use of this header parameter is OPTIONAL. This header parameter MUST be understood by implementations. -- The document date (July 11, 2013) is 3935 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: '227' on line 1380 -- Looks like a reference, but probably isn't: '197' on line 1380 -- Looks like a reference, but probably isn't: '117' on line 1380 -- Looks like a reference, but probably isn't: '252' on line 1380 -- Looks like a reference, but probably isn't: '2' on line 1380 -- Looks like a reference, but probably isn't: '219' on line 1380 -- Looks like a reference, but probably isn't: '233' on line 1380 -- Looks like a reference, but probably isn't: '68' on line 1380 -- Looks like a reference, but probably isn't: '180' on line 1380 -- Looks like a reference, but probably isn't: '225' on line 1380 -- Looks like a reference, but probably isn't: '77' on line 1380 -- Looks like a reference, but probably isn't: '0' on line 1999 -- Looks like a reference, but probably isn't: '1' on line 1999 -- Looks like a reference, but probably isn't: '152' on line 1999 -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMAScript' -- Possible downref: Non-RFC (?) normative reference: ref. 'ITU.X690.1994' ** Downref: Normative reference to an Historic RFC: RFC 1421 ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) == Outdated reference: A later version (-05) exists of draft-mcgrew-aead-aes-cbc-hmac-sha2-01 Summary: 5 errors (**), 0 flaws (~~), 3 warnings (==), 17 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track E. Rescorla 5 Expires: January 12, 2014 RTFM 6 J. Hildebrand 7 Cisco 8 July 11, 2013 10 JSON Web Encryption (JWE) 11 draft-ietf-jose-json-web-encryption-12 13 Abstract 15 JSON Web Encryption (JWE) is a means of representing encrypted 16 content using JavaScript Object Notation (JSON) based data 17 structures. Cryptographic algorithms and identifiers for use with 18 this specification are described in the separate JSON Web Algorithms 19 (JWA) specification. Related digital signature and MAC capabilities 20 are described in the separate JSON Web Signature (JWS) specification. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on January 12, 2014. 39 Copyright Notice 41 Copyright (c) 2013 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 5 58 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 8 60 3.1. Example JWE . . . . . . . . . . . . . . . . . . . . . . . 9 61 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10 62 4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 11 63 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 11 64 4.1.2. "enc" (Encryption Method) Header Parameter . . . . . . 12 65 4.1.3. "zip" (Compression Algorithm) Header Parameter . . . . 12 66 4.1.4. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 12 67 4.1.5. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 12 68 4.1.6. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 13 69 4.1.7. "x5t" (X.509 Certificate Thumbprint) Header 70 Parameter . . . . . . . . . . . . . . . . . . . . . . 13 71 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter . . . 13 72 4.1.9. "kid" (Key ID) Header Parameter . . . . . . . . . . . 14 73 4.1.10. "typ" (Type) Header Parameter . . . . . . . . . . . . 14 74 4.1.11. "cty" (Content Type) Header Parameter . . . . . . . . 14 75 4.1.12. "crit" (Critical) Header Parameter . . . . . . . . . . 15 76 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 15 77 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 16 78 5. Producing and Consuming JWEs . . . . . . . . . . . . . . . . . 16 79 5.1. Message Encryption . . . . . . . . . . . . . . . . . . . . 16 80 5.2. Message Decryption . . . . . . . . . . . . . . . . . . . . 18 81 5.3. String Comparison Rules . . . . . . . . . . . . . . . . . 20 82 6. Key Identification . . . . . . . . . . . . . . . . . . . . . . 20 83 7. Serializations . . . . . . . . . . . . . . . . . . . . . . . . 20 84 7.1. JWE Compact Serialization . . . . . . . . . . . . . . . . 21 85 7.2. JWE JSON Serialization . . . . . . . . . . . . . . . . . . 21 86 8. Distinguishing Between JWS and JWE Objects . . . . . . . . . . 23 87 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 88 9.1. Registration of JWE Header Parameter Names . . . . . . . . 24 89 9.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 24 90 10. Security Considerations . . . . . . . . . . . . . . . . . . . 26 91 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 92 11.1. Normative References . . . . . . . . . . . . . . . . . . . 26 93 11.2. Informative References . . . . . . . . . . . . . . . . . . 28 94 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 28 95 A.1. Example JWE using RSAES OAEP and AES GCM . . . . . . . . . 28 96 A.1.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 29 97 A.1.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 29 98 A.1.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 29 99 A.1.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 29 100 A.1.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 30 101 A.1.6. Initialization Vector . . . . . . . . . . . . . . . . 31 102 A.1.7. Additional Authenticated Data . . . . . . . . . . . . 31 103 A.1.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 31 104 A.1.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 31 105 A.1.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 32 106 A.1.11. Complete Representation . . . . . . . . . . . . . . . 32 107 A.1.12. Validation . . . . . . . . . . . . . . . . . . . . . . 32 108 A.2. Example JWE using RSAES-PKCS1-V1_5 and 109 AES_128_CBC_HMAC_SHA_256 . . . . . . . . . . . . . . . . . 32 110 A.2.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 33 111 A.2.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 33 112 A.2.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 33 113 A.2.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 33 114 A.2.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 34 115 A.2.6. Initialization Vector . . . . . . . . . . . . . . . . 35 116 A.2.7. Additional Authenticated Data . . . . . . . . . . . . 35 117 A.2.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 35 118 A.2.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 35 119 A.2.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 36 120 A.2.11. Complete Representation . . . . . . . . . . . . . . . 36 121 A.2.12. Validation . . . . . . . . . . . . . . . . . . . . . . 36 122 A.3. Example JWE using AES Key Wrap and AES GCM . . . . . . . . 36 123 A.3.1. JWE Header . . . . . . . . . . . . . . . . . . . . . . 37 124 A.3.2. Encoded JWE Header . . . . . . . . . . . . . . . . . . 37 125 A.3.3. Content Encryption Key (CEK) . . . . . . . . . . . . . 37 126 A.3.4. Key Encryption . . . . . . . . . . . . . . . . . . . . 37 127 A.3.5. Encoded JWE Encrypted Key . . . . . . . . . . . . . . 38 128 A.3.6. Initialization Vector . . . . . . . . . . . . . . . . 38 129 A.3.7. Additional Authenticated Data . . . . . . . . . . . . 38 130 A.3.8. Plaintext Encryption . . . . . . . . . . . . . . . . . 38 131 A.3.9. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 39 132 A.3.10. Encoded JWE Authentication Tag . . . . . . . . . . . . 39 133 A.3.11. Complete Representation . . . . . . . . . . . . . . . 39 134 A.3.12. Validation . . . . . . . . . . . . . . . . . . . . . . 39 135 A.4. Example JWE Using JWE JSON Serialization . . . . . . . . . 39 136 A.4.1. JWE Per-Recipient Unprotected Headers . . . . . . . . 40 137 A.4.2. JWE Protected Header . . . . . . . . . . . . . . . . . 40 138 A.4.3. JWE Unprotected Header . . . . . . . . . . . . . . . . 40 139 A.4.4. Complete JWE Header Values . . . . . . . . . . . . . . 41 140 A.4.5. Additional Authenticated Data . . . . . . . . . . . . 41 141 A.4.6. Plaintext Encryption . . . . . . . . . . . . . . . . . 41 142 A.4.7. Encoded JWE Ciphertext . . . . . . . . . . . . . . . . 41 143 A.4.8. Encoded JWE Authentication Tag . . . . . . . . . . . . 42 144 A.4.9. Complete JWE JSON Serialization Representation . . . . 42 145 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation . . . . 42 146 B.1. Extract MAC_KEY and ENC_KEY from Key . . . . . . . . . . . 43 147 B.2. Encrypt Plaintext to Create Ciphertext . . . . . . . . . . 43 148 B.3. 64 Bit Big Endian Representation of AAD Length . . . . . . 43 149 B.4. Initialization Vector Value . . . . . . . . . . . . . . . 44 150 B.5. Create Input to HMAC Computation . . . . . . . . . . . . . 44 151 B.6. Compute HMAC Value . . . . . . . . . . . . . . . . . . . . 44 152 B.7. Truncate HMAC Value to Create Authentication Tag . . . . . 44 153 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 45 154 Appendix D. Document History . . . . . . . . . . . . . . . . . . 45 155 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 52 157 1. Introduction 159 JSON Web Encryption (JWE) is a means of representing encrypted 160 content using JavaScript Object Notation (JSON) [RFC4627] based data 161 structures. The JWE cryptographic mechanisms encrypt and provide 162 integrity protection for arbitrary sequences of octets. 164 Two closely related representations for JWE objects are defined. The 165 JWE Compact Serialization is a compact, URL-safe representation 166 intended for space constrained environments such as HTTP 167 Authorization headers and URI query parameters. The JWE JSON 168 Serialization represents JWE objects as JSON objects and enables the 169 same content to be encrypted to multiple parties. Both share the 170 same cryptographic underpinnings. 172 Cryptographic algorithms and identifiers for use with this 173 specification are described in the separate JSON Web Algorithms (JWA) 174 [JWA] specification. Related digital signature and MAC capabilities 175 are described in the separate JSON Web Signature (JWS) [JWS] 176 specification. 178 1.1. Notational Conventions 180 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 181 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 182 document are to be interpreted as described in Key words for use in 183 RFCs to Indicate Requirement Levels [RFC2119]. 185 2. Terminology 187 JSON Web Encryption (JWE) A data structure representing an encrypted 188 message. The structure represents five values: the JWE Header, 189 the JWE Encrypted Key, the JWE Initialization Vector, the JWE 190 Ciphertext, and the JWE Authentication Tag. 192 Authenticated Encryption with Associated Data (AEAD) An AEAD 193 algorithm is one that encrypts the Plaintext, allows Additional 194 Authenticated Data to be specified, and provides an integrated 195 content integrity check over the Ciphertext and Additional 196 Authenticated Data. AEAD algorithms accept two inputs, the 197 Plaintext and the Additional Authenticated Data value, and produce 198 two outputs, the Ciphertext and the Authentication Tag value. AES 199 Galois/Counter Mode (GCM) is one such algorithm. 201 Plaintext The sequence of octets to be encrypted -- a.k.a., the 202 message. The plaintext can contain an arbitrary sequence of 203 octets. 205 Ciphertext An encrypted representation of the Plaintext. 207 Additional Authenticated Data (AAD) An input to an AEAD operation 208 that is integrity protected but not encrypted. 210 Authentication Tag An output of an AEAD operation that ensures the 211 integrity of the Ciphertext and the Additional Authenticated Data. 212 Note that some algorithms may not use an Authentication Tag, in 213 which case this value is the empty octet sequence. 215 Content Encryption Key (CEK) A symmetric key for the AEAD algorithm 216 used to encrypt the Plaintext for the recipient to produce the 217 Ciphertext and the Authentication Tag. 219 JSON Text Object A UTF-8 [RFC3629] encoded text string representing 220 a JSON object; the syntax of JSON objects is defined in Section 221 2.2 of [RFC4627]. 223 JWE Header A JSON Text Object (or JSON Text Objects, when using the 224 JWE JSON Serialization) that describes the encryption operations 225 applied to create the JWE Encrypted Key, the JWE Ciphertext, and 226 the JWE Authentication Tag. The members of the JWE Header 227 object(s) are Header Parameters. 229 JWE Encrypted Key The result of encrypting the Content Encryption 230 Key (CEK) with the intended recipient's key using the specified 231 algorithm. Note that for some algorithms, the JWE Encrypted Key 232 value is specified as being the empty octet sequence. 234 JWE Initialization Vector A sequence of octets containing the 235 Initialization Vector used when encrypting the Plaintext. Note 236 that some algorithms may not use an Initialization Vector, in 237 which case this value is the empty octet sequence. 239 JWE Ciphertext A sequence of octets containing the Ciphertext for a 240 JWE. 242 JWE Authentication Tag A sequence of octets containing the 243 Authentication Tag for a JWE. 245 JWE Protected Header A JSON Text Object that contains the portion of 246 the JWE Header that is integrity protected. For the JWE Compact 247 Serialization, this comprises the entire JWE Header. For the JWE 248 JSON Serialization, this is one component of the JWE Header. 250 Header Parameter A name/value pair that is member of the JWE Header. 252 Header Parameter Name The name of a member of the JWE Header. 254 Header Parameter Value The value of a member of the JWE Header. 256 Base64url Encoding The URL- and filename-safe Base64 encoding 257 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 258 safe) '=' padding characters omitted, as permitted by Section 3.2. 259 (See Appendix C of [JWS] for notes on implementing base64url 260 encoding without padding.) 262 Encoded JWE Header Base64url encoding of the JWE Protected Header. 264 Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted 265 Key. 267 Encoded JWE Initialization Vector Base64url encoding of the JWE 268 Initialization Vector. 270 Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. 272 Encoded JWE Authentication Tag Base64url encoding of the JWE 273 Authentication Tag. 275 JWE Compact Serialization A representation of the JWE as the 276 concatenation of the Encoded JWE Header, the Encoded JWE Encrypted 277 Key, the Encoded JWE Initialization Vector, the Encoded JWE 278 Ciphertext, and the Encoded JWE Authentication Tag in that order, 279 with the five strings being separated by four period ('.') 280 characters. This representation is compact and URL-safe. 282 JWE JSON Serialization A representation of the JWE as a JSON 283 structure containing JWE Header, Encoded JWE Encrypted Key, 284 Encoded JWE Initialization Vector, Encoded JWE Ciphertext, and 285 Encoded JWE Authentication Tag values. Unlike the JWE Compact 286 Serialization, the JWE JSON Serialization enables the same content 287 to be encrypted to multiple parties. This representation is 288 neither compact nor URL-safe. 290 Collision Resistant Namespace A namespace that allows names to be 291 allocated in a manner such that they are highly unlikely to 292 collide with other names. For instance, collision resistance can 293 be achieved through administrative delegation of portions of the 294 namespace or through use of collision-resistant name allocation 295 functions. Examples of Collision Resistant Namespaces include: 296 Domain Names, Object Identifiers (OIDs) as defined in the ITU-T 297 X.660 and X.670 Recommendation series, and Universally Unique 298 IDentifiers (UUIDs) [RFC4122]. When using an administratively 299 delegated namespace, the definer of a name needs to take 300 reasonable precautions to ensure they are in control of the 301 portion of the namespace they use to define the name. 303 StringOrURI A JSON string value, with the additional requirement 304 that while arbitrary string values MAY be used, any value 305 containing a ":" character MUST be a URI [RFC3986]. StringOrURI 306 values are compared as case-sensitive strings with no 307 transformations or canonicalizations applied. 309 Key Management Mode A method of determining the Content Encryption 310 Key (CEK) value to use. Each algorithm used for determining the 311 CEK value uses a specific Key Management Mode. Key Management 312 Modes employed by this specification are Key Encryption, Key 313 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 314 and Direct Encryption. 316 Key Encryption A Key Management Mode in which the Content Encryption 317 Key (CEK) value is encrypted to the intended recipient using an 318 asymmetric encryption algorithm. 320 Key Wrapping A Key Management Mode in which the Content Encryption 321 Key (CEK) value is encrypted to the intended recipient using a 322 symmetric key wrapping algorithm. 324 Direct Key Agreement A Key Management Mode in which a key agreement 325 algorithm is used to agree upon the Content Encryption Key (CEK) 326 value. 328 Key Agreement with Key Wrapping A Key Management Mode in which a key 329 agreement algorithm is used to agree upon a symmetric key used to 330 encrypt the Content Encryption Key (CEK) value to the intended 331 recipient using a symmetric key wrapping algorithm. 333 Direct Encryption A Key Management Mode in which the Content 334 Encryption Key (CEK) value used is the secret symmetric key value 335 shared between the parties. 337 3. JSON Web Encryption (JWE) Overview 339 JWE represents encrypted content using JSON data structures and 340 base64url encoding. Five values are represented in a JWE: the JWE 341 Header, the JWE Encrypted Key, the JWE Initialization Vector, the JWE 342 Ciphertext, and the JWE Authentication Tag. In the Compact 343 Serialization, the five values are base64url-encoded for 344 transmission, and represented as the concatenation of the encoded 345 strings in that order, with the five strings being separated by four 346 period ('.') characters. A JSON Serialization for this information 347 is also defined in Section 7.2. 349 JWE utilizes authenticated encryption to ensure the confidentiality 350 and integrity of the Plaintext and the integrity of the JWE Protected 351 Header. 353 3.1. Example JWE 355 This example encrypts the plaintext "The true sign of intelligence is 356 not knowledge but imagination." to the recipient using RSAES OAEP for 357 key encryption and AES GCM for content encryption. 359 The following example JWE Header declares that: 361 o the Content Encryption Key is encrypted to the recipient using the 362 RSAES OAEP algorithm to produce the JWE Encrypted Key and 364 o the Plaintext is encrypted using the AES GCM algorithm with a 256 365 bit key to produce the Ciphertext. 367 {"alg":"RSA-OAEP","enc":"A256GCM"} 369 Base64url encoding the octets of the UTF-8 representation of the JWE 370 Header yields this Encoded JWE Header value: 372 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 374 The remaining steps to finish creating this JWE are: 376 o Generate a random Content Encryption Key (CEK). 378 o Encrypt the CEK with the recipient's public key using the RSAES 379 OAEP algorithm to produce the JWE Encrypted Key. 381 o Base64url encode the JWE Encrypted Key to produce the Encoded JWE 382 Encrypted Key. 384 o Generate a random JWE Initialization Vector. 386 o Base64url encode the JWE Initialization Vector to produce the 387 Encoded JWE Initialization Vector. 389 o Let the Additional Authenticated Data encryption parameter be the 390 octets of the ASCII representation of the Encoded JWE Header 391 value. 393 o Encrypt the Plaintext with AES GCM using the CEK as the encryption 394 key, the JWE Initialization Vector, and the Additional 395 Authenticated Data value, requesting a 128 bit Authentication Tag 396 output. 398 o Base64url encode the Ciphertext to create the Encoded JWE 399 Ciphertext. 401 o Base64url encode the Authentication Tag to create the Encoded JWE 402 Authentication Tag. 404 o Assemble the final representation: The Compact Serialization of 405 this result is the concatenation of the Encoded JWE Header, the 406 Encoded JWE Encrypted Key, the Encoded JWE Initialization Vector, 407 the Encoded JWE Ciphertext, and the Encoded JWE Authentication Tag 408 in that order, with the five strings being separated by four 409 period ('.') characters. 411 The final result in this example (with line breaks for display 412 purposes only) is: 414 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 415 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 416 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 417 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 418 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 419 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 420 6UklfCpIMfIjf7iGdXKHzg. 421 48V1_ALb6US04U3b. 422 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 423 SdiwkIr3ajwQzaBtQD_A. 424 XFBoMYUZodetZdvTiFvSkQ 426 See Appendix A.1 for the complete details of computing this JWE. See 427 Appendix A for additional examples. 429 4. JWE Header 431 The members of the JSON object(s) representing the JWE Header 432 describe the encryption applied to the Plaintext and optionally 433 additional properties of the JWE. The Header Parameter Names within 434 the JWE Header MUST be unique; receipients MUST either reject JWEs 435 with duplicate Header Parameter Names or use a JSON parser that 436 returns only the lexically last duplicate member name, as specified 437 in Section 15.12 (The JSON Object) of ECMAScript 5.1 [ECMAScript]. 439 Implementations are required to understand the specific header 440 parameters defined by this specification that are designated as "MUST 441 be understood" and process them in the manner defined in this 442 specification. All other header parameters defined by this 443 specification that are not so designated MUST be ignored when not 444 understood. Unless listed as a critical header parameter, per 445 Section 4.1.12, all header parameters not defined by this 446 specification MUST be ignored when not understood. 448 There are three classes of Header Parameter Names: Reserved Header 449 Parameter Names, Public Header Parameter Names, and Private Header 450 Parameter Names. 452 4.1. Reserved Header Parameter Names 454 The following Header Parameter Names are reserved with meanings as 455 defined below. All the names are short because a core goal of this 456 specification is for the resulting representations using the JWE 457 Compact Serialization to be compact. 459 Additional reserved Header Parameter Names can be defined via the 460 IANA JSON Web Signature and Encryption Header Parameters registry 461 [JWS]. As indicated by the common registry, JWSs and JWEs share a 462 common header parameter space; when a parameter is used by both 463 specifications, its usage must be compatible between the 464 specifications. 466 4.1.1. "alg" (Algorithm) Header Parameter 468 The "alg" (algorithm) header parameter identifies a cryptographic 469 algorithm used to encrypt or determine the value of the Content 470 Encryption Key (CEK). The recipient MUST reject the JWE if the "alg" 471 value does not represent a supported algorithm, or if the recipient 472 does not have a key that can be used with that algorithm. "alg" 473 values SHOULD either be registered in the IANA JSON Web Signature and 474 Encryption Algorithms registry [JWA] or be a value that contains a 475 Collision Resistant Namespace. The "alg" value is a case sensitive 476 string containing a StringOrURI value. Use of this header parameter 477 is REQUIRED. This header parameter MUST be understood by 478 implementations. 480 A list of defined "alg" values can be found in the IANA JSON Web 481 Signature and Encryption Algorithms registry [JWA]; the initial 482 contents of this registry are the values defined in Section 4.1 of 483 the JSON Web Algorithms (JWA) [JWA] specification. 485 4.1.2. "enc" (Encryption Method) Header Parameter 487 The "enc" (encryption method) header parameter identifies the content 488 encryption algorithm used to encrypt the Plaintext to produce the 489 Ciphertext. This algorithm MUST be an AEAD algorithm with a 490 specified key length. The recipient MUST reject the JWE if the "enc" 491 value does not represent a supported algorithm. "enc" values SHOULD 492 either be registered in the IANA JSON Web Signature and Encryption 493 Algorithms registry [JWA] or be a value that contains a Collision 494 Resistant Namespace. The "enc" value is a case sensitive string 495 containing a StringOrURI value. Use of this header parameter is 496 REQUIRED. This header parameter MUST be understood by 497 implementations. 499 A list of defined "enc" values can be found in the IANA JSON Web 500 Signature and Encryption Algorithms registry [JWA]; the initial 501 contents of this registry are the values defined in Section 4.2 of 502 the JSON Web Algorithms (JWA) [JWA] specification. 504 4.1.3. "zip" (Compression Algorithm) Header Parameter 506 The "zip" (compression algorithm) applied to the Plaintext before 507 encryption, if any. If present, the value of the "zip" header 508 parameter MUST be the case sensitive string "DEF". Compression is 509 performed with the DEFLATE [RFC1951] algorithm. If no "zip" 510 parameter is present, no compression is applied to the Plaintext 511 before encryption. This header parameter MUST be integrity 512 protected, and therefore MUST occur only with the JWE Protected 513 Header, when used. Use of this header parameter is OPTIONAL. This 514 header parameter MUST be understood by implementations. 516 4.1.4. "jku" (JWK Set URL) Header Parameter 518 The "jku" (JWK Set URL) header parameter is a URI [RFC3986] that 519 refers to a resource for a set of JSON-encoded public keys, one of 520 which is the key to which the JWE was encrypted; this can be used to 521 determine the private key needed to decrypt the JWE. The keys MUST 522 be encoded as a JSON Web Key Set (JWK Set) [JWK]. The protocol used 523 to acquire the resource MUST provide integrity protection; an HTTP 524 GET request to retrieve the JWK Set MUST use TLS [RFC2818] [RFC5246]; 525 the identity of the server MUST be validated, as per Section 3.1 of 526 HTTP Over TLS [RFC2818]. Use of this header parameter is OPTIONAL. 528 4.1.5. "jwk" (JSON Web Key) Header Parameter 530 The "jwk" (JSON Web Key) header parameter is the public key to which 531 the JWE was encrypted; this can be used to determine the private key 532 needed to decrypt the JWE. This key is represented as a JSON Web Key 534 [JWK]. Use of this header parameter is OPTIONAL. 536 4.1.6. "x5u" (X.509 URL) Header Parameter 538 The "x5u" (X.509 URL) header parameter is a URI [RFC3986] that refers 539 to a resource for the X.509 public key certificate or certificate 540 chain [RFC5280] containing the key to which the JWE was encrypted; 541 this can be used to determine the private key needed to decrypt the 542 JWE. The identified resource MUST provide a representation of the 543 certificate or certificate chain that conforms to RFC 5280 [RFC5280] 544 in PEM encoded form [RFC1421]. The certificate containing the public 545 key to which the JWE was encrypted MUST be the first certificate. 546 This MAY be followed by additional certificates, with each subsequent 547 certificate being the one used to certify the previous one. The 548 protocol used to acquire the resource MUST provide integrity 549 protection; an HTTP GET request to retrieve the certificate MUST use 550 TLS [RFC2818] [RFC5246]; the identity of the server MUST be 551 validated, as per Section 3.1 of HTTP Over TLS [RFC2818]. Use of 552 this header parameter is OPTIONAL. 554 4.1.7. "x5t" (X.509 Certificate Thumbprint) Header Parameter 556 The "x5t" (X.509 Certificate Thumbprint) header parameter is a 557 base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER 558 encoding of the X.509 certificate [RFC5280] containing the key to 559 which the JWE was encrypted; this can be used to determine the 560 private key needed to decrypt the JWE. Use of this header parameter 561 is OPTIONAL. 563 If, in the future, certificate thumbprints need to be computed using 564 hash functions other than SHA-1, it is suggested that additional 565 related header parameters be defined for that purpose. For example, 566 it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint 567 using SHA-256) header parameter could be defined by registering it in 568 the IANA JSON Web Signature and Encryption Header Parameters registry 569 [JWS]. 571 4.1.8. "x5c" (X.509 Certificate Chain) Header Parameter 573 The "x5c" (X.509 Certificate Chain) header parameter contains the 574 X.509 public key certificate or certificate chain [RFC5280] 575 containing the key to which the JWE was encrypted; this can be used 576 to determine the private key needed to decrypt the JWE. The 577 certificate or certificate chain is represented as a JSON array of 578 certificate value strings. Each string in the array is a base64 579 encoded ([RFC4648] Section 4 -- not base64url encoded) DER 580 [ITU.X690.1994] PKIX certificate value. The certificate containing 581 the public key to which the JWE was encrypted MUST be the first 582 certificate. This MAY be followed by additional certificates, with 583 each subsequent certificate being the one used to certify the 584 previous one. Use of this header parameter is OPTIONAL. 586 See Appendix B of [JWS] for an example "x5c" value. 588 4.1.9. "kid" (Key ID) Header Parameter 590 The "kid" (key ID) header parameter is a hint indicating which key to 591 which the JWE was encrypted; this can be used to determine the 592 private key needed to decrypt the JWE. This parameter allows 593 originators to explicitly signal a change of key to recipients. 594 Should the recipient be unable to locate a key corresponding to the 595 "kid" value, they SHOULD treat that condition as an error. The 596 interpretation of the "kid" value is unspecified. Its value MUST be 597 a string. Use of this header parameter is OPTIONAL. 599 When used with a JWK, the "kid" value can be used to match a JWK 600 "kid" parameter value. 602 4.1.10. "typ" (Type) Header Parameter 604 The "typ" (type) header parameter MAY be used to declare the type of 605 this complete JWE object in an application-specific manner in 606 contexts where this is useful to the application. This parameter has 607 no effect upon the JWE processing. The type value "JOSE" MAY be used 608 to indicate that this object is a JWS or JWE using the JWS Compact 609 Serialization or the JWE Compact Serialization. The type value 610 "JOSE+JSON" MAY be used to indicate that this object is a JWS or JWE 611 using the JWS JSON Serialization or the JWE JSON Serialization. 612 Other type values MAY be used, and if not understood, SHOULD be 613 ignored. The "typ" value is a case sensitive string. Use of this 614 header parameter is OPTIONAL. 616 MIME Media Type [RFC2046] values MAY be used as "typ" values. 618 "typ" values SHOULD either be registered in the IANA JSON Web 619 Signature and Encryption Type Values registry [JWS] or be a value 620 that contains a Collision Resistant Namespace. 622 4.1.11. "cty" (Content Type) Header Parameter 624 The "cty" (content type) header parameter MAY be used to declare the 625 type of the encrypted content (the Plaintext) in an application- 626 specific manner in contexts where this is useful to the application. 627 This parameter has no effect upon the JWE processing. Content type 628 values that are not understood SHOULD be ignored. The "cty" value is 629 a case sensitive string. Use of this header parameter is OPTIONAL. 631 The values used for the "cty" header parameter come from the same 632 value space as the "typ" header parameter, with the same rules 633 applying. 635 4.1.12. "crit" (Critical) Header Parameter 637 The "crit" (critical) header parameter indicates that extensions to 638 [[ this specification ]] are being used that MUST be understood and 639 processed. Its value is an array listing the header parameter names 640 defined by those extensions that are used in the JWE Header. If any 641 of the listed extension header parameters are not understood and 642 supported by the receiver, it MUST reject the JWE. Senders MUST NOT 643 include header parameter names defined by [[ this specification ]] or 644 by [JWA] for use with JWE, duplicate names, or names that do not 645 occur as header parameter names within the JWE Header in the "crit" 646 list. Senders MUST not use the empty list "[]" as the "crit" value. 647 Recipients MAY reject the JWE if the critical list contains any 648 header parameter names defined by [[ this specification ]] or by 649 [JWA] for use with JWE, or any other constraints on its use are 650 violated. This header parameter MUST be integrity protected, and 651 therefore MUST occur only with the JWE Protected Header, when used. 652 Use of this header parameter is OPTIONAL. This header parameter MUST 653 be understood by implementations. 655 An example use, along with a hypothetical "exp" (expiration-time) 656 field is: 658 {"alg":"RSA-OAEP", 659 "enc":"A256GCM", 660 "crit":["exp"], 661 "exp":1363284000 662 } 664 4.2. Public Header Parameter Names 666 Additional Header Parameter Names can be defined by those using JWEs. 667 However, in order to prevent collisions, any new Header Parameter 668 Name SHOULD either be registered in the IANA JSON Web Signature and 669 Encryption Header Parameters registry [JWS] or be a Public Name: a 670 value that contains a Collision Resistant Namespace. In each case, 671 the definer of the name or value needs to take reasonable precautions 672 to make sure they are in control of the part of the namespace they 673 use to define the Header Parameter Name. 675 New header parameters should be introduced sparingly, as they can 676 result in non-interoperable JWEs. 678 4.3. Private Header Parameter Names 680 A producer and consumer of a JWE may agree to use Header Parameter 681 Names that are Private Names: names that are not Reserved Names 682 Section 4.1 or Public Names Section 4.2. Unlike Public Names, 683 Private Names are subject to collision and should be used with 684 caution. 686 5. Producing and Consuming JWEs 688 5.1. Message Encryption 690 The message encryption process is as follows. The order of the steps 691 is not significant in cases where there are no dependencies between 692 the inputs and outputs of the steps. 694 1. Determine the Key Management Mode employed by the algorithm used 695 to determine the Content Encryption Key (CEK) value. (This is 696 the algorithm recorded in the "alg" (algorithm) header parameter 697 of the resulting JWE.) 699 2. When Key Wrapping, Key Encryption, or Key Agreement with Key 700 Wrapping are employed, generate a random Content Encryption Key 701 (CEK) value. See RFC 4086 [RFC4086] for considerations on 702 generating random values. The CEK MUST have a length equal to 703 that required for the content encryption algorithm. 705 3. When Direct Key Agreement or Key Agreement with Key Wrapping are 706 employed, use the key agreement algorithm to compute the value 707 of the agreed upon key. When Direct Key Agreement is employed, 708 let the Content Encryption Key (CEK) be the agreed upon key. 709 When Key Agreement with Key Wrapping is employed, the agreed 710 upon key will be used to wrap the CEK. 712 4. When Key Wrapping, Key Encryption, or Key Agreement with Key 713 Wrapping are employed, encrypt the CEK to the recipient and let 714 the result be the JWE Encrypted Key. 716 5. Otherwise, when Direct Key Agreement or Direct Encryption are 717 employed, let the JWE Encrypted Key be the empty octet sequence. 719 6. When Direct Encryption is employed, let the Content Encryption 720 Key (CEK) be the shared symmetric key. 722 7. Base64url encode the JWE Encrypted Key to create the Encoded JWE 723 Encrypted Key. 725 8. If the JWE JSON Serialization is being used, repeat this process 726 for each recipient. 728 9. Generate a random JWE Initialization Vector of the correct size 729 for the content encryption algorithm (if required for the 730 algorithm); otherwise, let the JWE Initialization Vector be the 731 empty octet sequence. 733 10. Base64url encode the JWE Initialization Vector to create the 734 Encoded JWE Initialization Vector. 736 11. Compress the Plaintext if a "zip" parameter was included. 738 12. Serialize the (compressed) Plaintext into an octet sequence M. 740 13. Create a JWE Header containing the encryption parameters used. 741 Note that white space is explicitly allowed in the 742 representation and no canonicalization need be performed before 743 encoding. 745 14. Base64url encode the octets of the UTF-8 representation of the 746 JWE Protected Header to create the Encoded JWE Header. If the 747 JWE Protected Header is not present (which can only happen when 748 using the JWE JSON Serialization and no "protected" member is 749 present), let the Encoded JWE Header be the empty string. 751 15. Let the Additional Authenticated Data encryption parameter be 752 the octets of the ASCII representation of the Encoded JWE Header 753 value. 755 16. Encrypt M using the CEK, the JWE Initialization Vector, and the 756 Additional Authenticated Data value using the specified content 757 encryption algorithm to create the JWE Ciphertext value and the 758 JWE Authentication Tag (which is the Authentication Tag output 759 from the encryption operation). 761 17. Base64url encode the JWE Ciphertext to create the Encoded JWE 762 Ciphertext. 764 18. Base64url encode the JWE Authentication Tag to create the 765 Encoded JWE Authentication Tag. 767 19. The five encoded parts are result values used in both the JWE 768 Compact Serialization and the JWE JSON Serialization 769 representations. 771 20. Create the desired serialized output. The JWE Compact 772 Serialization of this result is the concatenation of the Encoded 773 JWE Header, the Encoded JWE Encrypted Key, the Encoded JWE 774 Initialization Vector, the Encoded JWE Ciphertext, and the 775 Encoded JWE Authentication Tag in that order, with the five 776 strings being separated by four period ('.') characters. The 777 JWE JSON Serialization is described in Section 7.2. 779 5.2. Message Decryption 781 The message decryption process is the reverse of the encryption 782 process. The order of the steps is not significant in cases where 783 there are no dependencies between the inputs and outputs of the 784 steps. If any of these steps fails, the JWE MUST be rejected. 786 1. Parse the serialized input to determine the values of the JWE 787 Header, the Encoded JWE Encrypted Key, the Encoded JWE 788 Initialization Vector, the Encoded JWE Ciphertext, and the 789 Encoded JWE Authentication Tag. When using the JWE Compact 790 Serialization, the Encoded JWE Header, the Encoded JWE Encrypted 791 Key, the Encoded JWE Initialization Vector, the Encoded JWE 792 Ciphertext, and the Encoded JWE Authentication Tag are 793 represented as text strings in that order, separated by four 794 period ('.') characters. The JWE JSON Serialization is 795 described in Section 7.2. 797 2. The Encoded JWE Header, the Encoded JWE Encrypted Key, the 798 Encoded JWE Initialization Vector, the Encoded JWE Ciphertext, 799 and the Encoded JWE Authentication Tag MUST be successfully 800 base64url decoded following the restriction that no padding 801 characters have been used. 803 3. The resulting JWE Protected Header MUST be a completely valid 804 JSON object conforming to RFC 4627 [RFC4627]. 806 4. If using the JWE Compact Serialization, let the JWE Header be 807 the JWE Protected Header; otherwise, when using the JWE JSON 808 Serialization, let the JWE Header be the union of the members of 809 the JWE Protected Header, the members of the "unprotected" 810 value, and the members of the corresponding "header" value, all 811 of which must be completely valid JSON objects. 813 5. The resulting JWE Header MUST NOT contain duplicate Header 814 Parameter Names. When using the JWE JSON Serialization, this 815 restriction includes that the same Header Parameter Name also 816 MUST NOT occur in distinct JSON Text Object values that together 817 comprise the JWE Header. 819 6. The resulting JWE Header MUST be validated to only include 820 parameters and values whose syntax and semantics are both 821 understood and supported or that are specified as being ignored 822 when not understood. 824 7. Determine the Key Management Mode employed by the algorithm 825 specified by the "alg" (algorithm) header parameter. 827 8. Verify that the JWE uses a key known to the recipient. 829 9. When Direct Key Agreement or Key Agreement with Key Wrapping are 830 employed, use the key agreement algorithm to compute the value 831 of the agreed upon key. When Direct Key Agreement is employed, 832 let the Content Encryption Key (CEK) be the agreed upon key. 833 When Key Agreement with Key Wrapping is employed, the agreed 834 upon key will be used to decrypt the JWE Encrypted Key. 836 10. When Key Wrapping, Key Encryption, or Key Agreement with Key 837 Wrapping are employed, decrypt the JWE Encrypted Key to produce 838 the Content Encryption Key (CEK). The CEK MUST have a length 839 equal to that required for the content encryption algorithm. 840 Note that when there are multiple recipients, each recipient 841 will only be able decrypt any JWE Encrypted Key values that were 842 encrypted to a key in that recipient's possession. It is 843 therefore normal to only be able to decrypt one of the per- 844 recipient JWE Encrypted Key values to obtain the CEK value. To 845 mitigate against attacks described in RFC 3218 [RFC3218], the 846 recipient MUST NOT distinguish between format, padding, and 847 length errors of encrypted keys. It is strongly recommended, in 848 the event of receiving an improperly formatted key, that the 849 receiver substitute a randomly generated CEK and proceed to the 850 next step, to mitigate timing attacks. 852 11. Otherwise, when Direct Key Agreement or Direct Encryption are 853 employed, verify that the JWE Encrypted Key value is empty octet 854 sequence. 856 12. When Direct Encryption is employed, let the Content Encryption 857 Key (CEK) be the shared symmetric key. 859 13. If the JWE JSON Serialization is being used, repeat this process 860 for each recipient contained in the representation until the CEK 861 value has been determined. 863 14. Let the Additional Authenticated Data encryption parameter be 864 the octets of the ASCII representation of the Encoded JWE Header 865 value. 867 15. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization 868 Vector, the Additional Authenticated Data value, and the JWE 869 Authentication Tag (which is the Authentication Tag input to the 870 calculation) using the specified content encryption algorithm, 871 returning the decrypted plaintext and verifying the JWE 872 Authentication Tag in the manner specified for the algorithm, 873 rejecting the input without emitting any decrypted output if the 874 JWE Authentication Tag is incorrect. 876 16. Uncompress the decrypted plaintext if a "zip" parameter was 877 included. 879 17. Output the resulting Plaintext. 881 5.3. String Comparison Rules 883 Processing a JWE inevitably requires comparing known strings to 884 values in JSON objects. For example, in checking what the encryption 885 method is, the Unicode string encoding "enc" will be checked against 886 the member names in the JWE Header to see if there is a matching 887 Header Parameter Name. 889 Comparisons between JSON strings and other Unicode strings MUST be 890 performed by comparing Unicode code points without normalization as 891 specified in the String Comparison Rules in Section 5.3 of [JWS]. 893 6. Key Identification 895 It is necessary for the recipient of a JWE to be able to determine 896 the key that was employed for the encryption operation. The key 897 employed can be identified using the Header Parameter methods 898 described in Section 4.1 or can be identified using methods that are 899 outside the scope of this specification. Specifically, the Header 900 Parameters "jku", "jwk", "x5u", "x5t", "x5c", and "kid" can be used 901 to identify the key used. The sender SHOULD include sufficient 902 information in the Header Parameters to identify the key used, unless 903 the application uses another means or convention to determine the key 904 used. Recipients MUST reject the input when the key used cannot be 905 determined. 907 7. Serializations 909 JWE objects use one of two serializations, the JWE Compact 910 Serialization or the JWE JSON Serialization. The JWE Compact 911 Serialization is mandatory to implement. Implementation of the JWE 912 JSON Serialization is OPTIONAL. 914 7.1. JWE Compact Serialization 916 The JWE Compact Serialization represents encrypted content as a 917 compact URL-safe string. This string is the concatenation of the 918 Encoded JWE Header, the Encoded JWE Encrypted Key, the Encoded JWE 919 Initialization Vector, the Encoded JWE Ciphertext, and the Encoded 920 JWE Authentication Tag in that order, with the five strings being 921 separated by four period ('.') characters. Only one recipient is 922 supported by the JWE Compact Serialization. 924 7.2. JWE JSON Serialization 926 The JWE JSON Serialization represents encrypted content as a JSON 927 object. Unlike the JWE Compact Serialization, content using the JWE 928 JSON Serialization can be encrypted to more than one recipient. 930 The representation is closely related to that used in the JWE Compact 931 Serialization, with the following differences for the JWE JSON 932 Serialization: 934 o Values in the JWE JSON Serialization are represented as members of 935 a JSON object, rather than as base64url encoded strings separated 936 by period ('.') characters. (However binary values and values 937 that are integrity protected are still base64url encoded.) 939 o The Encoded JWE Header value, if non-empty, is stored in the 940 "protected" member. 942 o The Encoded JWE Initialization Vector value is stored in the "iv" 943 member. 945 o The Encoded JWE Ciphertext value is stored in the "ciphertext" 946 member. 948 o The Encoded JWE Authentication Tag value is stored in the "tag" 949 member. 951 o The JWE can be encrypted to multiple recipients, rather than just 952 one. A JSON array in the "recipients" member is used to hold 953 values that are specific to a particular recipient, with one array 954 element per recipient represented. These array elements are JSON 955 objects. 957 o Each Encoded JWE Encrypted Key value is stored in the 958 "encrypted_key" member of a JSON object that is an element of the 959 "recipients" array. 961 o Some header parameter values, such as the "alg" value and 962 parameters used for selecting keys, can also differ for different 963 recipient computations. Per-recipient header parameter values are 964 stored in the "header" members of the same JSON objects that are 965 elements of the "recipients" array. 967 o Some header parameters, including the "alg" parameter, can be 968 shared among all recipient computations. These header parameters 969 are stored in either of two top-level member(s) of the JSON 970 object: the "protected" member and the "unprotected" member. The 971 values of these members are JSON Text Objects containing Header 972 Parameters. 974 o Not all header parameters are integrity protected. The shared 975 header parameters in the "protected" member are integrity 976 protected, and are base64url encoded. The per-recipient header 977 parameters in the "header" array element members and the shared 978 header parameters in the "unprotected" member are not integrity 979 protected. These JSON Text Objects containing header parameters 980 that are not integrity protected are not base64url encoded. 982 o The header parameter values used when creating or validating per- 983 recipient Ciphertext and Authentication Tag values are the union 984 of the three sets of header parameter values that may be present: 985 (1) the per-recipient values in the "header" member of the 986 recipient's array element, (2) the shared integrity-protected 987 values in the "protected" member, and (3) the shared non- 988 integrity-protected values in the "unprotected" member. The union 989 of these sets of header parameters comprises the JWE Header. The 990 header parameter names in the three locations MUST be disjoint. 992 The syntax of a JWE using the JWE JSON Serialization is as follows: 994 {"protected":", 995 "unprotected":", 996 "recipients":[ 997 {"header":"", 998 "encrypted_key":""}, 999 ... 1000 {"header":"", 1001 "encrypted_key":""}], 1002 "iv":"", 1003 "ciphertext":"", 1004 "tag":"" 1005 } 1007 Of these members, only the "ciphertext" member MUST be present. The 1008 "iv", "tag", and "encrypted_key" members MUST be present when 1009 corresponding JWE Initialization Vector, JWE Authentication Tag, and 1010 JWE Encrypted Key values are non-empty. The "recipients" member MUST 1011 be present when any "header" or "encrypted_key" members are needed 1012 for recipients. At least one of the "header", "protected", and 1013 "unprotected" members MUST be present so that "alg" and "enc" header 1014 parameter values are conveyed for each recipient computation. 1016 The contents of the Encoded JWE Encrypted Key, Encoded JWE 1017 Initialization Vector, Encoded JWE Ciphertext, and Encoded JWE 1018 Authentication Tag values are exactly as defined in the rest of this 1019 specification. They are interpreted and validated in the same 1020 manner, with each corresponding Encoded JWE Encrypted Key, Encoded 1021 JWE Initialization Vector, Encoded JWE Ciphertext, Encoded JWE 1022 Authentication Tag, and set of header parameter values being created 1023 and validated together. The JWE Header values used are the union of 1024 the header parameters in the "protected", "unprotected", and 1025 corresponding "header" members, as described earlier. 1027 Each JWE Encrypted Key value is computed using the parameters of the 1028 corresponding JWE Header value in the same manner as for the JWE 1029 Compact Serialization. This has the desirable property that each 1030 Encoded JWE Encrypted Key value in the "recipients" array is 1031 identical to the value that would have been computed for the same 1032 parameter in the JWE Compact Serialization. Likewise, the JWE 1033 Ciphertext and JWE Authentication Tag values match those produced for 1034 the JWE Compact Serialization, provided that the Encoded JWE Header 1035 value (which represents the integrity-protected header parameter 1036 values) matches that used in the JWE Compact Serialization. 1038 All recipients use the same JWE Protected Header, JWE Initialization 1039 Vector, JWE Ciphertext, and JWE Authentication Tag values, resulting 1040 in potentially significant space savings if the message is large. 1041 Therefore, all header parameters that specify the treatment of the 1042 Plaintext value MUST be the same for all recipients. This primarily 1043 means that the "enc" (encryption method) header parameter value in 1044 the JWE Header for each recipient and any parameters of that 1045 algorithm MUST be the same. 1047 See Appendix A.4 for an example of computing a JWE using the JWE JSON 1048 Serialization. 1050 8. Distinguishing Between JWS and JWE Objects 1052 There are several ways of distinguishing whether an object is a JWS 1053 or JWE object. All these methods will yield the same result for all 1054 legal input values. 1056 o If the object is using the JWS Compact Serialization or the JWE 1057 Compact Serialization, the number of base64url encoded segments 1058 separated by period ('.') characters differs for JWSs and JWEs. 1059 JWSs have three segments separated by two period ('.') characters. 1060 JWEs have five segments separated by four period ('.') characters. 1062 o If the object is using the JWS JSON Serialization or the JWE JSON 1063 Serialization, the members used will be different. JWSs have a 1064 "signatures" member and JWEs do not. JWEs have a "recipients" 1065 member and JWSs do not. 1067 o A JWS Header can be distinguished from a JWE header by examining 1068 the "alg" (algorithm) header parameter value. If the value 1069 represents a digital signature or MAC algorithm, or is the value 1070 "none", it is for a JWS; if it represents a Key Encryption, Key 1071 Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, 1072 or Direct Encryption algorithm, it is for a JWE. 1074 o A JWS Header can also be distinguished from a JWE header by 1075 determining whether an "enc" (encryption method) member exists. 1076 If the "enc" member exists, it is a JWE; otherwise, it is a JWS. 1078 9. IANA Considerations 1080 9.1. Registration of JWE Header Parameter Names 1082 This specification registers the Header Parameter Names defined in 1083 Section 4.1 in the IANA JSON Web Signature and Encryption Header 1084 Parameters registry [JWS]. 1086 9.1.1. Registry Contents 1088 o Header Parameter Name: "alg" 1089 o Header Parameter Usage Location(s): JWE 1090 o Change Controller: IETF 1091 o Specification Document(s): Section 4.1.1 of [[ this document ]] 1093 o Header Parameter Name: "enc" 1094 o Header Parameter Usage Location(s): JWE 1095 o Change Controller: IETF 1096 o Specification Document(s): Section 4.1.2 of [[ this document ]] 1098 o Header Parameter Name: "zip" 1099 o Header Parameter Usage Location(s): JWE 1100 o Change Controller: IETF 1101 o Specification Document(s): Section 4.1.3 of [[ this document ]] 1103 o Header Parameter Name: "jku" 1104 o Header Parameter Usage Location(s): JWE 1105 o Change Controller: IETF 1106 o Specification Document(s): Section 4.1.4 of [[ this document ]] 1108 o Header Parameter Name: "jwk" 1109 o Header Parameter Usage Location(s): JWE 1110 o Change Controller: IETF 1111 o Specification document(s): Section 4.1.5 of [[ this document ]] 1113 o Header Parameter Name: "x5u" 1114 o Header Parameter Usage Location(s): JWE 1115 o Change Controller: IETF 1116 o Specification Document(s): Section 4.1.6 of [[ this document ]] 1118 o Header Parameter Name: "x5t" 1119 o Header Parameter Usage Location(s): JWE 1120 o Change Controller: IETF 1121 o Specification Document(s): Section 4.1.7 of [[ this document ]] 1123 o Header Parameter Name: "x5c" 1124 o Header Parameter Usage Location(s): JWE 1125 o Change Controller: IETF 1126 o Specification Document(s): Section 4.1.8 of [[ this document ]] 1128 o Header Parameter Name: "kid" 1129 o Header Parameter Usage Location(s): JWE 1130 o Change Controller: IETF 1131 o Specification Document(s): Section 4.1.9 of [[ this document ]] 1133 o Header Parameter Name: "typ" 1134 o Header Parameter Usage Location(s): JWE 1135 o Change Controller: IETF 1136 o Specification Document(s): Section 4.1.10 of [[ this document ]] 1138 o Header Parameter Name: "cty" 1139 o Header Parameter Usage Location(s): JWE 1140 o Change Controller: IETF 1141 o Specification Document(s): Section 4.1.11 of [[ this document ]] 1143 o Header Parameter Name: "crit" 1144 o Header Parameter Usage Location(s): JWE 1145 o Change Controller: IETF 1146 o Specification Document(s): Section 4.1.12 of [[ this document ]] 1148 10. Security Considerations 1150 All of the security issues faced by any cryptographic application 1151 must be faced by a JWS/JWE/JWK agent. Among these issues are 1152 protecting the user's private and symmetric keys, preventing various 1153 attacks, and helping the user avoid mistakes such as inadvertently 1154 encrypting a message for the wrong recipient. The entire list of 1155 security considerations is beyond the scope of this document. 1157 All the security considerations in the JWS specification also apply 1158 to this specification. Likewise, all the security considerations in 1159 XML Encryption 1.1 [W3C.CR-xmlenc-core1-20120313] also apply, other 1160 than those that are XML specific. 1162 When decrypting, particular care must be taken not to allow the JWE 1163 recipient to be used as an oracle for decrypting messages. RFC 3218 1164 [RFC3218] should be consulted for specific countermeasures to attacks 1165 on RSAES-PKCS1-V1_5. An attacker might modify the contents of the 1166 "alg" parameter from "RSA-OAEP" to "RSA1_5" in order to generate a 1167 formatting error that can be detected and used to recover the CEK 1168 even if RSAES OAEP was used to encrypt the CEK. It is therefore 1169 particularly important to report all formatting errors to the CEK, 1170 Additional Authenticated Data, or ciphertext as a single error when 1171 the JWE is rejected. 1173 11. References 1175 11.1. Normative References 1177 [ECMAScript] 1178 Ecma International, "ECMAScript Language Specification, 1179 5.1 Edition", ECMA 262, June 2011. 1181 [ITU.X690.1994] 1182 International Telecommunications Union, "Information 1183 Technology - ASN.1 encoding rules: Specification of Basic 1184 Encoding Rules (BER), Canonical Encoding Rules (CER) and 1185 Distinguished Encoding Rules (DER)", ITU-T Recommendation 1186 X.690, 1994. 1188 [JWA] Jones, M., "JSON Web Algorithms (JWA)", 1189 draft-ietf-jose-json-web-algorithms (work in progress), 1190 July 2013. 1192 [JWK] Jones, M., "JSON Web Key (JWK)", 1193 draft-ietf-jose-json-web-key (work in progress), 1194 July 2013. 1196 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1197 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1198 in progress), July 2013. 1200 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 1201 Mail: Part I: Message Encryption and Authentication 1202 Procedures", RFC 1421, February 1993. 1204 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1205 version 1.3", RFC 1951, May 1996. 1207 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1208 Extensions (MIME) Part Two: Media Types", RFC 2046, 1209 November 1996. 1211 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1212 Requirement Levels", BCP 14, RFC 2119, March 1997. 1214 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1216 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1217 10646", STD 63, RFC 3629, November 2003. 1219 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1220 Resource Identifier (URI): Generic Syntax", STD 66, 1221 RFC 3986, January 2005. 1223 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 1224 Requirements for Security", BCP 106, RFC 4086, June 2005. 1226 [RFC4627] Crockford, D., "The application/json Media Type for 1227 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1229 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1230 Encodings", RFC 4648, October 2006. 1232 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1233 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1235 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1236 Housley, R., and W. Polk, "Internet X.509 Public Key 1237 Infrastructure Certificate and Certificate Revocation List 1238 (CRL) Profile", RFC 5280, May 2008. 1240 [W3C.CR-xmlenc-core1-20120313] 1241 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 1242 "XML Encryption Syntax and Processing Version 1.1", World 1243 Wide Web Consortium CR CR-xmlenc-core1-20120313, 1244 March 2012, 1245 . 1247 11.2. Informative References 1249 [I-D.mcgrew-aead-aes-cbc-hmac-sha2] 1250 McGrew, D. and K. Paterson, "Authenticated Encryption with 1251 AES-CBC and HMAC-SHA", 1252 draft-mcgrew-aead-aes-cbc-hmac-sha2-01 (work in progress), 1253 October 2012. 1255 [I-D.rescorla-jsms] 1256 Rescorla, E. and J. Hildebrand, "JavaScript Message 1257 Security Format", draft-rescorla-jsms-00 (work in 1258 progress), March 2011. 1260 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 1261 Encryption", September 2010. 1263 [RFC3218] Rescorla, E., "Preventing the Million Message Attack on 1264 Cryptographic Message Syntax", RFC 3218, January 2002. 1266 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1267 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1268 July 2005. 1270 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1271 RFC 5652, September 2009. 1273 Appendix A. JWE Examples 1275 This section provides examples of JWE computations. 1277 A.1. Example JWE using RSAES OAEP and AES GCM 1279 This example encrypts the plaintext "The true sign of intelligence is 1280 not knowledge but imagination." to the recipient using RSAES OAEP for 1281 key encryption and AES GCM for content encryption. The 1282 representation of this plaintext is: 1284 [84, 104, 101, 32, 116, 114, 117, 101, 32, 115, 105, 103, 110, 32, 1285 111, 102, 32, 105, 110, 116, 101, 108, 108, 105, 103, 101, 110, 99, 1286 101, 32, 105, 115, 32, 110, 111, 116, 32, 107, 110, 111, 119, 108, 1287 101, 100, 103, 101, 32, 98, 117, 116, 32, 105, 109, 97, 103, 105, 1288 110, 97, 116, 105, 111, 110, 46] 1290 A.1.1. JWE Header 1292 The following example JWE Header declares that: 1294 o the Content Encryption Key is encrypted to the recipient using the 1295 RSAES OAEP algorithm to produce the JWE Encrypted Key and 1297 o the Plaintext is encrypted using the AES GCM algorithm with a 256 1298 bit key to produce the Ciphertext. 1300 {"alg":"RSA-OAEP","enc":"A256GCM"} 1302 A.1.2. Encoded JWE Header 1304 Base64url encoding the octets of the UTF-8 representation of the JWE 1305 Header yields this Encoded JWE Header value: 1307 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ 1309 A.1.3. Content Encryption Key (CEK) 1311 Generate a 256 bit random Content Encryption Key (CEK). In this 1312 example, the value is: 1314 [177, 161, 244, 128, 84, 143, 225, 115, 63, 180, 3, 255, 107, 154, 1315 212, 246, 138, 7, 110, 91, 112, 46, 34, 105, 47, 130, 203, 46, 122, 1316 234, 64, 252] 1318 A.1.4. Key Encryption 1320 Encrypt the CEK with the recipient's public key using the RSAES OAEP 1321 algorithm to produce the JWE Encrypted Key. This example uses the RSA 1322 key represented in JSON Web Key [JWK] format below (with line breaks 1323 for display purposes only): 1325 {"kty":"RSA", 1326 "n":"oahUIoWw0K0usKNuOR6H4wkf4oBUXHTxRvgb48E-BVvxkeDNjbC4he8rUW 1327 cJoZmds2h7M70imEVhRU5djINXtqllXI4DFqcI1DgjT9LewND8MW2Krf3S 1328 psk_ZkoFnilakGygTwpZ3uesH-PFABNIUYpOiN15dsQRkgr0vEhxN92i2a 1329 sbOenSZeyaxziK72UwxrrKoExv6kc5twXTq4h-QChLOln0_mtUZwfsRaMS 1330 tPs6mS6XrgxnxbWhojf663tuEQueGC-FCMfra36C9knDFGzKsNa7LZK2dj 1331 YgyD3JR_MB_4NUJW_TqOQtwHYbxevoJArm-L5StowjzGy-_bq6Gw", 1332 "e":"AQAB", 1333 "d":"kLdtIj6GbDks_ApCSTYQtelcNttlKiOyPzMrXHeI-yk1F7-kpDxY4-WY5N 1334 WV5KntaEeXS1j82E375xxhWMHXyvjYecPT9fpwR_M9gV8n9Hrh2anTpTD9 1335 3Dt62ypW3yDsJzBnTnrYu1iwWRgBKrEYY46qAZIrA2xAwnm2X7uGR1hghk 1336 qDp0Vqj3kbSCz1XyfCs6_LehBwtxHIyh8Ripy40p24moOAbgxVw3rxT_vl 1337 t3UVe4WO3JkJOzlpUf-KTVI2Ptgm-dARxTEtE-id-4OJr0h-K-VFs3VSnd 1338 VTIznSxfyrj8ILL6MG_Uv8YAu7VILSB3lOW085-4qE3DzgrTjgyQ" 1339 } 1341 The resulting JWE Encrypted Key value is: 1343 [56, 163, 154, 192, 58, 53, 222, 4, 105, 218, 136, 218, 29, 94, 203, 1344 22, 150, 92, 129, 94, 211, 232, 53, 89, 41, 60, 138, 56, 196, 216, 1345 82, 98, 168, 76, 37, 73, 70, 7, 36, 8, 191, 100, 136, 196, 244, 220, 1346 145, 158, 138, 155, 4, 117, 141, 230, 199, 247, 173, 45, 182, 214, 1347 74, 177, 107, 211, 153, 11, 205, 196, 171, 226, 162, 128, 171, 182, 1348 13, 237, 239, 99, 193, 4, 91, 219, 121, 223, 107, 167, 61, 119, 228, 1349 173, 156, 137, 134, 200, 80, 219, 74, 253, 56, 185, 91, 177, 34, 158, 1350 89, 154, 205, 96, 55, 18, 138, 43, 96, 218, 215, 128, 124, 75, 138, 1351 243, 85, 25, 109, 117, 140, 26, 155, 249, 67, 167, 149, 231, 100, 6, 1352 41, 65, 214, 251, 232, 87, 72, 40, 182, 149, 154, 168, 31, 193, 126, 1353 215, 89, 28, 111, 219, 125, 182, 139, 235, 195, 197, 23, 234, 55, 58, 1354 63, 180, 68, 202, 206, 149, 75, 205, 248, 176, 67, 39, 178, 60, 98, 1355 193, 32, 238, 122, 96, 158, 222, 57, 183, 111, 210, 55, 188, 215, 1356 206, 180, 166, 150, 166, 106, 250, 55, 229, 72, 40, 69, 214, 216, 1357 104, 23, 40, 135, 212, 28, 127, 41, 80, 175, 174, 168, 115, 171, 197, 1358 89, 116, 92, 103, 246, 83, 216, 182, 176, 84, 37, 147, 35, 45, 219, 1359 172, 99, 226, 233, 73, 37, 124, 42, 72, 49, 242, 35, 127, 184, 134, 1360 117, 114, 135, 206] 1362 A.1.5. Encoded JWE Encrypted Key 1364 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1365 Encrypted Key. This result (with line breaks for display purposes 1366 only) is: 1368 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1369 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1370 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1371 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1372 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1373 6UklfCpIMfIjf7iGdXKHzg 1375 A.1.6. Initialization Vector 1377 Generate a random 96 bit JWE Initialization Vector. In this example, 1378 the value is: 1380 [227, 197, 117, 252, 2, 219, 233, 68, 180, 225, 77, 219] 1382 Base64url encoding this value yields this Encoded JWE Initialization 1383 Vector value: 1385 48V1_ALb6US04U3b 1387 A.1.7. Additional Authenticated Data 1389 Let the Additional Authenticated Data encryption parameter be the 1390 octets of the ASCII representation of the Encoded JWE Header value. 1391 This AAD value is: 1393 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1394 116, 84, 48, 70, 70, 85, 67, 73, 115, 73, 109, 86, 117, 89, 121, 73, 1395 54, 73, 107, 69, 121, 78, 84, 90, 72, 81, 48, 48, 105, 102, 81] 1397 A.1.8. Plaintext Encryption 1399 Encrypt the Plaintext with AES GCM using the CEK as the encryption 1400 key, the JWE Initialization Vector, and the Additional Authenticated 1401 Data value above, requesting a 128 bit Authentication Tag output. 1402 The resulting Ciphertext is: 1404 [229, 236, 166, 241, 53, 191, 115, 196, 174, 43, 73, 109, 39, 122, 1405 233, 96, 140, 206, 120, 52, 51, 237, 48, 11, 190, 219, 186, 80, 111, 1406 104, 50, 142, 47, 167, 59, 61, 181, 127, 196, 21, 40, 82, 242, 32, 1407 123, 143, 168, 226, 73, 216, 176, 144, 138, 247, 106, 60, 16, 205, 1408 160, 109, 64, 63, 192] 1410 The resulting Authentication Tag value is: 1412 [92, 80, 104, 49, 133, 25, 161, 215, 173, 101, 219, 211, 136, 91, 1413 210, 145] 1415 A.1.9. Encoded JWE Ciphertext 1417 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1418 This result (with line breaks for display purposes only) is: 1420 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1421 SdiwkIr3ajwQzaBtQD_A 1423 A.1.10. Encoded JWE Authentication Tag 1425 Base64url encode the Authentication Tag to create the Encoded JWE 1426 Authentication Tag. This result is: 1428 XFBoMYUZodetZdvTiFvSkQ 1430 A.1.11. Complete Representation 1432 Assemble the final representation: The Compact Serialization of this 1433 result is the concatenation of the Encoded JWE Header, the Encoded 1434 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1435 JWE Ciphertext, and the Encoded JWE Authentication Tag in that order, 1436 with the five strings being separated by four period ('.') 1437 characters. 1439 The final result in this example (with line breaks for display 1440 purposes only) is: 1442 eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ. 1443 OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe 1444 ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb 1445 Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV 1446 mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8 1447 1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi 1448 6UklfCpIMfIjf7iGdXKHzg. 1449 48V1_ALb6US04U3b. 1450 5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji 1451 SdiwkIr3ajwQzaBtQD_A. 1452 XFBoMYUZodetZdvTiFvSkQ 1454 A.1.12. Validation 1456 This example illustrates the process of creating a JWE with RSAES 1457 OAEP for key encryption and AES GCM for content encryption. These 1458 results can be used to validate JWE decryption implementations for 1459 these algorithms. Note that since the RSAES OAEP computation 1460 includes random values, the encryption results above will not be 1461 completely reproducible. However, since the AES GCM computation is 1462 deterministic, the JWE Encrypted Ciphertext values will be the same 1463 for all encryptions performed using these inputs. 1465 A.2. Example JWE using RSAES-PKCS1-V1_5 and AES_128_CBC_HMAC_SHA_256 1467 This example encrypts the plaintext "Live long and prosper." to the 1468 recipient using RSAES-PKCS1-V1_5 for key encryption and 1469 AES_128_CBC_HMAC_SHA_256 for content encryption. The representation 1470 of this plaintext is: 1472 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1473 112, 114, 111, 115, 112, 101, 114, 46] 1475 A.2.1. JWE Header 1477 The following example JWE Header (with line breaks for display 1478 purposes only) declares that: 1480 o the Content Encryption Key is encrypted to the recipient using the 1481 RSAES-PKCS1-V1_5 algorithm to produce the JWE Encrypted Key and 1483 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1484 algorithm to produce the Ciphertext. 1486 {"alg":"RSA1_5","enc":"A128CBC-HS256"} 1488 A.2.2. Encoded JWE Header 1490 Base64url encoding the octets of the UTF-8 representation of the JWE 1491 Header yields this Encoded JWE Header value: 1493 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1495 A.2.3. Content Encryption Key (CEK) 1497 Generate a 256 bit random Content Encryption Key (CEK). In this 1498 example, the key value is: 1500 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1501 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1502 44, 207] 1504 A.2.4. Key Encryption 1506 Encrypt the CEK with the recipient's public key using the RSAES- 1507 PKCS1-V1_5 algorithm to produce the JWE Encrypted Key. This example 1508 uses the RSA key represented in JSON Web Key [JWK] format below (with 1509 line breaks for display purposes only): 1511 {"kty":"RSA", 1512 "n":"sXchDaQebHnPiGvyDOAT4saGEUetSyo9MKLOoWFsueri23bOdgWp4Dy1Wl 1513 UzewbgBHod5pcM9H95GQRV3JDXboIRROSBigeC5yjU1hGzHHyXss8UDpre 1514 cbAYxknTcQkhslANGRUZmdTOQ5qTRsLAt6BTYuyvVRdhS8exSZEy_c4gs_ 1515 7svlJJQ4H9_NxsiIoLwAEk7-Q3UXERGYw_75IDrGA84-lA_-Ct4eTlXHBI 1516 Y2EaV7t7LjJaynVJCpkv4LKjTTAumiGUIuQhrNhZLuF_RJLqHpM2kgWFLU 1517 7-VTdL1VbC2tejvcI2BlMkEpk1BzBZI0KQB0GaDWFLN-aEAw3vRw", 1518 "e":"AQAB", 1519 "d":"VFCWOqXr8nvZNyaaJLXdnNPXZKRaWCjkU5Q2egQQpTBMwhprMzWzpR8Sxq 1520 1OPThh_J6MUD8Z35wky9b8eEO0pwNS8xlh1lOFRRBoNqDIKVOku0aZb-ry 1521 nq8cxjDTLZQ6Fz7jSjR1Klop-YKaUHc9GsEofQqYruPhzSA-QgajZGPbE_ 1522 0ZaVDJHfyd7UUBUKunFMScbflYAAOYJqVIVwaYR5zWEEceUjNnTNo_CVSj 1523 -VvXLO5VZfCUAVLgW4dpf1SrtZjSt34YLsRarSb127reG_DUwg9Ch-Kyvj 1524 T1SkHgUWRVGcyly7uvVGRSDwsXypdrNinPA4jlhoNdizK2zF2CWQ" 1525 } 1527 The resulting JWE Encrypted Key value is: 1529 [80, 104, 72, 58, 11, 130, 236, 139, 132, 189, 255, 205, 61, 86, 151, 1530 176, 99, 40, 44, 233, 176, 189, 205, 70, 202, 169, 72, 40, 226, 181, 1531 156, 223, 120, 156, 115, 232, 150, 209, 145, 133, 104, 112, 237, 156, 1532 116, 250, 65, 102, 212, 210, 103, 240, 177, 61, 93, 40, 71, 231, 223, 1533 226, 240, 157, 15, 31, 150, 89, 200, 215, 198, 203, 108, 70, 117, 66, 1534 212, 238, 193, 205, 23, 161, 169, 218, 243, 203, 128, 214, 127, 253, 1535 215, 139, 43, 17, 135, 103, 179, 220, 28, 2, 212, 206, 131, 158, 128, 1536 66, 62, 240, 78, 186, 141, 125, 132, 227, 60, 137, 43, 31, 152, 199, 1537 54, 72, 34, 212, 115, 11, 152, 101, 70, 42, 219, 233, 142, 66, 151, 1538 250, 126, 146, 141, 216, 190, 73, 50, 177, 146, 5, 52, 247, 28, 197, 1539 21, 59, 170, 247, 181, 89, 131, 241, 169, 182, 246, 99, 15, 36, 102, 1540 166, 182, 172, 197, 136, 230, 120, 60, 58, 219, 243, 149, 94, 222, 1541 150, 154, 194, 110, 227, 225, 112, 39, 89, 233, 112, 207, 211, 241, 1542 124, 174, 69, 221, 179, 107, 196, 225, 127, 167, 112, 226, 12, 242, 1543 16, 24, 28, 120, 182, 244, 213, 244, 153, 194, 162, 69, 160, 244, 1544 248, 63, 165, 141, 4, 207, 249, 193, 79, 131, 0, 169, 233, 127, 167, 1545 101, 151, 125, 56, 112, 111, 248, 29, 232, 90, 29, 147, 110, 169, 1546 146, 114, 165, 204, 71, 136, 41, 252] 1548 A.2.5. Encoded JWE Encrypted Key 1550 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1551 Encrypted Key. This result (with line breaks for display purposes 1552 only) is: 1554 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1555 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1556 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1557 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1558 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1559 -B3oWh2TbqmScqXMR4gp_A 1561 A.2.6. Initialization Vector 1563 Generate a random 128 bit JWE Initialization Vector. In this 1564 example, the value is: 1566 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1567 101] 1569 Base64url encoding this value yields this Encoded JWE Initialization 1570 Vector value: 1572 AxY8DCtDaGlsbGljb3RoZQ 1574 A.2.7. Additional Authenticated Data 1576 Let the Additional Authenticated Data encryption parameter be the 1577 octets of the ASCII representation of the Encoded JWE Header value. 1578 This AAD value is: 1580 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 83, 85, 48, 69, 1581 120, 88, 122, 85, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 1582 74, 66, 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 1583 50, 73, 110, 48] 1585 A.2.8. Plaintext Encryption 1587 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1588 the encryption key, the JWE Initialization Vector, and the Additional 1589 Authenticated Data value above. The steps for doing this using the 1590 values from Appendix A.3 are detailed in Appendix B. The resulting 1591 Ciphertext is: 1593 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1594 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1595 112, 56, 102] 1597 The resulting Authentication Tag value is: 1599 [246, 17, 244, 190, 4, 95, 98, 3, 231, 0, 115, 157, 242, 203, 100, 1600 191] 1602 A.2.9. Encoded JWE Ciphertext 1604 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1605 This result is: 1607 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1609 A.2.10. Encoded JWE Authentication Tag 1611 Base64url encode the Authentication Tag to create the Encoded JWE 1612 Authentication Tag. This result is: 1614 9hH0vgRfYgPnAHOd8stkvw 1616 A.2.11. Complete Representation 1618 Assemble the final representation: The Compact Serialization of this 1619 result is the concatenation of the Encoded JWE Header, the Encoded 1620 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1621 JWE Ciphertext, and the Encoded JWE Authentication Tag in that order, 1622 with the five strings being separated by four period ('.') 1623 characters. 1625 The final result in this example (with line breaks for display 1626 purposes only) is: 1628 eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1629 UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm 1630 1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7Pc 1631 HALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIF 1632 NPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPhcCdZ6XDP0_F8 1633 rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPgwCp6X-nZZd9OHBv 1634 -B3oWh2TbqmScqXMR4gp_A. 1635 AxY8DCtDaGlsbGljb3RoZQ. 1636 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1637 9hH0vgRfYgPnAHOd8stkvw 1639 A.2.12. Validation 1641 This example illustrates the process of creating a JWE with RSAES- 1642 PKCS1-V1_5 for key encryption and AES_CBC_HMAC_SHA2 for content 1643 encryption. These results can be used to validate JWE decryption 1644 implementations for these algorithms. Note that since the RSAES- 1645 PKCS1-V1_5 computation includes random values, the encryption results 1646 above will not be completely reproducible. However, since the AES 1647 CBC computation is deterministic, the JWE Encrypted Ciphertext values 1648 will be the same for all encryptions performed using these inputs. 1650 A.3. Example JWE using AES Key Wrap and AES GCM 1652 This example encrypts the plaintext "Live long and prosper." to the 1653 recipient using AES Key Wrap for key encryption and AES GCM for 1654 content encryption. The representation of this plaintext is: 1656 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1657 112, 114, 111, 115, 112, 101, 114, 46] 1659 A.3.1. JWE Header 1661 The following example JWE Header declares that: 1663 o the Content Encryption Key is encrypted to the recipient using the 1664 AES Key Wrap algorithm with a 128 bit key to produce the JWE 1665 Encrypted Key and 1667 o the Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1668 algorithm to produce the Ciphertext. 1670 {"alg":"A128KW","enc":"A128CBC-HS256"} 1672 A.3.2. Encoded JWE Header 1674 Base64url encoding the octets of the UTF-8 representation of the JWE 1675 Header yields this Encoded JWE Header value: 1677 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1679 A.3.3. Content Encryption Key (CEK) 1681 Generate a 256 bit random Content Encryption Key (CEK). In this 1682 example, the value is: 1684 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1685 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1686 44, 207] 1688 A.3.4. Key Encryption 1690 Encrypt the CEK with the shared symmetric key using the AES Key Wrap 1691 algorithm to produce the JWE Encrypted Key. This example uses the 1692 symmetric key represented in JSON Web Key [JWK] format below: 1694 {"kty":"oct", 1695 "k":"GawgguFyGrWKav7AX4VKUg" 1696 } 1698 The resulting JWE Encrypted Key value is: 1700 [232, 160, 123, 211, 183, 76, 245, 132, 200, 128, 123, 75, 190, 216, 1701 22, 67, 201, 138, 193, 186, 9, 91, 122, 31, 246, 90, 28, 139, 57, 3, 1702 76, 124, 193, 11, 98, 37, 173, 61, 104, 57] 1704 A.3.5. Encoded JWE Encrypted Key 1706 Base64url encode the JWE Encrypted Key to produce the Encoded JWE 1707 Encrypted Key. This result is: 1709 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ 1711 A.3.6. Initialization Vector 1713 Generate a random 128 bit JWE Initialization Vector. In this 1714 example, the value is: 1716 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 1717 101] 1719 Base64url encoding this value yields this Encoded JWE Initialization 1720 Vector value: 1722 AxY8DCtDaGlsbGljb3RoZQ 1724 A.3.7. Additional Authenticated Data 1726 Let the Additional Authenticated Data encryption parameter be the 1727 octets of the ASCII representation of the Encoded JWE Header value. 1728 This AAD value is: 1730 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1731 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1732 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1733 110, 48] 1735 A.3.8. Plaintext Encryption 1737 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1738 the encryption key, the JWE Initialization Vector, and the Additional 1739 Authenticated Data value above. The steps for doing this using the 1740 values from this example are detailed in Appendix B. The resulting 1741 Ciphertext is: 1743 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1744 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1745 112, 56, 102] 1747 The resulting Authentication Tag value is: 1749 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 1750 194, 85] 1752 A.3.9. Encoded JWE Ciphertext 1754 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1755 This result is: 1757 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1759 A.3.10. Encoded JWE Authentication Tag 1761 Base64url encode the Authentication Tag to create the Encoded JWE 1762 Authentication Tag. This result is: 1764 U0m_YmjN04DJvceFICbCVQ 1766 A.3.11. Complete Representation 1768 Assemble the final representation: The Compact Serialization of this 1769 result is the concatenation of the Encoded JWE Header, the Encoded 1770 JWE Encrypted Key, the Encoded JWE Initialization Vector, the Encoded 1771 JWE Ciphertext, and the Encoded JWE Authentication Tag in that order, 1772 with the five strings being separated by four period ('.') 1773 characters. 1775 The final result in this example (with line breaks for display 1776 purposes only) is: 1778 eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0. 1779 6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ. 1780 AxY8DCtDaGlsbGljb3RoZQ. 1781 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY. 1782 U0m_YmjN04DJvceFICbCVQ 1784 A.3.12. Validation 1786 This example illustrates the process of creating a JWE with AES Key 1787 Wrap for key encryption and AES GCM for content encryption. These 1788 results can be used to validate JWE decryption implementations for 1789 these algorithms. Also, since both the AES Key Wrap and AES GCM 1790 computations are deterministic, the resulting JWE value will be the 1791 same for all encryptions performed using these inputs. Since the 1792 computation is reproducible, these results can also be used to 1793 validate JWE encryption implementations for these algorithms. 1795 A.4. Example JWE Using JWE JSON Serialization 1797 This section contains an example using the JWE JSON Serialization. 1798 This example demonstrates the capability for encrypting the same 1799 plaintext to multiple recipients. 1801 Two recipients are present in this example. The algorithm and key 1802 used for the first recipient are the same as that used in 1803 Appendix A.2. The algorithm and key used for the second recipient 1804 are the same as that used in Appendix A.3. The resulting JWE 1805 Encrypted Key values are therefore the same; those computations are 1806 not repeated here. 1808 The Plaintext, the Content Encryption Key (CEK), Initialization 1809 Vector, and JWE Protected Header are shared by all recipients (which 1810 must be the case, since the Ciphertext and Authentication Tag are 1811 also shared). 1813 A.4.1. JWE Per-Recipient Unprotected Headers 1815 The first recipient uses the RSAES-PKCS1-V1_5 algorithm to encrypt 1816 the Content Encryption Key (CEK). The second uses RSAES OAEP to 1817 encrypt the CEK. Key ID values are supplied for both keys. The two 1818 per-recipient header values used to represent these algorithms and 1819 Key IDs are: 1821 {"alg":"RSA1_5","kid":"2011-04-29"} 1823 and: 1825 {"alg":"A128KW","kid":"7"} 1827 A.4.2. JWE Protected Header 1829 The Plaintext is encrypted using the AES_128_CBC_HMAC_SHA_256 1830 algorithm to produce the common JWE Ciphertext and JWE Authentication 1831 Tag values. The JWE Protected Header value representing this is: 1833 {"enc":"A128CBC-HS256"} 1835 Base64url encoding the octets of the UTF-8 representation of the JWE 1836 Protected Header yields this Encoded JWE Protected Header value: 1838 eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0 1840 A.4.3. JWE Unprotected Header 1842 This JWE uses the "jku" header parameter to reference a JWK Set. This 1843 is represented in the following JWE Unprotected Header value as: 1845 {"jku":"https://server.example.com/keys.jwks"} 1847 A.4.4. Complete JWE Header Values 1849 Combining the per-recipient, protected, and unprotected header values 1850 supplied, the JWE Header values used for the first and second 1851 recipient respectively are: 1853 {"alg":"RSA1_5", 1854 "kid":"2011-04-29", 1855 "enc":"A128CBC-HS256", 1856 "jku":"https://server.example.com/keys.jwks"} 1858 and: 1860 {"alg":"A128KW", 1861 "kid":"7", 1862 "enc":"A128CBC-HS256", 1863 "jku":"https://server.example.com/keys.jwks"} 1865 A.4.5. Additional Authenticated Data 1867 Let the Additional Authenticated Data encryption parameter be the 1868 octets of the ASCII representation of the Encoded JWE Protected 1869 Header value. This AAD value is: 1871 [101, 121, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 77, 84, 73, 1872 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 110, 48] 1874 A.4.6. Plaintext Encryption 1876 Encrypt the Plaintext with AES_128_CBC_HMAC_SHA_256 using the CEK as 1877 the encryption key, the JWE Initialization Vector, and the Additional 1878 Authenticated Data value above. The steps for doing this using the 1879 values from Appendix A.3 are detailed in Appendix B. The resulting 1880 Ciphertext is: 1882 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1883 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1884 112, 56, 102] 1886 The resulting Authentication Tag value is: 1888 [51, 63, 149, 60, 252, 148, 225, 25, 92, 185, 139, 245, 35, 2, 47, 1889 207] 1891 A.4.7. Encoded JWE Ciphertext 1893 Base64url encode the Ciphertext to create the Encoded JWE Ciphertext. 1894 This result is: 1896 KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY 1898 A.4.8. Encoded JWE Authentication Tag 1900 Base64url encode the Authentication Tag to create the Encoded JWE 1901 Authentication Tag. This result is: 1903 Mz-VPPyU4RlcuYv1IwIvzw 1905 A.4.9. Complete JWE JSON Serialization Representation 1907 The complete JSON Web Encryption JSON Serialization for these values 1908 is as follows (with line breaks for display purposes only): 1910 {"protected": 1911 "eyJlbmMiOiJBMTI4Q0JDLUhTMjU2In0", 1912 "unprotected": 1913 {"jku":"https://server.example.com/keys.jwks"}, 1914 "recipients":[ 1915 {"header": 1916 {"alg":"RSA1_5"}, 1917 "encrypted_key": 1918 "UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0- 1919 kFm1NJn8LE9XShH59_i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKx 1920 GHZ7PcHALUzoOegEI-8E66jX2E4zyJKx-YxzZIItRzC5hlRirb6Y5Cl_p-ko3 1921 YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8OtvzlV7elprCbuPh 1922 cCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTP-cFPg 1923 wCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A"}, 1924 {"header": 1925 {"alg":"A128KW"}, 1926 "encrypted_key": 1927 "6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ"}], 1928 "iv": 1929 "AxY8DCtDaGlsbGljb3RoZQ", 1930 "ciphertext": 1931 "KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY", 1932 "tag": 1933 "Mz-VPPyU4RlcuYv1IwIvzw" 1934 } 1936 Appendix B. Example AES_128_CBC_HMAC_SHA_256 Computation 1938 This example shows the steps in the AES_128_CBC_HMAC_SHA_256 1939 authenticated encryption computation using the values from the 1940 example in Appendix A.3. As described where this algorithm is 1941 defined in Sections 4.8 and 4.8.3 of JWA, the AES_CBC_HMAC_SHA2 1942 family of algorithms are implemented using Advanced Encryption 1943 Standard (AES) in Cipher Block Chaining (CBC) mode with PKCS #5 1944 padding to perform the encryption and an HMAC SHA-2 function to 1945 perform the integrity calculation - in this case, HMAC SHA-256. 1947 B.1. Extract MAC_KEY and ENC_KEY from Key 1949 The 256 bit AES_128_CBC_HMAC_SHA_256 key K used in this example is: 1951 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1952 206, 107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 1953 44, 207] 1955 Use the first 128 bits of this key as the HMAC SHA-256 key MAC_KEY, 1956 which is: 1958 [4, 211, 31, 197, 84, 157, 252, 254, 11, 100, 157, 250, 63, 170, 106, 1959 206] 1961 Use the last 128 bits of this key as the AES CBC key ENC_KEY, which 1962 is: 1964 [107, 124, 212, 45, 111, 107, 9, 219, 200, 177, 0, 240, 143, 156, 44, 1965 207] 1967 Note that the MAC key comes before the encryption key in the input 1968 key K; this is in the opposite order of the algorithm names in the 1969 identifiers "AES_128_CBC_HMAC_SHA_256" and "A128CBC-HS256". 1971 B.2. Encrypt Plaintext to Create Ciphertext 1973 Encrypt the Plaintext with AES in Cipher Block Chaining (CBC) mode 1974 using PKCS #5 padding using the ENC_KEY above. The Plaintext in this 1975 example is: 1977 [76, 105, 118, 101, 32, 108, 111, 110, 103, 32, 97, 110, 100, 32, 1978 112, 114, 111, 115, 112, 101, 114, 46] 1980 The encryption result is as follows, which is the Ciphertext output: 1982 [40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 152, 230, 6, 1983 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 104, 143, 1984 112, 56, 102] 1986 B.3. 64 Bit Big Endian Representation of AAD Length 1988 The Additional Authenticated Data (AAD) in this example is: 1990 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 1991 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 1992 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 1993 110, 48] 1995 This AAD is 51 bytes long, which is 408 bits long. The octet string 1996 AL, which is the number of bits in AAD expressed as a big endian 64 1997 bit unsigned integer is: 1999 [0, 0, 0, 0, 0, 0, 1, 152] 2001 B.4. Initialization Vector Value 2003 The Initialization Vector value used in this example is: 2005 [3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 116, 104, 2006 101] 2008 B.5. Create Input to HMAC Computation 2010 Concatenate the AAD, the Initialization Vector, the Ciphertext, and 2011 the AL value. The result of this concatenation is: 2013 [101, 121, 74, 104, 98, 71, 99, 105, 79, 105, 74, 66, 77, 84, 73, 52, 2014 83, 49, 99, 105, 76, 67, 74, 108, 98, 109, 77, 105, 79, 105, 74, 66, 2015 77, 84, 73, 52, 81, 48, 74, 68, 76, 85, 104, 84, 77, 106, 85, 50, 73, 2016 110, 48, 3, 22, 60, 12, 43, 67, 104, 105, 108, 108, 105, 99, 111, 2017 116, 104, 101, 40, 57, 83, 181, 119, 33, 133, 148, 198, 185, 243, 24, 2018 152, 230, 6, 75, 129, 223, 127, 19, 210, 82, 183, 230, 168, 33, 215, 2019 104, 143, 112, 56, 102, 0, 0, 0, 0, 0, 0, 1, 152] 2021 B.6. Compute HMAC Value 2023 Compute the HMAC SHA-256 of the concatenated value above. This 2024 result M is: 2026 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2027 194, 85, 9, 84, 229, 201, 219, 135, 44, 252, 145, 102, 179, 140, 105, 2028 86, 229, 116] 2030 B.7. Truncate HMAC Value to Create Authentication Tag 2032 Use the first half (128 bits) of the HMAC output M as the 2033 Authentication Tag output T. This truncated value is: 2035 [83, 73, 191, 98, 104, 205, 211, 128, 201, 189, 199, 133, 32, 38, 2036 194, 85] 2038 Appendix C. Acknowledgements 2040 Solutions for encrypting JSON content were also explored by JSON 2041 Simple Encryption [JSE] and JavaScript Message Security Format 2042 [I-D.rescorla-jsms], both of which significantly influenced this 2043 draft. This draft attempts to explicitly reuse as many of the 2044 relevant concepts from XML Encryption 1.1 2045 [W3C.CR-xmlenc-core1-20120313] and RFC 5652 [RFC5652] as possible, 2046 while utilizing simple, compact JSON-based data structures. 2048 Special thanks are due to John Bradley and Nat Sakimura for the 2049 discussions that helped inform the content of this specification and 2050 to Eric Rescorla and Joe Hildebrand for allowing the reuse of text 2051 from [I-D.rescorla-jsms] in this document. 2053 Thanks to Axel Nennker, Emmanuel Raviart, Brian Campbell, and Edmund 2054 Jay for validating the examples in this specification. 2056 This specification is the work of the JOSE Working Group, which 2057 includes dozens of active and dedicated participants. In particular, 2058 the following individuals contributed ideas, feedback, and wording 2059 that influenced this specification: 2061 Richard Barnes, John Bradley, Brian Campbell, Breno de Medeiros, Dick 2062 Hardt, Jeff Hodges, Edmund Jay, James Manger, Matt Miller, Tony 2063 Nadalin, Axel Nennker, Emmanuel Raviart, Nat Sakimura, Jim Schaad, 2064 Hannes Tschofenig, and Sean Turner. 2066 Jim Schaad and Karen O'Donoghue chaired the JOSE working group and 2067 Sean Turner and Stephen Farrell served as Security area directors 2068 during the creation of this specification. 2070 Appendix D. Document History 2072 [[ to be removed by the RFC editor before publication as an RFC ]] 2074 -12 2076 o Clarified that the "typ" and "cty" header parameters are used in 2077 an application-specific manner and have no effect upon the JWE 2078 processing. 2080 o Replaced the MIME types "application/jwe+json" and 2081 "application/jwe" with "application/jose+json" and 2082 "application/jose". 2084 o Stated that receipients MUST either reject JWEs with duplicate 2085 Header Parameter Names or use a JSON parser that returns only the 2086 lexically last duplicate member name. 2088 o Moved the "epk", "apu", and "apv" Header Parameter definitions to 2089 be with the algorithm descriptions that use them. 2091 o Added a Serializations section with parallel treatment of the JWE 2092 Compact Serialization and the JWE JSON Serialization and also 2093 moved the former Implementation Considerations content there. 2095 o Restored use of the term "AEAD". 2097 o Changed terminology from "block encryption" to "content 2098 encryption". 2100 -11 2102 o Added Key Identification section. 2104 o Removed the Encrypted Key value from the AAD computation since it 2105 is already effectively integrity protected by the encryption 2106 process. The AAD value now only contains the representation of 2107 the JWE Encrypted Header. 2109 o For the JWE JSON Serialization, enable header parameter values to 2110 be specified in any of three parameters: the "protected" member 2111 that is integrity protected and shared among all recipients, the 2112 "unprotected" member that is not integrity protected and shared 2113 among all recipients, and the "header" member that is not 2114 integrity protected and specific to a particular recipient. (This 2115 does not affect the JWE Compact Serialization, in which all header 2116 parameter values are in a single integrity protected JWE Header 2117 value.) 2119 o Shortened the names "authentication_tag" to "tag" and 2120 "initialization_vector" to "iv" in the JWE JSON Serialization, 2121 addressing issue #20. 2123 o Removed "apv" (agreement PartyVInfo) since it is no longer used. 2125 o Removed suggested compact serialization for multiple recipients. 2127 o Changed the MIME type name "application/jwe-js" to 2128 "application/jwe+json", addressing issue #22. 2130 o Tightened the description of the "crit" (critical) header 2131 parameter. 2133 -10 2135 o Changed the JWE processing rules for multiple recipients so that a 2136 single AAD value contains the header parameters and encrypted key 2137 values for all the recipients, enabling AES GCM to be safely used 2138 for multiple recipients. 2140 o Added an appendix suggesting a possible compact serialization for 2141 JWEs with multiple recipients. 2143 -09 2145 o Added JWE JSON Serialization, as specified by 2146 draft-jones-jose-jwe-json-serialization-04. 2148 o Registered "application/jwe-js" MIME type and "JWE-JS" typ header 2149 parameter value. 2151 o Defined that the default action for header parameters that are not 2152 understood is to ignore them unless specifically designated as 2153 "MUST be understood" or included in the new "crit" (critical) 2154 header parameter list. This addressed issue #6. 2156 o Corrected "x5c" description. This addressed issue #12. 2158 o Changed from using the term "byte" to "octet" when referring to 8 2159 bit values. 2161 o Added Key Management Mode definitions to terminology section and 2162 used the defined terms to provide clearer key management 2163 instructions. This addressed issue #5. 2165 o Added text about preventing the recipient from behaving as an 2166 oracle during decryption, especially when using RSAES-PKCS1-V1_5. 2168 o Changed from using the term "Integrity Value" to "Authentication 2169 Tag". 2171 o Changed member name from "integrity_value" to "authentication_tag" 2172 in the JWE JSON Serialization. 2174 o Removed Initialization Vector from the AAD value since it is 2175 already integrity protected by all of the authenticated encryption 2176 algorithms specified in the JWA specification. 2178 o Replaced "A128CBC+HS256" and "A256CBC+HS512" with "A128CBC-HS256" 2179 and "A256CBC-HS512". The new algorithms perform the same 2180 cryptographic computations as [I-D.mcgrew-aead-aes-cbc-hmac-sha2], 2181 but with the Initialization Vector and Authentication Tag values 2182 remaining separate from the Ciphertext value in the output 2183 representation. Also deleted the header parameters "epu" 2184 (encryption PartyUInfo) and "epv" (encryption PartyVInfo), since 2185 they are no longer used. 2187 -08 2189 o Replaced uses of the term "AEAD" with "Authenticated Encryption", 2190 since the term AEAD in the RFC 5116 sense implied the use of a 2191 particular data representation, rather than just referring to the 2192 class of algorithms that perform authenticated encryption with 2193 associated data. 2195 o Applied editorial improvements suggested by Jeff Hodges and Hannes 2196 Tschofenig. Many of these simplified the terminology used. 2198 o Clarified statements of the form "This header parameter is 2199 OPTIONAL" to "Use of this header parameter is OPTIONAL". 2201 o Added a Header Parameter Usage Location(s) field to the IANA JSON 2202 Web Signature and Encryption Header Parameters registry. 2204 o Added seriesInfo information to Internet Draft references. 2206 -07 2208 o Added a data length prefix to PartyUInfo and PartyVInfo values. 2210 o Updated values for example AES CBC calculations. 2212 o Made several local editorial changes to clean up loose ends left 2213 over from to the decision to only support block encryption methods 2214 providing integrity. One of these changes was to explicitly state 2215 that the "enc" (encryption method) algorithm must be an 2216 Authenticated Encryption algorithm with a specified key length. 2218 -06 2220 o Removed the "int" and "kdf" parameters and defined the new 2221 composite Authenticated Encryption algorithms "A128CBC+HS256" and 2222 "A256CBC+HS512" to replace the former uses of AES CBC, which 2223 required the use of separate integrity and key derivation 2224 functions. 2226 o Included additional values in the Concat KDF calculation -- the 2227 desired output size and the algorithm value, and optionally 2228 PartyUInfo and PartyVInfo values. Added the optional header 2229 parameters "apu" (agreement PartyUInfo), "apv" (agreement 2230 PartyVInfo), "epu" (encryption PartyUInfo), and "epv" (encryption 2231 PartyVInfo). Updated the KDF examples accordingly. 2233 o Promoted Initialization Vector from being a header parameter to 2234 being a top-level JWE element. This saves approximately 16 bytes 2235 in the compact serialization, which is a significant savings for 2236 some use cases. Promoting the Initialization Vector out of the 2237 header also avoids repeating this shared value in the JSON 2238 serialization. 2240 o Changed "x5c" (X.509 Certificate Chain) representation from being 2241 a single string to being an array of strings, each containing a 2242 single base64 encoded DER certificate value, representing elements 2243 of the certificate chain. 2245 o Added an AES Key Wrap example. 2247 o Reordered the encryption steps so CMK creation is first, when 2248 required. 2250 o Correct statements in examples about which algorithms produce 2251 reproducible results. 2253 -05 2255 o Support both direct encryption using a shared or agreed upon 2256 symmetric key, and the use of a shared or agreed upon symmetric 2257 key to key wrap the CMK. 2259 o Added statement that "StringOrURI values are compared as case- 2260 sensitive strings with no transformations or canonicalizations 2261 applied". 2263 o Updated open issues. 2265 o Indented artwork elements to better distinguish them from the body 2266 text. 2268 -04 2270 o Refer to the registries as the primary sources of defined values 2271 and then secondarily reference the sections defining the initial 2272 contents of the registries. 2274 o Normatively reference XML Encryption 1.1 2275 [W3C.CR-xmlenc-core1-20120313] for its security considerations. 2277 o Reference draft-jones-jose-jwe-json-serialization instead of 2278 draft-jones-json-web-encryption-json-serialization. 2280 o Described additional open issues. 2282 o Applied editorial suggestions. 2284 -03 2286 o Added the "kdf" (key derivation function) header parameter to 2287 provide crypto agility for key derivation. The default KDF 2288 remains the Concat KDF with the SHA-256 digest function. 2290 o Reordered encryption steps so that the Encoded JWE Header is 2291 always created before it is needed as an input to the 2292 Authenticated Encryption "additional authenticated data" 2293 parameter. 2295 o Added the "cty" (content type) header parameter for declaring type 2296 information about the secured content, as opposed to the "typ" 2297 (type) header parameter, which declares type information about 2298 this object. 2300 o Moved description of how to determine whether a header is for a 2301 JWS or a JWE from the JWT spec to the JWE spec. 2303 o Added complete encryption examples for both Authenticated 2304 Encryption and non-Authenticated Encryption algorithms. 2306 o Added complete key derivation examples. 2308 o Added "Collision Resistant Namespace" to the terminology section. 2310 o Reference ITU.X690.1994 for DER encoding. 2312 o Added Registry Contents sections to populate registry values. 2314 o Numerous editorial improvements. 2316 -02 2318 o When using Authenticated Encryption algorithms (such as AES GCM), 2319 use the "additional authenticated data" parameter to provide 2320 integrity for the header, encrypted key, and ciphertext and use 2321 the resulting "authentication tag" value as the JWE Authentication 2322 Tag. 2324 o Defined KDF output key sizes. 2326 o Generalized text to allow key agreement to be employed as an 2327 alternative to key wrapping or key encryption. 2329 o Changed compression algorithm from gzip to DEFLATE. 2331 o Clarified that it is an error when a "kid" value is included and 2332 no matching key is found. 2334 o Clarified that JWEs with duplicate Header Parameter Names MUST be 2335 rejected. 2337 o Clarified the relationship between "typ" header parameter values 2338 and MIME types. 2340 o Registered application/jwe MIME type and "JWE" typ header 2341 parameter value. 2343 o Simplified JWK terminology to get replace the "JWK Key Object" and 2344 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 2345 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 2346 between single keys and sets of keys. As part of this change, the 2347 Header Parameter Name for a public key value was changed from 2348 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 2350 o Added suggestion on defining additional header parameters such as 2351 "x5t#S256" in the future for certificate thumbprints using hash 2352 algorithms other than SHA-1. 2354 o Specify RFC 2818 server identity validation, rather than RFC 6125 2355 (paralleling the same decision in the OAuth specs). 2357 o Generalized language to refer to Message Authentication Codes 2358 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 2359 unless in a context specific to HMAC algorithms. 2361 o Reformatted to give each header parameter its own section heading. 2363 -01 2365 o Added an integrity check for non-Authenticated Encryption 2366 algorithms. 2368 o Added "jpk" and "x5c" header parameters for including JWK public 2369 keys and X.509 certificate chains directly in the header. 2371 o Clarified that this specification is defining the JWE Compact 2372 Serialization. Referenced the new JWE-JS spec, which defines the 2373 JWE JSON Serialization. 2375 o Added text "New header parameters should be introduced sparingly 2376 since an implementation that does not understand a parameter MUST 2377 reject the JWE". 2379 o Clarified that the order of the encryption and decryption steps is 2380 not significant in cases where there are no dependencies between 2381 the inputs and outputs of the steps. 2383 o Made other editorial improvements suggested by JOSE working group 2384 participants. 2386 -00 2388 o Created the initial IETF draft based upon 2389 draft-jones-json-web-encryption-02 with no normative changes. 2391 o Changed terminology to no longer call both digital signatures and 2392 HMACs "signatures". 2394 Authors' Addresses 2396 Michael B. Jones 2397 Microsoft 2399 Email: mbj@microsoft.com 2400 URI: http://self-issued.info/ 2402 Eric Rescorla 2403 RTFM, Inc. 2405 Email: ekr@rtfm.com 2407 Joe Hildebrand 2408 Cisco Systems, Inc. 2410 Email: jhildebr@cisco.com