idnits 2.17.1 draft-ietf-httpbis-encryption-encoding-03.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 9, 2016) is 2756 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. 'FIPS180-4' ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** 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 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 (==), 6 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 October 9, 2016 5 Expires: April 12, 2017 7 Encrypted Content-Encoding for HTTP 8 draft-ietf-httpbis-encryption-encoding-03 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 April 12, 2017. 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 . . . . . . . . . . . . . . . . . 3 61 2. The "aesgcm" HTTP Content Coding . . . . . . . . . . . . . . 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 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 5.1. Encryption of a Response . . . . . . . . . . . . . . . . 9 69 5.2. Encryption with Multiple Records . . . . . . . . . . . . 10 70 5.3. Encryption and Compression . . . . . . . . . . . . . . . 10 71 5.4. Encryption with More Than One Key . . . . . . . . . . . . 11 72 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 73 6.1. Key and Nonce Reuse . . . . . . . . . . . . . . . . . . . 11 74 6.2. Data Encryption Limits . . . . . . . . . . . . . . . . . 12 75 6.3. Content Integrity . . . . . . . . . . . . . . . . . . . . 12 76 6.4. Leaking Information in Headers . . . . . . . . . . . . . 12 77 6.5. Poisoning Storage . . . . . . . . . . . . . . . . . . . . 13 78 6.6. Sizing and Timing Attacks . . . . . . . . . . . . . . . . 13 79 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 80 7.1. The "aesgcm" HTTP Content Coding . . . . . . . . . . . . 13 81 7.2. Encryption Header Fields . . . . . . . . . . . . . . . . 14 82 7.3. The HTTP Encryption Parameter Registry . . . . . . . . . 14 83 7.3.1. keyid . . . . . . . . . . . . . . . . . . . . . . . . 15 84 7.3.2. salt . . . . . . . . . . . . . . . . . . . . . . . . 15 85 7.3.3. rs . . . . . . . . . . . . . . . . . . . . . . . . . 15 86 7.4. The HTTP Crypto-Key Parameter Registry . . . . . . . . . 15 87 7.4.1. keyid . . . . . . . . . . . . . . . . . . . . . . . . 16 88 7.4.2. aesgcm . . . . . . . . . . . . . . . . . . . . . . . 16 89 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 90 8.1. Normative References . . . . . . . . . . . . . . . . . . 16 91 8.2. Informative References . . . . . . . . . . . . . . . . . 17 92 Appendix A. JWE Mapping . . . . . . . . . . . . . . . . . . . . 18 93 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 19 94 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19 96 1. Introduction 98 It is sometimes desirable to encrypt the contents of a HTTP message 99 (request or response) so that when the payload is stored (e.g., with 100 a HTTP PUT), only someone with the appropriate key can read it. 102 For example, it might be necessary to store a file on a server 103 without exposing its contents to that server. Furthermore, that same 104 file could be replicated to other servers (to make it more resistant 105 to server or network failure), downloaded by clients (to make it 106 available offline), etc. without exposing its contents. 108 These uses are not met by the use of TLS [RFC5246], since it only 109 encrypts the channel between the client and server. 111 This document specifies a content coding (Section 3.1.2 of [RFC7231]) 112 for HTTP to serve these and other use cases. 114 This content coding is not a direct adaptation of message-based 115 encryption formats - such as those that are described by [RFC4880], 116 [RFC5652], [RFC7516], and [XMLENC] - which are not suited to stream 117 processing, which is necessary for HTTP. The format described here 118 cleaves more closely to the lower level constructs described in 119 [RFC5116]. 121 To the extent that message-based encryption formats use the same 122 primitives, the format can be considered as sequence of encrypted 123 messages with a particular profile. For instance, Appendix A 124 explains how the format is congruent with a sequence of JSON Web 125 Encryption [RFC7516] values with a fixed header. 127 This mechanism is likely only a small part of a larger design that 128 uses content encryption. How clients and servers acquire and 129 identify keys will depend on the use case. Though a complete key 130 management system is not described, this document defines an Crypto- 131 Key header field that can be used to convey keying material. 133 1.1. Notational Conventions 135 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 136 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 137 document are to be interpreted as described in [RFC2119]. 139 Base64url encoding is defined in Section 2 of [RFC7515]. 141 2. The "aesgcm" HTTP Content Coding 143 The "aesgcm" HTTP content coding indicates that a payload has been 144 encrypted using Advanced Encryption Standard (AES) in Galois/Counter 145 Mode (GCM) as identified as AEAD_AES_128_GCM in [RFC5116], 146 Section 5.1. The AEAD_AES_128_GCM algorithm uses a 128 bit content 147 encryption key. 149 When this content coding is in use, the Encryption header field 150 (Section 3) describes how encryption has been applied. The Crypto- 151 Key header field (Section 4) can be included to describe how the 152 content encryption key is derived or retrieved. 154 The "aesgcm" content coding uses a single fixed set of encryption 155 primitives. Cipher suite agility is achieved by defining a new 156 content coding scheme. This ensures that only the HTTP Accept- 157 Encoding header field is necessary to negotiate the use of 158 encryption. 160 The "aesgcm" content coding uses a fixed record size. The resulting 161 encoding is either a single record, or a series of fixed-size 162 records. The final record, or a lone record, MUST be shorter than 163 the fixed record size. 165 +-----------+ content is rs octets minus padding 166 | data | of between 2 and 65537 octets; 167 +-----------+ the last record is smaller 168 | 169 v 170 +-----+-----------+ add padding to get rs octets; 171 | pad | data | the last record contains 172 +-----+-----------+ up to rs minus 1 octets 173 | 174 v 175 +--------------------+ encrypt with AEAD_AES_128_GCM; 176 | ciphertext | final size is rs plus 16 octets 177 +--------------------+ the last record is smaller 179 The record size determines the length of each portion of plaintext 180 that is enciphered, with the exception of the final record, which is 181 necessarily smaller. The record size defaults to 4096 octets, but 182 can be changed using the "rs" parameter on the Encryption header 183 field. 185 AEAD_AES_128_GCM produces ciphertext 16 octets longer than its input 186 plaintext. Therefore, the length of each enciphered record other 187 than the last is equal to the value of the "rs" parameter plus 16 188 octets. A receiver MUST fail to decrypt if the final record 189 ciphertext is less than 18 octets in size. Valid records always 190 contain at least two octets of padding and a 16 octet authentication 191 tag. 193 Each record contains between 2 and 65537 octets of padding, inserted 194 into a record before the enciphered content. Padding consists of a 195 two octet unsigned integer in network byte order, followed that 196 number of zero-valued octets. A receiver MUST fail to decrypt if any 197 padding octet other than the first two are non-zero, or a record has 198 more padding than the record size can accommodate. 200 The nonce for each record is a 96-bit value constructed from the 201 record sequence number and the input keying material. Nonce 202 derivation is covered in Section 3.3. 204 The additional data passed to each invocation of AEAD_AES_128_GCM is 205 a zero-length octet sequence. 207 A sequence of full-sized records can be truncated to produce a 208 shorter sequence of records with valid authentication tags. To 209 prevent an attacker from truncating a stream, an encoder MUST append 210 a record that contains only padding and is smaller than the full 211 record size if the final record ends on a record boundary. A 212 receiver MUST treat the stream as failed due to truncation if the 213 final record is the full record size. 215 A consequence of this record structure is that range requests 216 [RFC7233] and random access to encrypted payload bodies are possible 217 at the granularity of the record size. However, without data from 218 adjacent ranges, partial records cannot be used. Thus, it is best if 219 range requests start and end on multiples of the record size, plus 220 the 16 octet authentication tag size. 222 Selecting the record size most appropriate for a given situation 223 requires a trade-off. A smaller record size allows decrypted octets 224 to be released more rapidly, which can be appropriate for 225 applications that depend on responsiveness. Smaller records also 226 reduce the additional data required if random access into the 227 ciphertext is needed. Applications that depend on being able to pad 228 by arbitrary amounts cannot increase the record size beyond 65537 229 octets. 231 Applications that don't depending on streaming, random access, or 232 arbitrary padding can use larger records, or even a single record. A 233 larger record size reduces the processing and data overheads. 235 3. The Encryption HTTP Header Field 237 The "Encryption" HTTP header field describes the encrypted content 238 coding(s) that have been applied to a payload body, and therefore how 239 those content coding(s) can be removed. 241 The "Encryption" header field uses the extended ABNF syntax defined 242 in Section 1.2 of [RFC7230] and the "parameter" and "OWS" rules from 243 [RFC7231]. 245 Encryption = #encryption_params 246 encryption_params = [ parameter *( OWS ";" OWS parameter ) ] 248 If the payload is encrypted more than once (as reflected by having 249 multiple content codings that imply encryption), each application of 250 the content coding is reflected in a separate Encryption header field 251 value in the order in which they were applied. 253 Encryption header field values with multiple instances of the same 254 parameter name are invalid. 256 Servers processing PUT requests MUST persist the value of the 257 Encryption header field, unless they remove the content coding by 258 decrypting the payload. 260 3.1. Encryption Header Field Parameters 262 The following parameters are used in determining the content 263 encryption key that is used for encryption: 265 keyid: The "keyid" parameter identifies the keying material that is 266 used. When the Crypto-Key header field is used, the "keyid" 267 identifies a matching value in that field. The "keyid" parameter 268 MUST be used if keying material included in an Crypto-Key header 269 field is needed to derive the content encryption key. The "keyid" 270 parameter can also be used to identify keys in an application- 271 specific fashion. 273 salt: The "salt" parameter contains a base64url-encoded octets 274 [RFC7515] that is used as salt in deriving a unique content 275 encryption key (see Section 3.2). The "salt" parameter MUST be 276 present, and MUST be exactly 16 octets long when decoded. The 277 "salt" parameter MUST NOT be reused for two different payload 278 bodies that have the same input keying material; generating a 279 random salt for every application of the content coding ensures 280 that content encryption key reuse is highly unlikely. 282 rs: The "rs" parameter contains a positive decimal integer that 283 describes the record size in octets. This value MUST be greater 284 than 1. For the "aesgcm" content coding, this value MUST NOT be 285 greater than 2^36-31 (see Section 6.2). The "rs" parameter is 286 optional. If the "rs" parameter is absent, the record size 287 defaults to 4096 octets. 289 3.2. Content Encryption Key Derivation 291 In order to allow the reuse of keying material for multiple different 292 HTTP messages, a content encryption key is derived for each message. 293 The content encryption key is derived from the decoded value of the 294 "salt" parameter using the HMAC-based key derivation function (HKDF) 295 described in [RFC5869] using the SHA-256 hash algorithm [FIPS180-4]. 297 The decoded value of the "salt" parameter is the salt input to HKDF 298 function. The keying material identified by the "keyid" parameter is 299 the input keying material (IKM) to HKDF. Input keying material can 300 either be prearranged, or can be described using the Crypto-Key 301 header field (Section 4). The extract phase of HKDF therefore 302 produces a pseudorandom key (PRK) as follows: 304 PRK = HMAC-SHA-256(salt, IKM) 306 The info parameter to HKDF is set to the ASCII-encoded string 307 "Content-Encoding: aesgcm", a single zero octet and an optional 308 context string: 310 cek_info = "Content-Encoding: aesgcm" || 0x00 || context 312 Unless otherwise specified, the context is a zero length octet 313 sequence. Specifications that use this content coding MAY specify 314 the use of an expanded context to cover additional inputs in the key 315 derivation. 317 AEAD_AES_128_GCM requires a 16 octet (128 bit) content encryption key 318 (CEK), so the length (L) parameter to HKDF is 16. The second step of 319 HKDF can therefore be simplified to the first 16 octets of a single 320 HMAC: 322 CEK = HMAC-SHA-256(PRK, cek_info || 0x01) 324 3.3. Nonce Derivation 326 The nonce input to AEAD_AES_128_GCM is constructed for each record. 327 The nonce for each record is a 12 octet (96 bit) value is produced 328 from the record sequence number and a value derived from the input 329 keying material. 331 The input keying material and salt values are input to HKDF with 332 different info and length parameters. 334 The length (L) parameter is 12 octets. The info parameter for the 335 nonce is the ASCII-encoded string "Content-Encoding: nonce", a single 336 zero octet and an context: 338 nonce_info = "Content-Encoding: nonce" || 0x00 || context 340 The context for nonce derivation is the same as is used for content 341 encryption key derivation. 343 The result is combined with the record sequence number - using 344 exclusive or - to produce the nonce. The record sequence number 345 (SEQ) is a 96-bit unsigned integer in network byte order that starts 346 at zero. 348 Thus, the final nonce for each record is a 12 octet value: 350 NONCE = HMAC-SHA-256(PRK, nonce_info || 0x01) XOR SEQ 352 This nonce construction prevents removal or reordering of records. 353 However, it permits truncation of the tail of the sequence (see 354 Section 2 for how this is avoided). 356 4. Crypto-Key Header Field 358 A Crypto-Key header field can be used to describe the input keying 359 material used in the Encryption header field. 361 The Crypto-Key header field uses the extended ABNF syntax defined in 362 Section 1.2 of [RFC7230] and the "parameter" and "OWS" rules from 363 [RFC7231]. 365 Crypto-Key = #crypto_key_params 366 crypto_key_params = [ parameter *( OWS ";" OWS parameter ) ] 368 keyid: The "keyid" parameter corresponds to the "keyid" parameter in 369 the Encryption header field. 371 aesgcm: The "aesgcm" parameter contains the base64url-encoded octets 372 [RFC7515] of the input keying material for the "aesgcm" content 373 coding. 375 Crypto-Key header field values with multiple instances of the same 376 parameter name are invalid. 378 The input keying material used by the key derivation (see 379 Section 3.2) can be determined based on the information in the 380 Crypto-Key header field. 382 The value or values provided in the Crypto-Key header field is valid 383 only for the current HTTP message unless additional information 384 indicates a greater scope. 386 Alternative methods for determining input keying material MAY be 387 defined by specifications that use this content coding. This 388 document only defines the use of the "aesgcm" parameter which 389 describes an explicit key. 391 The "aesgcm" parameter MUST decode to at least 16 octets in order to 392 be used as input keying material for "aesgcm" content coding. 394 5. Examples 396 This section shows a few examples of the encrypted content coding. 398 Note: All binary values in the examples in this section use base64url 399 encoding [RFC7515]. This includes the bodies of requests. 400 Whitespace and line wrapping is added to fit formatting constraints. 402 5.1. Encryption of a Response 404 Here, a successful HTTP GET response has been encrypted using input 405 keying material that is identified by a URI. 407 The encrypted data in this example is the UTF-8 encoded string "I am 408 the walrus". The input keying material is included in the Crypto-Key 409 header field. The content body contains a single record only and is 410 shown here using base64url encoding for presentation reasons. 412 HTTP/1.1 200 OK 413 Content-Type: application/octet-stream 414 Content-Length: 33 415 Content-Encoding: aesgcm 416 Encryption: keyid="a1"; salt="vr0o6Uq3w_KDWeatc27mUg" 417 Crypto-Key: keyid="a1"; aesgcm="csPJEXBYA5U-Tal9EdJi-w" 419 VDeU0XxaJkOJDAxPl7h9JD5V8N43RorP7PfpPdZZQuwF 421 Note that the media type has been changed to "application/octet- 422 stream" to avoid exposing information about the content. 424 5.2. Encryption with Multiple Records 426 This example shows the same encrypted message, but split into records 427 of 10 octets each. The first record includes a single additional 428 octet of padding, which causes the end of the content to align with a 429 record boundary, forcing the creation of a third record that contains 430 only padding. 432 HTTP/1.1 200 OK 433 Content-Length: 70 434 Content-Encoding: aesgcm 435 Encryption: keyid="a1"; salt="4pdat984KmT9BWsU3np0nw"; rs=10 436 Crypto-Key: keyid="a1"; aesgcm="BO3ZVPxUlnLORbVGMpbT1Q" 438 uzLfrZ4cbMTC6hlUqHz4NvWZshFlTN3o2RLr6FrIuOKEfl2VrM_jYgoiIyEo 439 Zvc-ZGwV-RMJejG4M6ZfGysBAdhpPqrLzw 441 5.3. Encryption and Compression 443 In this example, a response is first compressed, then encrypted. 444 Note that this particular encoding might compromise confidentiality 445 if the contents could be influenced by an attacker. 447 HTTP/1.1 200 OK 448 Content-Type: text/html 449 Content-Encoding: gzip, aesgcm 450 Transfer-Encoding: chunked 451 Encryption: keyid="me@example.com"; 452 salt="m2hJ_NttRtFyUiMRPwfpHA" 454 [encrypted payload] 456 5.4. Encryption with More Than One Key 458 Here, a PUT request has been encrypted twice with different input 459 keying material; decrypting twice is necessary to read the content. 460 The outer layer of encryption uses a 1200 octet record size. 462 PUT /thing HTTP/1.1 463 Host: storage.example.com 464 Content-Type: application/http 465 Content-Encoding: aesgcm, aesgcm 466 Content-Length: 1235 467 Encryption: keyid="mailto:me@example.com"; 468 salt="NfzOeuV5USPRA-n_9s1Lag", 469 keyid="bob/keys/123"; 470 salt="bDMSGoc2uobK_IhavSHsHA"; rs=1200 472 [encrypted payload] 474 6. Security Considerations 476 This mechanism assumes the presence of a key management framework 477 that is used to manage the distribution of keys between valid senders 478 and receivers. Defining key management is part of composing this 479 mechanism into a larger application, protocol, or framework. 481 Implementation of cryptography - and key management in particular - 482 can be difficult. For instance, implementations need to account for 483 the potential for exposing keying material on side channels, such as 484 might be exposed by the time it takes to perform a given operation. 485 The requirements for a good implementation of cryptographic 486 algorithms can change over time. 488 6.1. Key and Nonce Reuse 490 Encrypting different plaintext with the same content encryption key 491 and nonce in AES-GCM is not safe [RFC5116]. The scheme defined here 492 uses a fixed progression of nonce values. Thus, a new content 493 encryption key is needed for every application of the content coding. 494 Since input keying material can be reused, a unique "salt" parameter 495 is needed to ensure a content encryption key is not reused. 497 If a content encryption key is reused - that is, if input keying 498 material and salt are reused - this could expose the plaintext and 499 the authentication key, nullifying the protection offered by 500 encryption. Thus, if the same input keying material is reused, then 501 the salt parameter MUST be unique each time. This ensures that the 502 content encryption key is not reused. An implementation SHOULD 503 generate a random salt parameter for every message; a counter could 504 achieve the same result. 506 6.2. Data Encryption Limits 508 There are limits to the data that AEAD_AES_128_GCM can encipher. The 509 maximum record size is 2^36-31 [RFC5116]. In order to preserve a 510 2^-40 probability of indistinguishability under chosen plaintext 511 attack (IND-CPA), the total amount of plaintext that can be 512 enciphered MUST be less than 2^44.5 blocks [AEBounds]. 514 If rs is a multiple of 16 octets, this means 398 terabytes can be 515 encrypted safely, including padding. However, if the record size is 516 a multiple of 16 octets, the total amount of data that can be safely 517 encrypted is reduced. The worst case is a record size of 3 octets, 518 for which at most 74 terabytes of plaintext can be encrypted, of 519 which at least two-thirds is padding. 521 6.3. Content Integrity 523 This mechanism only provides content origin authentication. The 524 authentication tag only ensures that an entity with access to the 525 content encryption key produced the encrypted data. 527 Any entity with the content encryption key can therefore produce 528 content that will be accepted as valid. This includes all recipients 529 of the same HTTP message. 531 Furthermore, any entity that is able to modify both the Encryption 532 header field and the HTTP message body can replace the contents. 533 Without the content encryption key or the input keying material, 534 modifications to or replacement of parts of a payload body are not 535 possible. 537 6.4. Leaking Information in Headers 539 Because only the payload body is encrypted, information exposed in 540 header fields is visible to anyone who can read the HTTP message. 541 This could expose side-channel information. 543 For example, the Content-Type header field can leak information about 544 the payload body. 546 There are a number of strategies available to mitigate this threat, 547 depending upon the application's threat model and the users' 548 tolerance for leaked information: 550 1. Determine that it is not an issue. For example, if it is 551 expected that all content stored will be "application/json", or 552 another very common media type, exposing the Content-Type header 553 field could be an acceptable risk. 555 2. If it is considered sensitive information and it is possible to 556 determine it through other means (e.g., out of band, using hints 557 in other representations, etc.), omit the relevant headers, and/ 558 or normalize them. In the case of Content-Type, this could be 559 accomplished by always sending Content-Type: application/octet- 560 stream (the most generic media type), or no Content-Type at all. 562 3. If it is considered sensitive information and it is not possible 563 to convey it elsewhere, encapsulate the HTTP message using the 564 application/http media type (Section 8.3.2 of [RFC7230]), 565 encrypting that as the payload of the "outer" message. 567 6.5. Poisoning Storage 569 This mechanism only offers encryption of content; it does not perform 570 authentication or authorization, which still needs to be performed 571 (e.g., by HTTP authentication [RFC7235]). 573 This is especially relevant when a HTTP PUT request is accepted by a 574 server; if the request is unauthenticated, it becomes possible for a 575 third party to deny service and/or poison the store. 577 6.6. Sizing and Timing Attacks 579 Applications using this mechanism need to be aware that the size of 580 encrypted messages, as well as their timing, HTTP methods, URIs and 581 so on, may leak sensitive information. 583 This risk can be mitigated through the use of the padding that this 584 mechanism provides. Alternatively, splitting up content into 585 segments and storing the separately might reduce exposure. HTTP/2 586 [RFC7540] combined with TLS [RFC5246] might be used to hide the size 587 of individual messages. 589 7. IANA Considerations 591 7.1. The "aesgcm" HTTP Content Coding 593 This memo registers the "aesgcm" HTTP content coding in the HTTP 594 Content Codings Registry, as detailed in Section 2. 596 o Name: aesgcm 597 o Description: AES-GCM encryption with a 128-bit content encryption 598 key 600 o Reference: this specification 602 7.2. Encryption Header Fields 604 This memo registers the "Encryption" HTTP header field in the 605 Permanent Message Header Registry, as detailed in Section 3. 607 o Field name: Encryption 609 o Protocol: HTTP 611 o Status: Standard 613 o Reference: this specification 615 o Notes: 617 This memo registers the "Crypto-Key" HTTP header field in the 618 Permanent Message Header Registry, as detailed in Section 4. 620 o Field name: Crypto-Key 622 o Protocol: HTTP 624 o Status: Standard 626 o Reference: this specification 628 o Notes: 630 7.3. The HTTP Encryption Parameter Registry 632 This memo establishes a registry for parameters used by the 633 "Encryption" header field under the "Hypertext Transfer Protocol 634 (HTTP) Parameters" grouping. The "Hypertext Transfer Protocol (HTTP) 635 Encryption Parameters" registry operates under an "Specification 636 Required" policy [RFC5226]. 638 Entries in this registry are expected to include the following 639 information: 641 o Parameter Name: The name of the parameter. 643 o Purpose: A brief description of the purpose of the parameter. 645 o Reference: A reference to a specification that defines the 646 semantics of the parameter. 648 The initial contents of this registry are: 650 7.3.1. keyid 652 o Parameter Name: keyid 654 o Purpose: Identify the key that is in use. 656 o Reference: this document 658 7.3.2. salt 660 o Parameter Name: salt 662 o Purpose: Provide a source of entropy for derivation of a content 663 encryption key. This value is mandatory. 665 o Reference: this document 667 7.3.3. rs 669 o Parameter Name: rs 671 o Purpose: The size of the encrypted records. 673 o Reference: this document 675 7.4. The HTTP Crypto-Key Parameter Registry 677 This memo establishes a registry for parameters used by the "Crypto- 678 Key" header field under the "Hypertext Transfer Protocol (HTTP) 679 Parameters" grouping. The "Hypertext Transfer Protocol (HTTP) 680 Crypto-Key Parameters" operates under an "Specification Required" 681 policy [RFC5226]. 683 Entries in this registry are expected to include the following 684 information: 686 o Parameter Name: The name of the parameter. 688 o Purpose: A brief description of the purpose of the parameter. 690 o Reference: A reference to a specification that defines the 691 semantics of the parameter. 693 The initial contents of this registry are: 695 7.4.1. keyid 697 o Parameter Name: keyid 699 o Purpose: Identify the key that is in use. 701 o Reference: this document 703 7.4.2. aesgcm 705 o Parameter Name: aesgcm 707 o Purpose: Provide an explicit input keying material value for the 708 aesgcm content coding. 710 o Reference: this document 712 8. References 714 8.1. Normative References 716 [FIPS180-4] 717 Department of Commerce, National., "NIST FIPS 180-4, 718 Secure Hash Standard", March 2012, 719 . 722 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 723 Requirement Levels", BCP 14, RFC 2119, 724 DOI 10.17487/RFC2119, March 1997, 725 . 727 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 728 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 729 . 731 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 732 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 733 DOI 10.17487/RFC5226, May 2008, 734 . 736 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 737 Key Derivation Function (HKDF)", RFC 5869, 738 DOI 10.17487/RFC5869, May 2010, 739 . 741 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 742 Protocol (HTTP/1.1): Message Syntax and Routing", 743 RFC 7230, DOI 10.17487/RFC7230, June 2014, 744 . 746 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 747 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 748 DOI 10.17487/RFC7231, June 2014, 749 . 751 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 752 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 753 2015, . 755 8.2. Informative References 757 [AEBounds] 758 Luykx, A. and K. Paterson, "Limits on Authenticated 759 Encryption Use in TLS", March 2016, 760 . 762 [RFC4880] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R. 763 Thayer, "OpenPGP Message Format", RFC 4880, 764 DOI 10.17487/RFC4880, November 2007, 765 . 767 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 768 (TLS) Protocol Version 1.2", RFC 5246, 769 DOI 10.17487/RFC5246, August 2008, 770 . 772 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 773 RFC 5652, DOI 10.17487/RFC5652, September 2009, 774 . 776 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 777 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 778 RFC 7233, DOI 10.17487/RFC7233, June 2014, 779 . 781 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 782 Protocol (HTTP/1.1): Authentication", RFC 7235, 783 DOI 10.17487/RFC7235, June 2014, 784 . 786 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 787 RFC 7516, DOI 10.17487/RFC7516, May 2015, 788 . 790 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 791 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 792 DOI 10.17487/RFC7540, May 2015, 793 . 795 [XMLENC] Eastlake, D., Reagle, J., Imamura, T., Dillaway, B., and 796 E. Simon, "XML Encryption Syntax and Processing", W3C 797 REC , December 2002, . 799 Appendix A. JWE Mapping 801 The "aesgcm" content coding can be considered as a sequence of JSON 802 Web Encryption (JWE) objects [RFC7516], each corresponding to a 803 single fixed size record that includes leading padding. The 804 following transformations are applied to a JWE object that might be 805 expressed using the JWE Compact Serialization: 807 o The JWE Protected Header is fixed to the value { "alg": "dir", 808 "enc": "A128GCM" }, describing direct encryption using AES-GCM 809 with a 128-bit content encryption key. This header is not 810 transmitted, it is instead implied by the value of the Content- 811 Encoding header field. 813 o The JWE Encrypted Key is empty, as stipulated by the direct 814 encryption algorithm. 816 o The JWE Initialization Vector ("iv") for each record is set to the 817 exclusive or of the 96-bit record sequence number, starting at 818 zero, and a value derived from the input keying material (see 819 Section 3.3). This value is also not transmitted. 821 o The final value is the concatenated JWE Ciphertext and the JWE 822 Authentication Tag, both expressed without base64url encoding. 823 The "." separator is omitted, since the length of these fields is 824 known. 826 Thus, the example in Section 5.1 can be rendered using the JWE 827 Compact Serialization as: 829 eyAiYWxnIjogImRpciIsICJlbmMiOiAiQTEyOEdDTSIgfQ..31iQYc1v4a36EgyJ. 830 VDeU0XxaJkOJDAxPl7h9JD4.VfDeN0aKz-z36T3WWULsBQ 832 Where the first line represents the fixed JWE Protected Header, an 833 empty JWE Encrypted Key, and the algorithmically-determined JWE 834 Initialization Vector. The second line contains the encoded body, 835 split into JWE Ciphertext and JWE Authentication Tag. 837 Appendix B. Acknowledgements 839 Mark Nottingham was an original author of this document. 841 The following people provided valuable input: Richard Barnes, David 842 Benjamin, Peter Beverloo, Mike Jones, Stephen Farrell, Adam Langley, 843 John Mattsson, Eric Rescorla, and Jim Schaad. 845 Author's Address 847 Martin Thomson 848 Mozilla 850 Email: martin.thomson@gmail.com