idnits 2.17.1 draft-ietf-httpbis-encryption-encoding-00.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 (December 22, 2015) is 3019 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 Network Working Group M. Thomson 3 Internet-Draft Mozilla 4 Intended status: Standards Track December 22, 2015 5 Expires: June 24, 2016 7 Encrypted Content-Encoding for HTTP 8 draft-ietf-httpbis-encryption-encoding-00 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 June 24, 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. Crypto-Key Header Field . . . . . . . . . . . . . . . . . . . 8 57 4.1. Explicit Key . . . . . . . . . . . . . . . . . . . . . . 8 58 4.2. Diffie-Hellman . . . . . . . . . . . . . . . . . . . . . 9 59 4.3. Pre-shared Authentication Secrets . . . . . . . . . . . . 10 60 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 11 61 5.1. Successful GET Response . . . . . . . . . . . . . . . . . 11 62 5.2. Encryption and Compression . . . . . . . . . . . . . . . 11 63 5.3. Encryption with More Than One Key . . . . . . . . . . . . 11 64 5.4. Encryption with Explicit Key . . . . . . . . . . . . . . 12 65 5.5. Diffie-Hellman Encryption . . . . . . . . . . . . . . . . 12 66 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 67 6.1. Key and Nonce Reuse . . . . . . . . . . . . . . . . . . . 13 68 6.2. Content Integrity . . . . . . . . . . . . . . . . . . . . 13 69 6.3. Leaking Information in Headers . . . . . . . . . . . . . 14 70 6.4. Poisoning Storage . . . . . . . . . . . . . . . . . . . . 14 71 6.5. Sizing and Timing Attacks . . . . . . . . . . . . . . . . 15 72 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 73 7.1. The "aesgcm128" HTTP Content Encoding . . . . . . . . . . 15 74 7.2. Encryption Header Fields . . . . . . . . . . . . . . . . 15 75 7.3. The HTTP Encryption Parameter Registry . . . . . . . . . 16 76 7.3.1. keyid . . . . . . . . . . . . . . . . . . . . . . . . 16 77 7.3.2. salt . . . . . . . . . . . . . . . . . . . . . . . . 16 78 7.3.3. rs . . . . . . . . . . . . . . . . . . . . . . . . . 17 79 7.4. The HTTP Crypto-Key Parameter Registry . . . . . . . . . 17 80 7.4.1. keyid . . . . . . . . . . . . . . . . . . . . . . . . 17 81 7.4.2. aesgcm128 . . . . . . . . . . . . . . . . . . . . . . 17 82 7.4.3. dh . . . . . . . . . . . . . . . . . . . . . . . . . 18 83 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 84 8.1. Normative References . . . . . . . . . . . . . . . . . . 18 85 8.2. Informative References . . . . . . . . . . . . . . . . . 19 86 Appendix A. JWE Mapping . . . . . . . . . . . . . . . . . . . . 20 87 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 21 88 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21 90 1. Introduction 92 It is sometimes desirable to encrypt the contents of a HTTP message 93 (request or response) so that when the payload is stored (e.g., with 94 a HTTP PUT), only someone with the appropriate key can read it. 96 For example, it might be necessary to store a file on a server 97 without exposing its contents to that server. Furthermore, that same 98 file could be replicated to other servers (to make it more resistant 99 to server or network failure), downloaded by clients (to make it 100 available offline), etc. without exposing its contents. 102 These uses are not met by the use of TLS [RFC5246], since it only 103 encrypts the channel between the client and server. 105 This document specifies a content-coding (Section 3.1.2 of [RFC7231]) 106 for HTTP to serve these and other use cases. 108 This content-coding is not a direct adaptation of message-based 109 encryption formats - such as those that are described by [RFC4880], 110 [RFC5652], [RFC7516], and [XMLENC] - which are not suited to stream 111 processing, which is necessary for HTTP. The format described here 112 cleaves more closely to the lower level constructs described in 113 [RFC5116]. 115 To the extent that message-based encryption formats use the same 116 primitives, the format can be considered as sequence of encrypted 117 messages with a particular profile. For instance, Appendix A 118 explains how the format is congruent with a sequence of JSON Web 119 Encryption [RFC7516] values with a fixed header. 121 This mechanism is likely only a small part of a larger design that 122 uses content encryption. How clients and servers acquire and 123 identify keys will depend on the use case. Though a complete key 124 management system is not described, this document defines an Crypto- 125 Key header field that can be used to convey keying 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 Crypto- 143 Key header field (Section 4) can be included to describe how the 144 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 = #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 Encryption header field values with multiple instances of the same 231 parameter name are invalid. 233 The Encryption header MAY be omitted if the sender does not intend 234 for the immediate recipient to be able to decrypt the payload body. 235 Alternatively, the Encryption header field MAY be omitted if the 236 sender intends for the recipient to acquire the header field by other 237 means. 239 Servers processing PUT requests MUST persist the value of the 240 Encryption header field, unless they remove the content-coding by 241 decrypting the payload. 243 3.1. Encryption Header Field Parameters 245 The following parameters are used in determining the content 246 encryption key that is used for encryption: 248 keyid: The "keyid" parameter contains a string that identifies the 249 keying material that is used. The "keyid" parameter SHOULD be 250 included, unless key identification is guaranteed by other means. 251 The "keyid" parameter MUST be used if keying material included in 252 an Crypto-Key header field is needed to derive the content 253 encryption key. 255 salt: The "salt" parameter contains a base64 URL-encoded octets that 256 is used as salt in deriving a unique content encryption key (see 257 Section 3.2). The "salt" parameter MUST be present, and MUST be 258 exactly 16 octets long when decoded. The "salt" parameter MUST 259 NOT be reused for two different payload bodies that have the same 260 input keying material; generating a random salt for every 261 application of the content encoding ensures that content 262 encryption key reuse is highly unlikely. 264 rs: The "rs" parameter contains a positive decimal integer that 265 describes the record size in octets. This value MUST be greater 266 than 1. If the "rs" parameter is absent, the record size defaults 267 to 4096 octets. 269 3.2. Content Encryption Key Derivation 271 In order to allow the reuse of keying material for multiple different 272 HTTP messages, a content encryption key is derived for each message. 273 The content encryption key is derived from the decoded value of the 274 "salt" parameter using the HMAC-based key derivation function (HKDF) 275 described in [RFC5869] using the SHA-256 hash algorithm [FIPS180-4]. 277 The decoded value of the "salt" parameter is the salt input to HKDF 278 function. The keying material identified by the "keyid" parameter is 279 the input keying material (IKM) to HKDF. Input keying material can 280 either be prearranged, or can be described using the Crypto-Key 281 header field (Section 4). The first step of HKDF is therefore: 283 PRK = HMAC-SHA-256(salt, IKM) 285 The info parameter to HKDF is set to the ASCII-encoded string 286 "Content-Encoding: aesgcm128", a single zero octet and an optional 287 context string: 289 cek_info = "Content-Encoding: aesgcm128" || 0x00 || context 291 Unless otherwise specified, the context is a zero length octet 292 sequence. Specifications that use this content encoding MAY specify 293 the use of an expanded context to cover additional inputs in the key 294 derivation. 296 AEAD_AES_128_GCM requires a 16 octet (128 bit) content encryption 297 key, so the length (L) parameter to HKDF is 16. The second step of 298 HKDF can therefore be simplified to the first 16 octets of a single 299 HMAC: 301 CEK = HMAC-SHA-256(PRK, cek_info || 0x01) 303 3.3. Nonce Derivation 305 The nonce input to AEAD_AES_128_GCM is constructed for each record. 306 The nonce for each record is a 12 octet (96 bit) value is produced 307 from the record sequence number and a value derived from the input 308 keying material. 310 The input keying material and salt values are input to HKDF with 311 different info and length parameters. 313 The length (L) parameter is 12 octets. The info parameter for the 314 nonce is the ASCII-encoded string "Content-Encoding: nonce", a single 315 zero octet and an context: 317 nonce_info = "Content-Encoding: nonce" || 0x00 || context 319 The context for nonce derivation SHOULD be the same as is used for 320 content encryption key derivation. 322 The result is combined with the record sequence number - using 323 exclusive or - to produce the nonce. The record sequence number 324 (SEQ) is a 96-bit unsigned integer in network byte order that starts 325 at zero. 327 Thus, the final nonce for each record is a 12 octet value: 329 NONCE = HMAC-SHA-256(PRK, nonce_info || 0x01) XOR SEQ 331 4. Crypto-Key Header Field 333 An Crypto-Key header field can be used to describe the input keying 334 material used in the Encryption header field. 336 The Crypto-Key header field uses the extended ABNF syntax defined in 337 Section 1.2 of [RFC7230] and the "parameter" rule from [RFC7231]. 339 Crypto-Key = #crypto_key_params 340 crypto_key_params = [ parameter *( ";" parameter ) ] 342 keyid: The "keyid" parameter corresponds to the "keyid" parameter in 343 the Encryption header field. 345 aesgcm128: The "aesgcm128" parameter contains the URL-safe base64 346 [RFC4648] octets of the input keying material. 348 dh: The "dh" parameter contains an ephemeral Diffie-Hellman share. 349 This form of the header field can be used to encrypt content for a 350 specific recipient. 352 Crypto-Key header field values with multiple instances of the same 353 parameter name are invalid. 355 The input keying material used by the key derivation (see 356 Section 3.2) can be determined based on the information in the 357 Crypto-Key header field. The method for key derivation depends on 358 the parameters that are present in the header field. 360 The value or values provided in the Crypto-Key header field is valid 361 only for the current HTTP message unless additional information 362 indicates a greater scope. 364 Note that different methods for determining input keying material 365 will produce different amounts of data. The HKDF process ensures 366 that the final content encryption key is the necessary size. 368 Alternative methods for determining input keying material MAY be 369 defined by specifications that use this content-encoding. 371 4.1. Explicit Key 373 The "aesgcm128" parameter is decoded and used as the input keying 374 material for the "aesgcm128" content encoding. The "aesgcm128" 375 parameter MUST decode to at least 16 octets in order to be used as 376 input keying material for "aesgcm128" content encoding. 378 Other key determination parameters can be ignored if the "aesgcm128" 379 parameter is present. 381 4.2. Diffie-Hellman 383 The "dh" parameter is included to describe a Diffie-Hellman share, 384 either modp (or finite field) Diffie-Hellman [DH] or elliptic curve 385 Diffie-Hellman (ECDH) [RFC4492]. 387 This share is combined with other information at the recipient to 388 determine the HKDF input keying material. In order for the exchange 389 to be successful, the following information MUST be established out 390 of band: 392 o Which Diffie-Hellman form is used. 394 o The modp group or elliptic curve that will be used. 396 o A label that uniquely identifies the group. This label will be 397 expressed as a sequence of octets and MUST NOT include a zero- 398 valued octet. 400 o The format of the ephemeral public share that is included in the 401 "dh" parameter. This encoding MUST result in a single, canonical 402 sequence of octets. For instance, using ECDH both parties need to 403 agree whether this is an uncompressed or compressed point. 405 In addition to identifying which content-encoding this input keying 406 material is used for, the "keyid" parameter is used to identify this 407 additional information at the receiver. 409 The intended recipient recovers their private key and are then able 410 to generate a shared secret using the designated Diffie-Hellman 411 process. 413 The context for content encryption key and nonce derivation (see 414 Section 3.2) is set to include the means by which the keys were 415 derived. The context is formed from the concatenation of group 416 label, a single zero octet, the length of the public key of the 417 recipient, the public key of the recipient, the length of the public 418 key of the sender, and the public key of the sender. The public keys 419 are encoded into octets as defined for the group when determining the 420 context string. 422 context = label || 0x00 || 423 length(recipient_public) || recipient_public || 424 length(sender_public) || sender_public 426 The two length fields are encoded as a two octet unsigned integer in 427 network byte order. 429 Specifications that rely on an Diffie-Hellman exchange for 430 determining input keying material MUST either specify the parameters 431 for Diffie-Hellman (group parameters, or curves and point format) 432 that are used, or describe how those parameters are negotiated 433 between sender and receiver. 435 4.3. Pre-shared Authentication Secrets 437 Key derivation MAY be extended to include an additional 438 authentication secret. Such a secret is shared between the sender 439 and receiver of a message using other means. 441 A pre-shared authentication secret is not explicitly signaled in 442 either the Encryption or Crypto-Key header fields. Use of this 443 additional step depends on prior agreement. 445 When a shared authentication secret is used, the keying material 446 produced by the key agreement method (e.g., Diffie-Hellman, explicit 447 key, or otherwise) is combined with the authentication secret using 448 HKDF. The output of HKDF is the input keying material used to derive 449 the content encryption key and nonce Section 3.2. 451 The authentication secret is used as the "salt" parameter to HKDF, 452 the raw keying material (e.g., Diffie-Hellman output) is used as the 453 "IKM" parameter, the ASCII-encoded string "Content-Encoding: auth" 454 with a terminal zero octet is used as the "info" parameter, and the 455 length of the output is 32 octets (i.e., the entire output of the 456 underlying SHA-256 HMAC function): 458 auth_info = "Content-Encoding: auth" || 0x00 459 IKM = HKDF(authentication, raw_key, auth_info, 32) 461 This invocation of HKDF does not take the same context that is 462 provided to the final key derivation stages. Alternatively, this 463 phase can be viewed as always having a zero-length context. 465 Note that in the absence of an authentication secret, the input 466 keying material is simply the raw keying material: 468 IKM = raw_key 470 5. Examples 472 5.1. Successful GET Response 474 HTTP/1.1 200 OK 475 Content-Type: application/octet-stream 476 Content-Encoding: aesgcm128 477 Connection: close 478 Encryption: keyid="http://example.org/bob/keys/123"; 479 salt="XZwpw6o37R-6qoZjw6KwAw" 481 [encrypted payload] 483 Here, a successful HTTP GET response has been encrypted using input 484 keying material that is identified by a URI. 486 Note that the media type has been changed to "application/octet- 487 stream" to avoid exposing information about the content. 489 5.2. Encryption and Compression 491 HTTP/1.1 200 OK 492 Content-Type: text/html 493 Content-Encoding: aesgcm128, gzip 494 Transfer-Encoding: chunked 495 Encryption: keyid="mailto:me@example.com"; 496 salt="m2hJ_NttRtFyUiMRPwfpHA" 498 [encrypted payload] 500 5.3. Encryption with More Than One Key 502 PUT /thing HTTP/1.1 503 Host: storage.example.com 504 Content-Type: application/http 505 Content-Encoding: aesgcm128, aesgcm128 506 Content-Length: 1234 507 Encryption: keyid="mailto:me@example.com"; 508 salt="NfzOeuV5USPRA-n_9s1Lag", 509 keyid="http://example.org/bob/keys/123"; 510 salt="bDMSGoc2uobK_IhavSHsHA"; rs=1200 512 [encrypted payload] 513 Here, a PUT request has been encrypted twice with different input 514 keying material; decrypting twice is necessary to read the content. 515 The outer layer of encryption uses a 1200 octet record size. 517 5.4. Encryption with Explicit Key 519 HTTP/1.1 200 OK 520 Content-Length: 32 521 Content-Encoding: aesgcm128 522 Encryption: keyid="a1"; salt="vr0o6Uq3w_KDWeatc27mUg" 523 Crypto-Key: keyid="a1"; aesgcm128="csPJEXBYA5U-Tal9EdJi-w" 525 fuag8ThIRIazSHKUqJ5OduR75UgEUuM76J8UFwadEvg 527 This example shows the string "I am the walrus" encrypted using an 528 directly provided value for the input keying material. The content 529 body contains a single record only and is shown here encoded in URL- 530 safe base64 for presentation reasons only. 532 5.5. Diffie-Hellman Encryption 534 HTTP/1.1 200 OK 535 Content-Length: 32 536 Content-Encoding: aesgcm128 537 Encryption: keyid="dhkey"; salt="Qg61ZJRva_XBE9IEUelU3A" 538 Crypto-Key: keyid="dhkey"; 539 dh="BDgpRKok2GZZDmS4r63vbJSUtcQx4Fq1V58-6-3NbZzS 540 TlZsQiCEDTQy3CZ0ZMsqeqsEb7qW2blQHA4S48fynTk" 542 G6j_sfKg0qebO62yXpTCayN2KV24QitNiTvLgcFiEj0 544 This example shows the same string, "I am the walrus", encrypted 545 using ECDH over the P-256 curve [FIPS186], which is identified with 546 the label "P-256" encoded in ASCII. The content body is shown here 547 encoded in URL-safe base64 for presentation reasons only. 549 The receiver (in this case, the HTTP client) uses a key pair that is 550 identified by the string "dhkey" and the sender (the server) uses a 551 key pair for which the public share is included in the "dh" parameter 552 above. The keys shown below use uncompressed points [X9.62] encoded 553 using URL-safe base64. Line wrapping is added for presentation 554 purposes only. 556 Receiver: 557 private key: 9FWl15_QUQAWDaD3k3l50ZBZQJ4au27F1V4F0uLSD_M 558 public key: BCEkBjzL8Z3C-oi2Q7oE5t2Np-p7osjGLg93qUP0wvqR 559 T21EEWyf0cQDQcakQMqz4hQKYOQ3il2nNZct4HgAUQU 560 Sender: 561 private key: vG7TmzUX9NfVR4XUGBkLAFu8iDyQe-q_165JkkN0Vlw 562 public key: 564 6. Security Considerations 566 This mechanism assumes the presence of a key management framework 567 that is used to manage the distribution of keys between valid senders 568 and receivers. Defining key management is part of composing this 569 mechanism into a larger application, protocol, or framework. 571 Implementation of cryptography - and key management in particular - 572 can be difficult. For instance, implementations need to account for 573 the potential for exposing keying material on side channels, such as 574 might be exposed by the time it takes to perform a given operation. 575 The requirements for a good implementation of cryptographic 576 algorithms can change over time. 578 6.1. Key and Nonce Reuse 580 Encrypting different plaintext with the same content encryption key 581 and nonce in AES-GCM is not safe [RFC5116]. The scheme defined here 582 uses a fixed progression of nonce values. Thus, a new content 583 encryption key is needed for every application of the content 584 encoding. Since input keying material can be reused, a unique "salt" 585 parameter is needed to ensure a content encryption key is not reused. 587 If a content encryption key is reused - that is, if input keying 588 material and salt are reused - this could expose the plaintext and 589 the authentication key, nullifying the protection offered by 590 encryption. Thus, if the same input keying material is reused, then 591 the salt parameter MUST be unique each time. This ensures that the 592 content encryption key is not reused. An implementation SHOULD 593 generate a random salt parameter for every message; a counter could 594 achieve the same result. 596 6.2. Content Integrity 598 This mechanism only provides content origin authentication. The 599 authentication tag only ensures that an entity with access to the 600 content encryption key produced the encrypted data. 602 Any entity with the content encryption key can therefore produce 603 content that will be accepted as valid. This includes all recipients 604 of the same HTTP message. 606 Furthermore, any entity that is able to modify both the Encryption 607 header field and the HTTP message body can replace the contents. 608 Without the content encryption key or the input keying material, 609 modifications to or replacement of parts of a payload body are not 610 possible. 612 6.3. Leaking Information in Headers 614 Because only the payload body is encrypted, information exposed in 615 header fields is visible to anyone who can read the HTTP message. 616 This could expose side-channel information. 618 For example, the Content-Type header field can leak information about 619 the payload body. 621 There are a number of strategies available to mitigate this threat, 622 depending upon the application's threat model and the users' 623 tolerance for leaked information: 625 1. Determine that it is not an issue. For example, if it is 626 expected that all content stored will be "application/json", or 627 another very common media type, exposing the Content-Type header 628 field could be an acceptable risk. 630 2. If it is considered sensitive information and it is possible to 631 determine it through other means (e.g., out of band, using hints 632 in other representations, etc.), omit the relevant headers, and/ 633 or normalize them. In the case of Content-Type, this could be 634 accomplished by always sending Content-Type: application/octet- 635 stream (the most generic media type), or no Content-Type at all. 637 3. If it is considered sensitive information and it is not possible 638 to convey it elsewhere, encapsulate the HTTP message using the 639 application/http media type (Section 8.3.2 of [RFC7230]), 640 encrypting that as the payload of the "outer" message. 642 6.4. Poisoning Storage 644 This mechanism only offers encryption of content; it does not perform 645 authentication or authorization, which still needs to be performed 646 (e.g., by HTTP authentication [RFC7235]). 648 This is especially relevant when a HTTP PUT request is accepted by a 649 server; if the request is unauthenticated, it becomes possible for a 650 third party to deny service and/or poison the store. 652 6.5. Sizing and Timing Attacks 654 Applications using this mechanism need to be aware that the size of 655 encrypted messages, as well as their timing, HTTP methods, URIs and 656 so on, may leak sensitive information. 658 This risk can be mitigated through the use of the padding that this 659 mechanism provides. Alternatively, splitting up content into 660 segments and storing the separately might reduce exposure. HTTP/2 661 [RFC7540] combined with TLS [RFC5246] might be used to hide the size 662 of individual messages. 664 7. IANA Considerations 666 7.1. The "aesgcm128" HTTP Content Encoding 668 This memo registers the "encrypted" HTTP content-coding in the HTTP 669 Content Codings Registry, as detailed in Section 2. 671 o Name: aesgcm128 673 o Description: AES-GCM encryption with a 128-bit content encryption 674 key 676 o Reference: this specification 678 7.2. Encryption Header Fields 680 This memo registers the "Encryption" HTTP header field in the 681 Permanent Message Header Registry, as detailed in Section 3. 683 o Field name: Encryption 685 o Protocol: HTTP 687 o Status: Standard 689 o Reference: this specification 691 o Notes: 693 This memo registers the "Crypto-Key" HTTP header field in the 694 Permanent Message Header Registry, as detailed in Section 4. 696 o Field name: Crypto-Key 698 o Protocol: HTTP 700 o Status: Standard 702 o Reference: this specification 704 o Notes: 706 7.3. The HTTP Encryption Parameter Registry 708 This memo establishes a registry for parameters used by the 709 "Encryption" header field under the "Hypertext Transfer Protocol 710 (HTTP) Parameters" grouping. The "Hypertext Transfer Protocol (HTTP) 711 Encryption Parameters" registry operates under an "Specification 712 Required" policy [RFC5226]. 714 Entries in this registry are expected to include the following 715 information: 717 o Parameter Name: The name of the parameter. 719 o Purpose: A brief description of the purpose of the parameter. 721 o Reference: A reference to a specification that defines the 722 semantics of the parameter. 724 The initial contents of this registry are: 726 7.3.1. keyid 728 o Parameter Name: keyid 730 o Purpose: Identify the key that is in use. 732 o Reference: this document 734 7.3.2. salt 736 o Parameter Name: salt 738 o Purpose: Provide a source of entropy for derivation of a content 739 encryption key. This value is mandatory. 741 o Reference: this document 743 7.3.3. rs 745 o Parameter Name: rs 747 o Purpose: The size of the encrypted records. 749 o Reference: this document 751 7.4. The HTTP Crypto-Key Parameter Registry 753 This memo establishes a registry for parameters used by the "Crypto- 754 Key" header field under the "Hypertext Transfer Protocol (HTTP) 755 Parameters" grouping. The "Hypertext Transfer Protocol (HTTP) 756 Encryption Parameters" operates under an "Specification Required" 757 policy [RFC5226]. 759 Entries in this registry are expected to include the following 760 information: 762 o Parameter Name: The name of the parameter. 764 o Purpose: A brief description of the purpose of the parameter. 766 o Reference: A reference to a specification that defines the 767 semantics of the parameter. 769 The initial contents of this registry are: 771 7.4.1. keyid 773 o Parameter Name: keyid 775 o Purpose: Identify the key that is in use. 777 o Reference: this document 779 7.4.2. aesgcm128 781 o Parameter Name: aesgcm128 783 o Purpose: Provide an explicit input keying material value for the 784 aesgcm128 content encoding. 786 o Reference: this document 788 7.4.3. dh 790 o Parameter Name: dh 792 o Purpose: Carry a modp or elliptic curve Diffie-Hellman share used 793 to derive input keying material. 795 o Reference: this document 797 8. References 799 8.1. Normative References 801 [DH] Diffie, W. and M. Hellman, "New Directions in 802 Cryptography", IEEE Transactions on Information Theory, 803 V.IT-22 n.6 , June 1977. 805 [FIPS180-4] 806 Department of Commerce, National., "NIST FIPS 180-4, 807 Secure Hash Standard", March 2012, 808 . 811 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 812 Requirement Levels", BCP 14, RFC 2119, 813 DOI 10.17487/RFC2119, March 1997, 814 . 816 [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. 817 Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites 818 for Transport Layer Security (TLS)", RFC 4492, 819 DOI 10.17487/RFC4492, May 2006, 820 . 822 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 823 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 824 . 826 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 827 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 828 . 830 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 831 Key Derivation Function (HKDF)", RFC 5869, 832 DOI 10.17487/RFC5869, May 2010, 833 . 835 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 836 Protocol (HTTP/1.1): Message Syntax and Routing", 837 RFC 7230, DOI 10.17487/RFC7230, June 2014, 838 . 840 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 841 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 842 DOI 10.17487/RFC7231, June 2014, 843 . 845 8.2. Informative References 847 [FIPS186] National Institute of Standards and Technology (NIST), 848 "Digital Signature Standard (DSS)", NIST PUB 186-4 , July 849 2013. 851 [RFC4880] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R. 852 Thayer, "OpenPGP Message Format", RFC 4880, 853 DOI 10.17487/RFC4880, November 2007, 854 . 856 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 857 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 858 DOI 10.17487/RFC5226, May 2008, 859 . 861 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 862 (TLS) Protocol Version 1.2", RFC 5246, 863 DOI 10.17487/RFC5246, August 2008, 864 . 866 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 867 RFC 5652, DOI 10.17487/RFC5652, September 2009, 868 . 870 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 871 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 872 RFC 7233, DOI 10.17487/RFC7233, June 2014, 873 . 875 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 876 Protocol (HTTP/1.1): Authentication", RFC 7235, 877 DOI 10.17487/RFC7235, June 2014, 878 . 880 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 881 RFC 7516, DOI 10.17487/RFC7516, May 2015, 882 . 884 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 885 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 886 DOI 10.17487/RFC7540, May 2015, 887 . 889 [X9.62] ANSI, "Public Key Cryptography For The Financial Services 890 Industry: The Elliptic Curve Digital Signature Algorithm 891 (ECDSA)", ANSI X9.62 , 1998. 893 [XMLENC] Eastlake, D., Reagle, J., Imamura, T., Dillaway, B., and 894 E. Simon, "XML Encryption Syntax and Processing", W3C 895 REC , December 2002, . 897 Appendix A. JWE Mapping 899 The "aesgcm128" content encoding can be considered as a sequence of 900 JSON Web Encryption (JWE) objects [RFC7516], each corresponding to a 901 single fixed size record. The following transformations are applied 902 to a JWE object that might be expressed using the JWE Compact 903 Serialization: 905 o The JWE Protected Header is fixed to a value { "alg": "dir", 906 "enc": "A128GCM" }, describing direct encryption using AES-GCM 907 with a 128-bit content encryption key. This header is not 908 transmitted, it is instead implied by the value of the Content- 909 Encoding header field. 911 o The JWE Encrypted Key is empty, as stipulated by the direct 912 encryption algorithm. 914 o The JWE Initialization Vector ("iv") for each record is set to the 915 exclusive or of the 96-bit record sequence number, starting at 916 zero, and a value derived from the input keying material (see 917 Section 3.3). This value is also not transmitted. 919 o The final value is the concatenated JWE Ciphertext and the JWE 920 Authentication Tag, both expressed without URL-safe Base 64 921 encoding. The "." separator is omitted, since the length of these 922 fields is known. 924 Thus, the example in Section 5.4 can be rendered using the JWE 925 Compact Serialization as: 927 eyAiYWxnIjogImRpciIsICJlbmMiOiAiQTEyOEdDTSIgfQ..AAAAAAAAAAAAAAAA. 928 LwTC-fwdKh8de0smD2jfzA.eh1vURhu65M2lxhctbbntA 929 Where the first line represents the fixed JWE Protected Header, JWE 930 Encrypted Key, and JWE Initialization Vector, all of which are 931 determined algorithmically. The second line contains the encoded 932 body, split into JWE Ciphertext and JWE Authentication Tag. 934 Appendix B. Acknowledgements 936 Mark Nottingham was an original author of this document. 938 The following people provided valuable input: Richard Barnes, David 939 Benjamin, Peter Beverloo, Mike Jones, Stephen Farrell, Adam Langley, 940 John Mattsson, Eric Rescorla, and Jim Schaad. 942 Author's Address 944 Martin Thomson 945 Mozilla 947 Email: martin.thomson@gmail.com