idnits 2.17.1 draft-ietf-httpbis-p5-range-19.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 seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 12, 2012) is 4400 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-19 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-19 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-19 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-19 -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 4288 (Obsoleted by RFC 6838) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPbis Working Group R. Fielding, Ed. 3 Internet-Draft Adobe 4 Obsoletes: 2616 (if approved) Y. Lafon, Ed. 5 Intended status: Standards Track W3C 6 Expires: September 13, 2012 J. Reschke, Ed. 7 greenbytes 8 March 12, 2012 10 HTTP/1.1, part 5: Range Requests and Partial Responses 11 draft-ietf-httpbis-p5-range-19 13 Abstract 15 The Hypertext Transfer Protocol (HTTP) is an application-level 16 protocol for distributed, collaborative, hypertext information 17 systems. HTTP has been in use by the World Wide Web global 18 information initiative since 1990. This document is Part 5 of the 19 seven-part specification that defines the protocol referred to as 20 "HTTP/1.1" and, taken together, obsoletes RFC 2616. 22 Part 5 defines range-specific requests and the rules for constructing 23 and combining responses to those requests. 25 Editorial Note (To be removed by RFC Editor) 27 Discussion of this draft should take place on the HTTPBIS working 28 group mailing list (ietf-http-wg@w3.org), which is archived at 29 . 31 The current issues list is at 32 and related 33 documents (including fancy diffs) can be found at 34 . 36 The changes in this draft are summarized in Appendix D.20. 38 Status of This Memo 40 This Internet-Draft is submitted in full conformance with the 41 provisions of BCP 78 and BCP 79. 43 Internet-Drafts are working documents of the Internet Engineering 44 Task Force (IETF). Note that other groups may also distribute 45 working documents as Internet-Drafts. The list of current Internet- 46 Drafts is at http://datatracker.ietf.org/drafts/current/. 48 Internet-Drafts are draft documents valid for a maximum of six months 49 and may be updated, replaced, or obsoleted by other documents at any 50 time. It is inappropriate to use Internet-Drafts as reference 51 material or to cite them other than as "work in progress." 53 This Internet-Draft will expire on September 13, 2012. 55 Copyright Notice 57 Copyright (c) 2012 IETF Trust and the persons identified as the 58 document authors. All rights reserved. 60 This document is subject to BCP 78 and the IETF Trust's Legal 61 Provisions Relating to IETF Documents 62 (http://trustee.ietf.org/license-info) in effect on the date of 63 publication of this document. Please review these documents 64 carefully, as they describe your rights and restrictions with respect 65 to this document. Code Components extracted from this document must 66 include Simplified BSD License text as described in Section 4.e of 67 the Trust Legal Provisions and are provided without warranty as 68 described in the Simplified BSD License. 70 This document may contain material from IETF Documents or IETF 71 Contributions published or made publicly available before November 72 10, 2008. The person(s) controlling the copyright in some of this 73 material may not have granted the IETF Trust the right to allow 74 modifications of such material outside the IETF Standards Process. 75 Without obtaining an adequate license from the person(s) controlling 76 the copyright in such materials, this document may not be modified 77 outside the IETF Standards Process, and derivative works of it may 78 not be created outside the IETF Standards Process, except to format 79 it for publication as an RFC or to translate it into languages other 80 than English. 82 Table of Contents 84 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 85 1.1. Conformance and Error Handling . . . . . . . . . . . . . . 4 86 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 5 87 1.2.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 5 88 1.2.2. ABNF Rules defined in other Parts of the 89 Specification . . . . . . . . . . . . . . . . . . . . 5 90 2. Range Units . . . . . . . . . . . . . . . . . . . . . . . . . 5 91 2.1. Range Specifier Registry . . . . . . . . . . . . . . . . . 6 92 3. Status Code Definitions . . . . . . . . . . . . . . . . . . . 6 93 3.1. 206 Partial Content . . . . . . . . . . . . . . . . . . . 6 94 3.2. 416 Requested Range Not Satisfiable . . . . . . . . . . . 7 95 4. Responses to a Range Request . . . . . . . . . . . . . . . . . 7 96 4.1. Response to a Single and Multiple Ranges Request . . . . . 7 97 4.2. Combining Ranges . . . . . . . . . . . . . . . . . . . . . 8 98 5. Header Field Definitions . . . . . . . . . . . . . . . . . . . 9 99 5.1. Accept-Ranges . . . . . . . . . . . . . . . . . . . . . . 9 100 5.2. Content-Range . . . . . . . . . . . . . . . . . . . . . . 10 101 5.3. If-Range . . . . . . . . . . . . . . . . . . . . . . . . . 11 102 5.4. Range . . . . . . . . . . . . . . . . . . . . . . . . . . 12 103 5.4.1. Byte Ranges . . . . . . . . . . . . . . . . . . . . . 12 104 5.4.2. Range Retrieval Requests . . . . . . . . . . . . . . . 14 105 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 106 6.1. Status Code Registration . . . . . . . . . . . . . . . . . 15 107 6.2. Header Field Registration . . . . . . . . . . . . . . . . 15 108 6.3. Range Specifier Registration . . . . . . . . . . . . . . . 16 109 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16 110 7.1. Overlapping Ranges . . . . . . . . . . . . . . . . . . . . 16 111 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 112 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 113 9.1. Normative References . . . . . . . . . . . . . . . . . . . 16 114 9.2. Informative References . . . . . . . . . . . . . . . . . . 17 115 Appendix A. Internet Media Type multipart/byteranges . . . . . . 17 116 Appendix B. Changes from RFC 2616 . . . . . . . . . . . . . . . . 20 117 Appendix C. Collected ABNF . . . . . . . . . . . . . . . . . . . 21 118 Appendix D. Change Log (to be removed by RFC Editor before 119 publication) . . . . . . . . . . . . . . . . . . . . 22 120 D.1. Since RFC 2616 . . . . . . . . . . . . . . . . . . . . . . 22 121 D.2. Since draft-ietf-httpbis-p5-range-00 . . . . . . . . . . . 22 122 D.3. Since draft-ietf-httpbis-p5-range-01 . . . . . . . . . . . 22 123 D.4. Since draft-ietf-httpbis-p5-range-02 . . . . . . . . . . . 22 124 D.5. Since draft-ietf-httpbis-p5-range-03 . . . . . . . . . . . 23 125 D.6. Since draft-ietf-httpbis-p5-range-04 . . . . . . . . . . . 23 126 D.7. Since draft-ietf-httpbis-p5-range-05 . . . . . . . . . . . 23 127 D.8. Since draft-ietf-httpbis-p5-range-06 . . . . . . . . . . . 23 128 D.9. Since draft-ietf-httpbis-p5-range-07 . . . . . . . . . . . 24 129 D.10. Since draft-ietf-httpbis-p5-range-08 . . . . . . . . . . . 24 130 D.11. Since draft-ietf-httpbis-p5-range-09 . . . . . . . . . . . 24 131 D.12. Since draft-ietf-httpbis-p5-range-10 . . . . . . . . . . . 24 132 D.13. Since draft-ietf-httpbis-p5-range-11 . . . . . . . . . . . 24 133 D.14. Since draft-ietf-httpbis-p5-range-12 . . . . . . . . . . . 25 134 D.15. Since draft-ietf-httpbis-p5-range-13 . . . . . . . . . . . 25 135 D.16. Since draft-ietf-httpbis-p5-range-14 . . . . . . . . . . . 25 136 D.17. Since draft-ietf-httpbis-p5-range-15 . . . . . . . . . . . 25 137 D.18. Since draft-ietf-httpbis-p5-range-16 . . . . . . . . . . . 25 138 D.19. Since draft-ietf-httpbis-p5-range-17 . . . . . . . . . . . 25 139 D.20. Since draft-ietf-httpbis-p5-range-18 . . . . . . . . . . . 25 140 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 142 1. Introduction 144 HTTP clients often encounter interrupted data transfers as a result 145 of cancelled requests or dropped connections. When a client has 146 stored a partial representation, it is desirable to request the 147 remainder of that representation in a subsequent request rather than 148 transfer the entire representation. There are also a number of Web 149 applications that benefit from being able to request only a subset of 150 a larger representation, such as a single page of a very large 151 document or only part of an image to be rendered by a device with 152 limited local storage. 154 This document defines HTTP/1.1 range requests, partial responses, and 155 the multipart/byteranges media type. The protocol for range requests 156 is an OPTIONAL feature of HTTP, designed so resources or recipients 157 that do not implement this feature can respond as if it is a normal 158 GET request without impacting interoperability. Partial responses 159 are indicated by a distinct status code to not be mistaken for full 160 responses by intermediate caches that might not implement the 161 feature. 163 Although the HTTP range request mechanism is designed to allow for 164 extensible range types, this specification only defines requests for 165 byte ranges. 167 1.1. Conformance and Error Handling 169 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 170 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 171 document are to be interpreted as described in [RFC2119]. 173 This document defines conformance criteria for several roles in HTTP 174 communication, including Senders, Recipients, Clients, Servers, User- 175 Agents, Origin Servers, Intermediaries, Proxies and Gateways. See 176 Section 2 of [Part1] for definitions of these terms. 178 An implementation is considered conformant if it complies with all of 179 the requirements associated with its role(s). Note that SHOULD-level 180 requirements are relevant here, unless one of the documented 181 exceptions is applicable. 183 This document also uses ABNF to define valid protocol elements 184 (Section 1.2). In addition to the prose requirements placed upon 185 them, Senders MUST NOT generate protocol elements that are invalid. 187 Unless noted otherwise, Recipients MAY take steps to recover a usable 188 protocol element from an invalid construct. However, HTTP does not 189 define specific error handling mechanisms, except in cases where it 190 has direct impact on security. This is because different uses of the 191 protocol require different error handling strategies; for example, a 192 Web browser may wish to transparently recover from a response where 193 the Location header field doesn't parse according to the ABNF, 194 whereby in a systems control protocol using HTTP, this type of error 195 recovery could lead to dangerous consequences. 197 1.2. Syntax Notation 199 This specification uses the Augmented Backus-Naur Form (ABNF) 200 notation of [RFC5234] with the list rule extension defined in Section 201 1.2 of [Part1]. Appendix C shows the collected ABNF with the list 202 rule expanded. 204 The following core rules are included by reference, as defined in 205 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 206 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 207 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 208 sequence of data), SP (space), and VCHAR (any visible US-ASCII 209 character). 211 Note that all rules derived from token are to be compared case- 212 insensitively, like range-unit and acceptable-ranges. 214 1.2.1. Core Rules 216 The core rules below are defined in [Part1] and [Part2]: 218 OWS = 219 token = 220 HTTP-date = 222 1.2.2. ABNF Rules defined in other Parts of the Specification 224 The ABNF rules below are defined in other parts: 226 entity-tag = 228 2. Range Units 230 HTTP/1.1 allows a client to request that only part (a range) of the 231 representation be included within the response. HTTP/1.1 uses range 232 units in the Range (Section 5.4) and Content-Range (Section 5.2) 233 header fields. A representation can be broken down into subranges 234 according to various structural units. 236 range-unit = bytes-unit / other-range-unit 237 bytes-unit = "bytes" 238 other-range-unit = token 240 HTTP/1.1 has been designed to allow implementations of applications 241 that do not depend on knowledge of ranges. The only range unit 242 defined by HTTP/1.1 is "bytes". Additional specifiers can be defined 243 as described in Section 2.1. 245 If a range unit is not understood in a request, a server MUST ignore 246 the whole Range header field (Section 5.4). If a range unit is not 247 understood in a response, an intermediary SHOULD pass the response to 248 the client; a client MUST fail. 250 2.1. Range Specifier Registry 252 The HTTP Range Specifier Registry defines the name space for the 253 range specifier names. 255 Registrations MUST include the following fields: 257 o Name 259 o Description 261 o Pointer to specification text 263 Values to be added to this name space require IETF Review (see 264 [RFC5226], Section 4.1). 266 The registry itself is maintained at 267 . 269 3. Status Code Definitions 271 3.1. 206 Partial Content 273 The server has fulfilled the partial GET request for the resource. 274 The request MUST have included a Range header field (Section 5.4) 275 indicating the desired range, and MAY have included an If-Range 276 header field (Section 5.3) to make the request conditional. 278 The response MUST include the following header fields: 280 o Either a Content-Range header field (Section 5.2) indicating the 281 range included with this response, or a multipart/byteranges 282 Content-Type including Content-Range fields for each part. If a 283 Content-Length header field is present in the response, its value 284 MUST match the actual number of octets transmitted in the message 285 body. 287 o Date 289 o Cache-Control, ETag, Expires, Content-Location, Last-Modified, 290 and/or Vary, if the header field would have been sent in a 200 291 response to the same request 293 If the 206 response is the result of an If-Range request, the 294 response SHOULD NOT include other representation header fields. 295 Otherwise, the response MUST include all of the representation header 296 fields that would have been returned with a 200 (OK) response to the 297 same request. 299 Caches MAY use a heuristic (see Section 2.3.1.1 of [Part6]) to 300 determine freshness for 206 responses. 302 3.2. 416 Requested Range Not Satisfiable 304 A server SHOULD return a response with this status code if a request 305 included a Range header field (Section 5.4), and none of the ranges- 306 specifier values in this field overlap the current extent of the 307 selected resource, and the request did not include an If-Range header 308 field (Section 5.3). (For byte-ranges, this means that the first- 309 byte-pos of all of the byte-range-spec values were greater than the 310 current length of the selected resource.) 312 When this status code is returned for a byte-range request, the 313 response SHOULD include a Content-Range header field specifying the 314 current length of the representation (see Section 5.2). This 315 response MUST NOT use the multipart/byteranges content-type. For 316 example, 318 HTTP/1.1 416 Requested Range Not Satisfiable 319 Date: Mon, 20 Jan 2012 15:41:54 GMT 320 Content-Range: bytes */47022 321 Content-Type: image/gif 323 Note: Clients cannot depend on servers to send a 416 (Requested 324 range not satisfiable) response instead of a 200 (OK) response for 325 an unsatisfiable Range header field, since not all servers 326 implement this header field. 328 4. Responses to a Range Request 330 4.1. Response to a Single and Multiple Ranges Request 332 When an HTTP message includes the content of a single range (for 333 example, a response to a request for a single range, or to a request 334 for a set of ranges that overlap without any holes), this content is 335 transmitted with a Content-Range header field, and a Content-Length 336 header field showing the number of bytes actually transferred. For 337 example, 339 HTTP/1.1 206 Partial Content 340 Date: Wed, 15 Nov 1995 06:25:24 GMT 341 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 342 Content-Range: bytes 21010-47021/47022 343 Content-Length: 26012 344 Content-Type: image/gif 346 When an HTTP message includes the content of multiple ranges (for 347 example, a response to a request for multiple non-overlapping 348 ranges), these are transmitted as a multipart message. The multipart 349 media type used for this purpose is "multipart/byteranges" as defined 350 in Appendix A. 352 A server MAY combine requested ranges when those ranges are 353 overlapping (see Section 7). 355 A response to a request for a single range MUST NOT be sent using the 356 multipart/byteranges media type. A response to a request for 357 multiple ranges, whose result is a single range, MAY be sent as a 358 multipart/byteranges media type with one part. A client that cannot 359 decode a multipart/byteranges message MUST NOT ask for multiple 360 ranges in a single request. 362 When a client requests multiple ranges in one request, the server 363 SHOULD return them in the order that they appeared in the request. 365 4.2. Combining Ranges 367 A response might transfer only a subrange of a representation if the 368 connection closed prematurely or if the request used one or more 369 Range specifications. After several such transfers, a client might 370 have received several ranges of the same representation. These 371 ranges can only be safely combined if they all have in common the 372 same strong validator, where "strong validator" is defined to be 373 either an entity-tag that is not marked as weak (Section 2.3 of 374 [Part4]) or, if no entity-tag is provided, a Last-Modified value that 375 is strong in the sense defined by Section 2.2.2 of [Part4]. 377 When a client receives an incomplete 200 (OK) or 206 (Partial 378 Content) response and already has one or more stored responses for 379 the same method and effective request URI, all of the stored 380 responses with the same strong validator MAY be combined with the 381 partial content in this new response. If none of the stored 382 responses contain the same strong validator, then this new response 383 corresponds to a new representation and MUST NOT be combined with the 384 existing stored responses. 386 If the new response is an incomplete 200 (OK) response, then the 387 header fields of that new response are used for any combined response 388 and replace those of the matching stored responses. 390 If the new response is a 206 (Partial Content) response and at least 391 one of the matching stored responses is a 200 (OK), then the combined 392 response header fields consist of the most recent 200 response's 393 header fields. If all of the matching stored responses are 206 394 responses, then the stored response with the most header fields is 395 used as the source of header fields for the combined response, except 396 that the client MUST use other header fields provided in the new 397 response, aside from Content-Range, to replace all instances of the 398 corresponding header fields in the stored response. 400 The combined response message body consists of the union of partial 401 content ranges in the new response and each of the selected 402 responses. If the union consists of the entire range of the 403 representation, then the combined response MUST be recorded as a 404 complete 200 (OK) response with a Content-Length header field that 405 reflects the complete length. Otherwise, the combined response(s) 406 MUST include a Content-Range header field describing the included 407 range(s) and be recorded as incomplete. If the union consists of a 408 discontinuous range of the representation, then the client MAY store 409 it as either a multipart range response or as multiple 206 responses 410 with one continuous range each. 412 5. Header Field Definitions 414 This section defines the syntax and semantics of HTTP/1.1 header 415 fields related to range requests and partial responses. 417 5.1. Accept-Ranges 419 The "Accept-Ranges" header field allows a resource to indicate its 420 acceptance of range requests. 422 Accept-Ranges = acceptable-ranges 423 acceptable-ranges = 1#range-unit / "none" 425 Origin servers that accept byte-range requests MAY send 427 Accept-Ranges: bytes 429 but are not required to do so. Clients MAY generate range requests 430 without having received this header field for the resource involved. 432 Range units are defined in Section 2. 434 Servers that do not accept any kind of range request for a resource 435 MAY send 437 Accept-Ranges: none 439 to advise the client not to attempt a range request. 441 5.2. Content-Range 443 The "Content-Range" header field is sent with a partial 444 representation to specify where in the full representation the 445 payload body is intended to be applied. 447 Range units are defined in Section 2. 449 Content-Range = byte-content-range-spec 450 / other-content-range-spec 452 byte-content-range-spec = bytes-unit SP 453 byte-range-resp-spec "/" 454 ( instance-length / "*" ) 456 byte-range-resp-spec = (first-byte-pos "-" last-byte-pos) 457 / "*" 459 instance-length = 1*DIGIT 461 other-content-range-spec = other-range-unit SP 462 other-range-resp-spec 463 other-range-resp-spec = *CHAR 465 The header field SHOULD indicate the total length of the full 466 representation, unless this length is unknown or difficult to 467 determine. The asterisk "*" character means that the instance-length 468 is unknown at the time when the response was generated. 470 Unlike byte-ranges-specifier values (see Section 5.4.1), a byte- 471 range-resp-spec MUST only specify one range, and MUST contain 472 absolute byte positions for both the first and last byte of the 473 range. 475 A byte-content-range-spec with a byte-range-resp-spec whose last- 476 byte-pos value is less than its first-byte-pos value, or whose 477 instance-length value is less than or equal to its last-byte-pos 478 value, is invalid. The recipient of an invalid byte-content-range- 479 spec MUST ignore it and any content transferred along with it. 481 In the case of a byte range request: A server sending a response with 482 status code 416 (Requested range not satisfiable) SHOULD include a 483 Content-Range field with a byte-range-resp-spec of "*". The 484 instance-length specifies the current length of the selected 485 resource. A response with status code 206 (Partial Content) MUST NOT 486 include a Content-Range field with a byte-range-resp-spec of "*". 488 The "Content-Range" header field has no meaning for status codes that 489 do not explicitly describe its semantic. Currently, only status 490 codes 206 (Partial Content) and 416 (Requested range not satisfiable) 491 describe the meaning of this header field. 493 Examples of byte-content-range-spec values, assuming that the 494 representation contains a total of 1234 bytes: 496 o The first 500 bytes: 498 bytes 0-499/1234 500 o The second 500 bytes: 502 bytes 500-999/1234 504 o All except for the first 500 bytes: 506 bytes 500-1233/1234 508 o The last 500 bytes: 510 bytes 734-1233/1234 512 If the server ignores a byte-range-spec (for example if it is 513 syntactically invalid, or if it may be seen as a denial-of-service 514 attack), the server SHOULD treat the request as if the invalid Range 515 header field did not exist. (Normally, this means return a 200 516 response containing the full representation). 518 5.3. If-Range 520 If a client has a partial copy of a representation and wishes to have 521 an up-to-date copy of the entire representation, it could use the 522 Range header field with a conditional GET (using either or both of 523 If-Unmodified-Since and If-Match.) However, if the condition fails 524 because the representation has been modified, the client would then 525 have to make a second request to obtain the entire current 526 representation. 528 The "If-Range" header field allows a client to "short-circuit" the 529 second request. Informally, its meaning is "if the representation is 530 unchanged, send me the part(s) that I am missing; otherwise, send me 531 the entire new representation". 533 If-Range = entity-tag / HTTP-date 535 Clients MUST NOT use an entity-tag marked as weak in an If-Range 536 field value and MUST NOT use a Last-Modified date in an If-Range 537 field value unless it has no entity-tag for the representation and 538 the Last-Modified date it does have for the representation is strong 539 in the sense defined by Section 2.2.2 of [Part4]. 541 A server that evaluates a conditional range request that is 542 applicable to one of its representations MUST evaluate the condition 543 as false if the entity-tag used as a validator is marked as weak or, 544 when an HTTP-date is used as the validator, if the date value is not 545 strong in the sense defined by Section 2.2.2 of [Part4]. (A server 546 can distinguish between a valid HTTP-date and any form of entity-tag 547 by examining the first two characters.) 549 The If-Range header field SHOULD only be sent by clients together 550 with a Range header field. The If-Range header field MUST be ignored 551 if it is received in a request that does not include a Range header 552 field. The If-Range header field MUST be ignored by a server that 553 does not support the sub-range operation. 555 If the validator given in the If-Range header field matches the 556 current validator for the selected representation of the target 557 resource, then the server SHOULD send the specified sub-range of the 558 representation using a 206 (Partial Content) response. If the 559 validator does not match, then the server SHOULD send the entire 560 representation using a 200 (OK) response. 562 5.4. Range 564 5.4.1. Byte Ranges 566 Since all HTTP representations are transferred as sequences of bytes, 567 the concept of a byte range is meaningful for any HTTP 568 representation. (However, not all clients and servers need to 569 support byte-range operations.) 571 Byte range specifications in HTTP apply to the sequence of bytes in 572 the representation body (not necessarily the same as the message 573 body). 575 A byte range operation MAY specify a single range of bytes, or a set 576 of ranges within a single representation. 578 byte-ranges-specifier = bytes-unit "=" byte-range-set 579 byte-range-set = 1#( byte-range-spec / suffix-byte-range-spec ) 580 byte-range-spec = first-byte-pos "-" [ last-byte-pos ] 581 first-byte-pos = 1*DIGIT 582 last-byte-pos = 1*DIGIT 584 The first-byte-pos value in a byte-range-spec gives the byte-offset 585 of the first byte in a range. The last-byte-pos value gives the 586 byte-offset of the last byte in the range; that is, the byte 587 positions specified are inclusive. Byte offsets start at zero. 589 If the last-byte-pos value is present, it MUST be greater than or 590 equal to the first-byte-pos in that byte-range-spec, or the byte- 591 range-spec is syntactically invalid. The recipient of a byte-range- 592 set that includes one or more syntactically invalid byte-range-spec 593 values MUST ignore the header field that includes that byte-range- 594 set. 596 If the last-byte-pos value is absent, or if the value is greater than 597 or equal to the current length of the representation body, last-byte- 598 pos is taken to be equal to one less than the current length of the 599 representation in bytes. 601 By its choice of last-byte-pos, a client can limit the number of 602 bytes retrieved without knowing the size of the representation. 604 suffix-byte-range-spec = "-" suffix-length 605 suffix-length = 1*DIGIT 607 A suffix-byte-range-spec is used to specify the suffix of the 608 representation body, of a length given by the suffix-length value. 609 (That is, this form specifies the last N bytes of a representation.) 610 If the representation is shorter than the specified suffix-length, 611 the entire representation is used. 613 If a syntactically valid byte-range-set includes at least one byte- 614 range-spec whose first-byte-pos is less than the current length of 615 the representation, or at least one suffix-byte-range-spec with a 616 non-zero suffix-length, then the byte-range-set is satisfiable. 617 Otherwise, the byte-range-set is unsatisfiable. If the byte-range- 618 set is unsatisfiable, the server SHOULD return a response with a 416 619 (Requested range not satisfiable) status code. Otherwise, the server 620 SHOULD return a response with a 206 (Partial Content) status code 621 containing the satisfiable ranges of the representation. 623 Examples of byte-ranges-specifier values (assuming a representation 624 of length 10000): 626 o The first 500 bytes (byte offsets 0-499, inclusive): 628 bytes=0-499 630 o The second 500 bytes (byte offsets 500-999, inclusive): 632 bytes=500-999 634 o The final 500 bytes (byte offsets 9500-9999, inclusive): 636 bytes=-500 638 Or: 640 bytes=9500- 642 o The first and last bytes only (bytes 0 and 9999): 644 bytes=0-0,-1 646 o Several legal but not canonical specifications of the second 500 647 bytes (byte offsets 500-999, inclusive): 649 bytes=500-600,601-999 650 bytes=500-700,601-999 652 5.4.2. Range Retrieval Requests 654 The "Range" header field defines the GET method (conditional or not) 655 to request one or more sub-ranges of the response representation 656 body, instead of the entire representation body. 658 Range = byte-ranges-specifier / other-ranges-specifier 659 other-ranges-specifier = other-range-unit "=" other-range-set 660 other-range-set = 1*CHAR 662 A server MAY ignore the Range header field. However, origin servers 663 and intermediate caches ought to support byte ranges when possible, 664 since Range supports efficient recovery from partially failed 665 transfers, and supports efficient partial retrieval of large 666 representations. 668 If the server supports the Range header field and the specified range 669 or ranges are appropriate for the representation: 671 o The presence of a Range header field in an unconditional GET 672 modifies what is returned if the GET is otherwise successful. In 673 other words, the response carries a status code of 206 (Partial 674 Content) instead of 200 (OK). 676 o The presence of a Range header field in a conditional GET (a 677 request using one or both of If-Modified-Since and If-None-Match, 678 or one or both of If-Unmodified-Since and If-Match) modifies what 679 is returned if the GET is otherwise successful and the condition 680 is true. It does not affect the 304 (Not Modified) response 681 returned if the conditional is false. 683 In some cases, it might be more appropriate to use the If-Range 684 header field (see Section 5.3) in addition to the Range header field. 686 If a proxy that supports ranges receives a Range request, forwards 687 the request to an inbound server, and receives an entire 688 representation in reply, it MAY only return the requested range to 689 its client. 691 6. IANA Considerations 693 6.1. Status Code Registration 695 The HTTP Status Code Registry located at 696 shall be updated 697 with the registrations below: 699 +-------+---------------------------------+-------------+ 700 | Value | Description | Reference | 701 +-------+---------------------------------+-------------+ 702 | 206 | Partial Content | Section 3.1 | 703 | 416 | Requested Range Not Satisfiable | Section 3.2 | 704 +-------+---------------------------------+-------------+ 706 6.2. Header Field Registration 708 The Message Header Field Registry located at shall be 710 updated with the permanent registrations below (see [RFC3864]): 712 +-------------------+----------+----------+-------------+ 713 | Header Field Name | Protocol | Status | Reference | 714 +-------------------+----------+----------+-------------+ 715 | Accept-Ranges | http | standard | Section 5.1 | 716 | Content-Range | http | standard | Section 5.2 | 717 | If-Range | http | standard | Section 5.3 | 718 | Range | http | standard | Section 5.4 | 719 +-------------------+----------+----------+-------------+ 721 The change controller is: "IETF (iesg@ietf.org) - Internet 722 Engineering Task Force". 724 6.3. Range Specifier Registration 726 The registration procedure for HTTP Range Specifiers is defined by 727 Section 2.1 of this document. 729 The HTTP Range Specifier Registry shall be created at 730 and be 731 populated with the registrations below: 733 +----------------------+-------------------+----------------------+ 734 | Range Specifier Name | Description | Reference | 735 +----------------------+-------------------+----------------------+ 736 | bytes | a range of octets | (this specification) | 737 +----------------------+-------------------+----------------------+ 739 The change controller is: "IETF (iesg@ietf.org) - Internet 740 Engineering Task Force". 742 7. Security Considerations 744 This section is meant to inform application developers, information 745 providers, and users of the security limitations in HTTP/1.1 as 746 described by this document. The discussion does not include 747 definitive solutions to the problems revealed, though it does make 748 some suggestions for reducing security risks. 750 7.1. Overlapping Ranges 752 Range requests containing overlapping ranges may lead to the 753 situation where a server is sending far more data than the size of 754 the complete resource representation. 756 8. Acknowledgments 758 See Section 9 of [Part1]. 760 9. References 762 9.1. Normative References 764 [Part1] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 765 "HTTP/1.1, part 1: URIs, Connections, and Message 766 Parsing", draft-ietf-httpbis-p1-messaging-19 (work in 767 progress), March 2012. 769 [Part2] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 770 "HTTP/1.1, part 2: Message Semantics", 771 draft-ietf-httpbis-p2-semantics-19 (work in progress), 772 March 2012. 774 [Part4] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 775 "HTTP/1.1, part 4: Conditional Requests", 776 draft-ietf-httpbis-p4-conditional-19 (work in progress), 777 March 2012. 779 [Part6] Fielding, R., Ed., Lafon, Y., Ed., Nottingham, M., Ed., 780 and J. Reschke, Ed., "HTTP/1.1, part 6: Caching", 781 draft-ietf-httpbis-p6-cache-19 (work in progress), 782 March 2012. 784 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 785 Extensions (MIME) Part Two: Media Types", RFC 2046, 786 November 1996. 788 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 789 Requirement Levels", BCP 14, RFC 2119, March 1997. 791 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 792 Specifications: ABNF", STD 68, RFC 5234, January 2008. 794 9.2. Informative References 796 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 797 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 798 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 800 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 801 Procedures for Message Header Fields", BCP 90, RFC 3864, 802 September 2004. 804 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 805 Registration Procedures", BCP 13, RFC 4288, December 2005. 807 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 808 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 809 May 2008. 811 Appendix A. Internet Media Type multipart/byteranges 813 When an HTTP 206 (Partial Content) response message includes the 814 content of multiple ranges (a response to a request for multiple non- 815 overlapping ranges), these are transmitted as a multipart message 816 body ([RFC2046], Section 5.1). The media type for this purpose is 817 called "multipart/byteranges". The following is to be registered 818 with IANA [RFC4288]. 820 Note: Despite the name "multipart/byteranges" is not limited to 821 the byte ranges only. 823 The multipart/byteranges media type includes one or more parts, each 824 with its own Content-Type and Content-Range fields. The required 825 boundary parameter specifies the boundary string used to separate 826 each body-part. 828 Type name: multipart 830 Subtype name: byteranges 832 Required parameters: boundary 834 Optional parameters: none 836 Encoding considerations: only "7bit", "8bit", or "binary" are 837 permitted 839 Security considerations: none 841 Interoperability considerations: none 843 Published specification: This specification (see Appendix A). 845 Applications that use this media type: 847 Additional information: 849 Magic number(s): none 851 File extension(s): none 853 Macintosh file type code(s): none 855 Person and email address to contact for further information: See 856 Authors Section. 858 Intended usage: COMMON 860 Restrictions on usage: none 862 Author/Change controller: IESG 863 For example: 865 HTTP/1.1 206 Partial Content 866 Date: Wed, 15 Nov 1995 06:25:24 GMT 867 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 868 Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 870 --THIS_STRING_SEPARATES 871 Content-type: application/pdf 872 Content-range: bytes 500-999/8000 874 ...the first range... 875 --THIS_STRING_SEPARATES 876 Content-type: application/pdf 877 Content-range: bytes 7000-7999/8000 879 ...the second range 880 --THIS_STRING_SEPARATES-- 882 Other example: 884 HTTP/1.1 206 Partial Content 885 Date: Tue, 14 Nov 1995 06:25:24 GMT 886 Last-Modified: Tue, 14 July 04:58:08 GMT 887 Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 889 --THIS_STRING_SEPARATES 890 Content-type: video/example 891 Content-range: exampleunit 1.2-4.3/25 893 ...the first range... 894 --THIS_STRING_SEPARATES 895 Content-type: video/example 896 Content-range: exampleunit 11.2-14.3/25 898 ...the second range 899 --THIS_STRING_SEPARATES-- 901 Notes: 903 1. Additional CRLFs MAY precede the first boundary string in the 904 body. 906 2. Although [RFC2046] permits the boundary string to be quoted, some 907 existing implementations handle a quoted boundary string 908 incorrectly. 910 3. A number of browsers and servers were coded to an early draft of 911 the byteranges specification to use a media type of multipart/ 912 x-byteranges, which is almost, but not quite compatible with the 913 version documented in HTTP/1.1. 915 Appendix B. Changes from RFC 2616 917 Clarify that it is not ok to use a weak validator in a 206 response. 918 (Section 3.1) 920 Change ABNF productions for header fields to only define the field 921 value. (Section 5) 923 Clarify that multipart/byteranges can consist of a single part. 924 (Appendix A) 926 Appendix C. Collected ABNF 928 Accept-Ranges = acceptable-ranges 930 Content-Range = byte-content-range-spec / other-content-range-spec 932 HTTP-date = 934 If-Range = entity-tag / HTTP-date 936 OWS = 938 Range = byte-ranges-specifier / other-ranges-specifier 940 acceptable-ranges = ( *( "," OWS ) range-unit *( OWS "," [ OWS 941 range-unit ] ) ) / "none" 943 byte-content-range-spec = bytes-unit SP byte-range-resp-spec "/" ( 944 instance-length / "*" ) 945 byte-range-resp-spec = ( first-byte-pos "-" last-byte-pos ) / "*" 946 byte-range-set = ( *( "," OWS ) byte-range-spec ) / ( 947 suffix-byte-range-spec *( OWS "," [ ( OWS byte-range-spec ) / 948 suffix-byte-range-spec ] ) ) 949 byte-range-spec = first-byte-pos "-" [ last-byte-pos ] 950 byte-ranges-specifier = bytes-unit "=" byte-range-set 951 bytes-unit = "bytes" 953 entity-tag = 955 first-byte-pos = 1*DIGIT 957 instance-length = 1*DIGIT 959 last-byte-pos = 1*DIGIT 961 other-content-range-spec = other-range-unit SP other-range-resp-spec 962 other-range-resp-spec = *CHAR 963 other-range-set = 1*CHAR 964 other-range-unit = token 965 other-ranges-specifier = other-range-unit "=" other-range-set 967 range-unit = bytes-unit / other-range-unit 969 suffix-byte-range-spec = "-" suffix-length 970 suffix-length = 1*DIGIT 972 token = 973 ABNF diagnostics: 975 ; Accept-Ranges defined but not used 976 ; Content-Range defined but not used 977 ; If-Range defined but not used 978 ; Range defined but not used 980 Appendix D. Change Log (to be removed by RFC Editor before publication) 982 D.1. Since RFC 2616 984 Extracted relevant partitions from [RFC2616]. 986 D.2. Since draft-ietf-httpbis-p5-range-00 988 Closed issues: 990 o : "Cache 991 validators in 206 responses" 992 () 994 o : "Normative and 995 Informative references" 997 o : "Normative up- 998 to-date references" 1000 D.3. Since draft-ietf-httpbis-p5-range-01 1002 Closed issues: 1004 o : "Updating to 1005 RFC4288" 1007 Ongoing work on ABNF conversion 1008 (): 1010 o Add explicit references to BNF syntax and rules imported from 1011 other parts of the specification. 1013 D.4. Since draft-ietf-httpbis-p5-range-02 1015 Ongoing work on IANA Message Header Field Registration 1016 (): 1018 o Reference RFC 3984, and update header field registrations for 1019 headers defined in this document. 1021 D.5. Since draft-ietf-httpbis-p5-range-03 1023 None. 1025 D.6. Since draft-ietf-httpbis-p5-range-04 1027 Closed issues: 1029 o : "multipart/ 1030 byteranges minimum number of parts" 1032 Ongoing work on ABNF conversion 1033 (): 1035 o Use "/" instead of "|" for alternatives. 1037 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 1038 whitespace ("OWS") and required whitespace ("RWS"). 1040 o Rewrite ABNFs to spell out whitespace rules, factor out header 1041 field value format definitions. 1043 D.7. Since draft-ietf-httpbis-p5-range-05 1045 Closed issues: 1047 o : "State base 1048 for *-byte-pos and suffix-length" 1050 Ongoing work on Custom Ranges 1051 (): 1053 o Remove bias in favor of byte ranges; allow custom ranges in ABNF. 1055 Final work on ABNF conversion 1056 (): 1058 o Add appendix containing collected and expanded ABNF, reorganize 1059 ABNF introduction. 1061 D.8. Since draft-ietf-httpbis-p5-range-06 1063 Closed issues: 1065 o : "base for 1066 numeric protocol elements" 1068 D.9. Since draft-ietf-httpbis-p5-range-07 1070 Closed issues: 1072 o Fixed discrepancy in the If-Range definition about allowed 1073 validators. 1075 o : "multipart/ 1076 byteranges for custom range units" 1078 o : "range unit 1079 missing from other-ranges-specifier in Range header" 1081 o : "move IANA 1082 registrations for optional status codes" 1084 D.10. Since draft-ietf-httpbis-p5-range-08 1086 No significant changes. 1088 D.11. Since draft-ietf-httpbis-p5-range-09 1090 No significant changes. 1092 D.12. Since draft-ietf-httpbis-p5-range-10 1094 Closed issues: 1096 o : "Clarify 1097 'Requested Variant'" 1099 o : "Clarify 1100 entity / representation / variant terminology" 1102 o : "consider 1103 removing the 'changes from 2068' sections" 1105 Ongoing work on Custom Ranges 1106 (): 1108 o Add IANA registry. 1110 D.13. Since draft-ietf-httpbis-p5-range-11 1112 Closed issues: 1114 o : "Caches can't 1115 be required to serve ranges" 1117 D.14. Since draft-ietf-httpbis-p5-range-12 1119 Closed issues: 1121 o : "Header 1122 Classification" 1124 D.15. Since draft-ietf-httpbis-p5-range-13 1126 Closed issues: 1128 o : "untangle 1129 ABNFs for header fields" 1131 D.16. Since draft-ietf-httpbis-p5-range-14 1133 None. 1135 D.17. Since draft-ietf-httpbis-p5-range-15 1137 Closed issues: 1139 o : "Security 1140 consideration: range flooding" 1142 D.18. Since draft-ietf-httpbis-p5-range-16 1144 Closed issues: 1146 o : "Document 1147 HTTP's error-handling philosophy" 1149 o : "Content- 1150 Range on responses other than 206" 1152 o : "case 1153 sensitivity of ranges in p5" 1155 D.19. Since draft-ietf-httpbis-p5-range-17 1157 None. 1159 D.20. Since draft-ietf-httpbis-p5-range-18 1161 Closed issues: 1163 o : "Add 1164 limitations to Range to reduce its use as a denial-of-service 1165 tool" 1167 Index 1169 2 1170 206 Partial Content (status code) 6 1172 4 1173 416 Requested Range Not Satisfiable (status code) 7 1175 A 1176 Accept-Ranges header field 9 1178 C 1179 Content-Range header field 10 1181 G 1182 Grammar 1183 Accept-Ranges 9 1184 acceptable-ranges 9 1185 byte-content-range-spec 10 1186 byte-range-resp-spec 10 1187 byte-range-set 13 1188 byte-range-spec 13 1189 byte-ranges-specifier 13 1190 bytes-unit 5 1191 Content-Range 10 1192 first-byte-pos 13 1193 If-Range 12 1194 instance-length 10 1195 last-byte-pos 13 1196 other-range-unit 5 1197 Range 14 1198 range-unit 5 1199 ranges-specifier 13 1200 suffix-byte-range-spec 13 1201 suffix-length 13 1203 H 1204 Header Fields 1205 Accept-Ranges 9 1206 Content-Range 10 1207 If-Range 11 1208 Range 12 1210 I 1211 If-Range header field 11 1213 M 1214 Media Type 1215 multipart/byteranges 17 1216 multipart/x-byteranges 20 1217 multipart/byteranges Media Type 17 1218 multipart/x-byteranges Media Type 20 1220 R 1221 Range header field 12 1223 S 1224 Status Codes 1225 206 Partial Content 6 1226 416 Requested Range Not Satisfiable 7 1228 Authors' Addresses 1230 Roy T. Fielding (editor) 1231 Adobe Systems Incorporated 1232 345 Park Ave 1233 San Jose, CA 95110 1234 USA 1236 EMail: fielding@gbiv.com 1237 URI: http://roy.gbiv.com/ 1239 Yves Lafon (editor) 1240 World Wide Web Consortium 1241 W3C / ERCIM 1242 2004, rte des Lucioles 1243 Sophia-Antipolis, AM 06902 1244 France 1246 EMail: ylafon@w3.org 1247 URI: http://www.raubacapeu.net/people/yves/ 1248 Julian F. Reschke (editor) 1249 greenbytes GmbH 1250 Hafenweg 16 1251 Muenster, NW 48155 1252 Germany 1254 Phone: +49 251 2807760 1255 Fax: +49 251 2807761 1256 EMail: julian.reschke@greenbytes.de 1257 URI: http://greenbytes.de/tech/webdav/