idnits 2.17.1 draft-thomson-http-mice-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 29, 2016) is 2851 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' -- Possible downref: Non-RFC (?) normative reference: ref. 'MERKLE' ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** 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 2818 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 6962 (Obsoleted by RFC 9162) -- Obsolete informational reference (is this intentional?): RFC 7233 (Obsoleted by RFC 9110) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 7 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 June 29, 2016 5 Expires: December 31, 2016 7 Merkle Integrity Content Encoding 8 draft-thomson-http-mice-01 10 Abstract 12 This memo introduces a content-coding for HTTP that provides 13 progressive integrity for message contents. This integrity 14 protection can be evaluated on a partial representation, allowing a 15 recipient to process a message as it is delivered while retaining 16 strong integrity protection. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on December 31, 2016. 35 Copyright Notice 37 Copyright (c) 2016 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 54 2. The "mi-sha256" HTTP Content Encoding . . . . . . . . . . . . 3 55 2.1. Content Encoding Structure . . . . . . . . . . . . . . . 4 56 2.2. Validating Integrity Proofs . . . . . . . . . . . . . . . 5 57 3. The MI HTTP Header Field . . . . . . . . . . . . . . . . . . 6 58 3.1. MI Header Field Parameters . . . . . . . . . . . . . . . 6 59 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 4.1. Simple Example . . . . . . . . . . . . . . . . . . . . . 6 61 4.2. Example with Multiple Records . . . . . . . . . . . . . . 7 62 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 63 5.1. Message Truncation . . . . . . . . . . . . . . . . . . . 7 64 5.2. Algorithm Agility . . . . . . . . . . . . . . . . . . . . 8 65 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 66 6.1. The "mi-sha256" HTTP Content Encoding . . . . . . . . . . 8 67 6.2. MI Header Field . . . . . . . . . . . . . . . . . . . . . 8 68 6.3. The HTTP MI Parameter Registry . . . . . . . . . . . . . 8 69 6.3.1. p parameter . . . . . . . . . . . . . . . . . . . . . 9 70 6.3.2. rs parameter . . . . . . . . . . . . . . . . . . . . 9 71 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 72 7.1. Normative References . . . . . . . . . . . . . . . . . . 9 73 7.2. Informative References . . . . . . . . . . . . . . . . . 10 74 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11 75 Appendix B. FAQ . . . . . . . . . . . . . . . . . . . . . . . . 11 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 78 1. Introduction 80 Integrity protection for HTTP content is highly valuable. HTTPS 81 [RFC2818] is the most common form of integrity protection deployed, 82 but that requires a direct TLS [RFC5246] connection to a host. 83 However, additional integrity protection might be desirable for some 84 use cases. This might be for additional protection against failures 85 or attack (see [SRI]) or because content needs to remain unmodified 86 throughout multiple HTTPS-protected exchanges. 88 This document describes a "mi-sha256" content-encoding (see 89 Section 2) that is a progressive, hash-based integrity check based on 90 Merkle Hash Trees [MERKLE]. 92 The means of conveying the root integrity proof used by this content 93 encoding will depend on deployment requirements. This document 94 defines an MI header field (see Section 3) that can carry an 95 integrity proof. 97 1.1. Notational Conventions 99 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 100 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 101 document are to be interpreted as described in [RFC2119]. 103 2. The "mi-sha256" HTTP Content Encoding 105 A Merkle Hash Tree [MERKLE] is a structured integrity mechanism that 106 collates multiple integrity checks into a tree. The leaf nodes of 107 the tree contain data (or hashes of data) and non-leaf nodes contain 108 hashes of the nodes below them. 110 A balanced Merkle Hash Tree is used to efficiently prove membership 111 in large sets (such as in [RFC6962]). However, in this case, a 112 right-skewed tree is used to provide a progressive integrity proof. 113 This integrity proof is used to establish that a given record is part 114 of a message. 116 The hash function used for "mi-sha256" content encoding is SHA-256 117 [FIPS180-4]. The integrity proof for all records other than the last 118 is the hash of the concatenation of the record, the integrity proof 119 of all subsequent records, and a single octet with a value of 0x1: 121 proof(r[i]) = SHA-256(r[i] || proof(r[i+1]) || 0x1) 123 The integrity proof for the final record is the hash of the record 124 with a single octet with a value 0x0 appended: 126 proof(r[last]) = SHA-256(r[last] || 0x0) 128 Figure 1 shows the structure of the integrity proofs for a message 129 that is split into 4 blocks: A, B, C, D). As shown, the integrity 130 proof for the entire message (that is, "proof(A)") is derived from 131 the content of the first block (A), plus the value of the proof for 132 the second and subsequent blocks. 134 proof(A) 135 /\ 136 / \ 137 / \ 138 A proof(B) 139 /\ 140 / \ 141 / \ 142 B proof(C) 143 /\ 144 / \ 145 / \ 146 C proof(D) 147 | 148 | 149 D 151 Figure 1: Proof structure for a message with 4 blocks 153 The final encoded message is formed from the first record, followed 154 by an arbitrary number of tuples of the integrity proof of the next 155 record and then the record itself. Thus, in Figure 1, the body is: 157 A || proof(B) || B || proof(C) || C || proof(D) || D 159 A message that has a content length less than or equal to the content 160 size does not include any inline proofs. The proof for a message 161 with a single record is simply the hash of the body plus a trailing 162 zero octet. 164 2.1. Content Encoding Structure 166 In order to produce the final content encoding the content of the 167 message is split into equal-sized records. The final record can 168 contain less than the defined record size. 170 The default record size for the "mi-sha256" content encoding is 4096 171 octets. This refers to the length of each data block. The MI header 172 field MAY contain an "rs" parameter that describes a different record 173 size. 175 The final encoded stream comprises of a record ("rs" octets in 176 length), followed by the proof for the following record (32 octets). 177 This allows a receiver to validate and act upon each record after 178 receiving the proof that precedes it. The final record is not 179 followed by a proof. 181 Note: This content encoding increases the size of a message by 32 182 octets times the length of the message divided by the record size, 183 rounded up, less one. That is, 32 * (ceil(length / rs) - 1). 185 Constructing a message with the "mi-sha256" content encoding requires 186 processing of the records in reverse order, inserting the proof 187 derived from each record before that record. 189 This structure permits the use of range requests [RFC7233]. However, 190 to validate a given record, a contiguous sequence of records back to 191 the start of the message is needed. 193 2.2. Validating Integrity Proofs 195 A receiver of a message with the "mi-sha256" content-encoding applied 196 first attempts to acquire the integrity proof for the first record. 197 If the MI header field is present, a value might be included there. 199 Then, the message is read into records of size "rs" (based on the 200 value in the MI header field) plus 32 octets. The last record is 201 between 1 and "rs" octets in length, if not then validation fails. 202 For each record: 204 1. Hash the record using SHA-256 with a single octet appended: 206 a. All records other than the last have an octet with a value of 207 0x1 appended. 209 b. The last record has an octet with a value of 0x0 appended. 211 2. Compare the hash with the expected value: 213 a. For the first record, the expected value might found in the 214 MI header field and is otherwise provided through some external 215 means. 217 b. For records after the first, the expected value is the last 218 32 octets of the previous record. 220 3. If the hash is different, then this record and all subsequent 221 records do not have integrity protection and this process ends. 223 4. If a record is valid, up to "rs" octets is passed on for 224 processing. In other words, the trailing 32 octets is removed 225 from every record other than the last before being used. 227 If an integrity check fails, the message SHOULD be discarded and the 228 exchange treated as an error unless explicitly configured otherwise. 230 For clients, treat this as equivalent to a server error; servers 231 SHOULD generate a 400 or other 4xx status code. However, if the 232 integrity proof for the first record is not known, this check SHOULD 233 NOT fail unless explicitly configured. 235 3. The MI HTTP Header Field 237 The MI HTTP header field describes the message integrity content 238 encoding(s) that have been applied to a payload body, and therefore 239 how those content encoding(s) can be removed. 241 The MI header field uses the extended ABNF syntax defined in 242 Section 1.2 of [RFC7230] and the "parameter" rule from [RFC7231]: 244 MI = #mi_params 245 mi_params = [ parameter *( ";" parameter ) ] 247 If the payload is encoded more than once (as reflected by having 248 multiple content-codings that use the message integrity header 249 field), each application of the content encoding is reflected in the 250 MI header field in the order in which they were applied. 252 The MI header MAY be omitted if the sender intends for the receiver 253 to acquire the integrity proof for the first record by other means. 255 3.1. MI Header Field Parameters 257 The following parameters are used in validating content encoded with 258 the "mi-sha256" content encoding: 260 p: The "p" parameter carries an integrity proof for the first record 261 of the message. This provides integrity for the entire message 262 body. This value is encoded using base64url encoding [RFC7515]. 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 0. If the "rs" parameter is absent, the record size defaults 267 to 4096 octets. 269 4. Examples 271 4.1. Simple Example 273 The following example contains a short message. This contains just a 274 single record, so there are no inline integrity proofs, just a single 275 value in a MI header field. 277 HTTP/1.1 200 OK 278 MI: p=dcRDgR2GM35DluAV13PzgnG6-pvQwPywfFvAu1UeFrs 279 Content-Encoding: mi-sha256 280 Content-Length: 41 282 When I grow up, I want to be a watermelon 284 4.2. Example with Multiple Records 286 This example shows the same message as above, but with a smaller 287 record size (16 octets). This results in two integrity proofs being 288 included in the representation. 290 PUT /test HTTP/1.1 291 Host: example.com 292 MI: rs=16; p=IVa9shfs0nyKEhHqtB3WVNANJ2Njm5KjQLjRtnbkYJ4 293 Content-Encoding: mi-sha256 294 Content-Length: 105 296 When I grow up, 297 OElbplJlPK-Rv6JNK6p5_515IaoPoZo-2elWL7OQ60A 298 I want to be a w 299 iPMpmgExHPrbEX3_RvwP4d16fWlK4l--p75PUu_KyN0 300 atermelon 302 Since the inline integrity proofs contain non-printing characters, 303 these are shown here using the base64url Encoding [RFC7515] with new 304 lines between the original text and integrity proofs. Note that 305 there is a single trailing space (0x20) on the first line. 307 5. Security Considerations 309 The integrity of an entire message body depends on the means by which 310 the integrity proof for the first record is protected. If this value 311 comes from the same place as the message, then this provides only 312 limited protection against transport-level errors (something that TLS 313 provides adequate protection against). 315 Separate protection for header fields might be provided by other 316 means if the first record retrieved is the first record in the 317 message, but range requests do not allow for this option. 319 5.1. Message Truncation 321 This integrity scheme permits the detection of truncated messages. 322 However, it enables and even encourages processing of messages prior 323 to receiving an complete message. Actions taken on a partial message 324 can produce incorrect results. For example, a message could say "I 325 need some 2mm copper cable, please send 100mm for evaluation 326 purposes" then be truncated to "I need some 2mm copper cable, please 327 send 100m". A network-based attacker might be able to force this 328 sort of truncation by delaying packets that contain the remainder of 329 the message. 331 Whether it is safe to act on partial messages will depend on the 332 nature of the message and the processing that is performed. 334 5.2. Algorithm Agility 336 A new content encoding type is needed in order to define the use of a 337 hash function other than SHA-256. 339 6. IANA Considerations 341 6.1. The "mi-sha256" HTTP Content Encoding 343 This memo registers the "mi-sha256" HTTP content-coding in the HTTP 344 Content Codings Registry, as detailed in Section 2. 346 o Name: mi-sha256 348 o Description: A Merkle Hash Tree based content encoding that 349 provides progressive integrity. 351 o Reference: this specification 353 6.2. MI Header Field 355 This memo registers the "MI" HTTP header field in the Permanent 356 Message Header Registry, as detailed in Section 3. 358 o Field name: MI 360 o Protocol: HTTP 362 o Status: Standard 364 o Reference: this specification 366 o Notes: 368 6.3. The HTTP MI Parameter Registry 370 This memo establishes a registry for parameters used by the "MI" 371 header field under the "Hypertext Transfer Protocol (HTTP) 372 Parameters" grouping. The "Hypertext Transfer Protocol (HTTP) MI 373 Parameters" registry operates under an "Specification Required" 374 policy [RFC5226]. 376 Entries in this registry are expected to include the following 377 information: 379 o Parameter Name: The name of the parameter. 381 o Purpose: A brief description of the purpose of the parameter. 383 o Reference: A reference to a specification that defines the 384 semantics of the parameter. 386 The initial contents of this registry are: 388 6.3.1. p parameter 390 o Parameter Name: p 392 o Purpose: The value of the integrity proof for the first record. 394 o Reference: this document 396 6.3.2. rs parameter 398 o Parameter Name: rs 400 o Purpose: The size of the records used for progressive integrity 401 protection. 403 o Reference: this document 405 7. References 407 7.1. Normative References 409 [FIPS180-4] 410 Department of Commerce, National., "NIST FIPS 180-4, 411 Secure Hash Standard", March 2012, 412 . 415 [MERKLE] Merkle, R., "A Digital Signature Based on a Conventional 416 Encryption Function", International Crytology Conference - 417 CRYPTO , 1987. 419 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 420 Requirement Levels", BCP 14, RFC 2119, 421 DOI 10.17487/RFC2119, March 1997, 422 . 424 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 425 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 426 DOI 10.17487/RFC5226, May 2008, 427 . 429 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 430 Protocol (HTTP/1.1): Message Syntax and Routing", 431 RFC 7230, DOI 10.17487/RFC7230, June 2014, 432 . 434 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 435 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 436 DOI 10.17487/RFC7231, June 2014, 437 . 439 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 440 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 441 2015, . 443 7.2. Informative References 445 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 446 DOI 10.17487/RFC2818, May 2000, 447 . 449 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 450 (TLS) Protocol Version 1.2", RFC 5246, 451 DOI 10.17487/RFC5246, August 2008, 452 . 454 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 455 Transparency", RFC 6962, DOI 10.17487/RFC6962, June 2013, 456 . 458 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 459 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 460 RFC 7233, DOI 10.17487/RFC7233, June 2014, 461 . 463 [SRI] Akhawe, D., Braun, F., Marier, F., and J. Weinberger, 464 "Subresource Integrity", W3C CR , November 2015, 465 . 467 Appendix A. Acknowledgements 469 David Benjamin and Erik Nygren both separately suggested that 470 something like this might be valuable. Eric Rescorla provided useful 471 feedback. 473 Appendix B. FAQ 475 1. Why not include the first proof in the encoding? 477 The requirements for the integrity proof for the first record 478 require a great deal more flexibility than this allows for. 479 Transferring the proof separately is sometimes necessary. 480 Separating the value out allows for that to happen more easily. 482 2. Why do messages have to be processed in reverse to construct 483 them? 485 The final integrity value, no matter how it is derived, has to 486 depend on every bit of the message. That means that there are 487 three choices: both sender and receiver have to process the whole 488 message, the sender has to work backwards, or the receiver has to 489 work backwards. The current form is the best option of the 490 three. The expectation is that this will be useful for content 491 that is generated once and sent multiple times, since the onerous 492 backwards processing requirement can be amortized. 494 Author's Address 496 Martin Thomson 497 Mozilla 499 Email: martin.thomson@gmail.com