idnits 2.17.1 draft-ietf-httpbis-encryption-encoding-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 (June 29, 2016) is 2852 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. 'DH' -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS180-4' ** Obsolete normative reference: RFC 4492 (Obsoleted by RFC 8422) ** Downref: Normative reference to an Informational RFC: RFC 5869 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 7233 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7235 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP Working Group M. Thomson 3 Internet-Draft Mozilla 4 Intended status: Standards Track June 29, 2016 5 Expires: December 31, 2016 7 Encrypted Content-Encoding for HTTP 8 draft-ietf-httpbis-encryption-encoding-02 10 Abstract 12 This memo introduces a content-coding for HTTP that allows message 13 payloads to be encrypted. 15 Note to Readers 17 Discussion of this draft takes place on the HTTP working group 18 mailing list (ietf-http-wg@w3.org), which is archived at 19 https://lists.w3.org/Archives/Public/ietf-http-wg/ . 21 Working Group information can be found at http://httpwg.github.io/ ; 22 source code and issues list for this draft can be found at 23 https://github.com/httpwg/http-extensions/labels/encryption . 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on December 31, 2016. 42 Copyright Notice 44 Copyright (c) 2016 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 61 2. The "aesgcm" HTTP Content Encoding . . . . . . . . . . . . . 4 62 3. The Encryption HTTP Header Field . . . . . . . . . . . . . . 6 63 3.1. Encryption Header Field Parameters . . . . . . . . . . . 6 64 3.2. Content Encryption Key Derivation . . . . . . . . . . . . 7 65 3.3. Nonce Derivation . . . . . . . . . . . . . . . . . . . . 8 66 4. Crypto-Key Header Field . . . . . . . . . . . . . . . . . . . 8 67 4.1. Explicit Key . . . . . . . . . . . . . . . . . . . . . . 9 68 4.2. Diffie-Hellman . . . . . . . . . . . . . . . . . . . . . 9 69 4.3. Pre-shared Authentication Secrets . . . . . . . . . . . . 11 70 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 11 71 5.1. Successful GET Response . . . . . . . . . . . . . . . . . 12 72 5.2. Encryption and Compression . . . . . . . . . . . . . . . 12 73 5.3. Encryption with More Than One Key . . . . . . . . . . . . 12 74 5.4. Encryption with Explicit Key . . . . . . . . . . . . . . 13 75 5.5. Encryption with Multiple Records . . . . . . . . . . . . 13 76 5.6. Diffie-Hellman Encryption . . . . . . . . . . . . . . . . 14 77 5.7. Diffie-Hellman with Authentication Secret . . . . . . . . 14 78 6. Security Considerations . . . . . . . . . . . . . . . . . . . 15 79 6.1. Key and Nonce Reuse . . . . . . . . . . . . . . . . . . . 15 80 6.2. Data Encryption Limits . . . . . . . . . . . . . . . . . 16 81 6.3. Content Integrity . . . . . . . . . . . . . . . . . . . . 16 82 6.4. Leaking Information in Headers . . . . . . . . . . . . . 16 83 6.5. Poisoning Storage . . . . . . . . . . . . . . . . . . . . 17 84 6.6. Sizing and Timing Attacks . . . . . . . . . . . . . . . . 17 85 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 86 7.1. The "aesgcm" HTTP Content Encoding . . . . . . . . . . . 17 87 7.2. Encryption Header Fields . . . . . . . . . . . . . . . . 18 88 7.3. The HTTP Encryption Parameter Registry . . . . . . . . . 18 89 7.3.1. keyid . . . . . . . . . . . . . . . . . . . . . . . . 19 90 7.3.2. salt . . . . . . . . . . . . . . . . . . . . . . . . 19 91 7.3.3. rs . . . . . . . . . . . . . . . . . . . . . . . . . 19 92 7.4. The HTTP Crypto-Key Parameter Registry . . . . . . . . . 19 93 7.4.1. keyid . . . . . . . . . . . . . . . . . . . . . . . . 20 94 7.4.2. aesgcm . . . . . . . . . . . . . . . . . . . . . . . 20 95 7.4.3. dh . . . . . . . . . . . . . . . . . . . . . . . . . 20 96 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 97 8.1. Normative References . . . . . . . . . . . . . . . . . . 20 98 8.2. Informative References . . . . . . . . . . . . . . . . . 21 99 Appendix A. JWE Mapping . . . . . . . . . . . . . . . . . . . . 22 100 Appendix B. Intermediate Values for Encryption . . . . . . . . . 23 101 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 24 102 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 24 104 1. Introduction 106 It is sometimes desirable to encrypt the contents of a HTTP message 107 (request or response) so that when the payload is stored (e.g., with 108 a HTTP PUT), only someone with the appropriate key can read it. 110 For example, it might be necessary to store a file on a server 111 without exposing its contents to that server. Furthermore, that same 112 file could be replicated to other servers (to make it more resistant 113 to server or network failure), downloaded by clients (to make it 114 available offline), etc. without exposing its contents. 116 These uses are not met by the use of TLS [RFC5246], since it only 117 encrypts the channel between the client and server. 119 This document specifies a content-coding (Section 3.1.2 of [RFC7231]) 120 for HTTP to serve these and other use cases. 122 This content-coding is not a direct adaptation of message-based 123 encryption formats - such as those that are described by [RFC4880], 124 [RFC5652], [RFC7516], and [XMLENC] - which are not suited to stream 125 processing, which is necessary for HTTP. The format described here 126 cleaves more closely to the lower level constructs described in 127 [RFC5116]. 129 To the extent that message-based encryption formats use the same 130 primitives, the format can be considered as sequence of encrypted 131 messages with a particular profile. For instance, Appendix A 132 explains how the format is congruent with a sequence of JSON Web 133 Encryption [RFC7516] values with a fixed header. 135 This mechanism is likely only a small part of a larger design that 136 uses content encryption. How clients and servers acquire and 137 identify keys will depend on the use case. Though a complete key 138 management system is not described, this document defines an Crypto- 139 Key header field that can be used to convey keying material. 141 1.1. Notational Conventions 143 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 144 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 145 document are to be interpreted as described in [RFC2119]. 147 Base64url encoding is defined in Section 2 of [RFC7515]. 149 2. The "aesgcm" HTTP Content Encoding 151 The "aesgcm" HTTP content-coding indicates that a payload has been 152 encrypted using Advanced Encryption Standard (AES) in Galois/Counter 153 Mode (GCM) as identified as AEAD_AES_128_GCM in [RFC5116], 154 Section 5.1. The AEAD_AES_128_GCM algorithm uses a 128 bit content 155 encryption key. 157 When this content-coding is in use, the Encryption header field 158 (Section 3) describes how encryption has been applied. The Crypto- 159 Key header field (Section 4) can be included to describe how the 160 content encryption key is derived or retrieved. 162 The "aesgcm" content-coding uses a single fixed set of encryption 163 primitives. Cipher suite agility is achieved by defining a new 164 content-coding scheme. This ensures that only the HTTP Accept- 165 Encoding header field is necessary to negotiate the use of 166 encryption. 168 The "aesgcm" content-coding uses a fixed record size. The resulting 169 encoding is either a single record, or a series of fixed-size 170 records. The final record, or a lone record, MUST be shorter than 171 the fixed record size. 173 +-----------+ content is rs octets minus padding 174 | data | of between 2 and 65537 octets; 175 +-----------+ the last record is smaller 176 | 177 v 178 +-----+-----------+ add padding to get rs octets; 179 | pad | data | the last record contains 180 +-----+-----------+ up to rs minus 1 octets 181 | 182 v 183 +--------------------+ encrypt with AEAD_AES_128_GCM; 184 | ciphertext | final size is rs plus 16 octets 185 +--------------------+ the last record is smaller 186 The record size determines the length of each portion of plaintext 187 that is enciphered, with the exception of the final record, which is 188 necessarily smaller. The record size defaults to 4096 octets, but 189 can be changed using the "rs" parameter on the Encryption header 190 field. 192 AEAD_AES_128_GCM produces ciphertext 16 octets longer than its input 193 plaintext. Therefore, the length of each enciphered record other 194 than the last is equal to the value of the "rs" parameter plus 16 195 octets. A receiver MUST fail to decrypt if the final record 196 ciphertext is less than 18 octets in size. Valid records always 197 contain at least two octets of padding and a 16 octet authentication 198 tag. 200 Each record contains between 2 and 65537 octets of padding, inserted 201 into a record before the enciphered content. Padding consists of a 202 two octet unsigned integer in network byte order, followed that 203 number of zero-valued octets. A receiver MUST fail to decrypt if any 204 padding octet other than the first two are non-zero, or a record has 205 more padding than the record size can accommodate. 207 The nonce for each record is a 96-bit value constructed from the 208 record sequence number and the input keying material. Nonce 209 derivation is covered in Section 3.3. 211 The additional data passed to each invocation of AEAD_AES_128_GCM is 212 a zero-length octet sequence. 214 A sequence of full-sized records can be truncated to produce a 215 shorter sequence of records with valid authentication tags. To 216 prevent an attacker from truncating a stream, an encoder MUST append 217 a record that contains only padding and is smaller than the full 218 record size if the final record ends on a record boundary. A 219 receiver MUST treat the stream as failed due to truncation if the 220 final record is the full record size. 222 A consequence of this record structure is that range requests 223 [RFC7233] and random access to encrypted payload bodies are possible 224 at the granularity of the record size. However, without data from 225 adjacent ranges, partial records cannot be used. Thus, it is best if 226 range requests start and end on multiples of the record size, plus 227 the 16 octet authentication tag size. 229 Selecting the record size most appropriate for a given situation 230 requires a trade-off. A smaller record size allows decrypted octets 231 to be released more rapidly, which can be appropriate for 232 applications that depend on responsiveness. Smaller records also 233 reduce the additional data required if random access into the 234 ciphertext is needed. Applications that depend on being able to pad 235 by arbitrary amounts cannot increase the record size beyond 65537 236 octets. 238 Applications that don't depending on streaming, random access, or 239 arbitrary padding can use larger records, or even a single record. A 240 larger record size reduces the processing and data overheads. 242 3. The Encryption HTTP Header Field 244 The "Encryption" HTTP header field describes the encrypted content 245 encoding(s) that have been applied to a payload body, and therefore 246 how those content encoding(s) can be removed. 248 The "Encryption" header field uses the extended ABNF syntax defined 249 in Section 1.2 of [RFC7230] and the "parameter" and "OWS" rules from 250 [RFC7231]. 252 Encryption = #encryption_params 253 encryption_params = [ parameter *( OWS ";" OWS parameter ) ] 255 If the payload is encrypted more than once (as reflected by having 256 multiple content-codings that imply encryption), each application of 257 the content encoding is reflected in a separate Encryption header 258 field value in the order in which they were applied. 260 Encryption header field values with multiple instances of the same 261 parameter name are invalid. 263 Servers processing PUT requests MUST persist the value of the 264 Encryption header field, unless they remove the content-coding by 265 decrypting the payload. 267 3.1. Encryption Header Field Parameters 269 The following parameters are used in determining the content 270 encryption key that is used for encryption: 272 keyid: The "keyid" parameter identifies the keying material that is 273 used. When the Crypto-Key header field is used, the "keyid" 274 identifies a matching value in that field. The "keyid" parameter 275 MUST be used if keying material included in an Crypto-Key header 276 field is needed to derive the content encryption key. The "keyid" 277 parameter can also be used to identify keys in an application- 278 specific fashion. 280 salt: The "salt" parameter contains a base64url-encoded octets 281 [RFC7515] that is used as salt in deriving a unique content 282 encryption key (see Section 3.2). The "salt" parameter MUST be 283 present, and MUST be exactly 16 octets long when decoded. The 284 "salt" parameter MUST NOT be reused for two different payload 285 bodies that have the same input keying material; generating a 286 random salt for every application of the content encoding ensures 287 that content encryption key reuse is highly unlikely. 289 rs: The "rs" parameter contains a positive decimal integer that 290 describes the record size in octets. This value MUST be greater 291 than 1. For the "aesgcm" content encoding, this value MUST NOT be 292 greater than 2^36-31 (see Section 6.2). The "rs" parameter is 293 optional. If the "rs" parameter is absent, the record size 294 defaults to 4096 octets. 296 3.2. Content Encryption Key Derivation 298 In order to allow the reuse of keying material for multiple different 299 HTTP messages, a content encryption key is derived for each message. 300 The content encryption key is derived from the decoded value of the 301 "salt" parameter using the HMAC-based key derivation function (HKDF) 302 described in [RFC5869] using the SHA-256 hash algorithm [FIPS180-4]. 304 The decoded value of the "salt" parameter is the salt input to HKDF 305 function. The keying material identified by the "keyid" parameter is 306 the input keying material (IKM) to HKDF. Input keying material can 307 either be prearranged, or can be described using the Crypto-Key 308 header field (Section 4). The extract phase of HKDF therefore 309 produces a pseudorandom key (PRK) as follows: 311 PRK = HMAC-SHA-256(salt, IKM) 313 The info parameter to HKDF is set to the ASCII-encoded string 314 "Content-Encoding: aesgcm", a single zero octet and an optional 315 context string: 317 cek_info = "Content-Encoding: aesgcm" || 0x00 || context 319 Unless otherwise specified, the context is a zero length octet 320 sequence. Specifications that use this content encoding MAY specify 321 the use of an expanded context to cover additional inputs in the key 322 derivation. 324 AEAD_AES_128_GCM requires a 16 octet (128 bit) content encryption key 325 (CEK), so the length (L) parameter to HKDF is 16. The second step of 326 HKDF can therefore be simplified to the first 16 octets of a single 327 HMAC: 329 CEK = HMAC-SHA-256(PRK, cek_info || 0x01) 331 3.3. Nonce Derivation 333 The nonce input to AEAD_AES_128_GCM is constructed for each record. 334 The nonce for each record is a 12 octet (96 bit) value is produced 335 from the record sequence number and a value derived from the input 336 keying material. 338 The input keying material and salt values are input to HKDF with 339 different info and length parameters. 341 The length (L) parameter is 12 octets. The info parameter for the 342 nonce is the ASCII-encoded string "Content-Encoding: nonce", a single 343 zero octet and an context: 345 nonce_info = "Content-Encoding: nonce" || 0x00 || context 347 The context for nonce derivation SHOULD be the same as is used for 348 content encryption key derivation. 350 The result is combined with the record sequence number - using 351 exclusive or - to produce the nonce. The record sequence number 352 (SEQ) is a 96-bit unsigned integer in network byte order that starts 353 at zero. 355 Thus, the final nonce for each record is a 12 octet value: 357 NONCE = HMAC-SHA-256(PRK, nonce_info || 0x01) XOR SEQ 359 This nonce construction prevents removal or reordering of records. 360 However, it permits truncation of the tail of the sequence (see 361 Section 2 for how this is avoided). 363 4. Crypto-Key Header Field 365 A Crypto-Key header field can be used to describe the input keying 366 material used in the Encryption header field. 368 The Crypto-Key header field uses the extended ABNF syntax defined in 369 Section 1.2 of [RFC7230] and the "parameter" and "OWS" rules from 370 [RFC7231]. 372 Crypto-Key = #crypto_key_params 373 crypto_key_params = [ parameter *( OWS ";" OWS parameter ) ] 375 keyid: The "keyid" parameter corresponds to the "keyid" parameter in 376 the Encryption header field. 378 aesgcm: The "aesgcm" parameter contains the base64url-encoded octets 379 [RFC7515] of the input keying material for the "aesgcm" content 380 encoding. 382 dh: The "dh" parameter contains an ephemeral Diffie-Hellman share. 383 This form of the header field can be used to encrypt content for a 384 specific recipient. 386 Crypto-Key header field values with multiple instances of the same 387 parameter name are invalid. 389 The input keying material used by the key derivation (see 390 Section 3.2) can be determined based on the information in the 391 Crypto-Key header field. The method for key derivation depends on 392 the parameters that are present in the header field. 394 The value or values provided in the Crypto-Key header field is valid 395 only for the current HTTP message unless additional information 396 indicates a greater scope. 398 Note that different methods for determining input keying material 399 will produce different amounts of data. The HKDF process ensures 400 that the final content encryption key is the necessary size. 402 Alternative methods for determining input keying material MAY be 403 defined by specifications that use this content-encoding. 405 4.1. Explicit Key 407 The "aesgcm" parameter is decoded and used as the input keying 408 material for the "aesgcm" content encoding. The "aesgcm" parameter 409 MUST decode to at least 16 octets in order to be used as input keying 410 material for "aesgcm" content encoding. 412 Other key determination parameters can be ignored if the "aesgcm" 413 parameter is present. 415 4.2. Diffie-Hellman 417 The "dh" parameter is included to describe a Diffie-Hellman share, 418 either modp (or finite field) Diffie-Hellman [DH] or elliptic curve 419 Diffie-Hellman (ECDH) [RFC4492]. 421 This share is combined with other information at the recipient to 422 determine the HKDF input keying material. In order for the exchange 423 to be successful, the following information MUST be established out 424 of band: 426 o Which Diffie-Hellman form is used. 428 o The modp group or elliptic curve that will be used. 430 o A label that uniquely identifies the group. This label will be 431 expressed as a sequence of octets and MUST NOT include a zero- 432 valued octet. 434 o The format of the ephemeral public share that is included in the 435 "dh" parameter. This encoding MUST result in a single, canonical 436 sequence of octets. For instance, using ECDH both parties need to 437 agree whether this is an uncompressed or compressed point. 439 In addition to identifying which content-encoding this input keying 440 material is used for, the "keyid" parameter is used to identify this 441 additional information at the receiver. 443 The intended recipient recovers their private key and are then able 444 to generate a shared secret using the designated Diffie-Hellman 445 process. 447 The context for content encryption key and nonce derivation (see 448 Section 3.2) is set to include the means by which the keys were 449 derived. The context is formed from the concatenation of group 450 label, a single zero octet, the length of the public key of the 451 recipient, the public key of the recipient, the length of the public 452 key of the sender, and the public key of the sender. The public keys 453 are encoded into octets as defined for the group when determining the 454 context string. 456 context = label || 0x00 || 457 length(recipient_public) || recipient_public || 458 length(sender_public) || sender_public 460 The two length fields are encoded as a two octet unsigned integer in 461 network byte order. 463 Specifications that rely on an Diffie-Hellman exchange for 464 determining input keying material MUST either specify the parameters 465 for Diffie-Hellman (label, group parameters, or curves and point 466 format) that are used, or describe how those parameters are 467 negotiated between sender and receiver. 469 4.3. Pre-shared Authentication Secrets 471 Key derivation MAY be extended to include an additional 472 authentication secret. Such a secret is shared between the sender 473 and receiver of a message using other means. 475 A pre-shared authentication secret is not explicitly signaled in 476 either the Encryption or Crypto-Key header fields. Use of this 477 additional step depends on prior agreement. 479 When a shared authentication secret is used, the keying material 480 produced by the key agreement method (e.g., Diffie-Hellman, explicit 481 key, or otherwise) is combined with the authentication secret using 482 HKDF. The output of HKDF is the input keying material used to derive 483 the content encryption key and nonce Section 3.2. 485 The authentication secret is used as the "salt" parameter to HKDF, 486 the raw keying material (e.g., Diffie-Hellman output) is used as the 487 "IKM" parameter, the ASCII-encoded string "Content-Encoding: auth" 488 with a terminal zero octet is used as the "info" parameter, and the 489 length of the output is 32 octets (i.e., the entire output of the 490 underlying SHA-256 HMAC function): 492 auth_info = "Content-Encoding: auth" || 0x00 493 IKM = HKDF(authentication, raw_key, auth_info, 32) 495 This invocation of HKDF does not take the same context that is 496 provided to the final key derivation stages. Alternatively, this 497 phase can be viewed as always having a zero-length context. 499 Note that in the absence of an authentication secret, the input 500 keying material is simply the raw keying material: 502 IKM = raw_key 504 5. Examples 506 This section shows a few examples of the content encoding. 508 Note: All binary values in the examples in this section use the URL 509 and filename safe variant of base64 [RFC4648]. This includes the 510 bodies of requests. Whitespace in these values is added to fit 511 formatting constraints. 513 5.1. Successful GET Response 515 HTTP/1.1 200 OK 516 Content-Type: application/octet-stream 517 Content-Encoding: aesgcm 518 Connection: close 519 Encryption: keyid="bob/keys/123"; 520 salt="XZwpw6o37R-6qoZjw6KwAw" 522 [encrypted payload] 524 Here, a successful HTTP GET response has been encrypted using input 525 keying material that is identified by a URI. 527 Note that the media type has been changed to "application/octet- 528 stream" to avoid exposing information about the content. 530 5.2. Encryption and Compression 532 In this example, a response is first compressed, then encrypted. 533 Note that this particular encoding might compromise confidentiality 534 if the contents of the response could be influenced by an attacker. 536 HTTP/1.1 200 OK 537 Content-Type: text/html 538 Content-Encoding: gzip, aesgcm 539 Transfer-Encoding: chunked 540 Encryption: keyid="me@example.com"; 541 salt="m2hJ_NttRtFyUiMRPwfpHA" 543 [encrypted payload] 545 5.3. Encryption with More Than One Key 547 Here, a PUT request has been encrypted twice with different input 548 keying material; decrypting twice is necessary to read the content. 549 The outer layer of encryption uses a 1200 octet record size. 551 PUT /thing HTTP/1.1 552 Host: storage.example.com 553 Content-Type: application/http 554 Content-Encoding: aesgcm, aesgcm 555 Content-Length: 1235 556 Encryption: keyid="mailto:me@example.com"; 557 salt="NfzOeuV5USPRA-n_9s1Lag", 558 keyid="bob/keys/123"; 559 salt="bDMSGoc2uobK_IhavSHsHA"; rs=1200 561 [encrypted payload] 563 5.4. Encryption with Explicit Key 565 This example shows the UTF-8 encoded string "I am the walrus" 566 encrypted using an directly provided value for the input keying 567 material. The content body contains a single record only and is 568 shown here using base64url encoding for presentation reasons. 570 HTTP/1.1 200 OK 571 Content-Length: 33 572 Content-Encoding: aesgcm 573 Encryption: keyid="a1"; salt="vr0o6Uq3w_KDWeatc27mUg" 574 Crypto-Key: keyid="a1"; aesgcm="csPJEXBYA5U-Tal9EdJi-w" 576 VDeU0XxaJkOJDAxPl7h9JD5V8N43RorP7PfpPdZZQuwF 578 5.5. Encryption with Multiple Records 580 This example shows the same encrypted message, but split into records 581 of 10 octets each. The first record includes a single additional 582 octet of padding, which causes the end of the content to align with a 583 record boundary, forcing the creation of a third record that contains 584 only padding. 586 HTTP/1.1 200 OK 587 Content-Length: 70 588 Content-Encoding: aesgcm 589 Encryption: keyid="a1"; salt="4pdat984KmT9BWsU3np0nw"; rs=10 590 Crypto-Key: keyid="a1"; aesgcm="BO3ZVPxUlnLORbVGMpbT1Q" 592 uzLfrZ4cbMTC6hlUqHz4NvWZshFlTN3o2RLr6FrIuOKEfl2VrM_jYgoiIyEo 593 Zvc-ZGwV-RMJejG4M6ZfGysBAdhpPqrLzw 595 5.6. Diffie-Hellman Encryption 597 HTTP/1.1 200 OK 598 Content-Length: 33 599 Content-Encoding: aesgcm 600 Encryption: keyid="dhkey"; salt="Qg61ZJRva_XBE9IEUelU3A" 601 Crypto-Key: keyid="dhkey"; 602 dh="BDgpRKok2GZZDmS4r63vbJSUtcQx4Fq1V58-6-3NbZzS 603 TlZsQiCEDTQy3CZ0ZMsqeqsEb7qW2blQHA4S48fynTk" 605 yqD2bapcx14XxUbtwjiGx69eHE3Yd6AqXcwBpT2Kd1uy 607 This example shows the same string, "I am the walrus", encrypted 608 using ECDH over the P-256 curve [FIPS186], which is identified with 609 the label "P-256" encoded in ASCII. The content body is shown here 610 encoded in URL-safe base64url for presentation reasons only. 612 The receiver (in this case, the HTTP client) uses a key pair that is 613 identified by the string "dhkey" and the sender (the server) uses a 614 key pair for which the public share is included in the "dh" parameter 615 above. The keys shown below use uncompressed points [X9.62] encoded 616 using base64url. Line wrapping is added for presentation purposes 617 only. 619 Receiver: 620 private key: 9FWl15_QUQAWDaD3k3l50ZBZQJ4au27F1V4F0uLSD_M 621 public key: BCEkBjzL8Z3C-oi2Q7oE5t2Np-p7osjGLg93qUP0wvqR 622 T21EEWyf0cQDQcakQMqz4hQKYOQ3il2nNZct4HgAUQU 623 Sender: 624 private key: vG7TmzUX9NfVR4XUGBkLAFu8iDyQe-q_165JkkN0Vlw 625 public key: 627 5.7. Diffie-Hellman with Authentication Secret 629 This example shows the same receiver key pair from Section 5.6, but 630 with a shared authentication secret of "R29vIGdvbyBnJyBqb29iIQ". 632 HTTP/1.1 200 OK 633 Content-Length: 33 634 Content-Encoding: aesgcm 635 Encryption: keyid="dhkey"; salt="lngarbyKfMoi9Z75xYXmkg" 636 Crypto-Key: keyid="dhkey"; 637 dh="BNoRDbb84JGm8g5Z5CFxurSqsXWJ11ItfXEWYVLE85Y7 638 CYkDjXsIEc4aqxYaQ1G8BqkXCJ6DPpDrWtdWj_mugHU" 640 6nqAQUME8hNqw5J3kl8cpVVJylXKYqZOeseZG8UueKpA 642 The sender's private key used in this example is "nCScek-QpEjmOOlT- 643 rQ38nZzvdPlqa00Zy0i6m2OJvY". Intermediate values for this example 644 are included in Appendix B. 646 6. Security Considerations 648 This mechanism assumes the presence of a key management framework 649 that is used to manage the distribution of keys between valid senders 650 and receivers. Defining key management is part of composing this 651 mechanism into a larger application, protocol, or framework. 653 Implementation of cryptography - and key management in particular - 654 can be difficult. For instance, implementations need to account for 655 the potential for exposing keying material on side channels, such as 656 might be exposed by the time it takes to perform a given operation. 657 The requirements for a good implementation of cryptographic 658 algorithms can change over time. 660 6.1. Key and Nonce Reuse 662 Encrypting different plaintext with the same content encryption key 663 and nonce in AES-GCM is not safe [RFC5116]. The scheme defined here 664 uses a fixed progression of nonce values. Thus, a new content 665 encryption key is needed for every application of the content 666 encoding. Since input keying material can be reused, a unique "salt" 667 parameter is needed to ensure a content encryption key is not reused. 669 If a content encryption key is reused - that is, if input keying 670 material and salt are reused - this could expose the plaintext and 671 the authentication key, nullifying the protection offered by 672 encryption. Thus, if the same input keying material is reused, then 673 the salt parameter MUST be unique each time. This ensures that the 674 content encryption key is not reused. An implementation SHOULD 675 generate a random salt parameter for every message; a counter could 676 achieve the same result. 678 6.2. Data Encryption Limits 680 There are limits to the data that AEAD_AES_128_GCM can encipher. The 681 maximum record size is 2^36-31 [RFC5116]. In order to preserve a 682 2^-40 probability of indistinguishability under chosen plaintext 683 attack (IND-CPA), the total amount of plaintext that can be 684 enciphered MUST be less than 2^44.5 blocks [AEBounds]. 686 If rs is a multiple of 16 octets, this means 398 terabytes can be 687 encrypted safely, including padding. However, if the record size is 688 a multiple of 16 octets, the total amount of data that can be safely 689 encrypted is reduced. The worst case is a record size of 3 octets, 690 for which at most 74 terabytes of plaintext can be encrypted, of 691 which at least two-thirds is padding. 693 6.3. Content Integrity 695 This mechanism only provides content origin authentication. The 696 authentication tag only ensures that an entity with access to the 697 content encryption key produced the encrypted data. 699 Any entity with the content encryption key can therefore produce 700 content that will be accepted as valid. This includes all recipients 701 of the same HTTP message. 703 Furthermore, any entity that is able to modify both the Encryption 704 header field and the HTTP message body can replace the contents. 705 Without the content encryption key or the input keying material, 706 modifications to or replacement of parts of a payload body are not 707 possible. 709 6.4. Leaking Information in Headers 711 Because only the payload body is encrypted, information exposed in 712 header fields is visible to anyone who can read the HTTP message. 713 This could expose side-channel information. 715 For example, the Content-Type header field can leak information about 716 the payload body. 718 There are a number of strategies available to mitigate this threat, 719 depending upon the application's threat model and the users' 720 tolerance for leaked information: 722 1. Determine that it is not an issue. For example, if it is 723 expected that all content stored will be "application/json", or 724 another very common media type, exposing the Content-Type header 725 field could be an acceptable risk. 727 2. If it is considered sensitive information and it is possible to 728 determine it through other means (e.g., out of band, using hints 729 in other representations, etc.), omit the relevant headers, and/ 730 or normalize them. In the case of Content-Type, this could be 731 accomplished by always sending Content-Type: application/octet- 732 stream (the most generic media type), or no Content-Type at all. 734 3. If it is considered sensitive information and it is not possible 735 to convey it elsewhere, encapsulate the HTTP message using the 736 application/http media type (Section 8.3.2 of [RFC7230]), 737 encrypting that as the payload of the "outer" message. 739 6.5. Poisoning Storage 741 This mechanism only offers encryption of content; it does not perform 742 authentication or authorization, which still needs to be performed 743 (e.g., by HTTP authentication [RFC7235]). 745 This is especially relevant when a HTTP PUT request is accepted by a 746 server; if the request is unauthenticated, it becomes possible for a 747 third party to deny service and/or poison the store. 749 6.6. Sizing and Timing Attacks 751 Applications using this mechanism need to be aware that the size of 752 encrypted messages, as well as their timing, HTTP methods, URIs and 753 so on, may leak sensitive information. 755 This risk can be mitigated through the use of the padding that this 756 mechanism provides. Alternatively, splitting up content into 757 segments and storing the separately might reduce exposure. HTTP/2 758 [RFC7540] combined with TLS [RFC5246] might be used to hide the size 759 of individual messages. 761 7. IANA Considerations 763 7.1. The "aesgcm" HTTP Content Encoding 765 This memo registers the "aesgcm" HTTP content-coding in the HTTP 766 Content Codings Registry, as detailed in Section 2. 768 o Name: aesgcm 770 o Description: AES-GCM encryption with a 128-bit content encryption 771 key 773 o Reference: this specification 775 7.2. Encryption Header Fields 777 This memo registers the "Encryption" HTTP header field in the 778 Permanent Message Header Registry, as detailed in Section 3. 780 o Field name: Encryption 782 o Protocol: HTTP 784 o Status: Standard 786 o Reference: this specification 788 o Notes: 790 This memo registers the "Crypto-Key" HTTP header field in the 791 Permanent Message Header Registry, as detailed in Section 4. 793 o Field name: Crypto-Key 795 o Protocol: HTTP 797 o Status: Standard 799 o Reference: this specification 801 o Notes: 803 7.3. The HTTP Encryption Parameter Registry 805 This memo establishes a registry for parameters used by the 806 "Encryption" header field under the "Hypertext Transfer Protocol 807 (HTTP) Parameters" grouping. The "Hypertext Transfer Protocol (HTTP) 808 Encryption Parameters" registry operates under an "Specification 809 Required" policy [RFC5226]. 811 Entries in this registry are expected to include the following 812 information: 814 o Parameter Name: The name of the parameter. 816 o Purpose: A brief description of the purpose of the parameter. 818 o Reference: A reference to a specification that defines the 819 semantics of the parameter. 821 The initial contents of this registry are: 823 7.3.1. keyid 825 o Parameter Name: keyid 827 o Purpose: Identify the key that is in use. 829 o Reference: this document 831 7.3.2. salt 833 o Parameter Name: salt 835 o Purpose: Provide a source of entropy for derivation of a content 836 encryption key. This value is mandatory. 838 o Reference: this document 840 7.3.3. rs 842 o Parameter Name: rs 844 o Purpose: The size of the encrypted records. 846 o Reference: this document 848 7.4. The HTTP Crypto-Key Parameter Registry 850 This memo establishes a registry for parameters used by the "Crypto- 851 Key" header field under the "Hypertext Transfer Protocol (HTTP) 852 Parameters" grouping. The "Hypertext Transfer Protocol (HTTP) 853 Crypto-Key Parameters" operates under an "Specification Required" 854 policy [RFC5226]. 856 Entries in this registry are expected to include the following 857 information: 859 o Parameter Name: The name of the parameter. 861 o Purpose: A brief description of the purpose of the parameter. 863 o Reference: A reference to a specification that defines the 864 semantics of the parameter. 866 The initial contents of this registry are: 868 7.4.1. keyid 870 o Parameter Name: keyid 872 o Purpose: Identify the key that is in use. 874 o Reference: this document 876 7.4.2. aesgcm 878 o Parameter Name: aesgcm 880 o Purpose: Provide an explicit input keying material value for the 881 aesgcm content encoding. 883 o Reference: this document 885 7.4.3. dh 887 o Parameter Name: dh 889 o Purpose: Carry a modp or elliptic curve Diffie-Hellman share used 890 to derive input keying material. 892 o Reference: this document 894 8. References 896 8.1. Normative References 898 [DH] Diffie, W. and M. Hellman, "New Directions in 899 Cryptography", IEEE Transactions on Information Theory, 900 V.IT-22 n.6 , June 1977. 902 [FIPS180-4] 903 Department of Commerce, National., "NIST FIPS 180-4, 904 Secure Hash Standard", March 2012, 905 . 908 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 909 Requirement Levels", BCP 14, RFC 2119, 910 DOI 10.17487/RFC2119, March 1997, 911 . 913 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 914 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 915 for Transport Layer Security (TLS)", RFC 4492, 916 DOI 10.17487/RFC4492, May 2006, 917 . 919 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 920 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 921 . 923 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 924 Key Derivation Function (HKDF)", RFC 5869, 925 DOI 10.17487/RFC5869, May 2010, 926 . 928 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 929 Protocol (HTTP/1.1): Message Syntax and Routing", 930 RFC 7230, DOI 10.17487/RFC7230, June 2014, 931 . 933 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 934 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 935 DOI 10.17487/RFC7231, June 2014, 936 . 938 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 939 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 940 2015, . 942 8.2. Informative References 944 [AEBounds] 945 Luykx, A. and K. Paterson, "Limits on Authenticated 946 Encryption Use in TLS", March 2016, 947 . 949 [FIPS186] National Institute of Standards and Technology (NIST), 950 "Digital Signature Standard (DSS)", NIST PUB 186-4 , July 951 2013. 953 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 954 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 955 . 957 [RFC4880] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R. 958 Thayer, "OpenPGP Message Format", RFC 4880, 959 DOI 10.17487/RFC4880, November 2007, 960 . 962 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 963 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 964 DOI 10.17487/RFC5226, May 2008, 965 . 967 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 968 (TLS) Protocol Version 1.2", RFC 5246, 969 DOI 10.17487/RFC5246, August 2008, 970 . 972 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 973 RFC 5652, DOI 10.17487/RFC5652, September 2009, 974 . 976 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 977 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 978 RFC 7233, DOI 10.17487/RFC7233, June 2014, 979 . 981 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 982 Protocol (HTTP/1.1): Authentication", RFC 7235, 983 DOI 10.17487/RFC7235, June 2014, 984 . 986 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 987 RFC 7516, DOI 10.17487/RFC7516, May 2015, 988 . 990 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 991 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 992 DOI 10.17487/RFC7540, May 2015, 993 . 995 [X9.62] ANSI, "Public Key Cryptography For The Financial Services 996 Industry: The Elliptic Curve Digital Signature Algorithm 997 (ECDSA)", ANSI X9.62 , 1998. 999 [XMLENC] Eastlake, D., Reagle, J., Imamura, T., Dillaway, B., and 1000 E. Simon, "XML Encryption Syntax and Processing", W3C 1001 REC , December 2002, . 1003 Appendix A. JWE Mapping 1005 The "aesgcm" content encoding can be considered as a sequence of JSON 1006 Web Encryption (JWE) objects [RFC7516], each corresponding to a 1007 single fixed size record that includes leading padding. The 1008 following transformations are applied to a JWE object that might be 1009 expressed using the JWE Compact Serialization: 1011 o The JWE Protected Header is fixed to a value { "alg": "dir", 1012 "enc": "A128GCM" }, describing direct encryption using AES-GCM 1013 with a 128-bit content encryption key. This header is not 1014 transmitted, it is instead implied by the value of the Content- 1015 Encoding header field. 1017 o The JWE Encrypted Key is empty, as stipulated by the direct 1018 encryption algorithm. 1020 o The JWE Initialization Vector ("iv") for each record is set to the 1021 exclusive or of the 96-bit record sequence number, starting at 1022 zero, and a value derived from the input keying material (see 1023 Section 3.3). This value is also not transmitted. 1025 o The final value is the concatenated JWE Ciphertext and the JWE 1026 Authentication Tag, both expressed without URL-safe Base 64 1027 encoding. The "." separator is omitted, since the length of these 1028 fields is known. 1030 Thus, the example in Section 5.4 can be rendered using the JWE 1031 Compact Serialization as: 1033 eyAiYWxnIjogImRpciIsICJlbmMiOiAiQTEyOEdDTSIgfQ..31iQYc1v4a36EgyJ. 1034 VDeU0XxaJkOJDAxPl7h9JD4.VfDeN0aKz-z36T3WWULsBQ 1036 Where the first line represents the fixed JWE Protected Header, an 1037 empty JWE Encrypted Key, and the algorithmically-determined JWE 1038 Initialization Vector. The second line contains the encoded body, 1039 split into JWE Ciphertext and JWE Authentication Tag. 1041 Appendix B. Intermediate Values for Encryption 1043 The intermediate values calculated for the example in Section 5.7 are 1044 shown here. The following are inputs to the calculation: 1046 Plaintext: SSBhbSB0aGUgd2FscnVz 1048 Sender public key: BNoRDbb84JGm8g5Z5CFxurSqsXWJ11ItfXEWYVLE85Y7 1049 CYkDjXsIEc4aqxYaQ1G8BqkXCJ6DPpDrWtdWj_mugHU 1051 Sender private key: nCScek-QpEjmOOlT-rQ38nZzvdPlqa00Zy0i6m2OJvY 1053 Receiver public key: BCEkBjzL8Z3C-oi2Q7oE5t2Np-p7osjGLg93qUP0wvqR 1054 T21EEWyf0cQDQcakQMqz4hQKYOQ3il2nNZct4HgAUQU 1056 Receiver private key: 9FWl15_QUQAWDaD3k3l50ZBZQJ4au27F1V4F0uLSD_M 1057 Salt: lngarbyKfMoi9Z75xYXmkg 1059 Note that knowledge of just one of the private keys is necessary. 1060 The sender randomly generates the salt value, whereas salt is input 1061 to the receiver. 1063 This produces the following intermediate values: 1065 Shared secret (raw_key): RNjC-NVW4BGJbxWPW7G2mowsLeDa53LYKYm4-NOQ6Y 1067 Input keying material (IKM): EhpZec37Ptm4IRD5-jtZ0q6r1iK5vYmY1tZwtN8 1068 fbZY 1070 Context for content encryption key derivation: 1071 Q29udGVudC1FbmNvZGluZzogYWVzZ2NtAFAtMjU2AABB BCEkBjzL8Z3C- 1072 oi2Q7oE5t2Np-p7osjGLg93qUP0wvqR 1073 T21EEWyf0cQDQcakQMqz4hQKYOQ3il2nNZct4HgAUQUA 1074 QQTaEQ22_OCRpvIOWeQhcbq0qrF1iddSLX1xFmFSxPOW 1075 OwmJA417CBHOGqsWGkNRvAapFwiegz6Q61rXVo_5roB1 1077 Content encryption key (CEK): AN2-xhvFWeYh5z0fcDu0Ww 1079 Context for nonce derivation: Q29udGVudC1FbmNvZGluZzogbm9uY2UAUC0yNT 1080 YAAEEE ISQGPMvxncL6iLZDugTm3Y2n6nuiyMYuD3epQ_TC-pFP 1081 bUQRbJ_RxANBxqRAyrPiFApg5DeKXac1ly3geABRBQBB 1082 BNoRDbb84JGm8g5Z5CFxurSqsXWJ11ItfXEWYVLE85Y7 1083 CYkDjXsIEc4aqxYaQ1G8BqkXCJ6DPpDrWtdWj_mugHU 1085 Base nonce: JY1Okw5rw1Drkg9J 1087 When the CEK and nonce are used with AES GCM and the padded plaintext 1088 of AABJIGFtIHRoZSB3YWxydXM, the final ciphertext is 1089 6nqAQUME8hNqw5J3kl8cpVVJylXKYqZOeseZG8UueKpA, as shown in the 1090 example. 1092 Appendix C. Acknowledgements 1094 Mark Nottingham was an original author of this document. 1096 The following people provided valuable input: Richard Barnes, David 1097 Benjamin, Peter Beverloo, Mike Jones, Stephen Farrell, Adam Langley, 1098 John Mattsson, Eric Rescorla, and Jim Schaad. 1100 Author's Address 1101 Martin Thomson 1102 Mozilla 1104 Email: martin.thomson@gmail.com