idnits 2.17.1 draft-thomson-http-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 (October 19, 2015) is 3105 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-2' ** 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 Network Working Group M. Thomson 3 Internet-Draft Mozilla 4 Intended status: Standards Track October 19, 2015 5 Expires: April 21, 2016 7 Encrypted Content-Encoding for HTTP 8 draft-thomson-http-encryption-02 10 Abstract 12 This memo introduces a content-coding for HTTP that allows message 13 payloads to be encrypted. 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at http://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on April 21, 2016. 32 Copyright Notice 34 Copyright (c) 2015 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (http://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 50 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 51 2. The "aesgcm128" HTTP Content Encoding . . . . . . . . . . . . 3 52 3. The Encryption HTTP Header Field . . . . . . . . . . . . . . 5 53 3.1. Encryption Header Field Parameters . . . . . . . . . . . 6 54 3.2. Content Encryption Key Derivation . . . . . . . . . . . . 6 55 3.3. Nonce Derivation . . . . . . . . . . . . . . . . . . . . 7 56 4. Encryption-Key Header Field . . . . . . . . . . . . . . . . . 7 57 4.1. Explicit Key . . . . . . . . . . . . . . . . . . . . . . 8 58 4.2. Diffie-Hellman . . . . . . . . . . . . . . . . . . . . . 8 59 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 9 60 5.1. Successful GET Response . . . . . . . . . . . . . . . . . 9 61 5.2. Encryption and Compression . . . . . . . . . . . . . . . 9 62 5.3. Encryption with More Than One Key . . . . . . . . . . . . 9 63 5.4. Encryption with Explicit Key . . . . . . . . . . . . . . 10 64 5.5. Diffie-Hellman Encryption . . . . . . . . . . . . . . . . 10 65 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 66 6.1. Key and Nonce Reuse . . . . . . . . . . . . . . . . . . . 11 67 6.2. Content Integrity . . . . . . . . . . . . . . . . . . . . 12 68 6.3. Leaking Information in Headers . . . . . . . . . . . . . 12 69 6.4. Poisoning Storage . . . . . . . . . . . . . . . . . . . . 13 70 6.5. Sizing and Timing Attacks . . . . . . . . . . . . . . . . 13 71 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 72 7.1. The "aesgcm128" HTTP Content Encoding . . . . . . . . . . 13 73 7.2. Encryption Header Fields . . . . . . . . . . . . . . . . 13 74 7.3. The HTTP Encryption Parameter Registry . . . . . . . . . 14 75 7.3.1. keyid . . . . . . . . . . . . . . . . . . . . . . . . 14 76 7.3.2. salt . . . . . . . . . . . . . . . . . . . . . . . . 14 77 7.3.3. rs . . . . . . . . . . . . . . . . . . . . . . . . . 15 78 7.4. The HTTP Encryption-Key Parameter Registry . . . . . . . 15 79 7.4.1. keyid . . . . . . . . . . . . . . . . . . . . . . . . 15 80 7.4.2. aesgcm128 . . . . . . . . . . . . . . . . . . . . . . 15 81 7.4.3. dh . . . . . . . . . . . . . . . . . . . . . . . . . 16 82 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 83 8.1. Normative References . . . . . . . . . . . . . . . . . . 16 84 8.2. Informative References . . . . . . . . . . . . . . . . . 17 85 Appendix A. JWE Mapping . . . . . . . . . . . . . . . . . . . . 18 86 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 19 87 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19 89 1. Introduction 91 It is sometimes desirable to encrypt the contents of a HTTP message 92 (request or response) so that when the payload is stored (e.g., with 93 a HTTP PUT), only someone with the appropriate key can read it. 95 For example, it might be necessary to store a file on a server 96 without exposing its contents to that server. Furthermore, that same 97 file could be replicated to other servers (to make it more resistant 98 to server or network failure), downloaded by clients (to make it 99 available offline), etc. without exposing its contents. 101 These uses are not met by the use of TLS [RFC5246], since it only 102 encrypts the channel between the client and server. 104 This document specifies a content-coding (Section 3.1.2 of [RFC7231]) 105 for HTTP to serve these and other use cases. 107 This content-coding is not a direct adaptation of message-based 108 encryption formats - such as those that are described by [RFC4880], 109 [RFC5652], [RFC7516], and [XMLENC] - which are not suited to stream 110 processing, which is necessary for HTTP. The format described here 111 cleaves more closely to the lower level constructs described in 112 [RFC5116]. 114 To the extent that message-based encryption formats use the same 115 primitives, the format can be considered as sequence of encrypted 116 messages with a particular profile. For instance, Appendix A 117 explains how the format is congruent with a sequence of JSON Web 118 Encryption [RFC7516] values with a fixed header. 120 This mechanism is likely only a small part of a larger design that 121 uses content encryption. How clients and servers acquire and 122 identify keys will depend on the use case. Though a complete key 123 management system is not described, this document defines an 124 Encryption-Key header field that can be used to convey keying 125 material. 127 1.1. Notational Conventions 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 131 document are to be interpreted as described in [RFC2119]. 133 2. The "aesgcm128" HTTP Content Encoding 135 The "aesgcm128" HTTP content-coding indicates that a payload has been 136 encrypted using Advanced Encryption Standard (AES) in Galois/Counter 137 Mode (GCM) as identified as AEAD_AES_128_GCM in [RFC5116], 138 Section 5.1. The AEAD_AES_128_GCM algorithm uses a 128 bit content 139 encryption key. 141 When this content-coding is in use, the Encryption header field 142 (Section 3) describes how encryption has been applied. The 143 Encryption-Key header field (Section 4) can be included to describe 144 how the content encryption key is derived or retrieved. 146 The "aesgcm128" content-coding uses a single fixed set of encryption 147 primitives. Cipher suite agility is achieved by defining a new 148 content-coding scheme. This ensures that only the HTTP Accept- 149 Encoding header field is necessary to negotiate the use of 150 encryption. 152 The "aesgcm128" content-coding uses a fixed record size. The 153 resulting encoding is a series of fixed-size records, with a final 154 record that is one or more octets shorter than a fixed sized record. 156 +------+ input of between rs-256 157 | data | and rs-1 octets 158 +------+ (one fewer for the last record) 159 | 160 v 161 +-----+-----------+ 162 | pad | data | add padding to form plaintext 163 +-----+-----------+ 164 | 165 v 166 +--------------------+ 167 | ciphertext | encrypt with AEAD_AES_128_GCM 168 +--------------------+ expands by 16 octets 170 The record size determines the length of each portion of plaintext 171 that is enciphered, with the exception of the final record, which is 172 necessarily smaller. The record size defaults to 4096 octets, but 173 can be changed using the "rs" parameter on the Encryption header 174 field. 176 AEAD_AES_128_GCM expands ciphertext to be 16 octets longer than its 177 input plaintext. Therefore, the length of each enciphered record 178 other than the last is equal to the value of the "rs" parameter plus 179 16 octets. A receiver MUST fail to decrypt if the final record 180 ciphertext is 16 octets or less in size. Valid records always 181 contain at least one byte of padding and a 16 octet authentication 182 tag. 184 Each record contains between 1 and 256 octets of padding, inserted 185 into a record before the enciphered content. Padding consists of a 186 length byte, followed that number of zero-valued octets. A receiver 187 MUST fail to decrypt if any padding octet other than the first is 188 non-zero, or a record has more padding than the record size can 189 accommodate. 191 The nonce for each record is a 96-bit value constructed from the 192 record sequence number and the input keying material. Nonce 193 derivation is covered in Section 3.3. 195 The additional data passed to each invocation of AEAD_AES_128_GCM is 196 a zero-length octet sequence. 198 A sequence of full-sized records can be truncated to produce a 199 shorter sequence of records with valid authentication tags. To 200 prevent an attacker from truncating a stream, an encoder MUST append 201 a record that contains only padding and is smaller than the full 202 record size if the final record ends on a record boundary. A 203 receiver MUST treat the stream as failed due to truncation if the 204 final record is the full record size. 206 A consequence of this record structure is that range requests 207 [RFC7233] and random access to encrypted payload bodies are possible 208 at the granularity of the record size. However, without data from 209 adjacent ranges, partial records cannot be used. Thus, it is best if 210 records start and end on multiples of the record size, plus the 16 211 octet authentication tag size. 213 3. The Encryption HTTP Header Field 215 The "Encryption" HTTP header field describes the encrypted content 216 encoding(s) that have been applied to a payload body, and therefore 217 how those content encoding(s) can be removed. 219 The "Encryption" header field uses the extended ABNF syntax defined 220 in Section 1.2 of [RFC7230] and the "parameter" rule from [RFC7231] 222 Encryption-val = #encryption_params 223 encryption_params = [ parameter *( ";" parameter ) ] 225 If the payload is encrypted more than once (as reflected by having 226 multiple content-codings that imply encryption), each application of 227 the content encoding is reflected in the Encryption header field, in 228 the order in which they were applied. 230 The Encryption header MAY be omitted if the sender does not intend 231 for the immediate recipient to be able to decrypt the payload body. 232 Alternatively, the Encryption header field MAY be omitted if the 233 sender intends for the recipient to acquire the header field by other 234 means. 236 Servers processing PUT requests MUST persist the value of the 237 Encryption header field, unless they remove the content-coding by 238 decrypting the payload. 240 3.1. Encryption Header Field Parameters 242 The following parameters are used in determining the content 243 encryption key that is used for encryption: 245 keyid: The "keyid" parameter contains a string that identifies the 246 keying material that is used. The "keyid" parameter SHOULD be 247 included, unless key identification is guaranteed by other means. 248 The "keyid" parameter MUST be used if keying material included in 249 an Encryption-Key header field is needed to derive the content 250 encryption key. 252 salt: The "salt" parameter contains a base64 URL-encoded octets that 253 is used as salt in deriving a unique content encryption key (see 254 Section 3.2). The "salt" parameter MUST be present, and MUST be 255 exactly 16 octets long when decoded. The "salt" parameter MUST 256 NOT be reused for two different payload bodies that have the same 257 input keying material; generating a random salt for every 258 application of the content encoding ensures that content 259 encryption key reuse is highly unlikely. 261 rs: The "rs" parameter contains a positive decimal integer that 262 describes the record size in octets. This value MUST be greater 263 than 1. If the "rs" parameter is absent, the record size defaults 264 to 4096 octets. 266 3.2. Content Encryption Key Derivation 268 In order to allow the reuse of keying material for multiple different 269 HTTP messages, a content encryption key is derived for each message. 270 The content encryption key is derived from the decoded value of the 271 "salt" parameter using the HMAC-based key derivation function (HKDF) 272 described in [RFC5869] using the SHA-256 hash algorithm [FIPS180-2]. 274 The decoded value of the "salt" parameter is the salt input to HKDF 275 function. The keying material identified by the "keyid" parameter is 276 the input keying material (IKM) to HKDF. Input keying material can 277 either be prearranged, or can be described using the Encryption-Key 278 header field (Section 4). The first step of HKDF is therefore: 280 PRK = HMAC-SHA-256(salt, IKM) 282 AEAD_AES_128_GCM requires a 16 octet (128 bit) content encryption 283 key, so the length (L) parameter to HKDF is 16. The info parameter 284 is set to the ASCII-encoded string "Content-Encoding: aesgcm128". 285 The second step of HKDF can therefore be simplified to the first 16 286 octets of a single HMAC: 288 CEK = HMAC-SHA-256(PRK, "Content-Encoding: aesgcm128" || 0x01) 290 3.3. Nonce Derivation 292 The nonce input to AEAD_AES_128_GCM is constructed for each record. 293 The nonce for each record is a 12 octet (96 bit) value is produced 294 from the record sequence number and a value derived from the input 295 keying material. 297 The input keying material and salt values are input to HKDF with 298 different info and length parameters. The info parameter for the 299 nonce is the ASCII-encoded string "Content-Encoding: nonce" and the 300 length (L) parameter is 12 octets. 302 The result is combined with the record sequence number - using 303 exclusive or - to produce the nonce. The record sequence number 304 (SEQ) is a 96-bit unsigned integer in network byte order that starts 305 at zero. 307 Thus, the final nonce for each record is a 12 octet value: 309 NONCE = HMAC-SHA-256(PRK, "Content-Encoding: nonce" || 0x01) ^ SEQ 311 4. Encryption-Key Header Field 313 An Encryption-Key header field can be used to describe the input 314 keying material used in the Encryption header field. 316 The Encryption-Key header field uses the extended ABNF syntax defined 317 in Section 1.2 of [RFC7230] and the "parameter" rule from [RFC7231]. 319 Encryption-Key-val = #encryption_key_params 320 encryption_key_params = [ parameter *( ";" parameter ) ] 322 keyid: The "keyid" parameter corresponds to the "keyid" parameter in 323 the Encryption header field. 325 aesgcm128: The "aesgcm128" parameter contains the URL-safe base64 326 [RFC4648] octets of the input keying material. 328 dh: The "dh" parameter contains an ephemeral Diffie-Hellman share. 329 This form of the header field can be used to encrypt content for a 330 specific recipient. 332 The input keying material used by the content-encoding key derivation 333 (see Section 3.2) can be determined based on the information in the 334 Encryption-Key header field. The method for key derivation depends 335 on the parameters that are present in the header field. 337 The value or values provided in the Encryption-Key header field is 338 valid only for the current HTTP message unless additional information 339 indicates a greater scope. 341 Note that different methods for determining input keying material 342 will produce different amounts of data. The HKDF process ensures 343 that the final content encryption key is the necessary size. 345 Alternative methods for determining input keying material MAY be 346 defined by specifications that use this content-encoding. 348 4.1. Explicit Key 350 The "aesgcm128" parameter is decoded and used as the input keying 351 material for the "aesgcm128" content encoding. The "aesgcm128" 352 parameter MUST decode to at least 16 octets in order to be used as 353 input keying material for "aesgcm128" content encoding. 355 Other key determination parameters can be ignored if the "aesgcm128" 356 parameter is present. 358 4.2. Diffie-Hellman 360 The "dh" parameter is included to describe a Diffie-Hellman share, 361 either modp (or finite field) Diffie-Hellman [DH] or elliptic curve 362 Diffie-Hellman (ECDH) [RFC4492]. 364 This share is combined with other information at the recipient to 365 determine the HKDF input keying material. In order for the exchange 366 to be successful, the following information MUST be established out 367 of band: 369 o Which Diffie-Hellman form is used. 371 o The modp group or elliptic curve that will be used. 373 o The format of the ephemeral public share that is included in the 374 "dh" parameter. For instance, using ECDH both parties need to 375 agree whether this is an uncompressed or compressed point. 377 In addition to identifying which content-encoding this input keying 378 material is used for, the "keyid" parameter is used to identify this 379 additional information at the receiver. 381 The intended recipient recovers their private key and are then able 382 to generate a shared secret using the appropriate Diffie-Hellman 383 process. 385 Specifications that rely on an Diffie-Hellman exchange for 386 determining input keying material MUST either specify the parameters 387 for Diffie-Hellman (group parameters, or curves and point format) 388 that are used, or describe how those parameters are negotiated 389 between sender and receiver. 391 5. Examples 393 5.1. Successful GET Response 395 HTTP/1.1 200 OK 396 Content-Type: application/octet-stream 397 Content-Encoding: aesgcm128 398 Connection: close 399 Encryption: keyid="http://example.org/bob/keys/123"; 400 salt="XZwpw6o37R-6qoZjw6KwAw" 402 [encrypted payload] 404 Here, a successful HTTP GET response has been encrypted using input 405 keying material that is identified by a URI. 407 Note that the media type has been changed to "application/octet- 408 stream" to avoid exposing information about the content. 410 5.2. Encryption and Compression 412 HTTP/1.1 200 OK 413 Content-Type: text/html 414 Content-Encoding: aesgcm128, gzip 415 Transfer-Encoding: chunked 416 Encryption: keyid="mailto:me@example.com"; 417 salt="m2hJ_NttRtFyUiMRPwfpHA" 419 [encrypted payload] 421 5.3. Encryption with More Than One Key 422 PUT /thing HTTP/1.1 423 Host: storage.example.com 424 Content-Type: application/http 425 Content-Encoding: aesgcm128, aesgcm128 426 Content-Length: 1234 427 Encryption: keyid="mailto:me@example.com"; 428 salt="NfzOeuV5USPRA-n_9s1Lag", 429 keyid="http://example.org/bob/keys/123"; 430 salt="bDMSGoc2uobK_IhavSHsHA"; rs=1200 432 [encrypted payload] 434 Here, a PUT request has been encrypted twice with different input 435 keying material; decrypting twice is necessary to read the content. 436 The outer layer of encryption uses a 1200 octet record size. 438 5.4. Encryption with Explicit Key 440 HTTP/1.1 200 OK 441 Content-Length: 32 442 Content-Encoding: aesgcm128 443 Encryption: keyid="a1"; salt="ibZx1RNz537h1XNkRcPpjA" 444 Encryption-Key: keyid="a1"; aesgcm128="9Z57YCb3dK95dSsdFJbkag" 446 zK3kpG__Z8whjIkG6RYgPz11oUkTKcxPy9WP-VPMfuc 448 This example shows the string "I am the walrus" encrypted using an 449 directly provided value for the input keying material. The content 450 body contains a single record only and is shown here encoded in URL- 451 safe base64 for presentation reasons only. 453 5.5. Diffie-Hellman Encryption 455 HTTP/1.1 200 OK 456 Content-Length: 32 457 Content-Encoding: aesgcm128 458 Encryption: keyid="dhkey"; salt="5hpuYfxDzG6nSs9-EQuaBg" 459 Encryption-Key: keyid="dhkey"; 460 dh="BLsyIPbDn6bquEOwHaju2gj8kUVoflzTtPs_6fGoock_ 461 dwxi1BcgFtObPVnic4alcEucx8I6G8HmEZCJnAl36Zg" 463 BmuHqRzdD4W1mibxglrPiRHZRSY49Dzdm6jHrWXzZrE 465 This example shows the same string, "I am the walrus", encrypted 466 using ECDH over the P-256 curve [FIPS186]. The content body is shown 467 here encoded in URL-safe base64 for presentation reasons only. 469 The receiver (in this case, the HTTP client) uses a key pair that is 470 identified by the string "dhkey" and the sender (the server) uses a 471 key pair for which the public share is included in the "dh" parameter 472 above. The keys shown below use uncompressed points [X.692] encoded 473 using URL-safe base64. Line wrapping is added for presentation 474 purposes only. 476 Receiver: 477 private key: iCjNf8v4ox_g1rJuSs_gbNmYuUYx76ZRruQs_CHRzDg 478 public key: BPM1w41cSD4BMeBTY0Fz9ryLM-LeM22Dvt0gaLRukf05 479 rMhzFAvxVW_mipg5O0hkWad9ZWW0uMRO2Nrd32v8odQ 480 Sender: 481 private key: W0cxgeHDZkR3uMQYAbVgF5swKQUAR7DgoTaaQVlA-Fg 482 public key: 484 6. Security Considerations 486 This mechanism assumes the presence of a key management framework 487 that is used to manage the distribution of keys between valid senders 488 and receivers. Defining key management is part of composing this 489 mechanism into a larger application, protocol, or framework. 491 Implementation of cryptography - and key management in particular - 492 can be difficult. For instance, implementations need to account for 493 the potential for exposing keying material on side channels, such as 494 might be exposed by the time it takes to perform a given operation. 495 The requirements for a good implementation of cryptographic 496 algorithms can change over time. 498 6.1. Key and Nonce Reuse 500 Encrypting different plaintext with the same content encryption key 501 and nonce in AES-GCM is not safe [RFC5116]. The scheme defined here 502 uses a fixed progression of nonce values. Thus, a new content 503 encryption key is needed for every application of the content 504 encoding. Since input keying material can be reused, a unique "salt" 505 parameter is needed to ensure a content encryption key is not reused. 507 If a content encryption key is reused - that is, if input keying 508 material and salt are reused - this could expose the plaintext and 509 the authentication key, nullifying the protection offered by 510 encryption. Thus, if the same input keying material is reused, then 511 the salt parameter MUST be unique each time. This ensures that the 512 content encryption key is not reused. An implementation SHOULD 513 generate a random salt parameter for every message; a counter could 514 achieve the same result. 516 6.2. Content Integrity 518 This mechanism only provides content origin authentication. The 519 authentication tag only ensures that an entity with access to the 520 content encryption key produced the encrypted data. 522 Any entity with the content encryption key can therefore produce 523 content that will be accepted as valid. This includes all recipients 524 of the same HTTP message. 526 Furthermore, any entity that is able to modify both the Encryption 527 header field and the HTTP message body can replace the contents. 528 Without the content encryption key or the input keying material, 529 modifications to or replacement of parts of a payload body are not 530 possible. 532 6.3. Leaking Information in Headers 534 Because only the payload body is encrypted, information exposed in 535 header fields is visible to anyone who can read the HTTP message. 536 This could expose side-channel information. 538 For example, the Content-Type header field can leak information about 539 the payload body. 541 There are a number of strategies available to mitigate this threat, 542 depending upon the application's threat model and the users' 543 tolerance for leaked information: 545 1. Determine that it is not an issue. For example, if it is 546 expected that all content stored will be "application/json", or 547 another very common media type, exposing the Content-Type header 548 field could be an acceptable risk. 550 2. If it is considered sensitive information and it is possible to 551 determine it through other means (e.g., out of band, using hints 552 in other representations, etc.), omit the relevant headers, and/ 553 or normalize them. In the case of Content-Type, this could be 554 accomplished by always sending Content-Type: application/octet- 555 stream (the most generic media type), or no Content-Type at all. 557 3. If it is considered sensitive information and it is not possible 558 to convey it elsewhere, encapsulate the HTTP message using the 559 application/http media type (Section 8.3.2 of [RFC7230]), 560 encrypting that as the payload of the "outer" message. 562 6.4. Poisoning Storage 564 This mechanism only offers encryption of content; it does not perform 565 authentication or authorization, which still needs to be performed 566 (e.g., by HTTP authentication [RFC7235]). 568 This is especially relevant when a HTTP PUT request is accepted by a 569 server; if the request is unauthenticated, it becomes possible for a 570 third party to deny service and/or poison the store. 572 6.5. Sizing and Timing Attacks 574 Applications using this mechanism need to be aware that the size of 575 encrypted messages, as well as their timing, HTTP methods, URIs and 576 so on, may leak sensitive information. 578 This risk can be mitigated through the use of the padding that this 579 mechanism provides. Alternatively, splitting up content into 580 segments and storing the separately might reduce exposure. HTTP/2 581 [RFC7540] combined with TLS [RFC5246] might be used to hide the size 582 of individual messages. 584 7. IANA Considerations 586 7.1. The "aesgcm128" HTTP Content Encoding 588 This memo registers the "encrypted" HTTP content-coding in the HTTP 589 Content Codings Registry, as detailed in Section 2. 591 o Name: aesgcm128 593 o Description: AES-GCM encryption with a 128-bit content encryption 594 key 596 o Reference: this specification 598 7.2. Encryption Header Fields 600 This memo registers the "Encryption" HTTP header field in the 601 Permanent Message Header Registry, as detailed in Section 3. 603 o Field name: Encryption 605 o Protocol: HTTP 607 o Status: Standard 609 o Reference: this specification 610 o Notes: 612 This memo registers the "Encryption-Key" HTTP header field in the 613 Permanent Message Header Registry, as detailed in Section 4. 615 o Field name: Encryption-Key 617 o Protocol: HTTP 619 o Status: Standard 621 o Reference: this specification 623 o Notes: 625 7.3. The HTTP Encryption Parameter Registry 627 This memo establishes a registry for parameters used by the 628 "Encryption" header field under the "Hypertext Transfer Protocol 629 (HTTP) Parameters" grouping. The "Hypertext Transfer Protocol (HTTP) 630 Encryption Parameters" operates under an "Specification Required" 631 policy [RFC5226]. 633 Entries in this registry are expected to include the following 634 information: 636 o Parameter Name: The name of the parameter. 638 o Purpose: A brief description of the purpose of the parameter. 640 o Reference: A reference to a specification that defines the 641 semantics of the parameter. 643 The initial contents of this registry are: 645 7.3.1. keyid 647 o Parameter Name: keyid 649 o Purpose: Identify the key that is in use. 651 o Reference: this document 653 7.3.2. salt 655 o Parameter Name: salt 656 o Purpose: Provide a source of entropy for derivation of a content 657 encryption key. This value is mandatory. 659 o Reference: this document 661 7.3.3. rs 663 o Parameter Name: rs 665 o Purpose: The size of the encrypted records. 667 o Reference: this document 669 7.4. The HTTP Encryption-Key Parameter Registry 671 This memo establishes a registry for parameters used by the 672 "Encryption-Key" header field under the "Hypertext Transfer Protocol 673 (HTTP) Parameters" grouping. The "Hypertext Transfer Protocol (HTTP) 674 Encryption Parameters" operates under an "Specification Required" 675 policy [RFC5226]. 677 Entries in this registry are expected to include the following 678 information: 680 o Parameter Name: The name of the parameter. 682 o Purpose: A brief description of the purpose of the parameter. 684 o Reference: A reference to a specification that defines the 685 semantics of the parameter. 687 The initial contents of this registry are: 689 7.4.1. keyid 691 o Parameter Name: keyid 693 o Purpose: Identify the key that is in use. 695 o Reference: this document 697 7.4.2. aesgcm128 699 o Parameter Name: aesgcm128 701 o Purpose: Provide an explicit input keying material value for the 702 aesgcm128 content encoding. 704 o Reference: this document 706 7.4.3. dh 708 o Parameter Name: dh 710 o Purpose: Carry a modp or elliptic curve Diffie-Hellman share used 711 to derive input keying material. 713 o Reference: this document 715 8. References 717 8.1. Normative References 719 [DH] Diffie, W. and M. Hellman, "New Directions in 720 Cryptography", IEEE Transactions on Information Theory, 721 V.IT-22 n.6 , June 1977. 723 [FIPS180-2] 724 Department of Commerce, National., "NIST FIPS 180-2, 725 Secure Hash Standard", August 2002. 727 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 728 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 729 RFC2119, March 1997, 730 . 732 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 733 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 734 for Transport Layer Security (TLS)", RFC 4492, DOI 735 10.17487/RFC4492, May 2006, 736 . 738 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 739 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 740 . 742 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 743 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 744 . 746 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 747 Key Derivation Function (HKDF)", RFC 5869, DOI 10.17487/ 748 RFC5869, May 2010, 749 . 751 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 752 Protocol (HTTP/1.1): Message Syntax and Routing", RFC 753 7230, DOI 10.17487/RFC7230, June 2014, 754 . 756 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 757 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 758 10.17487/RFC7231, June 2014, 759 . 761 8.2. Informative References 763 [FIPS186] National Institute of Standards and Technology (NIST), 764 "Digital Signature Standard (DSS)", NIST PUB 186-4 , July 765 2013. 767 [RFC4880] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R. 768 Thayer, "OpenPGP Message Format", RFC 4880, DOI 10.17487/ 769 RFC4880, November 2007, 770 . 772 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 773 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 774 DOI 10.17487/RFC5226, May 2008, 775 . 777 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 778 (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ 779 RFC5246, August 2008, 780 . 782 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 783 RFC 5652, DOI 10.17487/RFC5652, September 2009, 784 . 786 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 787 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 788 RFC 7233, DOI 10.17487/RFC7233, June 2014, 789 . 791 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 792 Protocol (HTTP/1.1): Authentication", RFC 7235, DOI 793 10.17487/RFC7235, June 2014, 794 . 796 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 797 RFC 7516, DOI 10.17487/RFC7516, May 2015, 798 . 800 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 801 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 802 10.17487/RFC7540, May 2015, 803 . 805 [X.692] ANSI, "Public Key Cryptography For The Financial Services 806 Industry: The Elliptic Curve Digital Signature Algorithm 807 (ECDSA)", ANSI X9.62 , 1998. 809 [XMLENC] Eastlake, D., Reagle, J., Imamura, T., Dillaway, B., and 810 E. Simon, "XML Encryption Syntax and Processing", W3C REC 811 , December 2002, . 813 Appendix A. JWE Mapping 815 The "aesgcm128" content encoding can be considered as a sequence of 816 JSON Web Encryption (JWE) objects [RFC7516], each corresponding to a 817 single fixed size record. The following transformations are applied 818 to a JWE object that might be expressed using the JWE Compact 819 Serialization: 821 o The JWE Protected Header is fixed to a value { "alg": "dir", 822 "enc": "A128GCM" }, describing direct encryption using AES-GCM 823 with a 128-bit content encryption key. This header is not 824 transmitted, it is instead implied by the value of the Content- 825 Encoding header field. 827 o The JWE Encrypted Key is empty, as stipulated by the direct 828 encryption algorithm. 830 o The JWE Initialization Vector ("iv") for each record is set to the 831 exclusive or of the 96-bit record sequence number, starting at 832 zero, and a value derived from the input keying material (see 833 Section 3.3). This value is also not transmitted. 835 o The final value is the concatenated JWE Ciphertext and the JWE 836 Authentication Tag, both expressed without URL-safe Base 64 837 encoding. The "." separator is omitted, since the length of these 838 fields is known. 840 Thus, the example in Section 5.4 can be rendered using the JWE 841 Compact Serialization as: 843 eyAiYWxnIjogImRpciIsICJlbmMiOiAiQTEyOEdDTSIgfQ..AAAAAAAAAAAAAAAA. 844 LwTC-fwdKh8de0smD2jfzA.eh1vURhu65M2lxhctbbntA 846 Where the first line represents the fixed JWE Protected Header, JWE 847 Encrypted Key, and JWE Initialization Vector, all of which are 848 determined algorithmically. The second line contains the encoded 849 body, split into JWE Ciphertext and JWE Authentication Tag. 851 Appendix B. Acknowledgements 853 Mark Nottingham was an original author of this document. 855 The following people provided valuable input: Richard Barnes, David 856 Benjamin, Peter Beverloo, Mike Jones, Stephen Farrell, Adam Langley, 857 John Mattsson, Eric Rescorla, and Jim Schaad. 859 Author's Address 861 Martin Thomson 862 Mozilla 864 Email: martin.thomson@gmail.com