idnits 2.17.1 draft-ietf-jose-json-web-encryption-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 12, 2012) is 4367 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'JWA' -- Possible downref: Non-RFC (?) normative reference: ref. 'JWK' -- Possible downref: Non-RFC (?) normative reference: ref. 'JWS' ** Downref: Normative reference to an Historic RFC: RFC 1421 ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Downref: Normative reference to an Informational RFC: RFC 6090 Summary: 6 errors (**), 0 flaws (~~), 1 warning (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JOSE Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track E. Rescorla 5 Expires: November 13, 2012 RTFM 6 J. Hildebrand 7 Cisco 8 May 12, 2012 10 JSON Web Encryption (JWE) 11 draft-ietf-jose-json-web-encryption-02 13 Abstract 15 JSON Web Encryption (JWE) is a means of representing encrypted 16 content using JSON data structures. Cryptographic algorithms and 17 identifiers used with this specification are enumerated in the 18 separate JSON Web Algorithms (JWA) specification. Related digital 19 signature and MAC capabilities are described in the separate JSON Web 20 Signature (JWS) specification. 22 Requirements Language 24 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 25 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 26 document are to be interpreted as described in RFC 2119 [RFC2119]. 28 Status of this Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on November 13, 2012. 45 Copyright Notice 47 Copyright (c) 2012 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 3. JSON Web Encryption (JWE) Overview . . . . . . . . . . . . . . 6 65 3.1. Example JWE with an Integrated Integrity Check . . . . . . 6 66 3.2. Example JWE with a Separate Integrity Check . . . . . . . 7 67 4. JWE Header . . . . . . . . . . . . . . . . . . . . . . . . . . 8 68 4.1. Reserved Header Parameter Names . . . . . . . . . . . . . 8 69 4.1.1. "alg" (Algorithm) Header Parameter . . . . . . . . . . 9 70 4.1.2. "enc" (Encryption Method) Header Parameter . . . . . . 9 71 4.1.3. "int" (Integrity Algorithm) Header Parameter . . . . . 9 72 4.1.4. "iv" (Initialization Vector) Header Parameter . . . . 10 73 4.1.5. "epk" (Ephemeral Public Key) Header Parameter . . . . 10 74 4.1.6. "zip" (Compression Algorithm) Header Parameter . . . . 10 75 4.1.7. "jku" (JWK Set URL) Header Parameter . . . . . . . . . 10 76 4.1.8. "jwk" (JSON Web Key) Header Parameter . . . . . . . . 10 77 4.1.9. "x5u" (X.509 URL) Header Parameter . . . . . . . . . . 11 78 4.1.10. "x5t" (X.509 Certificate Thumbprint) Header 79 Parameter . . . . . . . . . . . . . . . . . . . . . . 11 80 4.1.11. "x5c" (X.509 Certificate Chain) Header Parameter . . . 11 81 4.1.12. "kid" (Key ID) Header Parameter . . . . . . . . . . . 12 82 4.1.13. "typ" (Type) Header Parameter . . . . . . . . . . . . 12 83 4.2. Public Header Parameter Names . . . . . . . . . . . . . . 12 84 4.3. Private Header Parameter Names . . . . . . . . . . . . . . 12 85 5. Message Encryption . . . . . . . . . . . . . . . . . . . . . . 13 86 6. Message Decryption . . . . . . . . . . . . . . . . . . . . . . 14 87 7. Key Derivation . . . . . . . . . . . . . . . . . . . . . . . . 15 88 8. CMK Encryption . . . . . . . . . . . . . . . . . . . . . . . . 16 89 8.1. Asymmetric Encryption . . . . . . . . . . . . . . . . . . 16 90 8.2. Symmetric Encryption . . . . . . . . . . . . . . . . . . . 16 91 9. Integrity Value Calculation . . . . . . . . . . . . . . . . . 16 92 10. Encrypting JWEs with Cryptographic Algorithms . . . . . . . . 17 93 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 94 11.1. Registration of application/jwe MIME Media Type . . . . . 17 95 11.2. Registration of "JWE" Type Value . . . . . . . . . . . . . 18 96 12. Security Considerations . . . . . . . . . . . . . . . . . . . 19 97 13. Open Issues and Things To Be Done (TBD) . . . . . . . . . . . 19 98 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 99 14.1. Normative References . . . . . . . . . . . . . . . . . . . 19 100 14.2. Informative References . . . . . . . . . . . . . . . . . . 20 101 Appendix A. JWE Examples . . . . . . . . . . . . . . . . . . . . 21 102 A.1. JWE Example using TBD Algorithm . . . . . . . . . . . . . 21 103 A.1.1. Encrypting . . . . . . . . . . . . . . . . . . . . . . 21 104 A.1.2. Decrypting . . . . . . . . . . . . . . . . . . . . . . 21 105 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 21 106 Appendix C. Document History . . . . . . . . . . . . . . . . . . 22 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 109 1. Introduction 111 JSON Web Encryption (JWE) is a compact encryption format intended for 112 space constrained environments such as HTTP Authorization headers and 113 URI query parameters. It provides a wrapper for encrypted content 114 using JSON RFC 4627 [RFC4627] data structures. The JWE encryption 115 mechanisms are independent of the type of content being encrypted. 116 Cryptographic algorithms and identifiers used with this specification 117 are enumerated in the separate JSON Web Algorithms (JWA) [JWA] 118 specification. Related digital signature and MAC capabilities are 119 described in the separate JSON Web Signature (JWS) [JWS] 120 specification. 122 2. Terminology 124 JSON Web Encryption (JWE) A data structure representing an encrypted 125 version of a Plaintext. The structure consists of four parts: the 126 JWE Header, the JWE Encrypted Key, the JWE Ciphertext, and the JWE 127 Integrity Value. 129 Plaintext The bytes to be encrypted - a.k.a., the message. The 130 plaintext can contain an arbitrary sequence of bytes. 132 Ciphertext The encrypted version of the Plaintext. 134 Content Encryption Key (CEK) A symmetric key used to encrypt the 135 Plaintext for the recipient to produce the Ciphertext. 137 Content Integrity Key (CIK) A key used with a MAC function to ensure 138 the integrity of the Ciphertext and the parameters used to create 139 it. 141 Content Master Key (CMK) A key from which the CEK and CIK are 142 derived. When key wrapping or key encryption are employed, the 143 CMK is randomly generated and encrypted to the recipient as the 144 JWE Encrypted Key. When key agreement is employed, the CMK is the 145 result of the key agreement algorithm. 147 JWE Header A string representing a JSON object that describes the 148 encryption operations applied to create the JWE Encrypted Key, the 149 JWE Ciphertext, and the JWE Integrity Value. 151 JWE Encrypted Key When key wrapping or key encryption are employed, 152 the Content Master Key (CMK) is encrypted with the intended 153 recipient's key and the resulting encrypted content is recorded as 154 a byte array, which is referred to as the JWE Encrypted Key. 155 Otherwise, when key agreement is employed, the JWE Encrypted Key 156 is the empty byte array. 158 JWE Ciphertext A byte array containing the Ciphertext. 160 JWE Integrity Value A byte array containing a MAC value that ensures 161 the integrity of the Ciphertext and the parameters used to create 162 it. 164 Encoded JWE Header Base64url encoding of the bytes of the UTF-8 RFC 165 3629 [RFC3629] representation of the JWE Header. 167 Encoded JWE Encrypted Key Base64url encoding of the JWE Encrypted 168 Key. 170 Encoded JWE Ciphertext Base64url encoding of the JWE Ciphertext. 172 Encoded JWE Integrity Value Base64url encoding of the JWE Integrity 173 Value. 175 Header Parameter Names The names of the members within the JWE 176 Header. 178 Header Parameter Values The values of the members within the JWE 179 Header. 181 JWE Compact Serialization A representation of the JWE as the 182 concatenation of the Encoded JWE Header, the Encoded JWE Encrypted 183 Key, the Encoded JWE Ciphertext, and the Encoded JWE Integrity 184 Value in that order, with the four strings being separated by 185 period ('.') characters. 187 AEAD Algorithm An Authenticated Encryption with Associated Data 188 (AEAD) [RFC5116] encryption algorithm is one that provides an 189 integrated content integrity check. AES Galois/Counter Mode (GCM) 190 is one such algorithm. 192 Base64url Encoding For the purposes of this specification, this term 193 always refers to the URL- and filename-safe Base64 encoding 194 described in RFC 4648 [RFC4648], Section 5, with the (non URL- 195 safe) '=' padding characters omitted, as permitted by Section 3.2. 196 (See Appendix B of [JWS] for notes on implementing base64url 197 encoding without padding.) 199 StringOrURI A JSON string value, with the additional requirement 200 that while arbitrary string values MAY be used, any value 201 containing a ":" character MUST be a URI as defined in RFC 3986 202 [RFC3986]. 204 3. JSON Web Encryption (JWE) Overview 206 JWE represents encrypted content using JSON data structures and 207 base64url encoding. The representation consists of four parts: the 208 JWE Header, the JWE Encrypted Key, the JWE Ciphertext, and the JWE 209 Integrity Value. In the Compact Serialization, the four parts are 210 base64url-encoded for transmission, and represented as the 211 concatenation of the encoded strings in that order, with the four 212 strings being separated by period ('.') characters. (A JSON 213 Serialization for this information is defined in the separate JSON 214 Web Encryption JSON Serialization (JWE-JS) [JWE-JS] specification.) 216 JWE utilizes encryption to ensure the confidentiality of the contents 217 of the Plaintext. JWE adds a content integrity check if not provided 218 by the underlying encryption algorithm. 220 3.1. Example JWE with an Integrated Integrity Check 222 The following example JWE Header declares that: 224 o the Content Master Key is encrypted to the recipient using the 225 RSA-PKCS1_1.5 algorithm to produce the JWE Encrypted Key, 227 o the Plaintext is encrypted using the AES-256-GCM algorithm to 228 produce the JWE Ciphertext, 230 o the specified 96 bit Initialization Vector with the base64url 231 encoding "__79_Pv6-fj39vX0" was used, and 233 o a JSON Web Key Set (JWK Set) representation of the public key used 234 to encrypt the JWE is located at 235 "https://example.com/public_key.jwk". 237 {"alg":"RSA1_5", 238 "enc":"A256GCM", 239 "iv":"__79_Pv6-fj39vX0", 240 "jku":"https://example.com/public_key.jwk"} 242 Base64url encoding the bytes of the UTF-8 representation of the JWE 243 Header yields this Encoded JWE Header value (with line breaks for 244 display purposes only): 245 eyJhbGciOiJSU0ExXzUiLA0KICJlbmMiOiJBMjU2R0NNIiwNCiAiaXYiOiJfXzc5 246 X1B2Ni1mZyIsDQogImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vcHVibGljX2tl 247 eS5qd2sifQ 249 TBD: Finish this example by showing generation of a Content Master 250 Key (CMK), saying that the CMK is used as the CEK and there is no 251 separate integrity check since AES GCM is an AEAD algorithm, using 252 the recipient's key to encrypt the CMK to produce the JWE Encrypted 253 Key, using the CEK, IV, Encoded JWE Header, and Encoded JWE Encrypted 254 Key to encrypt the Plaintext to produce the Ciphertext and 255 "authentication tag" value, base64url encoding these values, and 256 assembling the result. 258 Concatenating these parts in the order 259 Header.EncryptedKey.Ciphertext.IntegrityValue with period characters 260 between the parts yields this complete JWE representation (with line 261 breaks for display purposes only): 262 eyJhbGciOiJSU0ExXzUiLA0KICJlbmMiOiJBMjU2R0NNIiwNCiAiaXYiOiJfXzc5 263 X1B2Ni1mZyIsDQogImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vcHVibGljX2tl 264 eS5qd2sifQ 265 . 266 TBD_encrypted_key_value_TBD 267 . 268 TBD_ciphertext_value_TBD 269 . 270 TBD_integrity_value_TBD 272 3.2. Example JWE with a Separate Integrity Check 274 The following example JWE Header declares that: 276 o the Content Master Key is encrypted to the recipient using the 277 RSA-PKCS1_1.5 algorithm to produce the JWE Encrypted Key, 279 o the Plaintext is encrypted using the AES-256-CBC algorithm to 280 produce the JWE Ciphertext, 282 o the JWE Integrity Value safeguarding the integrity of the 283 Ciphertext and the parameters used to create it was computed with 284 the HMAC SHA-256 algorithm, 286 o the specified 128 bit Initialization Vector with the base64url 287 encoding "AxY8DCtDaGlsbGljb3RoZQ" was used, and 289 o the thumbprint of the X.509 certificate that corresponds to the 290 key used to encrypt the JWE has the base64url encoding 291 "7noOPq-hJ1_hCnvWh6IeYI2w9Q0". 293 {"alg":"RSA1_5", 294 "enc":"A256CBC", 295 "int":"HS256", 296 "iv":"AxY8DCtDaGlsbGljb3RoZQ", 297 "x5t":"7noOPq-hJ1_hCnvWh6IeYI2w9Q0"} 299 Because AES CBC is not an AEAD algorithm (and so provides no 300 integrated content integrity check), a separate integrity check value 301 is used. 303 Base64url encoding the bytes of the UTF-8 representation of the JWE 304 Header yields this Encoded JWE Header value (with line breaks for 305 display purposes only): 306 eyJhbGciOiJSU0ExXzUiLA0KICJlbmMiOiJBMjU2Q0JDIiwNCiAiaW50IjoiSFMy 307 NTYiLA0KICJpdiI6Ik16LW1XXzRKSGZnIiwNCiAieDV0IjoiN25vT1BxLWhKMV9o 308 Q252V2g2SWVZSTJ3OVEwIn0 310 TBD: Finish this example by showing generation of a Content Master 311 Key (CMK), showing the derivation of the CEK and the CIK from the 312 CMK, using the recipient's key to encrypt the CMK to produce the JWE 313 Encrypted Key, using the CEK and IV to encrypt the Plaintext to 314 produce the Ciphertext, showing the computation of the JWE Integrity 315 Value, base64url encoding these values, and assembling the result. 316 eyJhbGciOiJSU0ExXzUiLA0KICJlbmMiOiJBMjU2Q0JDIiwNCiAiaW50IjoiSFMy 317 NTYiLA0KICJpdiI6Ik16LW1XXzRKSGZnIiwNCiAieDV0IjoiN25vT1BxLWhKMV9o 318 Q252V2g2SWVZSTJ3OVEwIn0 319 . 320 TBD_encrypted_key_value_TBD 321 . 322 TBD_ciphertext_value_TBD 323 . 324 TBD_integrity_value_TBD 326 4. JWE Header 328 The members of the JSON object represented by the JWE Header describe 329 the encryption applied to the Plaintext and optionally additional 330 properties of the JWE. The Header Parameter Names within this object 331 MUST be unique; JWEs with duplicate Header Parameter Names MUST be 332 rejected. Implementations MUST understand the entire contents of the 333 header; otherwise, the JWE MUST be rejected. 335 There are three classes of Header Parameter Names: Reserved Header 336 Parameter Names, Public Header Parameter Names, and Private Header 337 Parameter Names. 339 4.1. Reserved Header Parameter Names 341 The following header parameter names are reserved with meanings as 342 defined below. All the names are short because a core goal of JWE is 343 for the representations to be compact. 345 Additional reserved header parameter names MAY be defined via the 346 IANA JSON Web Signature and Encryption Header Parameters registry 348 [JWA]. As indicated by the common registry, JWSs and JWEs share a 349 common header parameter space; when a parameter is used by both 350 specifications, its usage must be compatible between the 351 specifications. 353 4.1.1. "alg" (Algorithm) Header Parameter 355 The "alg" (algorithm) header parameter identifies the cryptographic 356 algorithm used to secure the JWE Encrypted Key. A list of defined 357 "alg" values for use with JWE is presented in Section 4.1 of the JSON 358 Web Algorithms (JWA) [JWA] specification. The processing of the 359 "alg" header parameter requires that the value MUST be one that is 360 both supported and for which there exists a key for use with that 361 algorithm associated with the intended recipient. The "alg" value is 362 case sensitive. Its value MUST be a string containing a StringOrURI 363 value. This header parameter is REQUIRED. 365 "alg" values SHOULD either be defined in the IANA JSON Web Signature 366 and Encryption Algorithms registry [JWA] or be a URI that contains a 367 collision resistant namespace. 369 4.1.2. "enc" (Encryption Method) Header Parameter 371 The "enc" (encryption method) header parameter identifies the 372 symmetric encryption algorithm used to secure the Ciphertext. A list 373 of defined "enc" values is presented in Section 4.2 of the JSON Web 374 Algorithms (JWA) [JWA] specification. The processing of the "enc" 375 (encryption method) header parameter requires that the value MUST be 376 one that is supported. The "enc" value is case sensitive. Its value 377 MUST be a string containing a StringOrURI value. This header 378 parameter is REQUIRED. 380 "enc" values SHOULD either be defined in the IANA JSON Web Signature 381 and Encryption Algorithms registry [JWA] or be a URI that contains a 382 collision resistant namespace. 384 4.1.3. "int" (Integrity Algorithm) Header Parameter 386 The "int" (integrity algorithm) header parameter identifies the 387 cryptographic algorithm used to safeguard the integrity of the 388 Ciphertext and the parameters used to create it. A list of defined 389 "int" values is presented in Section 4.3 of the JSON Web Algorithms 390 (JWA) [JWA] specification. The "int" parameter uses the MAC subset 391 of the algorithm values used by the JWS "alg" parameter. The "int" 392 value is case sensitive. Its value MUST be a string containing a 393 StringOrURI value. This header parameter is REQUIRED when an AEAD 394 algorithm is not used to encrypt the Plaintext and MUST NOT be 395 present when an AEAD algorithm is used. 397 "int" values SHOULD either be defined in the IANA JSON Web Signature 398 and Encryption Algorithms registry [JWA] or be a URI that contains a 399 collision resistant namespace. 401 4.1.4. "iv" (Initialization Vector) Header Parameter 403 The "iv" (initialization vector) value for algorithms requiring it, 404 represented as a base64url encoded string. This header parameter is 405 OPTIONAL. 407 4.1.5. "epk" (Ephemeral Public Key) Header Parameter 409 The "epk" (ephemeral public key) value created by the originator for 410 the use in ECDH-ES RFC 6090 [RFC6090] encryption. This key is 411 represented as a JSON Web Key [JWK] value, containing "crv" (curve), 412 "x", and "y" members. The inclusion of the JWK "alg" (algorithm) 413 member is OPTIONAL. This header parameter is OPTIONAL. 415 4.1.6. "zip" (Compression Algorithm) Header Parameter 417 The "zip" (compression algorithm) applied to the Plaintext before 418 encryption, if any. If present, the value of the "zip" header 419 parameter MUST be the case sensitive string "DEF". Compression is 420 performed with the DEFLATE [RFC1951] algorithm. If no "zip" 421 parameter is present, no compression is applied to the Plaintext 422 before encryption. This header parameter is OPTIONAL. 424 4.1.7. "jku" (JWK Set URL) Header Parameter 426 The "jku" (JWK Set URL) header parameter is an absolute URL that 427 refers to a resource for a set of JSON-encoded public keys, one of 428 which corresponds to the key used to encrypt the JWE. The keys MUST 429 be encoded as a JSON Web Key Set (JWK Set) as defined in the JSON Web 430 Key (JWK) [JWK] specification. The protocol used to acquire the 431 resource MUST provide integrity protection; an HTTP GET request to 432 retrieve the certificate MUST use TLS RFC 2818 [RFC2818] RFC 5246 433 [RFC5246]; the identity of the server MUST be validated, as per 434 Section 3.1 of HTTP Over TLS [RFC2818]. This header parameter is 435 OPTIONAL. 437 4.1.8. "jwk" (JSON Web Key) Header Parameter 439 The "jwk" (JSON Web Key) header parameter is a public key that 440 corresponds to the key used to encrypt the JWE. This key is 441 represented as a JSON Web Key [JWK]. This header parameter is 442 OPTIONAL. 444 4.1.9. "x5u" (X.509 URL) Header Parameter 446 The "x5u" (X.509 URL) header parameter is an absolute URL that refers 447 to a resource for the X.509 public key certificate or certificate 448 chain corresponding to the key used to encrypt the JWE. The 449 identified resource MUST provide a representation of the certificate 450 or certificate chain that conforms to RFC 5280 [RFC5280] in PEM 451 encoded form RFC 1421 [RFC1421]. The certificate containing the 452 public key of the entity that encrypted the JWE MUST be the first 453 certificate. This MAY be followed by additional certificates, with 454 each subsequent certificate being the one used to certify the 455 previous one. The protocol used to acquire the resource MUST provide 456 integrity protection; an HTTP GET request to retrieve the certificate 457 MUST use TLS RFC 2818 [RFC2818] RFC 5246 [RFC5246]; the identity of 458 the server MUST be validated, as per Section 3.1 of HTTP Over TLS 459 [RFC2818]. This header parameter is OPTIONAL. 461 4.1.10. "x5t" (X.509 Certificate Thumbprint) Header Parameter 463 The "x5t" (X.509 Certificate Thumbprint) header parameter provides a 464 base64url encoded SHA-1 thumbprint (a.k.a. digest) of the DER 465 encoding of the X.509 certificate corresponding to the key used to 466 encrypt the JWE. This header parameter is OPTIONAL. 468 If, in the future, certificate thumbprints need to be computed using 469 hash functions other than SHA-1, it is suggested that additional 470 related header parameters be defined for that purpose. For example, 471 it is suggested that a new "x5t#S256" (X.509 Certificate Thumbprint 472 using SHA-256) header parameter could be defined by registering it in 473 the IANA JSON Web Signature and Encryption Header Parameters registry 474 [JWA]. 476 4.1.11. "x5c" (X.509 Certificate Chain) Header Parameter 478 The "x5c" (X.509 Certificate Chain) header parameter contains the 479 X.509 public key certificate or certificate chain corresponding to 480 the key used to encrypt the JWE. The certificate or certificate 481 chain is represented as an array of certificate values. Each value 482 is a base64-encoded (not base64url encoded) DER/BER PKIX certificate 483 value. The certificate containing the public key of the entity that 484 encrypted the JWE MUST be the first certificate. This MAY be 485 followed by additional certificates, with each subsequent certificate 486 being the one used to certify the previous one. The recipient MUST 487 verify the certificate chain according to [RFC5280] and reject the 488 JWE if any validation failure occurs. This header parameter is 489 OPTIONAL. 491 4.1.12. "kid" (Key ID) Header Parameter 493 The "kid" (key ID) header parameter is a hint indicating which key 494 was used to encrypt the JWE. This allows originators to explicitly 495 signal a change of key to recipients. Should the recipient be unable 496 to locate a key corresponding to the "kid" value, they SHOULD treat 497 that condition as an error. The interpretation of the contents of 498 the "kid" parameter is unspecified. Its value MUST be a string. 499 This header parameter is OPTIONAL. 501 4.1.13. "typ" (Type) Header Parameter 503 The "typ" (type) header parameter is used to declare the type of the 504 encrypted content. The type value "JWE" MAY be used to indicate that 505 the encrypted content is a JWE. The "typ" value is case sensitive. 506 Its value MUST be a string. This header parameter is OPTIONAL. 508 MIME Media Type RFC 2045 [RFC2045] values MAY be used as "typ" 509 values. 511 "typ" values SHOULD either be defined in the IANA JSON Web Signature 512 and Encryption "typ" Values registry [JWA] or be a URI that contains 513 a collision resistant namespace. 515 4.2. Public Header Parameter Names 517 Additional header parameter names can be defined by those using JWEs. 518 However, in order to prevent collisions, any new header parameter 519 name SHOULD either be defined in the IANA JSON Web Signature and 520 Encryption Header Parameters registry [JWA] or be a URI that contains 521 a collision resistant namespace. In each case, the definer of the 522 name or value needs to take reasonable precautions to make sure they 523 are in control of the part of the namespace they use to define the 524 header parameter name. 526 New header parameters should be introduced sparingly, as they can 527 result in non-interoperable JWEs. 529 4.3. Private Header Parameter Names 531 A producer and consumer of a JWE may agree to any header parameter 532 name that is not a Reserved Name Section 4.1 or a Public Name 533 Section 4.2. Unlike Public Names, these private names are subject to 534 collision and should be used with caution. 536 5. Message Encryption 538 The message encryption process is as follows. The order of the steps 539 is not significant in cases where there are no dependencies between 540 the inputs and outputs of the steps. 542 1. When key wrapping or key encryption are employed, generate a 543 random Content Master Key (CMK). See RFC 4086 [RFC4086] for 544 considerations on generating random values. Otherwise, when key 545 agreement is employed, use the key agreement algorithm to 546 compute the value of the Content Master Key (CMK). The CMK MUST 547 have a length equal to that of the larger of the required 548 encryption and integrity keys. 550 2. When key wrapping or key encryption are employed, encrypt the 551 CMK for the recipient (see Section 8) and let the result be the 552 JWE Encrypted Key. Otherwise, when key agreement is employed, 553 let the JWE Encrypted Key be an empty byte array. 555 3. Base64url encode the JWE Encrypted Key to create the Encoded JWE 556 Encrypted Key. 558 4. Generate a random Initialization Vector (IV) of the correct size 559 for the algorithm (if required for the algorithm). 561 5. If not using an AEAD algorithm, run the key derivation algorithm 562 (see Section 7) to generate the Content Encryption Key (CEK) and 563 the Content Integrity Key (CIK); otherwise (when using an AEAD 564 algorithm), set the CEK to be the CMK. 566 6. Compress the Plaintext if a "zip" parameter was included. 568 7. Serialize the (compressed) Plaintext into a byte sequence M. 570 8. Encrypt M using the CEK and IV to form the byte sequence C. If 571 an AEAD algorithm is used, use the concatenation of the Encoded 572 JWE Header, a period ('.') character, and the Encoded JWE 573 Encrypted Key as the "additional authenticated data" parameter 574 value for the encryption. 576 9. Base64url encode C to create the Encoded JWE Ciphertext. 578 10. Create a JWE Header containing the encryption parameters used. 579 Note that white space is explicitly allowed in the 580 representation and no canonicalization need be performed before 581 encoding. 583 11. Base64url encode the bytes of the UTF-8 representation of the 584 JWE Header to create the Encoded JWE Header. 586 12. If not using an AEAD algorithm, run the integrity algorithm (see 587 Section 9) using the CIK to compute the JWE Integrity Value; 588 otherwise (when using an AEAD algorithm), set the JWE Integrity 589 Value to be the "authentication tag" value produced by the AEAD 590 algorithm. 592 13. Base64url encode the JWE Integrity Value to create the Encoded 593 JWE Integrity Value. 595 14. The four encoded parts, taken together, are the result. The 596 Compact Serialization of this result is the concatenation of the 597 Encoded JWE Header, the Encoded JWE Encrypted Key, the Encoded 598 JWE Ciphertext, and the Encoded JWE Integrity Value in that 599 order, with the four strings being separated by period ('.') 600 characters. 602 6. Message Decryption 604 The message decryption process is the reverse of the encryption 605 process. The order of the steps is not significant in cases where 606 there are no dependencies between the inputs and outputs of the 607 steps. If any of these steps fails, the JWE MUST be rejected. 609 1. Parse the four parts of the input (which are separated by period 610 characters when using the JWE Compact Serialization) into the 611 Encoded JWE Header, the Encoded JWE Encrypted Key, the Encoded 612 JWE Ciphertext, and the Encoded JWE Integrity Value. 614 2. The Encoded JWE Header, the Encoded JWE Encrypted Key, the 615 Encoded JWE Ciphertext, and the Encoded JWE Integrity Value MUST 616 be successfully base64url decoded following the restriction that 617 no padding characters have been used. 619 3. The resulting JWE Header MUST be completely valid JSON syntax 620 conforming to RFC 4627 [RFC4627]. 622 4. The resulting JWE Header MUST be validated to only include 623 parameters and values whose syntax and semantics are both 624 understood and supported. 626 5. Verify that the JWE Header references a key known to the 627 recipient. 629 6. When key wrapping or key encryption are employed, decrypt the 630 JWE Encrypted Key to produce the Content Master Key (CMK). 631 Otherwise, when key agreement is employed, use the key agreement 632 algorithm to compute the value of the Content Master Key (CMK). 633 The CMK MUST have a length equal to that of the larger of the 634 required encryption and integrity keys. 636 7. If not using an AEAD algorithm, run the key derivation algorithm 637 (see Section 7) to generate the Content Encryption Key (CEK) and 638 the Content Integrity Key (CIK); otherwise (when using an AEAD 639 algorithm), set the CEK to be the CMK. 641 8. Decrypt the binary representation of the JWE Ciphertext using 642 the CEK and IV. If an AEAD algorithm is used, use the 643 concatenation of the Encoded JWE Header, a period ('.') 644 character, and the Encoded JWE Encrypted Key as the "additional 645 authenticated data" parameter value for the decryption. 647 9. If not using an AEAD algorithm, run the integrity algorithm (see 648 Section 9) using the CIK to compute an integrity value for the 649 input received. This computed value MUST match the received JWE 650 Integrity Value; otherwise (when using an AEAD algorithm), the 651 received JWE Integrity Value MUST match the "authentication tag" 652 value produced by the AEAD algorithm. 654 10. Uncompress the result of the previous step, if a "zip" parameter 655 was included. 657 11. Output the resulting Plaintext. 659 7. Key Derivation 661 The key derivation process converts the CMK into a CEK and a CIK. It 662 assumes as a primitive a Key Derivation Function (KDF) which 663 notionally takes three arguments: 665 MasterKey: The master key used to compute the individual use keys 667 Label: The use key label, used to differentiate individual use keys 669 Length: The desired length of the use key 671 The only KDF used in this document is the Concat KDF, as defined in 672 Section 5.8.1 of [NIST.800-56A], where the Digest Method is SHA-256, 673 the SuppPubInfo parameter is the Label, and the remaining OtherInfo 674 parameters are the empty bit string. 676 To compute the CEK from the CMK, the ASCII label "Encryption" ([69, 677 110, 99, 114, 121, 112, 116, 105, 111, 110]) is used. Use the key 678 size for the "enc" algorithm as the CEK desired key length. 680 To compute the CIK from the CMK, the ASCII label "Integrity" ([73, 681 110, 116, 101, 103, 114, 105, 116, 121]) is used. Use the minimum 682 key size for the "int" algorithm (for instance, 256 bits for "HS256") 683 as the CIK desired key length. 685 8. CMK Encryption 687 JWE supports two forms of CMK encryption: 689 o Asymmetric encryption under the recipient's public key. 691 o Symmetric encryption under a shared key. 693 8.1. Asymmetric Encryption 695 In the asymmetric encryption mode, the CMK is encrypted under the 696 recipient's public key. The asymmetric encryption modes defined for 697 use with this in this specification are listed in Section 4.1 of the 698 JSON Web Algorithms (JWA) [JWA] specification. 700 8.2. Symmetric Encryption 702 In the symmetric encryption mode, the CMK is encrypted under a 703 symmetric key shared between the sender and receiver. The symmetric 704 encryption modes defined for use with this in this specification are 705 listed in Section 4.1 of the JSON Web Algorithms (JWA) [JWA] 706 specification. 708 9. Integrity Value Calculation 710 When a non-AEAD algorithm is used (an algorithm without an integrated 711 content check), JWE adds an explicit integrity check value to the 712 representation. This value is computed in the manner described in 713 the JSON Web Signature (JWS) [JWS] specification, with these 714 modifications: 716 o The algorithm used is taken from the "int" (integrity algorithm) 717 header parameter rather than the "alg" header parameter. 719 o The algorithm MUST be a MAC algorithm (normally HMAC SHA-256). 721 o The JWS Secured Input used is the concatenation of the Encoded JWE 722 Header, a period ('.') character, the Encoded JWE Encrypted Key, a 723 period ('.') character, and the Encoded JWE Ciphertext. 725 o The CIK is used as the MAC key. 727 The computed JWS Signature value is the resulting integrity value. 729 10. Encrypting JWEs with Cryptographic Algorithms 731 JWE uses cryptographic algorithms to encrypt the Plaintext and the 732 Content Encryption Key (CMK) and to provide integrity protection for 733 the JWE Header, JWE Encrypted Key, and JWE Ciphertext. The JSON Web 734 Algorithms (JWA) [JWA] specification enumerates a set of 735 cryptographic algorithms and identifiers to be used with this 736 specification. Specifically, Section 4.1 enumerates a set of "alg" 737 (algorithm) header parameter values, Section 4.2 enumerates a set of 738 "enc" (encryption method) header parameter values, and Section 4.3 739 enumerates a set of "int" (integrity algorithm) header parameter 740 values intended for use this specification. It also describes the 741 semantics and operations that are specific to these algorithms and 742 algorithm families. 744 Public keys employed for encryption can be identified using the 745 Header Parameter methods described in Section 4.1 or can be 746 distributed using methods that are outside the scope of this 747 specification. 749 11. IANA Considerations 751 11.1. Registration of application/jwe MIME Media Type 753 This specification registers the "application/jwe" MIME Media Type 754 RFC 2045 [RFC2045]. 756 Type name: 757 application 759 Subtype name: 760 jwe 762 Required parameters: 763 n/a 765 Optional parameters: 766 n/a 768 Encoding considerations: 769 n/a 771 Security considerations: 772 See the Security Considerations section of this document 774 Interoperability considerations: 775 n/a 777 Published specification: 778 [[ this document ]] 780 Applications that use this media type: 781 OpenID Connect 783 Additional information: 784 Magic number(s): n/a 785 File extension(s): n/a 786 Macintosh file type code(s): n/a 788 Person & email address to contact for further information: 789 Michael B. Jones 790 mbj@microsoft.com 792 Intended usage: 793 COMMON 795 Restrictions on usage: 796 none 798 Author: 799 Michael B. Jones 800 mbj@microsoft.com 802 Change controller: 803 IETF 805 11.2. Registration of "JWE" Type Value 807 This specification registers the following "typ" header parameter 808 value in the JSON Web Signature and Encryption "typ" Values registry 809 established by the JSON Web Algorithms (JWA) [JWA] specification: 811 "typ" header parameter value: 812 "JWE" 814 Abbreviation for MIME type: 815 application/jwe 817 Change controller: 818 IETF 820 Description: 821 [[ this document ]] 823 12. Security Considerations 825 All the security considerations in the JWS specification also apply 826 to this specification, other than those that are signature specific. 827 Likewise, all the security considerations in XML Encryption 1.1 828 [W3C.CR-xmlenc-core1-20120313] also apply to JWE, other than those 829 that are XML specific. 831 13. Open Issues and Things To Be Done (TBD) 833 The following items remain to be done in this draft: 835 o Add examples, including a KDF and a key agreement example. 837 14. References 839 14.1. Normative References 841 [JWA] Jones, M., "JSON Web Algorithms (JWA)", May 2012. 843 [JWK] Jones, M., "JSON Web Key (JWK)", May 2012. 845 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 846 Signature (JWS)", May 2012. 848 [NIST.800-56A] 849 National Institute of Standards and Technology (NIST), 850 "Recommendation for Pair-Wise Key Establishment Schemes 851 Using Discrete Logarithm Cryptography (Revised)", NIST PUB 852 800-56A, March 2007. 854 [RFC1421] Linn, J., "Privacy Enhancement for Internet Electronic 855 Mail: Part I: Message Encryption and Authentication 856 Procedures", RFC 1421, February 1993. 858 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 859 version 1.3", RFC 1951, May 1996. 861 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 862 Extensions (MIME) Part One: Format of Internet Message 863 Bodies", RFC 2045, November 1996. 865 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 866 Requirement Levels", BCP 14, RFC 2119, March 1997. 868 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 870 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 871 10646", STD 63, RFC 3629, November 2003. 873 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 874 Resource Identifier (URI): Generic Syntax", STD 66, 875 RFC 3986, January 2005. 877 [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness 878 Requirements for Security", BCP 106, RFC 4086, June 2005. 880 [RFC4627] Crockford, D., "The application/json Media Type for 881 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 883 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 884 Encodings", RFC 4648, October 2006. 886 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 887 Encryption", RFC 5116, January 2008. 889 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 890 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 892 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 893 Housley, R., and W. Polk, "Internet X.509 Public Key 894 Infrastructure Certificate and Certificate Revocation List 895 (CRL) Profile", RFC 5280, May 2008. 897 [RFC6090] McGrew, D., Igoe, K., and M. Salter, "Fundamental Elliptic 898 Curve Cryptography Algorithms", RFC 6090, February 2011. 900 14.2. Informative References 902 [I-D.rescorla-jsms] 903 Rescorla, E. and J. Hildebrand, "JavaScript Message 904 Security Format", draft-rescorla-jsms-00 (work in 905 progress), March 2011. 907 [JSE] Bradley, J. and N. Sakimura (editor), "JSON Simple 908 Encryption", September 2010. 910 [JWE-JS] Jones, M., "JSON Web Encryption JSON Serialization 911 (JWE-JS)", March 2012. 913 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 914 RFC 5652, September 2009. 916 [W3C.CR-xmlenc-core1-20120313] 917 Eastlake, D., Reagle, J., Roessler, T., and F. Hirsch, 918 "XML Encryption Syntax and Processing Version 1.1", World 919 Wide Web Consortium CR CR-xmlenc-core1-20120313, 920 March 2012, 921 . 923 Appendix A. JWE Examples 925 This section provides several examples of JWEs. 927 A.1. JWE Example using TBD Algorithm 929 A.1.1. Encrypting 931 TBD: Demonstrate encryption steps with this algorithm 933 A.1.2. Decrypting 935 TBD: Demonstrate decryption steps with this algorithm 937 Appendix B. Acknowledgements 939 Solutions for encrypting JSON content were also explored by JSON 940 Simple Encryption [JSE] and JavaScript Message Security Format 941 [I-D.rescorla-jsms], both of which significantly influenced this 942 draft. This draft attempts to explicitly reuse as many of the 943 relevant concepts from XML Encryption 1.1 944 [W3C.CR-xmlenc-core1-20120313] and RFC 5652 [RFC5652] as possible, 945 while utilizing simple compact JSON-based data structures. 947 Special thanks are due to John Bradley and Nat Sakimura for the 948 discussions that helped inform the content of this specification and 949 to Eric Rescorla and Joe Hildebrand for allowing the reuse of text 950 from [I-D.rescorla-jsms] in this document. 952 Appendix C. Document History 954 -02 956 o When using AEAD algorithms (such as AES GCM), use the "additional 957 authenticated data" parameter to provide integrity for the header, 958 encrypted key, and ciphertext and use the resulting 959 "authentication tag" value as the JWE Integrity Value. 961 o Defined KDF output key sizes. 963 o Generalized text to allow key agreement to be employed as an 964 alternative to key wrapping or key encryption. 966 o Changed compression algorithm from gzip to DEFLATE. 968 o Clarified that it is an error when a "kid" value is included and 969 no matching key is found. 971 o Clarified that JWEs with duplicate Header Parameter Names MUST be 972 rejected. 974 o Clarified the relationship between "typ" header parameter values 975 and MIME types. 977 o Registered application/jwe MIME type and "JWE" typ header 978 parameter value. 980 o Simplified JWK terminology to get replace the "JWK Key Object" and 981 "JWK Container Object" terms with simply "JSON Web Key (JWK)" and 982 "JSON Web Key Set (JWK Set)" and to eliminate potential confusion 983 between single keys and sets of keys. As part of this change, the 984 header parameter name for a public key value was changed from 985 "jpk" (JSON Public Key) to "jwk" (JSON Web Key). 987 o Added suggestion on defining additional header parameters such as 988 "x5t#S256" in the future for certificate thumbprints using hash 989 algorithms other than SHA-1. 991 o Specify RFC 2818 server identity validation, rather than RFC 6125 992 (paralleling the same decision in the OAuth specs). 994 o Generalized language to refer to Message Authentication Codes 995 (MACs) rather than Hash-based Message Authentication Codes (HMACs) 996 unless in a context specific to HMAC algorithms. 998 o Reformatted to give each header parameter its own section heading. 1000 -01 1002 o Added an integrity check for non-AEAD algorithms. 1004 o Added "jpk" and "x5c" header parameters for including JWK public 1005 keys and X.509 certificate chains directly in the header. 1007 o Clarified that this specification is defining the JWE Compact 1008 Serialization. Referenced the new JWE-JS spec, which defines the 1009 JWE JSON Serialization. 1011 o Added text "New header parameters should be introduced sparingly 1012 since an implementation that does not understand a parameter MUST 1013 reject the JWE". 1015 o Clarified that the order of the encryption and decryption steps is 1016 not significant in cases where there are no dependencies between 1017 the inputs and outputs of the steps. 1019 o Made other editorial improvements suggested by JOSE working group 1020 participants. 1022 -00 1024 o Created the initial IETF draft based upon 1025 draft-jones-json-web-encryption-02 with no normative changes. 1027 o Changed terminology to no longer call both digital signatures and 1028 HMACs "signatures". 1030 Authors' Addresses 1032 Michael B. Jones 1033 Microsoft 1035 Email: mbj@microsoft.com 1036 URI: http://self-issued.info/ 1038 Eric Rescorla 1039 RTFM, Inc. 1041 Email: ekr@rtfm.com 1042 Joe Hildebrand 1043 Cisco Systems, Inc. 1045 Email: jhildebr@cisco.com