source: draft-ietf-httpbis/latest/auth48/rfc7233-to-be.unpg.txt @ 2705

Last change on this file since 2705 was 2690, checked in by julian.reschke@…, 6 years ago

updated AUTH48 version of RFC7233 (#553)

  • Property svn:eol-style set to native
File size: 45.4 KB
Line 
1
2
3
4Internet Engineering Task Force (IETF)                  R. Fielding, Ed.
5Request for Comments: 7233                                         Adobe
6Obsoletes: 2616                                            Y. Lafon, Ed.
7Category: Standards Track                                            W3C
8ISSN: 2070-1721                                          J. Reschke, Ed.
9                                                              greenbytes
10                                                                May 2014
11
12
13         Hypertext Transfer Protocol (HTTP/1.1): Range Requests
14
15Abstract
16
17   The Hypertext Transfer Protocol (HTTP) is a stateless application-
18   level protocol for distributed, collaborative, hypertext information
19   systems.  This document defines range requests and the rules for
20   constructing and combining responses to those requests.
21
22Status of This Memo
23
24   This is an Internet Standards Track document.
25
26   This document is a product of the Internet Engineering Task Force
27   (IETF).  It represents the consensus of the IETF community.  It has
28   received public review and has been approved for publication by the
29   Internet Engineering Steering Group (IESG).  Further information on
30   Internet Standards is available in Section 2 of RFC 5741.
31
32   Information about the current status of this document, any errata,
33   and how to provide feedback on it may be obtained at
34   http://www.rfc-editor.org/info/rfc7233.
35
36Copyright Notice
37
38   Copyright (c) 2014 IETF Trust and the persons identified as the
39   document authors.  All rights reserved.
40
41   This document is subject to BCP 78 and the IETF Trust's Legal
42   Provisions Relating to IETF Documents
43   (http://trustee.ietf.org/license-info) in effect on the date of
44   publication of this document.  Please review these documents
45   carefully, as they describe your rights and restrictions with respect
46   to this document.  Code Components extracted from this document must
47   include Simplified BSD License text as described in Section 4.e of
48   the Trust Legal Provisions and are provided without warranty as
49   described in the Simplified BSD License.
50
51   This document may contain material from IETF Documents or IETF
52
53
54
55Fielding, et al.             Standards Track                    [Page 1]
56
57RFC 7233                 HTTP/1.1 Range Requests                May 2014
58
59
60   Contributions published or made publicly available before November
61   10, 2008.  The person(s) controlling the copyright in some of this
62   material may not have granted the IETF Trust the right to allow
63   modifications of such material outside the IETF Standards Process.
64   Without obtaining an adequate license from the person(s) controlling
65   the copyright in such materials, this document may not be modified
66   outside the IETF Standards Process, and derivative works of it may
67   not be created outside the IETF Standards Process, except to format
68   it for publication as an RFC or to translate it into languages other
69   than English.
70
71Table of Contents
72
73   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
74     1.1.  Conformance and Error Handling . . . . . . . . . . . . . .  3
75     1.2.  Syntax Notation  . . . . . . . . . . . . . . . . . . . . .  3
76   2.  Range Units  . . . . . . . . . . . . . . . . . . . . . . . . .  3
77     2.1.  Byte Ranges  . . . . . . . . . . . . . . . . . . . . . . .  4
78     2.2.  Other Range Units  . . . . . . . . . . . . . . . . . . . .  6
79     2.3.  Accept-Ranges  . . . . . . . . . . . . . . . . . . . . . .  6
80   3.  Range Requests . . . . . . . . . . . . . . . . . . . . . . . .  6
81     3.1.  Range  . . . . . . . . . . . . . . . . . . . . . . . . . .  6
82     3.2.  If-Range . . . . . . . . . . . . . . . . . . . . . . . . .  8
83   4.  Responses to a Range Request . . . . . . . . . . . . . . . . .  9
84     4.1.  206 Partial Content  . . . . . . . . . . . . . . . . . . .  9
85     4.2.  Content-Range  . . . . . . . . . . . . . . . . . . . . . . 11
86     4.3.  Combining Ranges . . . . . . . . . . . . . . . . . . . . . 13
87     4.4.  416 Range Not Satisfiable  . . . . . . . . . . . . . . . . 14
88   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 14
89     5.1.  Range Unit Registry  . . . . . . . . . . . . . . . . . . . 14
90       5.1.1.  Procedure  . . . . . . . . . . . . . . . . . . . . . . 14
91       5.1.2.  Registrations  . . . . . . . . . . . . . . . . . . . . 15
92     5.2.  Status Code Registration . . . . . . . . . . . . . . . . . 15
93     5.3.  Header Field Registration  . . . . . . . . . . . . . . . . 15
94     5.4.  Internet Media Type Registration . . . . . . . . . . . . . 16
95       5.4.1.  Internet Media Type multipart/byteranges . . . . . . . 16
96   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 17
97     6.1.  Denial-of-Service Attacks Using Range  . . . . . . . . . . 17
98   7.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 17
99   8.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 18
100     8.1.  Normative References . . . . . . . . . . . . . . . . . . . 18
101     8.2.  Informative References . . . . . . . . . . . . . . . . . . 18
102   Appendix A.  Internet Media Type multipart/byteranges  . . . . . . 19
103   Appendix B.  Changes from RFC 2616 . . . . . . . . . . . . . . . . 20
104   Appendix C.  Imported ABNF . . . . . . . . . . . . . . . . . . . . 20
105   Appendix D.  Collected ABNF  . . . . . . . . . . . . . . . . . . . 20
106   Index  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
107
108
109
110
111Fielding, et al.             Standards Track                    [Page 2]
112
113RFC 7233                 HTTP/1.1 Range Requests                May 2014
114
115
1161.  Introduction
117
118   Hypertext Transfer Protocol (HTTP) clients often encounter
119   interrupted data transfers as a result of canceled requests or
120   dropped connections.  When a client has stored a partial
121   representation, it is desirable to request the remainder of that
122   representation in a subsequent request rather than transfer the
123   entire representation.  Likewise, devices with limited local storage
124   might benefit from being able to request only a subset of a larger
125   representation, such as a single page of a very large document, or
126   the dimensions of an embedded image.
127
128   This document defines HTTP/1.1 range requests, partial responses, and
129   the multipart/byteranges media type.  Range requests are an OPTIONAL
130   feature of HTTP, designed so that recipients not implementing this
131   feature (or not supporting it for the target resource) can respond as
132   if it is a normal GET request without impacting interoperability.
133   Partial responses are indicated by a distinct status code to not be
134   mistaken for full responses by caches that might not implement the
135   feature.
136
137   Although the range request mechanism is designed to allow for
138   extensible range types, this specification only defines requests for
139   byte ranges.
140
1411.1.  Conformance and Error Handling
142
143   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
144   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
145   document are to be interpreted as described in [RFC2119].
146
147   Conformance criteria and considerations regarding error handling are
148   defined in Section 2.5 of [RFC7230].
149
1501.2.  Syntax Notation
151
152   This specification uses the Augmented Backus-Naur Form (ABNF)
153   notation of [RFC5234] with a list extension, defined in Section 7 of
154   [RFC7230], that allows for compact definition of comma-separated
155   lists using a '#' operator (similar to how the '*' operator indicates
156   repetition).  Appendix C describes rules imported from other
157   documents.  Appendix D shows the collected grammar with all list
158   operators expanded to standard ABNF notation.
159
1602.  Range Units
161
162   A representation can be partitioned into subranges according to
163   various structural units, depending on the structure inherent in the
164
165
166
167Fielding, et al.             Standards Track                    [Page 3]
168
169RFC 7233                 HTTP/1.1 Range Requests                May 2014
170
171
172   representation's media type.  This "range unit" is used in the
173   Accept-Ranges (Section 2.3) response header field to advertise
174   support for range requests, the Range (Section 3.1) request header
175   field to delineate the parts of a representation that are requested,
176   and the Content-Range (Section 4.2) payload header field to describe
177   which part of a representation is being transferred.
178
179     range-unit       = bytes-unit / other-range-unit
180
1812.1.  Byte Ranges
182
183   Since representation data is transferred in payloads as a sequence of
184   octets, a byte range is a meaningful substructure for any
185   representation transferable over HTTP (Section 3 of [RFC7231]).  The
186   "bytes" range unit is defined for expressing subranges of the data's
187   octet sequence.
188
189     bytes-unit       = "bytes"
190
191   A byte-range request can specify a single range of bytes or a set of
192   ranges within a single representation.
193
194     byte-ranges-specifier = bytes-unit "=" byte-range-set
195     byte-range-set  = 1#( byte-range-spec / suffix-byte-range-spec )
196     byte-range-spec = first-byte-pos "-" [ last-byte-pos ]
197     first-byte-pos  = 1*DIGIT
198     last-byte-pos   = 1*DIGIT
199
200   The first-byte-pos value in a byte-range-spec gives the byte-offset
201   of the first byte in a range.  The last-byte-pos value gives the
202   byte-offset of the last byte in the range; that is, the byte
203   positions specified are inclusive.  Byte offsets start at zero.
204
205   Examples of byte-ranges-specifier values:
206
207   o  The first 500 bytes (byte offsets 0-499, inclusive):
208
209        bytes=0-499
210
211   o  The second 500 bytes (byte offsets 500-999, inclusive):
212
213        bytes=500-999
214
215   A byte-range-spec is invalid if the last-byte-pos value is present
216   and less than the first-byte-pos.
217
218   A client can limit the number of bytes requested without knowing the
219   size of the selected representation.  If the last-byte-pos value is
220
221
222
223Fielding, et al.             Standards Track                    [Page 4]
224
225RFC 7233                 HTTP/1.1 Range Requests                May 2014
226
227
228   absent, or if the value is greater than or equal to the current
229   length of the representation data, the byte range is interpreted as
230   the remainder of the representation (i.e., the server replaces the
231   value of last-byte-pos with a value that is one less than the current
232   length of the selected representation).
233
234   A client can request the last N bytes of the selected representation
235   using a suffix-byte-range-spec.
236
237     suffix-byte-range-spec = "-" suffix-length
238     suffix-length = 1*DIGIT
239
240   If the selected representation is shorter than the specified suffix-
241   length, the entire representation is used.
242
243   Additional examples, assuming a representation of length 10000:
244
245   o  The final 500 bytes (byte offsets 9500-9999, inclusive):
246
247        bytes=-500
248
249      Or:
250
251        bytes=9500-
252
253   o  The first and last bytes only (bytes 0 and 9999):
254
255        bytes=0-0,-1
256
257   o  Other valid (but not canonical) specifications of the second 500
258      bytes (byte offsets 500-999, inclusive):
259
260        bytes=500-600,601-999
261        bytes=500-700,601-999
262
263   If a valid byte-range-set includes at least one byte-range-spec with
264   a first-byte-pos that is less than the current length of the
265   representation, or at least one suffix-byte-range-spec with a non-
266   zero suffix-length, then the byte-range-set is satisfiable.
267   Otherwise, the byte-range-set is unsatisfiable.
268
269   In the byte-range syntax, first-byte-pos, last-byte-pos, and suffix-
270   length are expressed as decimal number of octets.  Since there is no
271   predefined limit to the length of a payload, recipients MUST
272   anticipate potentially large decimal numerals and prevent parsing
273   errors due to integer conversion overflows.
274
275
276
277
278
279Fielding, et al.             Standards Track                    [Page 5]
280
281RFC 7233                 HTTP/1.1 Range Requests                May 2014
282
283
2842.2.  Other Range Units
285
286   Range units are intended to be extensible.  New range units ought to
287   be registered with IANA, as defined in Section 5.1.
288
289     other-range-unit = token
290
2912.3.  Accept-Ranges
292
293   The "Accept-Ranges" header field allows a server to indicate that it
294   supports range requests for the target resource.
295
296     Accept-Ranges     = acceptable-ranges
297     acceptable-ranges = 1#range-unit / "none"
298
299   An origin server that supports byte-range requests for a given target
300   resource MAY send
301
302     Accept-Ranges: bytes
303
304   to indicate what range units are supported.  A client MAY generate
305   range requests without having received this header field for the
306   resource involved.  Range units are defined in Section 2.
307
308   A server that does not support any kind of range request for the
309   target resource MAY send
310
311     Accept-Ranges: none
312
313   to advise the client not to attempt a range request.
314
3153.  Range Requests
316
3173.1.  Range
318
319   The "Range" header field on a GET request modifies the method
320   semantics to request transfer of only one or more subranges of the
321   selected representation data, rather than the entire selected
322   representation data.
323
324     Range = byte-ranges-specifier / other-ranges-specifier
325     other-ranges-specifier = other-range-unit "=" other-range-set
326     other-range-set = 1*VCHAR
327
328   A server MAY ignore the Range header field.  However, origin servers
329   and intermediate caches ought to support byte ranges when possible,
330   since Range supports efficient recovery from partially failed
331   transfers and partial retrieval of large representations.  A server
332
333
334
335Fielding, et al.             Standards Track                    [Page 6]
336
337RFC 7233                 HTTP/1.1 Range Requests                May 2014
338
339
340   MUST ignore a Range header field received with a request method other
341   than GET.
342
343   An origin server MUST ignore a Range header field that contains a
344   range unit it does not understand.  A proxy MAY discard a Range
345   header field that contains a range unit it does not understand.
346
347   A server that supports range requests MAY ignore or reject a Range
348   header field that consists of more than two overlapping ranges, or a
349   set of many small ranges that are not listed in ascending order,
350   since both are indications of either a broken client or a deliberate
351   denial-of-service attack (Section 6.1).  A client SHOULD NOT request
352   multiple ranges that are inherently less efficient to process and
353   transfer than a single range that encompasses the same data.
354
355   A client that is requesting multiple ranges SHOULD list those ranges
356   in ascending order (the order in which they would typically be
357   received in a complete representation) unless there is a specific
358   need to request a later part earlier.  For example, a user agent
359   processing a large representation with an internal catalog of parts
360   might need to request later parts first, particularly if the
361   representation consists of pages stored in reverse order and the user
362   agent wishes to transfer one page at a time.
363
364   The Range header field is evaluated after evaluating the precondition
365   header fields defined in [RFC7232], and only if the result in absence
366   of the Range header field would be a 200 (OK) response.  In other
367   words, Range is ignored when a conditional GET would result in a 304
368   (Not Modified) response.
369
370   The If-Range header field (Section 3.2) can be used as a precondition
371   to applying the Range header field.
372
373   If all of the preconditions are true, the server supports the Range
374   header field for the target resource, and the specified range(s) are
375   valid and satisfiable (as defined in Section 2.1), the server SHOULD
376   send a 206 (Partial Content) response with a payload containing one
377   or more partial representations that correspond to the satisfiable
378   ranges requested, as defined in Section 4.
379
380   If all of the preconditions are true, the server supports the Range
381   header field for the target resource, and the specified range(s) are
382   invalid or unsatisfiable, the server SHOULD send a 416 (Range Not
383   Satisfiable) response.
384
385
386
387
388
389
390
391Fielding, et al.             Standards Track                    [Page 7]
392
393RFC 7233                 HTTP/1.1 Range Requests                May 2014
394
395
3963.2.  If-Range
397
398   If a client has a partial copy of a representation and wishes to have
399   an up-to-date copy of the entire representation, it could use the
400   Range header field with a conditional GET (using either or both of
401   If-Unmodified-Since and If-Match.)  However, if the precondition
402   fails because the representation has been modified, the client would
403   then have to make a second request to obtain the entire current
404   representation.
405
406   The "If-Range" header field allows a client to "short-circuit" the
407   second request.  Informally, its meaning is as follows: if the
408   representation is unchanged, send me the part(s) that I am requesting
409   in Range; otherwise, send me the entire representation.
410
411     If-Range = entity-tag / HTTP-date
412
413   A client MUST NOT generate an If-Range header field in a request that
414   does not contain a Range header field.  A server MUST ignore an
415   If-Range header field received in a request that does not contain a
416   Range header field.  An origin server MUST ignore an If-Range header
417   field received in a request for a target resource that does not
418   support Range requests.
419
420   A client MUST NOT generate an If-Range header field containing an
421   entity-tag that is marked as weak.  A client MUST NOT generate an If-
422   Range header field containing an HTTP-date unless the client has no
423   entity-tag for the corresponding representation and the date is a
424   strong validator in the sense defined by Section 2.2.2 of [RFC7232].
425
426   A server that evaluates an If-Range precondition MUST use the strong
427   comparison function when comparing entity-tags (Section 2.3.2 of
428   [RFC7232]) and MUST evaluate the condition as false if an HTTP-date
429   validator is provided that is not a strong validator in the sense
430   defined by Section 2.2.2 of [RFC7232].  A valid entity-tag can be
431   distinguished from a valid HTTP-date by examining the first two
432   characters for a DQUOTE.
433
434   If the validator given in the If-Range header field matches the
435   current validator for the selected representation of the target
436   resource, then the server SHOULD process the Range header field as
437   requested.  If the validator does not match, the server MUST ignore
438   the Range header field.  Note that this comparison by exact match,
439   including when the validator is an HTTP-date, differs from the
440   "earlier than or equal to" comparison used when evaluating an
441   If-Unmodified-Since conditional.
442
443
444
445
446
447Fielding, et al.             Standards Track                    [Page 8]
448
449RFC 7233                 HTTP/1.1 Range Requests                May 2014
450
451
4524.  Responses to a Range Request
453
4544.1.  206 Partial Content
455
456   The 206 (Partial Content) status code indicates that the server is
457   successfully fulfilling a range request for the target resource by
458   transferring one or more parts of the selected representation that
459   correspond to the satisfiable ranges found in the request's Range
460   header field (Section 3.1).
461
462   If a single part is being transferred, the server generating the 206
463   response MUST generate a Content-Range header field, describing what
464   range of the selected representation is enclosed, and a payload
465   consisting of the range.  For example:
466
467     HTTP/1.1 206 Partial Content
468     Date: Wed, 15 Nov 1995 06:25:24 GMT
469     Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
470     Content-Range: bytes 21010-47021/47022
471     Content-Length: 26012
472     Content-Type: image/gif
473
474     ... 26012 bytes of partial image data ...
475
476   If multiple parts are being transferred, the server generating the
477   206 response MUST generate a "multipart/byteranges" payload, as
478   defined in Appendix A, and a Content-Type header field containing the
479   multipart/byteranges media type and its required boundary parameter.
480   To avoid confusion with single-part responses, a server MUST NOT
481   generate a Content-Range header field in the HTTP header section of a
482   multiple part response (this field will be sent in each part
483   instead).
484
485   Within the header area of each body part in the multipart payload,
486   the server MUST generate a Content-Range header field corresponding
487   to the range being enclosed in that body part.  If the selected
488   representation would have had a Content-Type header field in a 200
489   (OK) response, the server SHOULD generate that same Content-Type
490   field in the header area of each body part.  For example:
491
492
493
494
495
496
497
498
499
500
501
502
503Fielding, et al.             Standards Track                    [Page 9]
504
505RFC 7233                 HTTP/1.1 Range Requests                May 2014
506
507
508     HTTP/1.1 206 Partial Content
509     Date: Wed, 15 Nov 1995 06:25:24 GMT
510     Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
511     Content-Length: 1741
512     Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES
513
514     --THIS_STRING_SEPARATES
515     Content-Type: application/pdf
516     Content-Range: bytes 500-999/8000
517
518     ...the first range...
519     --THIS_STRING_SEPARATES
520     Content-Type: application/pdf
521     Content-Range: bytes 7000-7999/8000
522
523     ...the second range
524     --THIS_STRING_SEPARATES--
525
526   When multiple ranges are requested, a server MAY coalesce any of the
527   ranges that overlap, or that are separated by a gap that is smaller
528   than the overhead of sending multiple parts, regardless of the order
529   in which the corresponding byte-range-spec appeared in the received
530   Range header field.  Since the typical overhead between parts of a
531   multipart/byteranges payload is around 80 bytes, depending on the
532   selected representation's media type and the chosen boundary
533   parameter length, it can be less efficient to transfer many small
534   disjoint parts than it is to transfer the entire selected
535   representation.
536
537   A server MUST NOT generate a multipart response to a request for a
538   single range, since a client that does not request multiple parts
539   might not support multipart responses.  However, a server MAY
540   generate a multipart/byteranges payload with only a single body part
541   if multiple ranges were requested and only one range was found to be
542   satisfiable or only one range remained after coalescing.  A client
543   that cannot process a multipart/byteranges response MUST NOT generate
544   a request that asks for multiple ranges.
545
546   When a multipart response payload is generated, the server SHOULD
547   send the parts in the same order that the corresponding byte-range-
548   spec appeared in the received Range header field, excluding those
549   ranges that were deemed unsatisfiable or that were coalesced into
550   other ranges.  A client that receives a multipart response MUST
551   inspect the Content-Range header field present in each body part in
552   order to determine which range is contained in that body part; a
553   client cannot rely on receiving the same ranges that it requested,
554   nor the same order that it requested.
555
556
557
558
559Fielding, et al.             Standards Track                   [Page 10]
560
561RFC 7233                 HTTP/1.1 Range Requests                May 2014
562
563
564   When a 206 response is generated, the server MUST generate the
565   following header fields, in addition to those required above, if the
566   field would have been sent in a 200 (OK) response to the same
567   request: Date, Cache-Control, ETag, Expires, Content-Location, and
568   Vary.
569
570   If a 206 is generated in response to a request with an If-Range
571   header field, the sender SHOULD NOT generate other representation
572   header fields beyond those required above, because the client is
573   understood to already have a prior response containing those header
574   fields.  Otherwise, the sender MUST generate all of the
575   representation header fields that would have been sent in a 200 (OK)
576   response to the same request.
577
578   A 206 response is cacheable by default; i.e., unless otherwise
579   indicated by explicit cache controls (see Section 4.2.2 of
580   [RFC7234]).
581
5824.2.  Content-Range
583
584   The "Content-Range" header field is sent in a single part 206
585   (Partial Content) response to indicate the partial range of the
586   selected representation enclosed as the message payload, sent in each
587   part of a multipart 206 response to indicate the range enclosed
588   within each body part, and sent in 416 (Range Not Satisfiable)
589   responses to provide information about the selected representation.
590
591     Content-Range       = byte-content-range
592                         / other-content-range
593
594     byte-content-range  = bytes-unit SP
595                           ( byte-range-resp / unsatisfied-range )
596
597     byte-range-resp     = byte-range "/" ( complete-length / "*" )
598     byte-range          = first-byte-pos "-" last-byte-pos
599     unsatisfied-range   = "*/" complete-length
600
601     complete-length     = 1*DIGIT
602
603     other-content-range = other-range-unit SP other-range-resp
604     other-range-resp    = *CHAR
605
606   If a 206 (Partial Content) response contains a Content-Range header
607   field with a range unit (Section 2) that the recipient does not
608   understand, the recipient MUST NOT attempt to recombine it with a
609   stored representation.  A proxy that receives such a message SHOULD
610   forward it downstream.
611
612
613
614
615Fielding, et al.             Standards Track                   [Page 11]
616
617RFC 7233                 HTTP/1.1 Range Requests                May 2014
618
619
620   For byte ranges, a sender SHOULD indicate the complete length of the
621   representation from which the range has been extracted, unless the
622   complete length is unknown or difficult to determine.  An asterisk
623   character ("*") in place of the complete-length indicates that the
624   representation length was unknown when the header field was
625   generated.
626
627   The following example illustrates when the complete length of the
628   selected representation is known by the sender to be 1234 bytes:
629
630     Content-Range: bytes 42-1233/1234
631
632   and this second example illustrates when the complete length is
633   unknown:
634
635     Content-Range: bytes 42-1233/*
636
637   A Content-Range field value is invalid if it contains a byte-range-
638   resp that has a last-byte-pos value less than its first-byte-pos
639   value, or a complete-length value less than or equal to its last-
640   byte-pos value.  The recipient of an invalid Content-Range MUST NOT
641   attempt to recombine the received content with a stored
642   representation.
643
644   A server generating a 416 (Range Not Satisfiable) response to a byte-
645   range request SHOULD send a Content-Range header field with an
646   unsatisfied-range value, as in the following example:
647
648     Content-Range: bytes */1234
649
650   The complete-length in a 416 response indicates the current length of
651   the selected representation.
652
653   The Content-Range header field has no meaning for status codes that
654   do not explicitly describe its semantic.  For this specification,
655   only the 206 (Partial Content) and 416 (Range Not Satisfiable) status
656   codes describe a meaning for Content-Range.
657
658   The following are examples of Content-Range values in which the
659   selected representation contains a total of 1234 bytes:
660
661   o  The first 500 bytes:
662
663        Content-Range: bytes 0-499/1234
664
665   o  The second 500 bytes:
666
667        Content-Range: bytes 500-999/1234
668
669
670
671Fielding, et al.             Standards Track                   [Page 12]
672
673RFC 7233                 HTTP/1.1 Range Requests                May 2014
674
675
676   o  All except for the first 500 bytes:
677
678        Content-Range: bytes 500-1233/1234
679
680   o  The last 500 bytes:
681
682        Content-Range: bytes 734-1233/1234
683
6844.3.  Combining Ranges
685
686   A response might transfer only a subrange of a representation if the
687   connection closed prematurely or if the request used one or more
688   Range specifications.  After several such transfers, a client might
689   have received several ranges of the same representation.  These
690   ranges can only be safely combined if they all have in common the
691   same strong validator (Section 2.1 of [RFC7232]).
692
693   A client that has received multiple partial responses to GET requests
694   on a target resource MAY combine those responses into a larger
695   continuous range if they share the same strong validator.
696
697   If the most recent response is an incomplete 200 (OK) response, then
698   the header fields of that response are used for any combined response
699   and replace those of the matching stored responses.
700
701   If the most recent response is a 206 (Partial Content) response and
702   at least one of the matching stored responses is a 200 (OK), then the
703   combined response header fields consist of the most recent 200
704   response's header fields.  If all of the matching stored responses
705   are 206 responses, then the stored response with the most recent
706   header fields is used as the source of header fields for the combined
707   response, except that the client MUST use other header fields
708   provided in the new response, aside from Content-Range, to replace
709   all instances of the corresponding header fields in the stored
710   response.
711
712   The combined response message body consists of the union of partial
713   content ranges in the new response and each of the selected
714   responses.  If the union consists of the entire range of the
715   representation, then the client MUST process the combined response as
716   if it were a complete 200 (OK) response, including a Content-Length
717   header field that reflects the complete length.  Otherwise, the
718   client MUST process the set of continuous ranges as one of the
719   following: an incomplete 200 (OK) response if the combined response
720   is a prefix of the representation, a single 206 (Partial Content)
721   response containing a multipart/byteranges body, or multiple 206
722   (Partial Content) responses, each with one continuous range that is
723   indicated by a Content-Range header field.
724
725
726
727Fielding, et al.             Standards Track                   [Page 13]
728
729RFC 7233                 HTTP/1.1 Range Requests                May 2014
730
731
7324.4.  416 Range Not Satisfiable
733
734   The 416 (Range Not Satisfiable) status code indicates that none of
735   the ranges in the request's Range header field (Section 3.1) overlap
736   the current extent of the selected resource or that the set of ranges
737   requested has been rejected due to invalid ranges or an excessive
738   request of small or overlapping ranges.
739
740   For byte ranges, failing to overlap the current extent means that the
741   first-byte-pos of all of the byte-range-spec values were greater than
742   the current length of the selected representation.  When this status
743   code is generated in response to a byte-range request, the sender
744   SHOULD generate a Content-Range header field specifying the current
745   length of the selected representation (Section 4.2).
746
747   For example:
748
749     HTTP/1.1 416 Range Not Satisfiable
750     Date: Fri, 20 Jan 2012 15:41:54 GMT
751     Content-Range: bytes */47022
752
753      Note: Because servers are free to ignore Range, many
754      implementations will simply respond with the entire selected
755      representation in a 200 (OK) response.  That is partly because
756      most clients are prepared to receive a 200 (OK) to complete the
757      task (albeit less efficiently) and partly because clients might
758      not stop making an invalid partial request until they have
759      received a complete representation.  Thus, clients cannot depend
760      on receiving a 416 (Range Not Satisfiable) response even when it
761      is most appropriate.
762
7635.  IANA Considerations
764
7655.1.  Range Unit Registry
766
767   The "HTTP Range Unit Registry" defines the namespace for the range
768   unit names and refers to their corresponding specifications.  The
769   registry has been created and is now maintained at
770   <http://www.iana.org/assignments/http-parameters>.
771
7725.1.1.  Procedure
773
774   Registration of an HTTP Range Unit MUST include the following fields:
775
776   o  Name
777
778   o  Description
779
780
781
782
783Fielding, et al.             Standards Track                   [Page 14]
784
785RFC 7233                 HTTP/1.1 Range Requests                May 2014
786
787
788   o  Pointer to specification text
789
790   Values to be added to this namespace require IETF Review (see
791   [RFC5226], Section 4.1).
792
7935.1.2.  Registrations
794
795   The initial range unit registry contains the registrations below:
796
797   +-------------+---------------------------------------+-------------+
798   | Range Unit  | Description                           | Reference   |
799   | Name        |                                       |             |
800   +-------------+---------------------------------------+-------------+
801   | bytes       | a range of octets                     | Section 2.1 |
802   | none        | reserved as keyword, indicating no    | Section 2.3 |
803   |             | ranges are supported                  |             |
804   +-------------+---------------------------------------+-------------+
805
806   The change controller is: "IETF (iesg@ietf.org) - Internet
807   Engineering Task Force".
808
8095.2.  Status Code Registration
810
811   The "Hypertext Transfer Protocol (HTTP) Status Code Registry" located
812   at <http://www.iana.org/assignments/http-status-codes> has been
813   updated to include the registrations below:
814
815   +-------+-----------------------+-------------+
816   | Value | Description           | Reference   |
817   +-------+-----------------------+-------------+
818   | 206   | Partial Content       | Section 4.1 |
819   | 416   | Range Not Satisfiable | Section 4.4 |
820   +-------+-----------------------+-------------+
821
8225.3.  Header Field Registration
823
824   HTTP header fields are registered within the "Message Headers"
825   registry maintained at
826   <http://www.iana.org/assignments/message-headers/>.
827
828   This document defines the following HTTP header fields, so their
829   associated registry entries have been updated according to the
830   permanent registrations below (see [BCP90]):
831
832
833
834
835
836
837
838
839Fielding, et al.             Standards Track                   [Page 15]
840
841RFC 7233                 HTTP/1.1 Range Requests                May 2014
842
843
844   +-------------------+----------+----------+-------------+
845   | Header Field Name | Protocol | Status   | Reference   |
846   +-------------------+----------+----------+-------------+
847   | Accept-Ranges     | http     | standard | Section 2.3 |
848   | Content-Range     | http     | standard | Section 4.2 |
849   | If-Range          | http     | standard | Section 3.2 |
850   | Range             | http     | standard | Section 3.1 |
851   +-------------------+----------+----------+-------------+
852
853   The change controller is: "IETF (iesg@ietf.org) - Internet
854   Engineering Task Force".
855
8565.4.  Internet Media Type Registration
857
858   IANA maintains the registry of Internet media types [BCP13] at
859   <http://www.iana.org/assignments/media-types>.
860
861   This document serves as the specification for the Internet media type
862   "multipart/byteranges".  The following has been registered with IANA.
863
8645.4.1.  Internet Media Type multipart/byteranges
865
866   Type name:  multipart
867
868   Subtype name:  byteranges
869
870   Required parameters:  boundary
871
872   Optional parameters:  N/A
873
874   Encoding considerations:  only "7bit", "8bit", or "binary" are
875      permitted
876
877   Security considerations:  see Section 6
878
879   Interoperability considerations:  N/A
880
881   Published specification:  This specification (see Appendix A).
882
883   Applications that use this media type:  HTTP components supporting
884      multiple ranges in a single request.
885
886   Fragment identifier considerations:  N/A
887
888   Additional information:
889
890
891
892
893
894
895Fielding, et al.             Standards Track                   [Page 16]
896
897RFC 7233                 HTTP/1.1 Range Requests                May 2014
898
899
900      Deprecated alias names for this type:  N/A
901
902      Magic number(s):  N/A
903
904      File extension(s):  N/A
905
906      Macintosh file type code(s):  N/A
907
908   Person and email address to contact for further information:  See
909      Authors' Addresses section.
910
911   Intended usage:  COMMON
912
913   Restrictions on usage:  N/A
914
915   Author:  See Authors' Addresses section.
916
917   Change controller:  IESG
918
9196.  Security Considerations
920
921   This section is meant to inform developers, information providers,
922   and users of known security concerns specific to the HTTP range
923   request mechanisms.  More general security considerations are
924   addressed in HTTP messaging [RFC7230] and semantics [RFC7231].
925
9266.1.  Denial-of-Service Attacks Using Range
927
928   Unconstrained multiple range requests are susceptible to denial-of-
929   service attacks because the effort required to request many
930   overlapping ranges of the same data is tiny compared to the time,
931   memory, and bandwidth consumed by attempting to serve the requested
932   data in many parts.  Servers ought to ignore, coalesce, or reject
933   egregious range requests, such as requests for more than two
934   overlapping ranges or for many small ranges in a single set,
935   particularly when the ranges are requested out of order for no
936   apparent reason.  Multipart range requests are not designed to
937   support random access.
938
9397.  Acknowledgments
940
941   See Section 10 of [RFC7230].
942
9438.  References
944
945
946
947
948
949
950
951Fielding, et al.             Standards Track                   [Page 17]
952
953RFC 7233                 HTTP/1.1 Range Requests                May 2014
954
955
9568.1.  Normative References
957
958   [RFC2046]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
959              Extensions (MIME) Part Two: Media Types", RFC 2046,
960              November 1996.
961
962   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
963              Requirement Levels", BCP 14, RFC 2119, March 1997.
964
965   [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
966              Specifications: ABNF", STD 68, RFC 5234, January 2008.
967
968   [RFC7230]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
969              Protocol (HTTP/1.1): Message Syntax and Routing",
970              RFC 7230, May 2014.
971
972   [RFC7231]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
973              Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
974              May 2014.
975
976   [RFC7232]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
977              Protocol (HTTP/1.1): Conditional Requests", RFC 7232,
978              May 2014.
979
980   [RFC7234]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
981              Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
982              RFC 7234, May 2014.
983
9848.2.  Informative References
985
986   [BCP13]    Freed, N., Klensin, J., and T. Hansen, "Media Type
987              Specifications and Registration Procedures", BCP 13,
988              RFC 6838, January 2013.
989
990   [BCP90]    Klyne, G., Nottingham, M., and J. Mogul, "Registration
991              Procedures for Message Header Fields", BCP 90, RFC 3864,
992              September 2004.
993
994   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
995              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
996              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
997
998   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
999              IANA Considerations Section in RFCs", BCP 26, RFC 5226,
1000              May 2008.
1001
1002
1003
1004
1005
1006
1007Fielding, et al.             Standards Track                   [Page 18]
1008
1009RFC 7233                 HTTP/1.1 Range Requests                May 2014
1010
1011
1012Appendix A.  Internet Media Type multipart/byteranges
1013
1014   When a 206 (Partial Content) response message includes the content of
1015   multiple ranges, they are transmitted as body parts in a multipart
1016   message body ([RFC2046], Section 5.1) with the media type of
1017   "multipart/byteranges".
1018
1019   The multipart/byteranges media type includes one or more body parts,
1020   each with its own Content-Type and Content-Range fields.  The
1021   required boundary parameter specifies the boundary string used to
1022   separate each body part.
1023
1024   Implementation Notes:
1025
1026   1.  Additional CRLFs might precede the first boundary string in the
1027       body.
1028
1029   2.  Although [RFC2046] permits the boundary string to be quoted, some
1030       existing implementations handle a quoted boundary string
1031       incorrectly.
1032
1033   3.  A number of clients and servers were coded to an early draft of
1034       the byteranges specification that used a media type of multipart/
1035       x-byteranges, which is almost (but not quite) compatible with
1036       this type.
1037
1038   Despite the name, the "multipart/byteranges" media type is not
1039   limited to byte ranges.  The following example uses an "exampleunit"
1040   range unit:
1041
1042     HTTP/1.1 206 Partial Content
1043     Date: Tue, 14 Nov 1995 06:25:24 GMT
1044     Last-Modified: Tue, 14 July 04:58:08 GMT
1045     Content-Length: 2331785
1046     Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES
1047
1048     --THIS_STRING_SEPARATES
1049     Content-Type: video/example
1050     Content-Range: exampleunit 1.2-4.3/25
1051
1052     ...the first range...
1053     --THIS_STRING_SEPARATES
1054     Content-Type: video/example
1055     Content-Range: exampleunit 11.2-14.3/25
1056
1057     ...the second range
1058     --THIS_STRING_SEPARATES--
1059
1060
1061
1062
1063Fielding, et al.             Standards Track                   [Page 19]
1064
1065RFC 7233                 HTTP/1.1 Range Requests                May 2014
1066
1067
1068Appendix B.  Changes from RFC 2616
1069
1070   Servers are given more leeway in how they respond to a range request,
1071   in order to mitigate abuse by malicious (or just greedy) clients.
1072   (Section 3.1)
1073
1074   A weak validator cannot be used in a 206 response.  (Section 4.1)
1075
1076   The Content-Range header field only has meaning when the status code
1077   explicitly defines its use.  (Section 4.2)
1078
1079   This specification introduces a Range Unit Registry.  (Section 5.1)
1080
1081   multipart/byteranges can consist of a single part.  (Appendix A)
1082
1083Appendix C.  Imported ABNF
1084
1085   The following core rules are included by reference, as defined in
1086   Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return),
1087   CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double
1088   quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any
1089   8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII
1090   character).
1091
1092   Note that all rules derived from token are to be compared case-
1093   insensitively, like range-unit and acceptable-ranges.
1094
1095   The rules below are defined in [RFC7230]:
1096
1097     OWS        = <OWS, see [RFC7230], Section 3.2.3>
1098     token      = <token, see [RFC7230], Section 3.2.6>
1099
1100   The rules below are defined in other parts:
1101
1102     HTTP-date  = <HTTP-date, see [RFC7231], Section 7.1.1.1>
1103     entity-tag = <entity-tag, see [RFC7232], Section 2.3>
1104
1105Appendix D.  Collected ABNF
1106
1107   In the collected ABNF below, list rules are expanded as per Section
1108   1.2 of [RFC7230].
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119Fielding, et al.             Standards Track                   [Page 20]
1120
1121RFC 7233                 HTTP/1.1 Range Requests                May 2014
1122
1123
1124   Accept-Ranges = acceptable-ranges
1125
1126   Content-Range = byte-content-range / other-content-range
1127
1128   HTTP-date = <HTTP-date, see [RFC7231], Section 7.1.1.1>
1129
1130   If-Range = entity-tag / HTTP-date
1131
1132   OWS = <OWS, see [RFC7230], Section 3.2.3>
1133
1134   Range = byte-ranges-specifier / other-ranges-specifier
1135
1136   acceptable-ranges = ( *( "," OWS ) range-unit *( OWS "," [ OWS
1137    range-unit ] ) ) / "none"
1138
1139   byte-content-range = bytes-unit SP ( byte-range-resp /
1140    unsatisfied-range )
1141   byte-range = first-byte-pos "-" last-byte-pos
1142   byte-range-resp = byte-range "/" ( complete-length / "*" )
1143   byte-range-set = *( "," OWS ) ( byte-range-spec /
1144    suffix-byte-range-spec ) *( OWS "," [ OWS ( byte-range-spec /
1145    suffix-byte-range-spec ) ] )
1146   byte-range-spec = first-byte-pos "-" [ last-byte-pos ]
1147   byte-ranges-specifier = bytes-unit "=" byte-range-set
1148   bytes-unit = "bytes"
1149
1150   complete-length = 1*DIGIT
1151
1152   entity-tag = <entity-tag, see [RFC7232], Section 2.3>
1153
1154   first-byte-pos = 1*DIGIT
1155
1156   last-byte-pos = 1*DIGIT
1157
1158   other-content-range = other-range-unit SP other-range-resp
1159   other-range-resp = *CHAR
1160   other-range-set = 1*VCHAR
1161   other-range-unit = token
1162   other-ranges-specifier = other-range-unit "=" other-range-set
1163
1164   range-unit = bytes-unit / other-range-unit
1165
1166   suffix-byte-range-spec = "-" suffix-length
1167   suffix-length = 1*DIGIT
1168
1169   token = <token, see [RFC7230], Section 3.2.6>
1170
1171   unsatisfied-range = "*/" complete-length
1172
1173
1174
1175Fielding, et al.             Standards Track                   [Page 21]
1176
1177RFC 7233                 HTTP/1.1 Range Requests                May 2014
1178
1179
1180Index
1181
1182   2
1183      206 Partial Content (status code)  9
1184
1185   4
1186      416 Range Not Satisfiable (status code)  14
1187
1188   A
1189      Accept-Ranges header field  6
1190
1191   C
1192      Content-Range header field  11
1193
1194   G
1195      Grammar
1196         Accept-Ranges  6
1197         acceptable-ranges  6
1198         byte-content-range  11
1199         byte-range  11
1200         byte-range-resp  11
1201         byte-range-set  4
1202         byte-range-spec  4
1203         byte-ranges-specifier  4
1204         bytes-unit  4
1205         complete-length  11
1206         Content-Range  11
1207         first-byte-pos  4
1208         If-Range  8
1209         last-byte-pos  4
1210         other-content-range  11
1211         other-range-resp  11
1212         other-range-unit  4, 6
1213         Range  6
1214         range-unit  4
1215         ranges-specifier  4
1216         suffix-byte-range-spec  5
1217         suffix-length  5
1218         unsatisfied-range  11
1219
1220   I
1221      If-Range header field  8
1222
1223   M
1224      Media Type
1225         multipart/byteranges  16, 19
1226         multipart/x-byteranges  19
1227      multipart/byteranges Media Type  16, 19
1228
1229
1230
1231Fielding, et al.             Standards Track                   [Page 22]
1232
1233RFC 7233                 HTTP/1.1 Range Requests                May 2014
1234
1235
1236      multipart/x-byteranges Media Type  19
1237
1238   R
1239      Range header field  6
1240
1241Authors' Addresses
1242
1243   Roy T. Fielding (editor)
1244   Adobe Systems Incorporated
1245   345 Park Ave
1246   San Jose, CA  95110
1247   USA
1248
1249   EMail: fielding@gbiv.com
1250   URI:   http://roy.gbiv.com/
1251
1252
1253   Yves Lafon (editor)
1254   World Wide Web Consortium
1255   W3C / ERCIM
1256   2004, rte des Lucioles
1257   Sophia-Antipolis, AM  06902
1258   France
1259
1260   EMail: ylafon@w3.org
1261   URI:   http://www.raubacapeu.net/people/yves/
1262
1263
1264   Julian F. Reschke (editor)
1265   greenbytes GmbH
1266   Hafenweg 16
1267   Muenster, NW  48155
1268   Germany
1269
1270   EMail: julian.reschke@greenbytes.de
1271   URI:   http://greenbytes.de/tech/webdav/
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287Fielding, et al.             Standards Track                   [Page 23]
1288
Note: See TracBrowser for help on using the repository browser.