Commit | Line | Data |
---|---|---|
d7ee16ed LM |
1 | |
2 | ||
3 | ||
4 | ||
5 | Internet Engineering Task Force (IETF) R. Fielding, Ed. | |
6 | Request for Comments: 9112 Adobe | |
7 | STD: 99 M. Nottingham, Ed. | |
8 | Obsoletes: 7230 Fastly | |
9 | Category: Standards Track J. Reschke, Ed. | |
10 | ISSN: 2070-1721 greenbytes | |
11 | June 2022 | |
12 | ||
13 | ||
14 | HTTP/1.1 | |
15 | ||
16 | Abstract | |
17 | ||
18 | The Hypertext Transfer Protocol (HTTP) is a stateless application- | |
19 | level protocol for distributed, collaborative, hypertext information | |
20 | systems. This document specifies the HTTP/1.1 message syntax, | |
21 | message parsing, connection management, and related security | |
22 | concerns. | |
23 | ||
24 | This document obsoletes portions of RFC 7230. | |
25 | ||
26 | Status of This Memo | |
27 | ||
28 | This is an Internet Standards Track document. | |
29 | ||
30 | This document is a product of the Internet Engineering Task Force | |
31 | (IETF). It represents the consensus of the IETF community. It has | |
32 | received public review and has been approved for publication by the | |
33 | Internet Engineering Steering Group (IESG). Further information on | |
34 | Internet Standards is available in Section 2 of RFC 7841. | |
35 | ||
36 | Information about the current status of this document, any errata, | |
37 | and how to provide feedback on it may be obtained at | |
38 | https://www.rfc-editor.org/info/rfc9112. | |
39 | ||
40 | Copyright Notice | |
41 | ||
42 | Copyright (c) 2022 IETF Trust and the persons identified as the | |
43 | document authors. All rights reserved. | |
44 | ||
45 | This document is subject to BCP 78 and the IETF Trust's Legal | |
46 | Provisions Relating to IETF Documents | |
47 | (https://trustee.ietf.org/license-info) in effect on the date of | |
48 | publication of this document. Please review these documents | |
49 | carefully, as they describe your rights and restrictions with respect | |
50 | to this document. Code Components extracted from this document must | |
51 | include Revised BSD License text as described in Section 4.e of the | |
52 | Trust Legal Provisions and are provided without warranty as described | |
53 | in the Revised BSD License. | |
54 | ||
55 | This document may contain material from IETF Documents or IETF | |
56 | Contributions published or made publicly available before November | |
57 | 10, 2008. The person(s) controlling the copyright in some of this | |
58 | material may not have granted the IETF Trust the right to allow | |
59 | modifications of such material outside the IETF Standards Process. | |
60 | Without obtaining an adequate license from the person(s) controlling | |
61 | the copyright in such materials, this document may not be modified | |
62 | outside the IETF Standards Process, and derivative works of it may | |
63 | not be created outside the IETF Standards Process, except to format | |
64 | it for publication as an RFC or to translate it into languages other | |
65 | than English. | |
66 | ||
67 | Table of Contents | |
68 | ||
69 | 1. Introduction | |
70 | 1.1. Requirements Notation | |
71 | 1.2. Syntax Notation | |
72 | 2. Message | |
73 | 2.1. Message Format | |
74 | 2.2. Message Parsing | |
75 | 2.3. HTTP Version | |
76 | 3. Request Line | |
77 | 3.1. Method | |
78 | 3.2. Request Target | |
79 | 3.2.1. origin-form | |
80 | 3.2.2. absolute-form | |
81 | 3.2.3. authority-form | |
82 | 3.2.4. asterisk-form | |
83 | 3.3. Reconstructing the Target URI | |
84 | 4. Status Line | |
85 | 5. Field Syntax | |
86 | 5.1. Field Line Parsing | |
87 | 5.2. Obsolete Line Folding | |
88 | 6. Message Body | |
89 | 6.1. Transfer-Encoding | |
90 | 6.2. Content-Length | |
91 | 6.3. Message Body Length | |
92 | 7. Transfer Codings | |
93 | 7.1. Chunked Transfer Coding | |
94 | 7.1.1. Chunk Extensions | |
95 | 7.1.2. Chunked Trailer Section | |
96 | 7.1.3. Decoding Chunked | |
97 | 7.2. Transfer Codings for Compression | |
98 | 7.3. Transfer Coding Registry | |
99 | 7.4. Negotiating Transfer Codings | |
100 | 8. Handling Incomplete Messages | |
101 | 9. Connection Management | |
102 | 9.1. Establishment | |
103 | 9.2. Associating a Response to a Request | |
104 | 9.3. Persistence | |
105 | 9.3.1. Retrying Requests | |
106 | 9.3.2. Pipelining | |
107 | 9.4. Concurrency | |
108 | 9.5. Failures and Timeouts | |
109 | 9.6. Tear-down | |
110 | 9.7. TLS Connection Initiation | |
111 | 9.8. TLS Connection Closure | |
112 | 10. Enclosing Messages as Data | |
113 | 10.1. Media Type message/http | |
114 | 10.2. Media Type application/http | |
115 | 11. Security Considerations | |
116 | 11.1. Response Splitting | |
117 | 11.2. Request Smuggling | |
118 | 11.3. Message Integrity | |
119 | 11.4. Message Confidentiality | |
120 | 12. IANA Considerations | |
121 | 12.1. Field Name Registration | |
122 | 12.2. Media Type Registration | |
123 | 12.3. Transfer Coding Registration | |
124 | 12.4. ALPN Protocol ID Registration | |
125 | 13. References | |
126 | 13.1. Normative References | |
127 | 13.2. Informative References | |
128 | Appendix A. Collected ABNF | |
129 | Appendix B. Differences between HTTP and MIME | |
130 | B.1. MIME-Version | |
131 | B.2. Conversion to Canonical Form | |
132 | B.3. Conversion of Date Formats | |
133 | B.4. Conversion of Content-Encoding | |
134 | B.5. Conversion of Content-Transfer-Encoding | |
135 | B.6. MHTML and Line Length Limitations | |
136 | Appendix C. Changes from Previous RFCs | |
137 | C.1. Changes from HTTP/0.9 | |
138 | C.2. Changes from HTTP/1.0 | |
139 | C.2.1. Multihomed Web Servers | |
140 | C.2.2. Keep-Alive Connections | |
141 | C.2.3. Introduction of Transfer-Encoding | |
142 | C.3. Changes from RFC 7230 | |
143 | Acknowledgements | |
144 | Index | |
145 | Authors' Addresses | |
146 | ||
147 | 1. Introduction | |
148 | ||
149 | The Hypertext Transfer Protocol (HTTP) is a stateless application- | |
150 | level request/response protocol that uses extensible semantics and | |
151 | self-descriptive messages for flexible interaction with network-based | |
152 | hypertext information systems. HTTP/1.1 is defined by: | |
153 | ||
154 | * This document | |
155 | ||
156 | * "HTTP Semantics" [HTTP] | |
157 | ||
158 | * "HTTP Caching" [CACHING] | |
159 | ||
160 | This document specifies how HTTP semantics are conveyed using the | |
161 | HTTP/1.1 message syntax, framing, and connection management | |
162 | mechanisms. Its goal is to define the complete set of requirements | |
163 | for HTTP/1.1 message parsers and message-forwarding intermediaries. | |
164 | ||
165 | This document obsoletes the portions of RFC 7230 related to HTTP/1.1 | |
166 | messaging and connection management, with the changes being | |
167 | summarized in Appendix C.3. The other parts of RFC 7230 are | |
168 | obsoleted by "HTTP Semantics" [HTTP]. | |
169 | ||
170 | 1.1. Requirements Notation | |
171 | ||
172 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |
173 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | |
174 | "OPTIONAL" in this document are to be interpreted as described in | |
175 | BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all | |
176 | capitals, as shown here. | |
177 | ||
178 | Conformance criteria and considerations regarding error handling are | |
179 | defined in Section 2 of [HTTP]. | |
180 | ||
181 | 1.2. Syntax Notation | |
182 | ||
183 | This specification uses the Augmented Backus-Naur Form (ABNF) | |
184 | notation of [RFC5234], extended with the notation for case- | |
185 | sensitivity in strings defined in [RFC7405]. | |
186 | ||
187 | It also uses a list extension, defined in Section 5.6.1 of [HTTP], | |
188 | that allows for compact definition of comma-separated lists using a | |
189 | "#" operator (similar to how the "*" operator indicates repetition). | |
190 | Appendix A shows the collected grammar with all list operators | |
191 | expanded to standard ABNF notation. | |
192 | ||
193 | As a convention, ABNF rule names prefixed with "obs-" denote obsolete | |
194 | grammar rules that appear for historical reasons. | |
195 | ||
196 | The following core rules are included by reference, as defined in | |
197 | [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF | |
198 | (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), | |
199 | HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF (line | |
200 | feed), OCTET (any 8-bit sequence of data), SP (space), and VCHAR (any | |
201 | visible [USASCII] character). | |
202 | ||
203 | The rules below are defined in [HTTP]: | |
204 | ||
205 | BWS = <BWS, see [HTTP], Section 5.6.3> | |
206 | OWS = <OWS, see [HTTP], Section 5.6.3> | |
207 | RWS = <RWS, see [HTTP], Section 5.6.3> | |
208 | absolute-path = <absolute-path, see [HTTP], Section 4.1> | |
209 | field-name = <field-name, see [HTTP], Section 5.1> | |
210 | field-value = <field-value, see [HTTP], Section 5.5> | |
211 | obs-text = <obs-text, see [HTTP], Section 5.6.4> | |
212 | quoted-string = <quoted-string, see [HTTP], Section 5.6.4> | |
213 | token = <token, see [HTTP], Section 5.6.2> | |
214 | transfer-coding = | |
215 | <transfer-coding, see [HTTP], Section 10.1.4> | |
216 | ||
217 | The rules below are defined in [URI]: | |
218 | ||
219 | absolute-URI = <absolute-URI, see [URI], Section 4.3> | |
220 | authority = <authority, see [URI], Section 3.2> | |
221 | uri-host = <host, see [URI], Section 3.2.2> | |
222 | port = <port, see [URI], Section 3.2.3> | |
223 | query = <query, see [URI], Section 3.4> | |
224 | ||
225 | 2. Message | |
226 | ||
227 | HTTP/1.1 clients and servers communicate by sending messages. See | |
228 | Section 3 of [HTTP] for the general terminology and core concepts of | |
229 | HTTP. | |
230 | ||
231 | 2.1. Message Format | |
232 | ||
233 | An HTTP/1.1 message consists of a start-line followed by a CRLF and a | |
234 | sequence of octets in a format similar to the Internet Message Format | |
235 | [RFC5322]: zero or more header field lines (collectively referred to | |
236 | as the "headers" or the "header section"), an empty line indicating | |
237 | the end of the header section, and an optional message body. | |
238 | ||
239 | HTTP-message = start-line CRLF | |
240 | *( field-line CRLF ) | |
241 | CRLF | |
242 | [ message-body ] | |
243 | ||
244 | A message can be either a request from client to server or a response | |
245 | from server to client. Syntactically, the two types of messages | |
246 | differ only in the start-line, which is either a request-line (for | |
247 | requests) or a status-line (for responses), and in the algorithm for | |
248 | determining the length of the message body (Section 6). | |
249 | ||
250 | start-line = request-line / status-line | |
251 | ||
252 | In theory, a client could receive requests and a server could receive | |
253 | responses, distinguishing them by their different start-line formats. | |
254 | In practice, servers are implemented to only expect a request (a | |
255 | response is interpreted as an unknown or invalid request method), and | |
256 | clients are implemented to only expect a response. | |
257 | ||
258 | HTTP makes use of some protocol elements similar to the Multipurpose | |
259 | Internet Mail Extensions (MIME) [RFC2045]. See Appendix B for the | |
260 | differences between HTTP and MIME messages. | |
261 | ||
262 | 2.2. Message Parsing | |
263 | ||
264 | The normal procedure for parsing an HTTP message is to read the | |
265 | start-line into a structure, read each header field line into a hash | |
266 | table by field name until the empty line, and then use the parsed | |
267 | data to determine if a message body is expected. If a message body | |
268 | has been indicated, then it is read as a stream until an amount of | |
269 | octets equal to the message body length is read or the connection is | |
270 | closed. | |
271 | ||
272 | A recipient MUST parse an HTTP message as a sequence of octets in an | |
273 | encoding that is a superset of US-ASCII [USASCII]. Parsing an HTTP | |
274 | message as a stream of Unicode characters, without regard for the | |
275 | specific encoding, creates security vulnerabilities due to the | |
276 | varying ways that string processing libraries handle invalid | |
277 | multibyte character sequences that contain the octet LF (%x0A). | |
278 | String-based parsers can only be safely used within protocol elements | |
279 | after the element has been extracted from the message, such as within | |
280 | a header field line value after message parsing has delineated the | |
281 | individual field lines. | |
282 | ||
283 | Although the line terminator for the start-line and fields is the | |
284 | sequence CRLF, a recipient MAY recognize a single LF as a line | |
285 | terminator and ignore any preceding CR. | |
286 | ||
287 | A sender MUST NOT generate a bare CR (a CR character not immediately | |
288 | followed by LF) within any protocol elements other than the content. | |
289 | A recipient of such a bare CR MUST consider that element to be | |
290 | invalid or replace each bare CR with SP before processing the element | |
291 | or forwarding the message. | |
292 | ||
293 | Older HTTP/1.0 user agent implementations might send an extra CRLF | |
294 | after a POST request as a workaround for some early server | |
295 | applications that failed to read message body content that was not | |
296 | terminated by a line-ending. An HTTP/1.1 user agent MUST NOT preface | |
297 | or follow a request with an extra CRLF. If terminating the request | |
298 | message body with a line-ending is desired, then the user agent MUST | |
299 | count the terminating CRLF octets as part of the message body length. | |
300 | ||
301 | In the interest of robustness, a server that is expecting to receive | |
302 | and parse a request-line SHOULD ignore at least one empty line (CRLF) | |
303 | received prior to the request-line. | |
304 | ||
305 | A sender MUST NOT send whitespace between the start-line and the | |
306 | first header field. | |
307 | ||
308 | A recipient that receives whitespace between the start-line and the | |
309 | first header field MUST either reject the message as invalid or | |
310 | consume each whitespace-preceded line without further processing of | |
311 | it (i.e., ignore the entire line, along with any subsequent lines | |
312 | preceded by whitespace, until a properly formed header field is | |
313 | received or the header section is terminated). Rejection or removal | |
314 | of invalid whitespace-preceded lines is necessary to prevent their | |
315 | misinterpretation by downstream recipients that might be vulnerable | |
316 | to request smuggling (Section 11.2) or response splitting | |
317 | (Section 11.1) attacks. | |
318 | ||
319 | When a server listening only for HTTP request messages, or processing | |
320 | what appears from the start-line to be an HTTP request message, | |
321 | receives a sequence of octets that does not match the HTTP-message | |
322 | grammar aside from the robustness exceptions listed above, the server | |
323 | SHOULD respond with a 400 (Bad Request) response and close the | |
324 | connection. | |
325 | ||
326 | 2.3. HTTP Version | |
327 | ||
328 | HTTP uses a "<major>.<minor>" numbering scheme to indicate versions | |
329 | of the protocol. This specification defines version "1.1". | |
330 | Section 2.5 of [HTTP] specifies the semantics of HTTP version | |
331 | numbers. | |
332 | ||
333 | The version of an HTTP/1.x message is indicated by an HTTP-version | |
334 | field in the start-line. HTTP-version is case-sensitive. | |
335 | ||
336 | HTTP-version = HTTP-name "/" DIGIT "." DIGIT | |
337 | HTTP-name = %s"HTTP" | |
338 | ||
339 | When an HTTP/1.1 message is sent to an HTTP/1.0 recipient [HTTP/1.0] | |
340 | or a recipient whose version is unknown, the HTTP/1.1 message is | |
341 | constructed such that it can be interpreted as a valid HTTP/1.0 | |
342 | message if all of the newer features are ignored. This specification | |
343 | places recipient-version requirements on some new features so that a | |
344 | conformant sender will only use compatible features until it has | |
345 | determined, through configuration or the receipt of a message, that | |
346 | the recipient supports HTTP/1.1. | |
347 | ||
348 | Intermediaries that process HTTP messages (i.e., all intermediaries | |
349 | other than those acting as tunnels) MUST send their own HTTP-version | |
350 | in forwarded messages, unless it is purposefully downgraded as a | |
351 | workaround for an upstream issue. In other words, an intermediary is | |
352 | not allowed to blindly forward the start-line without ensuring that | |
353 | the protocol version in that message matches a version to which that | |
354 | intermediary is conformant for both the receiving and sending of | |
355 | messages. Forwarding an HTTP message without rewriting the HTTP- | |
356 | version might result in communication errors when downstream | |
357 | recipients use the message sender's version to determine what | |
358 | features are safe to use for later communication with that sender. | |
359 | ||
360 | A server MAY send an HTTP/1.0 response to an HTTP/1.1 request if it | |
361 | is known or suspected that the client incorrectly implements the HTTP | |
362 | specification and is incapable of correctly processing later version | |
363 | responses, such as when a client fails to parse the version number | |
364 | correctly or when an intermediary is known to blindly forward the | |
365 | HTTP-version even when it doesn't conform to the given minor version | |
366 | of the protocol. Such protocol downgrades SHOULD NOT be performed | |
367 | unless triggered by specific client attributes, such as when one or | |
368 | more of the request header fields (e.g., User-Agent) uniquely match | |
369 | the values sent by a client known to be in error. | |
370 | ||
371 | 3. Request Line | |
372 | ||
373 | A request-line begins with a method token, followed by a single space | |
374 | (SP), the request-target, and another single space (SP), and ends | |
375 | with the protocol version. | |
376 | ||
377 | request-line = method SP request-target SP HTTP-version | |
378 | ||
379 | Although the request-line grammar rule requires that each of the | |
380 | component elements be separated by a single SP octet, recipients MAY | |
381 | instead parse on whitespace-delimited word boundaries and, aside from | |
382 | the CRLF terminator, treat any form of whitespace as the SP separator | |
383 | while ignoring preceding or trailing whitespace; such whitespace | |
384 | includes one or more of the following octets: SP, HTAB, VT (%x0B), FF | |
385 | (%x0C), or bare CR. However, lenient parsing can result in request | |
386 | smuggling security vulnerabilities if there are multiple recipients | |
387 | of the message and each has its own unique interpretation of | |
388 | robustness (see Section 11.2). | |
389 | ||
390 | HTTP does not place a predefined limit on the length of a request- | |
391 | line, as described in Section 2.3 of [HTTP]. A server that receives | |
392 | a method longer than any that it implements SHOULD respond with a 501 | |
393 | (Not Implemented) status code. A server that receives a request- | |
394 | target longer than any URI it wishes to parse MUST respond with a 414 | |
395 | (URI Too Long) status code (see Section 15.5.15 of [HTTP]). | |
396 | ||
397 | Various ad hoc limitations on request-line length are found in | |
398 | practice. It is RECOMMENDED that all HTTP senders and recipients | |
399 | support, at a minimum, request-line lengths of 8000 octets. | |
400 | ||
401 | 3.1. Method | |
402 | ||
403 | The method token indicates the request method to be performed on the | |
404 | target resource. The request method is case-sensitive. | |
405 | ||
406 | method = token | |
407 | ||
408 | The request methods defined by this specification can be found in | |
409 | Section 9 of [HTTP], along with information regarding the HTTP method | |
410 | registry and considerations for defining new methods. | |
411 | ||
412 | 3.2. Request Target | |
413 | ||
414 | The request-target identifies the target resource upon which to apply | |
415 | the request. The client derives a request-target from its desired | |
416 | target URI. There are four distinct formats for the request-target, | |
417 | depending on both the method being requested and whether the request | |
418 | is to a proxy. | |
419 | ||
420 | request-target = origin-form | |
421 | / absolute-form | |
422 | / authority-form | |
423 | / asterisk-form | |
424 | ||
425 | No whitespace is allowed in the request-target. Unfortunately, some | |
426 | user agents fail to properly encode or exclude whitespace found in | |
427 | hypertext references, resulting in those disallowed characters being | |
428 | sent as the request-target in a malformed request-line. | |
429 | ||
430 | Recipients of an invalid request-line SHOULD respond with either a | |
431 | 400 (Bad Request) error or a 301 (Moved Permanently) redirect with | |
432 | the request-target properly encoded. A recipient SHOULD NOT attempt | |
433 | to autocorrect and then process the request without a redirect, since | |
434 | the invalid request-line might be deliberately crafted to bypass | |
435 | security filters along the request chain. | |
436 | ||
437 | A client MUST send a Host header field (Section 7.2 of [HTTP]) in all | |
438 | HTTP/1.1 request messages. If the target URI includes an authority | |
439 | component, then a client MUST send a field value for Host that is | |
440 | identical to that authority component, excluding any userinfo | |
441 | subcomponent and its "@" delimiter (Section 4.2 of [HTTP]). If the | |
442 | authority component is missing or undefined for the target URI, then | |
443 | a client MUST send a Host header field with an empty field value. | |
444 | ||
445 | A server MUST respond with a 400 (Bad Request) status code to any | |
446 | HTTP/1.1 request message that lacks a Host header field and to any | |
447 | request message that contains more than one Host header field line or | |
448 | a Host header field with an invalid field value. | |
449 | ||
450 | 3.2.1. origin-form | |
451 | ||
452 | The most common form of request-target is the "origin-form". | |
453 | ||
454 | origin-form = absolute-path [ "?" query ] | |
455 | ||
456 | When making a request directly to an origin server, other than a | |
457 | CONNECT or server-wide OPTIONS request (as detailed below), a client | |
458 | MUST send only the absolute path and query components of the target | |
459 | URI as the request-target. If the target URI's path component is | |
460 | empty, the client MUST send "/" as the path within the origin-form of | |
461 | request-target. A Host header field is also sent, as defined in | |
462 | Section 7.2 of [HTTP]. | |
463 | ||
464 | For example, a client wishing to retrieve a representation of the | |
465 | resource identified as | |
466 | ||
467 | http://www.example.org/where?q=now | |
468 | ||
469 | directly from the origin server would open (or reuse) a TCP | |
470 | connection to port 80 of the host "www.example.org" and send the | |
471 | lines: | |
472 | ||
473 | GET /where?q=now HTTP/1.1 | |
474 | Host: www.example.org | |
475 | ||
476 | followed by the remainder of the request message. | |
477 | ||
478 | 3.2.2. absolute-form | |
479 | ||
480 | When making a request to a proxy, other than a CONNECT or server-wide | |
481 | OPTIONS request (as detailed below), a client MUST send the target | |
482 | URI in "absolute-form" as the request-target. | |
483 | ||
484 | absolute-form = absolute-URI | |
485 | ||
486 | The proxy is requested to either service that request from a valid | |
487 | cache, if possible, or make the same request on the client's behalf | |
488 | either to the next inbound proxy server or directly to the origin | |
489 | server indicated by the request-target. Requirements on such | |
490 | "forwarding" of messages are defined in Section 7.6 of [HTTP]. | |
491 | ||
492 | An example absolute-form of request-line would be: | |
493 | ||
494 | GET http://www.example.org/pub/WWW/TheProject.html HTTP/1.1 | |
495 | ||
496 | A client MUST send a Host header field in an HTTP/1.1 request even if | |
497 | the request-target is in the absolute-form, since this allows the | |
498 | Host information to be forwarded through ancient HTTP/1.0 proxies | |
499 | that might not have implemented Host. | |
500 | ||
501 | When a proxy receives a request with an absolute-form of request- | |
502 | target, the proxy MUST ignore the received Host header field (if any) | |
503 | and instead replace it with the host information of the request- | |
504 | target. A proxy that forwards such a request MUST generate a new | |
505 | Host field value based on the received request-target rather than | |
506 | forward the received Host field value. | |
507 | ||
508 | When an origin server receives a request with an absolute-form of | |
509 | request-target, the origin server MUST ignore the received Host | |
510 | header field (if any) and instead use the host information of the | |
511 | request-target. Note that if the request-target does not have an | |
512 | authority component, an empty Host header field will be sent in this | |
513 | case. | |
514 | ||
515 | A server MUST accept the absolute-form in requests even though most | |
516 | HTTP/1.1 clients will only send the absolute-form to a proxy. | |
517 | ||
518 | 3.2.3. authority-form | |
519 | ||
520 | The "authority-form" of request-target is only used for CONNECT | |
521 | requests (Section 9.3.6 of [HTTP]). It consists of only the uri-host | |
522 | and port number of the tunnel destination, separated by a colon | |
523 | (":"). | |
524 | ||
525 | authority-form = uri-host ":" port | |
526 | ||
527 | When making a CONNECT request to establish a tunnel through one or | |
528 | more proxies, a client MUST send only the host and port of the tunnel | |
529 | destination as the request-target. The client obtains the host and | |
530 | port from the target URI's authority component, except that it sends | |
531 | the scheme's default port if the target URI elides the port. For | |
532 | example, a CONNECT request to "http://www.example.com" looks like the | |
533 | following: | |
534 | ||
535 | CONNECT www.example.com:80 HTTP/1.1 | |
536 | Host: www.example.com | |
537 | ||
538 | 3.2.4. asterisk-form | |
539 | ||
540 | The "asterisk-form" of request-target is only used for a server-wide | |
541 | OPTIONS request (Section 9.3.7 of [HTTP]). | |
542 | ||
543 | asterisk-form = "*" | |
544 | ||
545 | When a client wishes to request OPTIONS for the server as a whole, as | |
546 | opposed to a specific named resource of that server, the client MUST | |
547 | send only "*" (%x2A) as the request-target. For example, | |
548 | ||
549 | OPTIONS * HTTP/1.1 | |
550 | ||
551 | If a proxy receives an OPTIONS request with an absolute-form of | |
552 | request-target in which the URI has an empty path and no query | |
553 | component, then the last proxy on the request chain MUST send a | |
554 | request-target of "*" when it forwards the request to the indicated | |
555 | origin server. | |
556 | ||
557 | For example, the request | |
558 | ||
559 | OPTIONS http://www.example.org:8001 HTTP/1.1 | |
560 | ||
561 | would be forwarded by the final proxy as | |
562 | ||
563 | OPTIONS * HTTP/1.1 | |
564 | Host: www.example.org:8001 | |
565 | ||
566 | after connecting to port 8001 of host "www.example.org". | |
567 | ||
568 | 3.3. Reconstructing the Target URI | |
569 | ||
570 | The target URI is the request-target when the request-target is in | |
571 | absolute-form. In that case, a server will parse the URI into its | |
572 | generic components for further evaluation. | |
573 | ||
574 | Otherwise, the server reconstructs the target URI from the connection | |
575 | context and various parts of the request message in order to identify | |
576 | the target resource (Section 7.1 of [HTTP]): | |
577 | ||
578 | * If the server's configuration provides for a fixed URI scheme, or | |
579 | a scheme is provided by a trusted outbound gateway, that scheme is | |
580 | used for the target URI. This is common in large-scale | |
581 | deployments because a gateway server will receive the client's | |
582 | connection context and replace that with their own connection to | |
583 | the inbound server. Otherwise, if the request is received over a | |
584 | secured connection, the target URI's scheme is "https"; if not, | |
585 | the scheme is "http". | |
586 | ||
587 | * If the request-target is in authority-form, the target URI's | |
588 | authority component is the request-target. Otherwise, the target | |
589 | URI's authority component is the field value of the Host header | |
590 | field. If there is no Host header field or if its field value is | |
591 | empty or invalid, the target URI's authority component is empty. | |
592 | ||
593 | * If the request-target is in authority-form or asterisk-form, the | |
594 | target URI's combined path and query component is empty. | |
595 | Otherwise, the target URI's combined path and query component is | |
596 | the request-target. | |
597 | ||
598 | * The components of a reconstructed target URI, once determined as | |
599 | above, can be recombined into absolute-URI form by concatenating | |
600 | the scheme, "://", authority, and combined path and query | |
601 | component. | |
602 | ||
603 | Example 1: The following message received over a secure connection | |
604 | ||
605 | GET /pub/WWW/TheProject.html HTTP/1.1 | |
606 | Host: www.example.org | |
607 | ||
608 | has a target URI of | |
609 | ||
610 | https://www.example.org/pub/WWW/TheProject.html | |
611 | ||
612 | Example 2: The following message received over an insecure connection | |
613 | ||
614 | OPTIONS * HTTP/1.1 | |
615 | Host: www.example.org:8080 | |
616 | ||
617 | has a target URI of | |
618 | ||
619 | http://www.example.org:8080 | |
620 | ||
621 | If the target URI's authority component is empty and its URI scheme | |
622 | requires a non-empty authority (as is the case for "http" and | |
623 | "https"), the server can reject the request or determine whether a | |
624 | configured default applies that is consistent with the incoming | |
625 | connection's context. Context might include connection details like | |
626 | address and port, what security has been applied, and locally defined | |
627 | information specific to that server's configuration. An empty | |
628 | authority is replaced with the configured default before further | |
629 | processing of the request. | |
630 | ||
631 | Supplying a default name for authority within the context of a | |
632 | secured connection is inherently unsafe if there is any chance that | |
633 | the user agent's intended authority might differ from the default. A | |
634 | server that can uniquely identify an authority from the request | |
635 | context MAY use that identity as a default without this risk. | |
636 | Alternatively, it might be better to redirect the request to a safe | |
637 | resource that explains how to obtain a new client. | |
638 | ||
639 | Note that reconstructing the client's target URI is only half of the | |
640 | process for identifying a target resource. The other half is | |
641 | determining whether that target URI identifies a resource for which | |
642 | the server is willing and able to send a response, as defined in | |
643 | Section 7.4 of [HTTP]. | |
644 | ||
645 | 4. Status Line | |
646 | ||
647 | The first line of a response message is the status-line, consisting | |
648 | of the protocol version, a space (SP), the status code, and another | |
649 | space and ending with an OPTIONAL textual phrase describing the | |
650 | status code. | |
651 | ||
652 | status-line = HTTP-version SP status-code SP [ reason-phrase ] | |
653 | ||
654 | Although the status-line grammar rule requires that each of the | |
655 | component elements be separated by a single SP octet, recipients MAY | |
656 | instead parse on whitespace-delimited word boundaries and, aside from | |
657 | the line terminator, treat any form of whitespace as the SP separator | |
658 | while ignoring preceding or trailing whitespace; such whitespace | |
659 | includes one or more of the following octets: SP, HTAB, VT (%x0B), FF | |
660 | (%x0C), or bare CR. However, lenient parsing can result in response | |
661 | splitting security vulnerabilities if there are multiple recipients | |
662 | of the message and each has its own unique interpretation of | |
663 | robustness (see Section 11.1). | |
664 | ||
665 | The status-code element is a 3-digit integer code describing the | |
666 | result of the server's attempt to understand and satisfy the client's | |
667 | corresponding request. A recipient parses and interprets the | |
668 | remainder of the response message in light of the semantics defined | |
669 | for that status code, if the status code is recognized by that | |
670 | recipient, or in accordance with the class of that status code when | |
671 | the specific code is unrecognized. | |
672 | ||
673 | status-code = 3DIGIT | |
674 | ||
675 | HTTP's core status codes are defined in Section 15 of [HTTP], along | |
676 | with the classes of status codes, considerations for the definition | |
677 | of new status codes, and the IANA registry for collecting such | |
678 | definitions. | |
679 | ||
680 | The reason-phrase element exists for the sole purpose of providing a | |
681 | textual description associated with the numeric status code, mostly | |
682 | out of deference to earlier Internet application protocols that were | |
683 | more frequently used with interactive text clients. | |
684 | ||
685 | reason-phrase = 1*( HTAB / SP / VCHAR / obs-text ) | |
686 | ||
687 | A client SHOULD ignore the reason-phrase content because it is not a | |
688 | reliable channel for information (it might be translated for a given | |
689 | locale, overwritten by intermediaries, or discarded when the message | |
690 | is forwarded via other versions of HTTP). A server MUST send the | |
691 | space that separates the status-code from the reason-phrase even when | |
692 | the reason-phrase is absent (i.e., the status-line would end with the | |
693 | space). | |
694 | ||
695 | 5. Field Syntax | |
696 | ||
697 | Each field line consists of a case-insensitive field name followed by | |
698 | a colon (":"), optional leading whitespace, the field line value, and | |
699 | optional trailing whitespace. | |
700 | ||
701 | field-line = field-name ":" OWS field-value OWS | |
702 | ||
703 | Rules for parsing within field values are defined in Section 5.5 of | |
704 | [HTTP]. This section covers the generic syntax for header field | |
705 | inclusion within, and extraction from, HTTP/1.1 messages. | |
706 | ||
707 | 5.1. Field Line Parsing | |
708 | ||
709 | Messages are parsed using a generic algorithm, independent of the | |
710 | individual field names. The contents within a given field line value | |
711 | are not parsed until a later stage of message interpretation (usually | |
712 | after the message's entire field section has been processed). | |
713 | ||
714 | No whitespace is allowed between the field name and colon. In the | |
715 | past, differences in the handling of such whitespace have led to | |
716 | security vulnerabilities in request routing and response handling. A | |
717 | server MUST reject, with a response status code of 400 (Bad Request), | |
718 | any received request message that contains whitespace between a | |
719 | header field name and colon. A proxy MUST remove any such whitespace | |
720 | from a response message before forwarding the message downstream. | |
721 | ||
722 | A field line value might be preceded and/or followed by optional | |
723 | whitespace (OWS); a single SP preceding the field line value is | |
724 | preferred for consistent readability by humans. The field line value | |
725 | does not include that leading or trailing whitespace: OWS occurring | |
726 | before the first non-whitespace octet of the field line value, or | |
727 | after the last non-whitespace octet of the field line value, is | |
728 | excluded by parsers when extracting the field line value from a field | |
729 | line. | |
730 | ||
731 | 5.2. Obsolete Line Folding | |
732 | ||
733 | Historically, HTTP/1.x field values could be extended over multiple | |
734 | lines by preceding each extra line with at least one space or | |
735 | horizontal tab (obs-fold). This specification deprecates such line | |
736 | folding except within the "message/http" media type (Section 10.1). | |
737 | ||
738 | obs-fold = OWS CRLF RWS | |
739 | ; obsolete line folding | |
740 | ||
741 | A sender MUST NOT generate a message that includes line folding | |
742 | (i.e., that has any field line value that contains a match to the | |
743 | obs-fold rule) unless the message is intended for packaging within | |
744 | the "message/http" media type. | |
745 | ||
746 | A server that receives an obs-fold in a request message that is not | |
747 | within a "message/http" container MUST either reject the message by | |
748 | sending a 400 (Bad Request), preferably with a representation | |
749 | explaining that obsolete line folding is unacceptable, or replace | |
750 | each received obs-fold with one or more SP octets prior to | |
751 | interpreting the field value or forwarding the message downstream. | |
752 | ||
753 | A proxy or gateway that receives an obs-fold in a response message | |
754 | that is not within a "message/http" container MUST either discard the | |
755 | message and replace it with a 502 (Bad Gateway) response, preferably | |
756 | with a representation explaining that unacceptable line folding was | |
757 | received, or replace each received obs-fold with one or more SP | |
758 | octets prior to interpreting the field value or forwarding the | |
759 | message downstream. | |
760 | ||
761 | A user agent that receives an obs-fold in a response message that is | |
762 | not within a "message/http" container MUST replace each received | |
763 | obs-fold with one or more SP octets prior to interpreting the field | |
764 | value. | |
765 | ||
766 | 6. Message Body | |
767 | ||
768 | The message body (if any) of an HTTP/1.1 message is used to carry | |
769 | content (Section 6.4 of [HTTP]) for the request or response. The | |
770 | message body is identical to the content unless a transfer coding has | |
771 | been applied, as described in Section 6.1. | |
772 | ||
773 | message-body = *OCTET | |
774 | ||
775 | The rules for determining when a message body is present in an | |
776 | HTTP/1.1 message differ for requests and responses. | |
777 | ||
778 | The presence of a message body in a request is signaled by a | |
779 | Content-Length or Transfer-Encoding header field. Request message | |
780 | framing is independent of method semantics. | |
781 | ||
782 | The presence of a message body in a response, as detailed in | |
783 | Section 6.3, depends on both the request method to which it is | |
784 | responding and the response status code. This corresponds to when | |
785 | response content is allowed by HTTP semantics (Section 6.4.1 of | |
786 | [HTTP]). | |
787 | ||
788 | 6.1. Transfer-Encoding | |
789 | ||
790 | The Transfer-Encoding header field lists the transfer coding names | |
791 | corresponding to the sequence of transfer codings that have been (or | |
792 | will be) applied to the content in order to form the message body. | |
793 | Transfer codings are defined in Section 7. | |
794 | ||
795 | Transfer-Encoding = #transfer-coding | |
796 | ; defined in [HTTP], Section 10.1.4 | |
797 | ||
798 | Transfer-Encoding is analogous to the Content-Transfer-Encoding field | |
799 | of MIME, which was designed to enable safe transport of binary data | |
800 | over a 7-bit transport service ([RFC2045], Section 6). However, safe | |
801 | transport has a different focus for an 8bit-clean transfer protocol. | |
802 | In HTTP's case, Transfer-Encoding is primarily intended to accurately | |
803 | delimit dynamically generated content. It also serves to distinguish | |
804 | encodings that are only applied in transit from the encodings that | |
805 | are a characteristic of the selected representation. | |
806 | ||
807 | A recipient MUST be able to parse the chunked transfer coding | |
808 | (Section 7.1) because it plays a crucial role in framing messages | |
809 | when the content size is not known in advance. A sender MUST NOT | |
810 | apply the chunked transfer coding more than once to a message body | |
811 | (i.e., chunking an already chunked message is not allowed). If any | |
812 | transfer coding other than chunked is applied to a request's content, | |
813 | the sender MUST apply chunked as the final transfer coding to ensure | |
814 | that the message is properly framed. If any transfer coding other | |
815 | than chunked is applied to a response's content, the sender MUST | |
816 | either apply chunked as the final transfer coding or terminate the | |
817 | message by closing the connection. | |
818 | ||
819 | For example, | |
820 | ||
821 | Transfer-Encoding: gzip, chunked | |
822 | ||
823 | indicates that the content has been compressed using the gzip coding | |
824 | and then chunked using the chunked coding while forming the message | |
825 | body. | |
826 | ||
827 | Unlike Content-Encoding (Section 8.4.1 of [HTTP]), Transfer-Encoding | |
828 | is a property of the message, not of the representation. Any | |
829 | recipient along the request/response chain MAY decode the received | |
830 | transfer coding(s) or apply additional transfer coding(s) to the | |
831 | message body, assuming that corresponding changes are made to the | |
832 | Transfer-Encoding field value. Additional information about the | |
833 | encoding parameters can be provided by other header fields not | |
834 | defined by this specification. | |
835 | ||
836 | Transfer-Encoding MAY be sent in a response to a HEAD request or in a | |
837 | 304 (Not Modified) response (Section 15.4.5 of [HTTP]) to a GET | |
838 | request, neither of which includes a message body, to indicate that | |
839 | the origin server would have applied a transfer coding to the message | |
840 | body if the request had been an unconditional GET. This indication | |
841 | is not required, however, because any recipient on the response chain | |
842 | (including the origin server) can remove transfer codings when they | |
843 | are not needed. | |
844 | ||
845 | A server MUST NOT send a Transfer-Encoding header field in any | |
846 | response with a status code of 1xx (Informational) or 204 (No | |
847 | Content). A server MUST NOT send a Transfer-Encoding header field in | |
848 | any 2xx (Successful) response to a CONNECT request (Section 9.3.6 of | |
849 | [HTTP]). | |
850 | ||
851 | A server that receives a request message with a transfer coding it | |
852 | does not understand SHOULD respond with 501 (Not Implemented). | |
853 | ||
854 | Transfer-Encoding was added in HTTP/1.1. It is generally assumed | |
855 | that implementations advertising only HTTP/1.0 support will not | |
856 | understand how to process transfer-encoded content, and that an | |
857 | HTTP/1.0 message received with a Transfer-Encoding is likely to have | |
858 | been forwarded without proper handling of the chunked transfer coding | |
859 | in transit. | |
860 | ||
861 | A client MUST NOT send a request containing Transfer-Encoding unless | |
862 | it knows the server will handle HTTP/1.1 requests (or later minor | |
863 | revisions); such knowledge might be in the form of specific user | |
864 | configuration or by remembering the version of a prior received | |
865 | response. A server MUST NOT send a response containing Transfer- | |
866 | Encoding unless the corresponding request indicates HTTP/1.1 (or | |
867 | later minor revisions). | |
868 | ||
869 | Early implementations of Transfer-Encoding would occasionally send | |
870 | both a chunked transfer coding for message framing and an estimated | |
871 | Content-Length header field for use by progress bars. This is why | |
872 | Transfer-Encoding is defined as overriding Content-Length, as opposed | |
873 | to them being mutually incompatible. Unfortunately, forwarding such | |
874 | a message can lead to vulnerabilities regarding request smuggling | |
875 | (Section 11.2) or response splitting (Section 11.1) attacks if any | |
876 | downstream recipient fails to parse the message according to this | |
877 | specification, particularly when a downstream recipient only | |
878 | implements HTTP/1.0. | |
879 | ||
880 | A server MAY reject a request that contains both Content-Length and | |
881 | Transfer-Encoding or process such a request in accordance with the | |
882 | Transfer-Encoding alone. Regardless, the server MUST close the | |
883 | connection after responding to such a request to avoid the potential | |
884 | attacks. | |
885 | ||
886 | A server or client that receives an HTTP/1.0 message containing a | |
887 | Transfer-Encoding header field MUST treat the message as if the | |
888 | framing is faulty, even if a Content-Length is present, and close the | |
889 | connection after processing the message. The message sender might | |
890 | have retained a portion of the message, in buffer, that could be | |
891 | misinterpreted by further use of the connection. | |
892 | ||
893 | 6.2. Content-Length | |
894 | ||
895 | When a message does not have a Transfer-Encoding header field, a | |
896 | Content-Length header field (Section 8.6 of [HTTP]) can provide the | |
897 | anticipated size, as a decimal number of octets, for potential | |
898 | content. For messages that do include content, the Content-Length | |
899 | field value provides the framing information necessary for | |
900 | determining where the data (and message) ends. For messages that do | |
901 | not include content, the Content-Length indicates the size of the | |
902 | selected representation (Section 8.6 of [HTTP]). | |
903 | ||
904 | A sender MUST NOT send a Content-Length header field in any message | |
905 | that contains a Transfer-Encoding header field. | |
906 | ||
907 | | *Note:* HTTP's use of Content-Length for message framing | |
908 | | differs significantly from the same field's use in MIME, where | |
909 | | it is an optional field used only within the "message/external- | |
910 | | body" media-type. | |
911 | ||
912 | 6.3. Message Body Length | |
913 | ||
914 | The length of a message body is determined by one of the following | |
915 | (in order of precedence): | |
916 | ||
917 | 1. Any response to a HEAD request and any response with a 1xx | |
918 | (Informational), 204 (No Content), or 304 (Not Modified) status | |
919 | code is always terminated by the first empty line after the | |
920 | header fields, regardless of the header fields present in the | |
921 | message, and thus cannot contain a message body or trailer | |
922 | section. | |
923 | ||
924 | 2. Any 2xx (Successful) response to a CONNECT request implies that | |
925 | the connection will become a tunnel immediately after the empty | |
926 | line that concludes the header fields. A client MUST ignore any | |
927 | Content-Length or Transfer-Encoding header fields received in | |
928 | such a message. | |
929 | ||
930 | 3. If a message is received with both a Transfer-Encoding and a | |
931 | Content-Length header field, the Transfer-Encoding overrides the | |
932 | Content-Length. Such a message might indicate an attempt to | |
933 | perform request smuggling (Section 11.2) or response splitting | |
934 | (Section 11.1) and ought to be handled as an error. An | |
935 | intermediary that chooses to forward the message MUST first | |
936 | remove the received Content-Length field and process the | |
937 | Transfer-Encoding (as described below) prior to forwarding the | |
938 | message downstream. | |
939 | ||
940 | 4. If a Transfer-Encoding header field is present and the chunked | |
941 | transfer coding (Section 7.1) is the final encoding, the message | |
942 | body length is determined by reading and decoding the chunked | |
943 | data until the transfer coding indicates the data is complete. | |
944 | ||
945 | If a Transfer-Encoding header field is present in a response and | |
946 | the chunked transfer coding is not the final encoding, the | |
947 | message body length is determined by reading the connection until | |
948 | it is closed by the server. | |
949 | ||
950 | If a Transfer-Encoding header field is present in a request and | |
951 | the chunked transfer coding is not the final encoding, the | |
952 | message body length cannot be determined reliably; the server | |
953 | MUST respond with the 400 (Bad Request) status code and then | |
954 | close the connection. | |
955 | ||
956 | 5. If a message is received without Transfer-Encoding and with an | |
957 | invalid Content-Length header field, then the message framing is | |
958 | invalid and the recipient MUST treat it as an unrecoverable | |
959 | error, unless the field value can be successfully parsed as a | |
960 | comma-separated list (Section 5.6.1 of [HTTP]), all values in the | |
961 | list are valid, and all values in the list are the same (in which | |
962 | case, the message is processed with that single value used as the | |
963 | Content-Length field value). If the unrecoverable error is in a | |
964 | request message, the server MUST respond with a 400 (Bad Request) | |
965 | status code and then close the connection. If it is in a | |
966 | response message received by a proxy, the proxy MUST close the | |
967 | connection to the server, discard the received response, and send | |
968 | a 502 (Bad Gateway) response to the client. If it is in a | |
969 | response message received by a user agent, the user agent MUST | |
970 | close the connection to the server and discard the received | |
971 | response. | |
972 | ||
973 | 6. If a valid Content-Length header field is present without | |
974 | Transfer-Encoding, its decimal value defines the expected message | |
975 | body length in octets. If the sender closes the connection or | |
976 | the recipient times out before the indicated number of octets are | |
977 | received, the recipient MUST consider the message to be | |
978 | incomplete and close the connection. | |
979 | ||
980 | 7. If this is a request message and none of the above are true, then | |
981 | the message body length is zero (no message body is present). | |
982 | ||
983 | 8. Otherwise, this is a response message without a declared message | |
984 | body length, so the message body length is determined by the | |
985 | number of octets received prior to the server closing the | |
986 | connection. | |
987 | ||
988 | Since there is no way to distinguish a successfully completed, close- | |
989 | delimited response message from a partially received message | |
990 | interrupted by network failure, a server SHOULD generate encoding or | |
991 | length-delimited messages whenever possible. The close-delimiting | |
992 | feature exists primarily for backwards compatibility with HTTP/1.0. | |
993 | ||
994 | | *Note:* Request messages are never close-delimited because they | |
995 | | are always explicitly framed by length or transfer coding, with | |
996 | | the absence of both implying the request ends immediately after | |
997 | | the header section. | |
998 | ||
999 | A server MAY reject a request that contains a message body but not a | |
1000 | Content-Length by responding with 411 (Length Required). | |
1001 | ||
1002 | Unless a transfer coding other than chunked has been applied, a | |
1003 | client that sends a request containing a message body SHOULD use a | |
1004 | valid Content-Length header field if the message body length is known | |
1005 | in advance, rather than the chunked transfer coding, since some | |
1006 | existing services respond to chunked with a 411 (Length Required) | |
1007 | status code even though they understand the chunked transfer coding. | |
1008 | This is typically because such services are implemented via a gateway | |
1009 | that requires a content length in advance of being called, and the | |
1010 | server is unable or unwilling to buffer the entire request before | |
1011 | processing. | |
1012 | ||
1013 | A user agent that sends a request that contains a message body MUST | |
1014 | send either a valid Content-Length header field or use the chunked | |
1015 | transfer coding. A client MUST NOT use the chunked transfer coding | |
1016 | unless it knows the server will handle HTTP/1.1 (or later) requests; | |
1017 | such knowledge can be in the form of specific user configuration or | |
1018 | by remembering the version of a prior received response. | |
1019 | ||
1020 | If the final response to the last request on a connection has been | |
1021 | completely received and there remains additional data to read, a user | |
1022 | agent MAY discard the remaining data or attempt to determine if that | |
1023 | data belongs as part of the prior message body, which might be the | |
1024 | case if the prior message's Content-Length value is incorrect. A | |
1025 | client MUST NOT process, cache, or forward such extra data as a | |
1026 | separate response, since such behavior would be vulnerable to cache | |
1027 | poisoning. | |
1028 | ||
1029 | 7. Transfer Codings | |
1030 | ||
1031 | Transfer coding names are used to indicate an encoding transformation | |
1032 | that has been, can be, or might need to be applied to a message's | |
1033 | content in order to ensure "safe transport" through the network. | |
1034 | This differs from a content coding in that the transfer coding is a | |
1035 | property of the message rather than a property of the representation | |
1036 | that is being transferred. | |
1037 | ||
1038 | All transfer-coding names are case-insensitive and ought to be | |
1039 | registered within the HTTP Transfer Coding registry, as defined in | |
1040 | Section 7.3. They are used in the Transfer-Encoding (Section 6.1) | |
1041 | and TE (Section 10.1.4 of [HTTP]) header fields (the latter also | |
1042 | defining the "transfer-coding" grammar). | |
1043 | ||
1044 | 7.1. Chunked Transfer Coding | |
1045 | ||
1046 | The chunked transfer coding wraps content in order to transfer it as | |
1047 | a series of chunks, each with its own size indicator, followed by an | |
1048 | OPTIONAL trailer section containing trailer fields. Chunked enables | |
1049 | content streams of unknown size to be transferred as a sequence of | |
1050 | length-delimited buffers, which enables the sender to retain | |
1051 | connection persistence and the recipient to know when it has received | |
1052 | the entire message. | |
1053 | ||
1054 | chunked-body = *chunk | |
1055 | last-chunk | |
1056 | trailer-section | |
1057 | CRLF | |
1058 | ||
1059 | chunk = chunk-size [ chunk-ext ] CRLF | |
1060 | chunk-data CRLF | |
1061 | chunk-size = 1*HEXDIG | |
1062 | last-chunk = 1*("0") [ chunk-ext ] CRLF | |
1063 | ||
1064 | chunk-data = 1*OCTET ; a sequence of chunk-size octets | |
1065 | ||
1066 | The chunk-size field is a string of hex digits indicating the size of | |
1067 | the chunk-data in octets. The chunked transfer coding is complete | |
1068 | when a chunk with a chunk-size of zero is received, possibly followed | |
1069 | by a trailer section, and finally terminated by an empty line. | |
1070 | ||
1071 | A recipient MUST be able to parse and decode the chunked transfer | |
1072 | coding. | |
1073 | ||
1074 | HTTP/1.1 does not define any means to limit the size of a chunked | |
1075 | response such that an intermediary can be assured of buffering the | |
1076 | entire response. Additionally, very large chunk sizes may cause | |
1077 | overflows or loss of precision if their values are not represented | |
1078 | accurately in a receiving implementation. Therefore, recipients MUST | |
1079 | anticipate potentially large hexadecimal numerals and prevent parsing | |
1080 | errors due to integer conversion overflows or precision loss due to | |
1081 | integer representation. | |
1082 | ||
1083 | The chunked coding does not define any parameters. Their presence | |
1084 | SHOULD be treated as an error. | |
1085 | ||
1086 | 7.1.1. Chunk Extensions | |
1087 | ||
1088 | The chunked coding allows each chunk to include zero or more chunk | |
1089 | extensions, immediately following the chunk-size, for the sake of | |
1090 | supplying per-chunk metadata (such as a signature or hash), mid- | |
1091 | message control information, or randomization of message body size. | |
1092 | ||
1093 | chunk-ext = *( BWS ";" BWS chunk-ext-name | |
1094 | [ BWS "=" BWS chunk-ext-val ] ) | |
1095 | ||
1096 | chunk-ext-name = token | |
1097 | chunk-ext-val = token / quoted-string | |
1098 | ||
1099 | The chunked coding is specific to each connection and is likely to be | |
1100 | removed or recoded by each recipient (including intermediaries) | |
1101 | before any higher-level application would have a chance to inspect | |
1102 | the extensions. Hence, the use of chunk extensions is generally | |
1103 | limited to specialized HTTP services such as "long polling" (where | |
1104 | client and server can have shared expectations regarding the use of | |
1105 | chunk extensions) or for padding within an end-to-end secured | |
1106 | connection. | |
1107 | ||
1108 | A recipient MUST ignore unrecognized chunk extensions. A server | |
1109 | ought to limit the total length of chunk extensions received in a | |
1110 | request to an amount reasonable for the services provided, in the | |
1111 | same way that it applies length limitations and timeouts for other | |
1112 | parts of a message, and generate an appropriate 4xx (Client Error) | |
1113 | response if that amount is exceeded. | |
1114 | ||
1115 | 7.1.2. Chunked Trailer Section | |
1116 | ||
1117 | A trailer section allows the sender to include additional fields at | |
1118 | the end of a chunked message in order to supply metadata that might | |
1119 | be dynamically generated while the content is sent, such as a message | |
1120 | integrity check, digital signature, or post-processing status. The | |
1121 | proper use and limitations of trailer fields are defined in | |
1122 | Section 6.5 of [HTTP]. | |
1123 | ||
1124 | trailer-section = *( field-line CRLF ) | |
1125 | ||
1126 | A recipient that removes the chunked coding from a message MAY | |
1127 | selectively retain or discard the received trailer fields. A | |
1128 | recipient that retains a received trailer field MUST either store/ | |
1129 | forward the trailer field separately from the received header fields | |
1130 | or merge the received trailer field into the header section. A | |
1131 | recipient MUST NOT merge a received trailer field into the header | |
1132 | section unless its corresponding header field definition explicitly | |
1133 | permits and instructs how the trailer field value can be safely | |
1134 | merged. | |
1135 | ||
1136 | 7.1.3. Decoding Chunked | |
1137 | ||
1138 | A process for decoding the chunked transfer coding can be represented | |
1139 | in pseudo-code as: | |
1140 | ||
1141 | length := 0 | |
1142 | read chunk-size, chunk-ext (if any), and CRLF | |
1143 | while (chunk-size > 0) { | |
1144 | read chunk-data and CRLF | |
1145 | append chunk-data to content | |
1146 | length := length + chunk-size | |
1147 | read chunk-size, chunk-ext (if any), and CRLF | |
1148 | } | |
1149 | read trailer field | |
1150 | while (trailer field is not empty) { | |
1151 | if (trailer fields are stored/forwarded separately) { | |
1152 | append trailer field to existing trailer fields | |
1153 | } | |
1154 | else if (trailer field is understood and defined as mergeable) { | |
1155 | merge trailer field with existing header fields | |
1156 | } | |
1157 | else { | |
1158 | discard trailer field | |
1159 | } | |
1160 | read trailer field | |
1161 | } | |
1162 | Content-Length := length | |
1163 | Remove "chunked" from Transfer-Encoding | |
1164 | ||
1165 | 7.2. Transfer Codings for Compression | |
1166 | ||
1167 | The following transfer coding names for compression are defined by | |
1168 | the same algorithm as their corresponding content coding: | |
1169 | ||
1170 | compress (and x-compress) | |
1171 | See Section 8.4.1.1 of [HTTP]. | |
1172 | ||
1173 | deflate | |
1174 | See Section 8.4.1.2 of [HTTP]. | |
1175 | ||
1176 | gzip (and x-gzip) | |
1177 | See Section 8.4.1.3 of [HTTP]. | |
1178 | ||
1179 | The compression codings do not define any parameters. The presence | |
1180 | of parameters with any of these compression codings SHOULD be treated | |
1181 | as an error. | |
1182 | ||
1183 | 7.3. Transfer Coding Registry | |
1184 | ||
1185 | The "HTTP Transfer Coding Registry" defines the namespace for | |
1186 | transfer coding names. It is maintained at | |
1187 | <https://www.iana.org/assignments/http-parameters>. | |
1188 | ||
1189 | Registrations MUST include the following fields: | |
1190 | ||
1191 | * Name | |
1192 | ||
1193 | * Description | |
1194 | ||
1195 | * Pointer to specification text | |
1196 | ||
1197 | Names of transfer codings MUST NOT overlap with names of content | |
1198 | codings (Section 8.4.1 of [HTTP]) unless the encoding transformation | |
1199 | is identical, as is the case for the compression codings defined in | |
1200 | Section 7.2. | |
1201 | ||
1202 | The TE header field (Section 10.1.4 of [HTTP]) uses a pseudo- | |
1203 | parameter named "q" as the rank value when multiple transfer codings | |
1204 | are acceptable. Future registrations of transfer codings SHOULD NOT | |
1205 | define parameters called "q" (case-insensitively) in order to avoid | |
1206 | ambiguities. | |
1207 | ||
1208 | Values to be added to this namespace require IETF Review (see | |
1209 | Section 4.8 of [RFC8126]) and MUST conform to the purpose of transfer | |
1210 | coding defined in this specification. | |
1211 | ||
1212 | Use of program names for the identification of encoding formats is | |
1213 | not desirable and is discouraged for future encodings. | |
1214 | ||
1215 | 7.4. Negotiating Transfer Codings | |
1216 | ||
1217 | The TE field (Section 10.1.4 of [HTTP]) is used in HTTP/1.1 to | |
1218 | indicate what transfer codings, besides chunked, the client is | |
1219 | willing to accept in the response and whether the client is willing | |
1220 | to preserve trailer fields in a chunked transfer coding. | |
1221 | ||
1222 | A client MUST NOT send the chunked transfer coding name in TE; | |
1223 | chunked is always acceptable for HTTP/1.1 recipients. | |
1224 | ||
1225 | Three examples of TE use are below. | |
1226 | ||
1227 | TE: deflate | |
1228 | TE: | |
1229 | TE: trailers, deflate;q=0.5 | |
1230 | ||
1231 | When multiple transfer codings are acceptable, the client MAY rank | |
1232 | the codings by preference using a case-insensitive "q" parameter | |
1233 | (similar to the qvalues used in content negotiation fields; see | |
1234 | Section 12.4.2 of [HTTP]). The rank value is a real number in the | |
1235 | range 0 through 1, where 0.001 is the least preferred and 1 is the | |
1236 | most preferred; a value of 0 means "not acceptable". | |
1237 | ||
1238 | If the TE field value is empty or if no TE field is present, the only | |
1239 | acceptable transfer coding is chunked. A message with no transfer | |
1240 | coding is always acceptable. | |
1241 | ||
1242 | The keyword "trailers" indicates that the sender will not discard | |
1243 | trailer fields, as described in Section 6.5 of [HTTP]. | |
1244 | ||
1245 | Since the TE header field only applies to the immediate connection, a | |
1246 | sender of TE MUST also send a "TE" connection option within the | |
1247 | Connection header field (Section 7.6.1 of [HTTP]) in order to prevent | |
1248 | the TE header field from being forwarded by intermediaries that do | |
1249 | not support its semantics. | |
1250 | ||
1251 | 8. Handling Incomplete Messages | |
1252 | ||
1253 | A server that receives an incomplete request message, usually due to | |
1254 | a canceled request or a triggered timeout exception, MAY send an | |
1255 | error response prior to closing the connection. | |
1256 | ||
1257 | A client that receives an incomplete response message, which can | |
1258 | occur when a connection is closed prematurely or when decoding a | |
1259 | supposedly chunked transfer coding fails, MUST record the message as | |
1260 | incomplete. Cache requirements for incomplete responses are defined | |
1261 | in Section 3.3 of [CACHING]. | |
1262 | ||
1263 | If a response terminates in the middle of the header section (before | |
1264 | the empty line is received) and the status code might rely on header | |
1265 | fields to convey the full meaning of the response, then the client | |
1266 | cannot assume that meaning has been conveyed; the client might need | |
1267 | to repeat the request in order to determine what action to take next. | |
1268 | ||
1269 | A message body that uses the chunked transfer coding is incomplete if | |
1270 | the zero-sized chunk that terminates the encoding has not been | |
1271 | received. A message that uses a valid Content-Length is incomplete | |
1272 | if the size of the message body received (in octets) is less than the | |
1273 | value given by Content-Length. A response that has neither chunked | |
1274 | transfer coding nor Content-Length is terminated by closure of the | |
1275 | connection and, if the header section was received intact, is | |
1276 | considered complete unless an error was indicated by the underlying | |
1277 | connection (e.g., an "incomplete close" in TLS would leave the | |
1278 | response incomplete, as described in Section 9.8). | |
1279 | ||
1280 | 9. Connection Management | |
1281 | ||
1282 | HTTP messaging is independent of the underlying transport- or | |
1283 | session-layer connection protocol(s). HTTP only presumes a reliable | |
1284 | transport with in-order delivery of requests and the corresponding | |
1285 | in-order delivery of responses. The mapping of HTTP request and | |
1286 | response structures onto the data units of an underlying transport | |
1287 | protocol is outside the scope of this specification. | |
1288 | ||
1289 | As described in Section 7.3 of [HTTP], the specific connection | |
1290 | protocols to be used for an HTTP interaction are determined by client | |
1291 | configuration and the target URI. For example, the "http" URI scheme | |
1292 | (Section 4.2.1 of [HTTP]) indicates a default connection of TCP over | |
1293 | IP, with a default TCP port of 80, but the client might be configured | |
1294 | to use a proxy via some other connection, port, or protocol. | |
1295 | ||
1296 | HTTP implementations are expected to engage in connection management, | |
1297 | which includes maintaining the state of current connections, | |
1298 | establishing a new connection or reusing an existing connection, | |
1299 | processing messages received on a connection, detecting connection | |
1300 | failures, and closing each connection. Most clients maintain | |
1301 | multiple connections in parallel, including more than one connection | |
1302 | per server endpoint. Most servers are designed to maintain thousands | |
1303 | of concurrent connections, while controlling request queues to enable | |
1304 | fair use and detect denial-of-service attacks. | |
1305 | ||
1306 | 9.1. Establishment | |
1307 | ||
1308 | It is beyond the scope of this specification to describe how | |
1309 | connections are established via various transport- or session-layer | |
1310 | protocols. Each HTTP connection maps to one underlying transport | |
1311 | connection. | |
1312 | ||
1313 | 9.2. Associating a Response to a Request | |
1314 | ||
1315 | HTTP/1.1 does not include a request identifier for associating a | |
1316 | given request message with its corresponding one or more response | |
1317 | messages. Hence, it relies on the order of response arrival to | |
1318 | correspond exactly to the order in which requests are made on the | |
1319 | same connection. More than one response message per request only | |
1320 | occurs when one or more informational responses (1xx; see | |
1321 | Section 15.2 of [HTTP]) precede a final response to the same request. | |
1322 | ||
1323 | A client that has more than one outstanding request on a connection | |
1324 | MUST maintain a list of outstanding requests in the order sent and | |
1325 | MUST associate each received response message on that connection to | |
1326 | the first outstanding request that has not yet received a final (non- | |
1327 | 1xx) response. | |
1328 | ||
1329 | If a client receives data on a connection that doesn't have | |
1330 | outstanding requests, the client MUST NOT consider that data to be a | |
1331 | valid response; the client SHOULD close the connection, since message | |
1332 | delimitation is now ambiguous, unless the data consists only of one | |
1333 | or more CRLF (which can be discarded per Section 2.2). | |
1334 | ||
1335 | 9.3. Persistence | |
1336 | ||
1337 | HTTP/1.1 defaults to the use of "persistent connections", allowing | |
1338 | multiple requests and responses to be carried over a single | |
1339 | connection. HTTP implementations SHOULD support persistent | |
1340 | connections. | |
1341 | ||
1342 | A recipient determines whether a connection is persistent or not | |
1343 | based on the protocol version and Connection header field | |
1344 | (Section 7.6.1 of [HTTP]) in the most recently received message, if | |
1345 | any: | |
1346 | ||
1347 | * If the "close" connection option is present (Section 9.6), the | |
1348 | connection will not persist after the current response; else, | |
1349 | ||
1350 | * If the received protocol is HTTP/1.1 (or later), the connection | |
1351 | will persist after the current response; else, | |
1352 | ||
1353 | * If the received protocol is HTTP/1.0, the "keep-alive" connection | |
1354 | option is present, either the recipient is not a proxy or the | |
1355 | message is a response, and the recipient wishes to honor the | |
1356 | HTTP/1.0 "keep-alive" mechanism, the connection will persist after | |
1357 | the current response; otherwise, | |
1358 | ||
1359 | * The connection will close after the current response. | |
1360 | ||
1361 | A client that does not support persistent connections MUST send the | |
1362 | "close" connection option in every request message. | |
1363 | ||
1364 | A server that does not support persistent connections MUST send the | |
1365 | "close" connection option in every response message that does not | |
1366 | have a 1xx (Informational) status code. | |
1367 | ||
1368 | A client MAY send additional requests on a persistent connection | |
1369 | until it sends or receives a "close" connection option or receives an | |
1370 | HTTP/1.0 response without a "keep-alive" connection option. | |
1371 | ||
1372 | In order to remain persistent, all messages on a connection need to | |
1373 | have a self-defined message length (i.e., one not defined by closure | |
1374 | of the connection), as described in Section 6. A server MUST read | |
1375 | the entire request message body or close the connection after sending | |
1376 | its response; otherwise, the remaining data on a persistent | |
1377 | connection would be misinterpreted as the next request. Likewise, a | |
1378 | client MUST read the entire response message body if it intends to | |
1379 | reuse the same connection for a subsequent request. | |
1380 | ||
1381 | A proxy server MUST NOT maintain a persistent connection with an | |
1382 | HTTP/1.0 client (see Appendix C.2.2 for information and discussion of | |
1383 | the problems with the Keep-Alive header field implemented by many | |
1384 | HTTP/1.0 clients). | |
1385 | ||
1386 | See Appendix C.2.2 for more information on backwards compatibility | |
1387 | with HTTP/1.0 clients. | |
1388 | ||
1389 | 9.3.1. Retrying Requests | |
1390 | ||
1391 | Connections can be closed at any time, with or without intention. | |
1392 | Implementations ought to anticipate the need to recover from | |
1393 | asynchronous close events. The conditions under which a client can | |
1394 | automatically retry a sequence of outstanding requests are defined in | |
1395 | Section 9.2.2 of [HTTP]. | |
1396 | ||
1397 | 9.3.2. Pipelining | |
1398 | ||
1399 | A client that supports persistent connections MAY "pipeline" its | |
1400 | requests (i.e., send multiple requests without waiting for each | |
1401 | response). A server MAY process a sequence of pipelined requests in | |
1402 | parallel if they all have safe methods (Section 9.2.1 of [HTTP]), but | |
1403 | it MUST send the corresponding responses in the same order that the | |
1404 | requests were received. | |
1405 | ||
1406 | A client that pipelines requests SHOULD retry unanswered requests if | |
1407 | the connection closes before it receives all of the corresponding | |
1408 | responses. When retrying pipelined requests after a failed | |
1409 | connection (a connection not explicitly closed by the server in its | |
1410 | last complete response), a client MUST NOT pipeline immediately after | |
1411 | connection establishment, since the first remaining request in the | |
1412 | prior pipeline might have caused an error response that can be lost | |
1413 | again if multiple requests are sent on a prematurely closed | |
1414 | connection (see the TCP reset problem described in Section 9.6). | |
1415 | ||
1416 | Idempotent methods (Section 9.2.2 of [HTTP]) are significant to | |
1417 | pipelining because they can be automatically retried after a | |
1418 | connection failure. A user agent SHOULD NOT pipeline requests after | |
1419 | a non-idempotent method, until the final response status code for | |
1420 | that method has been received, unless the user agent has a means to | |
1421 | detect and recover from partial failure conditions involving the | |
1422 | pipelined sequence. | |
1423 | ||
1424 | An intermediary that receives pipelined requests MAY pipeline those | |
1425 | requests when forwarding them inbound, since it can rely on the | |
1426 | outbound user agent(s) to determine what requests can be safely | |
1427 | pipelined. If the inbound connection fails before receiving a | |
1428 | response, the pipelining intermediary MAY attempt to retry a sequence | |
1429 | of requests that have yet to receive a response if the requests all | |
1430 | have idempotent methods; otherwise, the pipelining intermediary | |
1431 | SHOULD forward any received responses and then close the | |
1432 | corresponding outbound connection(s) so that the outbound user | |
1433 | agent(s) can recover accordingly. | |
1434 | ||
1435 | 9.4. Concurrency | |
1436 | ||
1437 | A client ought to limit the number of simultaneous open connections | |
1438 | that it maintains to a given server. | |
1439 | ||
1440 | Previous revisions of HTTP gave a specific number of connections as a | |
1441 | ceiling, but this was found to be impractical for many applications. | |
1442 | As a result, this specification does not mandate a particular maximum | |
1443 | number of connections but, instead, encourages clients to be | |
1444 | conservative when opening multiple connections. | |
1445 | ||
1446 | Multiple connections are typically used to avoid the "head-of-line | |
1447 | blocking" problem, wherein a request that takes significant server- | |
1448 | side processing and/or transfers very large content would block | |
1449 | subsequent requests on the same connection. However, each connection | |
1450 | consumes server resources. | |
1451 | ||
1452 | Furthermore, using multiple connections can cause undesirable side | |
1453 | effects in congested networks. Using larger numbers of connections | |
1454 | can also cause side effects in otherwise uncongested networks, | |
1455 | because their aggregate and initially synchronized sending behavior | |
1456 | can cause congestion that would not have been present if fewer | |
1457 | parallel connections had been used. | |
1458 | ||
1459 | Note that a server might reject traffic that it deems abusive or | |
1460 | characteristic of a denial-of-service attack, such as an excessive | |
1461 | number of open connections from a single client. | |
1462 | ||
1463 | 9.5. Failures and Timeouts | |
1464 | ||
1465 | Servers will usually have some timeout value beyond which they will | |
1466 | no longer maintain an inactive connection. Proxy servers might make | |
1467 | this a higher value since it is likely that the client will be making | |
1468 | more connections through the same proxy server. The use of | |
1469 | persistent connections places no requirements on the length (or | |
1470 | existence) of this timeout for either the client or the server. | |
1471 | ||
1472 | A client or server that wishes to time out SHOULD issue a graceful | |
1473 | close on the connection. Implementations SHOULD constantly monitor | |
1474 | open connections for a received closure signal and respond to it as | |
1475 | appropriate, since prompt closure of both sides of a connection | |
1476 | enables allocated system resources to be reclaimed. | |
1477 | ||
1478 | A client, server, or proxy MAY close the transport connection at any | |
1479 | time. For example, a client might have started to send a new request | |
1480 | at the same time that the server has decided to close the "idle" | |
1481 | connection. From the server's point of view, the connection is being | |
1482 | closed while it was idle, but from the client's point of view, a | |
1483 | request is in progress. | |
1484 | ||
1485 | A server SHOULD sustain persistent connections, when possible, and | |
1486 | allow the underlying transport's flow-control mechanisms to resolve | |
1487 | temporary overloads rather than terminate connections with the | |
1488 | expectation that clients will retry. The latter technique can | |
1489 | exacerbate network congestion or server load. | |
1490 | ||
1491 | A client sending a message body SHOULD monitor the network connection | |
1492 | for an error response while it is transmitting the request. If the | |
1493 | client sees a response that indicates the server does not wish to | |
1494 | receive the message body and is closing the connection, the client | |
1495 | SHOULD immediately cease transmitting the body and close its side of | |
1496 | the connection. | |
1497 | ||
1498 | 9.6. Tear-down | |
1499 | ||
1500 | The "close" connection option is defined as a signal that the sender | |
1501 | will close this connection after completion of the response. A | |
1502 | sender SHOULD send a Connection header field (Section 7.6.1 of | |
1503 | [HTTP]) containing the "close" connection option when it intends to | |
1504 | close a connection. For example, | |
1505 | ||
1506 | Connection: close | |
1507 | ||
1508 | as a request header field indicates that this is the last request | |
1509 | that the client will send on this connection, while in a response, | |
1510 | the same field indicates that the server is going to close this | |
1511 | connection after the response message is complete. | |
1512 | ||
1513 | Note that the field name "Close" is reserved, since using that name | |
1514 | as a header field might conflict with the "close" connection option. | |
1515 | ||
1516 | A client that sends a "close" connection option MUST NOT send further | |
1517 | requests on that connection (after the one containing the "close") | |
1518 | and MUST close the connection after reading the final response | |
1519 | message corresponding to this request. | |
1520 | ||
1521 | A server that receives a "close" connection option MUST initiate | |
1522 | closure of the connection (see below) after it sends the final | |
1523 | response to the request that contained the "close" connection option. | |
1524 | The server SHOULD send a "close" connection option in its final | |
1525 | response on that connection. The server MUST NOT process any further | |
1526 | requests received on that connection. | |
1527 | ||
1528 | A server that sends a "close" connection option MUST initiate closure | |
1529 | of the connection (see below) after it sends the response containing | |
1530 | the "close" connection option. The server MUST NOT process any | |
1531 | further requests received on that connection. | |
1532 | ||
1533 | A client that receives a "close" connection option MUST cease sending | |
1534 | requests on that connection and close the connection after reading | |
1535 | the response message containing the "close" connection option; if | |
1536 | additional pipelined requests had been sent on the connection, the | |
1537 | client SHOULD NOT assume that they will be processed by the server. | |
1538 | ||
1539 | If a server performs an immediate close of a TCP connection, there is | |
1540 | a significant risk that the client will not be able to read the last | |
1541 | HTTP response. If the server receives additional data from the | |
1542 | client on a fully closed connection, such as another request sent by | |
1543 | the client before receiving the server's response, the server's TCP | |
1544 | stack will send a reset packet to the client; unfortunately, the | |
1545 | reset packet might erase the client's unacknowledged input buffers | |
1546 | before they can be read and interpreted by the client's HTTP parser. | |
1547 | ||
1548 | To avoid the TCP reset problem, servers typically close a connection | |
1549 | in stages. First, the server performs a half-close by closing only | |
1550 | the write side of the read/write connection. The server then | |
1551 | continues to read from the connection until it receives a | |
1552 | corresponding close by the client, or until the server is reasonably | |
1553 | certain that its own TCP stack has received the client's | |
1554 | acknowledgement of the packet(s) containing the server's last | |
1555 | response. Finally, the server fully closes the connection. | |
1556 | ||
1557 | It is unknown whether the reset problem is exclusive to TCP or might | |
1558 | also be found in other transport connection protocols. | |
1559 | ||
1560 | Note that a TCP connection that is half-closed by the client does not | |
1561 | delimit a request message, nor does it imply that the client is no | |
1562 | longer interested in a response. In general, transport signals | |
1563 | cannot be relied upon to signal edge cases, since HTTP/1.1 is | |
1564 | independent of transport. | |
1565 | ||
1566 | 9.7. TLS Connection Initiation | |
1567 | ||
1568 | Conceptually, HTTP/TLS is simply sending HTTP messages over a | |
1569 | connection secured via TLS [TLS13]. | |
1570 | ||
1571 | The HTTP client also acts as the TLS client. It initiates a | |
1572 | connection to the server on the appropriate port and sends the TLS | |
1573 | ClientHello to begin the TLS handshake. When the TLS handshake has | |
1574 | finished, the client may then initiate the first HTTP request. All | |
1575 | HTTP data MUST be sent as TLS "application data" but is otherwise | |
1576 | treated like a normal connection for HTTP (including potential reuse | |
1577 | as a persistent connection). | |
1578 | ||
1579 | 9.8. TLS Connection Closure | |
1580 | ||
1581 | TLS uses an exchange of closure alerts prior to (non-error) | |
1582 | connection closure to provide secure connection closure; see | |
1583 | Section 6.1 of [TLS13]. When a valid closure alert is received, an | |
1584 | implementation can be assured that no further data will be received | |
1585 | on that connection. | |
1586 | ||
1587 | When an implementation knows that it has sent or received all the | |
1588 | message data that it cares about, typically by detecting HTTP message | |
1589 | boundaries, it might generate an "incomplete close" by sending a | |
1590 | closure alert and then closing the connection without waiting to | |
1591 | receive the corresponding closure alert from its peer. | |
1592 | ||
1593 | An incomplete close does not call into question the security of the | |
1594 | data already received, but it could indicate that subsequent data | |
1595 | might have been truncated. As TLS is not directly aware of HTTP | |
1596 | message framing, it is necessary to examine the HTTP data itself to | |
1597 | determine whether messages are complete. Handling of incomplete | |
1598 | messages is defined in Section 8. | |
1599 | ||
1600 | When encountering an incomplete close, a client SHOULD treat as | |
1601 | completed all requests for which it has received either | |
1602 | ||
1603 | 1. as much data as specified in the Content-Length header field or | |
1604 | ||
1605 | 2. the terminal zero-length chunk (when Transfer-Encoding of chunked | |
1606 | is used). | |
1607 | ||
1608 | A response that has neither chunked transfer coding nor Content- | |
1609 | Length is complete only if a valid closure alert has been received. | |
1610 | Treating an incomplete message as complete could expose | |
1611 | implementations to attack. | |
1612 | ||
1613 | A client detecting an incomplete close SHOULD recover gracefully. | |
1614 | ||
1615 | Clients MUST send a closure alert before closing the connection. | |
1616 | Clients that do not expect to receive any more data MAY choose not to | |
1617 | wait for the server's closure alert and simply close the connection, | |
1618 | thus generating an incomplete close on the server side. | |
1619 | ||
1620 | Servers SHOULD be prepared to receive an incomplete close from the | |
1621 | client, since the client can often locate the end of server data. | |
1622 | ||
1623 | Servers MUST attempt to initiate an exchange of closure alerts with | |
1624 | the client before closing the connection. Servers MAY close the | |
1625 | connection after sending the closure alert, thus generating an | |
1626 | incomplete close on the client side. | |
1627 | ||
1628 | 10. Enclosing Messages as Data | |
1629 | ||
1630 | 10.1. Media Type message/http | |
1631 | ||
1632 | The "message/http" media type can be used to enclose a single HTTP | |
1633 | request or response message, provided that it obeys the MIME | |
1634 | restrictions for all "message" types regarding line length and | |
1635 | encodings. Because of the line length limitations, field values | |
1636 | within "message/http" are allowed to use line folding (obs-fold), as | |
1637 | described in Section 5.2, to convey the field value over multiple | |
1638 | lines. A recipient of "message/http" data MUST replace any obsolete | |
1639 | line folding with one or more SP characters when the message is | |
1640 | consumed. | |
1641 | ||
1642 | Type name: message | |
1643 | ||
1644 | Subtype name: http | |
1645 | ||
1646 | Required parameters: N/A | |
1647 | ||
1648 | Optional parameters: version, msgtype | |
1649 | ||
1650 | version: The HTTP-version number of the enclosed message (e.g., | |
1651 | "1.1"). If not present, the version can be determined from the | |
1652 | first line of the body. | |
1653 | ||
1654 | msgtype: The message type -- "request" or "response". If not | |
1655 | present, the type can be determined from the first line of the | |
1656 | body. | |
1657 | ||
1658 | Encoding considerations: only "7bit", "8bit", or "binary" are | |
1659 | permitted | |
1660 | ||
1661 | Security considerations: see Section 11 | |
1662 | ||
1663 | Interoperability considerations: N/A | |
1664 | ||
1665 | Published specification: RFC 9112 (see Section 10.1). | |
1666 | ||
1667 | Applications that use this media type: N/A | |
1668 | ||
1669 | Fragment identifier considerations: N/A | |
1670 | ||
1671 | Additional information: Magic number(s): N/A | |
1672 | ||
1673 | Deprecated alias names for this type: N/A | |
1674 | ||
1675 | File extension(s): N/A | |
1676 | ||
1677 | Macintosh file type code(s): N/A | |
1678 | ||
1679 | Person and email address to contact for further information: See Aut | |
1680 | hors' Addresses section. | |
1681 | ||
1682 | Intended usage: COMMON | |
1683 | ||
1684 | Restrictions on usage: N/A | |
1685 | ||
1686 | Author: See Authors' Addresses section. | |
1687 | ||
1688 | Change controller: IESG | |
1689 | ||
1690 | 10.2. Media Type application/http | |
1691 | ||
1692 | The "application/http" media type can be used to enclose a pipeline | |
1693 | of one or more HTTP request or response messages (not intermixed). | |
1694 | ||
1695 | Type name: application | |
1696 | ||
1697 | Subtype name: http | |
1698 | ||
1699 | Required parameters: N/A | |
1700 | ||
1701 | Optional parameters: version, msgtype | |
1702 | ||
1703 | version: The HTTP-version number of the enclosed messages (e.g., | |
1704 | "1.1"). If not present, the version can be determined from the | |
1705 | first line of the body. | |
1706 | ||
1707 | msgtype: The message type -- "request" or "response". If not | |
1708 | present, the type can be determined from the first line of the | |
1709 | body. | |
1710 | ||
1711 | Encoding considerations: HTTP messages enclosed by this type are in | |
1712 | "binary" format; use of an appropriate Content-Transfer-Encoding | |
1713 | is required when transmitted via email. | |
1714 | ||
1715 | Security considerations: see Section 11 | |
1716 | ||
1717 | Interoperability considerations: N/A | |
1718 | ||
1719 | Published specification: RFC 9112 (see Section 10.2). | |
1720 | ||
1721 | Applications that use this media type: N/A | |
1722 | ||
1723 | Fragment identifier considerations: N/A | |
1724 | ||
1725 | Additional information: Deprecated alias names for this type: N/A | |
1726 | ||
1727 | Magic number(s): N/A | |
1728 | ||
1729 | File extension(s): N/A | |
1730 | ||
1731 | Macintosh file type code(s): N/A | |
1732 | ||
1733 | Person and email address to contact for further information: See Aut | |
1734 | hors' Addresses section. | |
1735 | ||
1736 | Intended usage: COMMON | |
1737 | ||
1738 | Restrictions on usage: N/A | |
1739 | ||
1740 | Author: See Authors' Addresses section. | |
1741 | ||
1742 | Change controller: IESG | |
1743 | ||
1744 | 11. Security Considerations | |
1745 | ||
1746 | This section is meant to inform developers, information providers, | |
1747 | and users about known security considerations relevant to HTTP | |
1748 | message syntax and parsing. Security considerations about HTTP | |
1749 | semantics, content, and routing are addressed in [HTTP]. | |
1750 | ||
1751 | 11.1. Response Splitting | |
1752 | ||
1753 | Response splitting (a.k.a. CRLF injection) is a common technique, | |
1754 | used in various attacks on Web usage, that exploits the line-based | |
1755 | nature of HTTP message framing and the ordered association of | |
1756 | requests to responses on persistent connections [Klein]. This | |
1757 | technique can be particularly damaging when the requests pass through | |
1758 | a shared cache. | |
1759 | ||
1760 | Response splitting exploits a vulnerability in servers (usually | |
1761 | within an application server) where an attacker can send encoded data | |
1762 | within some parameter of the request that is later decoded and echoed | |
1763 | within any of the response header fields of the response. If the | |
1764 | decoded data is crafted to look like the response has ended and a | |
1765 | subsequent response has begun, the response has been split, and the | |
1766 | content within the apparent second response is controlled by the | |
1767 | attacker. The attacker can then make any other request on the same | |
1768 | persistent connection and trick the recipients (including | |
1769 | intermediaries) into believing that the second half of the split is | |
1770 | an authoritative answer to the second request. | |
1771 | ||
1772 | For example, a parameter within the request-target might be read by | |
1773 | an application server and reused within a redirect, resulting in the | |
1774 | same parameter being echoed in the Location header field of the | |
1775 | response. If the parameter is decoded by the application and not | |
1776 | properly encoded when placed in the response field, the attacker can | |
1777 | send encoded CRLF octets and other content that will make the | |
1778 | application's single response look like two or more responses. | |
1779 | ||
1780 | A common defense against response splitting is to filter requests for | |
1781 | data that looks like encoded CR and LF (e.g., "%0D" and "%0A"). | |
1782 | However, that assumes the application server is only performing URI | |
1783 | decoding rather than more obscure data transformations like charset | |
1784 | transcoding, XML entity translation, base64 decoding, sprintf | |
1785 | reformatting, etc. A more effective mitigation is to prevent | |
1786 | anything other than the server's core protocol libraries from sending | |
1787 | a CR or LF within the header section, which means restricting the | |
1788 | output of header fields to APIs that filter for bad octets and not | |
1789 | allowing application servers to write directly to the protocol | |
1790 | stream. | |
1791 | ||
1792 | 11.2. Request Smuggling | |
1793 | ||
1794 | Request smuggling ([Linhart]) is a technique that exploits | |
1795 | differences in protocol parsing among various recipients to hide | |
1796 | additional requests (which might otherwise be blocked or disabled by | |
1797 | policy) within an apparently harmless request. Like response | |
1798 | splitting, request smuggling can lead to a variety of attacks on HTTP | |
1799 | usage. | |
1800 | ||
1801 | This specification has introduced new requirements on request | |
1802 | parsing, particularly with regard to message framing in Section 6.3, | |
1803 | to reduce the effectiveness of request smuggling. | |
1804 | ||
1805 | 11.3. Message Integrity | |
1806 | ||
1807 | HTTP does not define a specific mechanism for ensuring message | |
1808 | integrity, instead relying on the error-detection ability of | |
1809 | underlying transport protocols and the use of length or chunk- | |
1810 | delimited framing to detect completeness. Historically, the lack of | |
1811 | a single integrity mechanism has been justified by the informal | |
1812 | nature of most HTTP communication. However, the prevalence of HTTP | |
1813 | as an information access mechanism has resulted in its increasing use | |
1814 | within environments where verification of message integrity is | |
1815 | crucial. | |
1816 | ||
1817 | The mechanisms provided with the "https" scheme, such as | |
1818 | authenticated encryption, provide protection against modification of | |
1819 | messages. Care is needed, however, to ensure that connection closure | |
1820 | cannot be used to truncate messages (see Section 9.8). User agents | |
1821 | might refuse to accept incomplete messages or treat them specially. | |
1822 | For example, a browser being used to view medical history or drug | |
1823 | interaction information needs to indicate to the user when such | |
1824 | information is detected by the protocol to be incomplete, expired, or | |
1825 | corrupted during transfer. Such mechanisms might be selectively | |
1826 | enabled via user agent extensions or the presence of message | |
1827 | integrity metadata in a response. | |
1828 | ||
1829 | The "http" scheme provides no protection against accidental or | |
1830 | malicious modification of messages. | |
1831 | ||
1832 | Extensions to the protocol might be used to mitigate the risk of | |
1833 | unwanted modification of messages by intermediaries, even when the | |
1834 | "https" scheme is used. Integrity might be assured by using message | |
1835 | authentication codes or digital signatures that are selectively added | |
1836 | to messages via extensible metadata fields. | |
1837 | ||
1838 | 11.4. Message Confidentiality | |
1839 | ||
1840 | HTTP relies on underlying transport protocols to provide message | |
1841 | confidentiality when that is desired. HTTP has been specifically | |
1842 | designed to be independent of the transport protocol, such that it | |
1843 | can be used over many forms of encrypted connection, with the | |
1844 | selection of such transports being identified by the choice of URI | |
1845 | scheme or within user agent configuration. | |
1846 | ||
1847 | The "https" scheme can be used to identify resources that require a | |
1848 | confidential connection, as described in Section 4.2.2 of [HTTP]. | |
1849 | ||
1850 | 12. IANA Considerations | |
1851 | ||
1852 | The change controller for the following registrations is: "IETF | |
1853 | (iesg@ietf.org) - Internet Engineering Task Force". | |
1854 | ||
1855 | 12.1. Field Name Registration | |
1856 | ||
1857 | IANA has added the following field names to the "Hypertext Transfer | |
1858 | Protocol (HTTP) Field Name Registry" at | |
1859 | <https://www.iana.org/assignments/http-fields>, as described in | |
1860 | Section 18.4 of [HTTP]. | |
1861 | ||
1862 | +===================+===========+=========+============+ | |
1863 | | Field Name | Status | Section | Comments | | |
1864 | +===================+===========+=========+============+ | |
1865 | | Close | permanent | 9.6 | (reserved) | | |
1866 | +-------------------+-----------+---------+------------+ | |
1867 | | MIME-Version | permanent | B.1 | | | |
1868 | +-------------------+-----------+---------+------------+ | |
1869 | | Transfer-Encoding | permanent | 6.1 | | | |
1870 | +-------------------+-----------+---------+------------+ | |
1871 | ||
1872 | Table 1 | |
1873 | ||
1874 | 12.2. Media Type Registration | |
1875 | ||
1876 | IANA has updated the "Media Types" registry at | |
1877 | <https://www.iana.org/assignments/media-types> with the registration | |
1878 | information in Sections 10.1 and 10.2 for the media types "message/ | |
1879 | http" and "application/http", respectively. | |
1880 | ||
1881 | 12.3. Transfer Coding Registration | |
1882 | ||
1883 | IANA has updated the "HTTP Transfer Coding Registry" at | |
1884 | <https://www.iana.org/assignments/http-parameters/> with the | |
1885 | registration procedure of Section 7.3 and the content coding names | |
1886 | summarized in the table below. | |
1887 | ||
1888 | +============+===========================================+=========+ | |
1889 | | Name | Description | Section | | |
1890 | +============+===========================================+=========+ | |
1891 | | chunked | Transfer in a series of chunks | 7.1 | | |
1892 | +------------+-------------------------------------------+---------+ | |
1893 | | compress | UNIX "compress" data format [Welch] | 7.2 | | |
1894 | +------------+-------------------------------------------+---------+ | |
1895 | | deflate | "deflate" compressed data ([RFC1951]) | 7.2 | | |
1896 | | | inside the "zlib" data format ([RFC1950]) | | | |
1897 | +------------+-------------------------------------------+---------+ | |
1898 | | gzip | GZIP file format [RFC1952] | 7.2 | | |
1899 | +------------+-------------------------------------------+---------+ | |
1900 | | trailers | (reserved) | 12.3 | | |
1901 | +------------+-------------------------------------------+---------+ | |
1902 | | x-compress | Deprecated (alias for compress) | 7.2 | | |
1903 | +------------+-------------------------------------------+---------+ | |
1904 | | x-gzip | Deprecated (alias for gzip) | 7.2 | | |
1905 | +------------+-------------------------------------------+---------+ | |
1906 | ||
1907 | Table 2 | |
1908 | ||
1909 | | *Note:* the coding name "trailers" is reserved because its use | |
1910 | | would conflict with the keyword "trailers" in the TE header | |
1911 | | field (Section 10.1.4 of [HTTP]). | |
1912 | ||
1913 | 12.4. ALPN Protocol ID Registration | |
1914 | ||
1915 | IANA has updated the "TLS Application-Layer Protocol Negotiation | |
1916 | (ALPN) Protocol IDs" registry at <https://www.iana.org/assignments/ | |
1917 | tls-extensiontype-values/> with the registration below: | |
1918 | ||
1919 | +==========+=============================+===========+ | |
1920 | | Protocol | Identification Sequence | Reference | | |
1921 | +==========+=============================+===========+ | |
1922 | | HTTP/1.1 | 0x68 0x74 0x74 0x70 0x2f | RFC 9112 | | |
1923 | | | 0x31 0x2e 0x31 ("http/1.1") | | | |
1924 | +----------+-----------------------------+-----------+ | |
1925 | ||
1926 | Table 3 | |
1927 | ||
1928 | 13. References | |
1929 | ||
1930 | 13.1. Normative References | |
1931 | ||
1932 | [CACHING] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | |
1933 | Ed., "HTTP Caching", STD 98, RFC 9111, | |
1934 | DOI 10.17487/RFC9111, June 2022, | |
1935 | <https://www.rfc-editor.org/info/rfc9111>. | |
1936 | ||
1937 | [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | |
1938 | Ed., "HTTP Semantics", STD 97, RFC 9110, | |
1939 | DOI 10.17487/RFC9110, June 2022, | |
1940 | <https://www.rfc-editor.org/info/rfc9110>. | |
1941 | ||
1942 | [RFC1950] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format | |
1943 | Specification version 3.3", RFC 1950, | |
1944 | DOI 10.17487/RFC1950, May 1996, | |
1945 | <https://www.rfc-editor.org/info/rfc1950>. | |
1946 | ||
1947 | [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification | |
1948 | version 1.3", RFC 1951, DOI 10.17487/RFC1951, May 1996, | |
1949 | <https://www.rfc-editor.org/info/rfc1951>. | |
1950 | ||
1951 | [RFC1952] Deutsch, P., "GZIP file format specification version 4.3", | |
1952 | RFC 1952, DOI 10.17487/RFC1952, May 1996, | |
1953 | <https://www.rfc-editor.org/info/rfc1952>. | |
1954 | ||
1955 | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | |
1956 | Requirement Levels", BCP 14, RFC 2119, | |
1957 | DOI 10.17487/RFC2119, March 1997, | |
1958 | <https://www.rfc-editor.org/info/rfc2119>. | |
1959 | ||
1960 | [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax | |
1961 | Specifications: ABNF", STD 68, RFC 5234, | |
1962 | DOI 10.17487/RFC5234, January 2008, | |
1963 | <https://www.rfc-editor.org/info/rfc5234>. | |
1964 | ||
1965 | [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", | |
1966 | RFC 7405, DOI 10.17487/RFC7405, December 2014, | |
1967 | <https://www.rfc-editor.org/info/rfc7405>. | |
1968 | ||
1969 | [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | |
1970 | 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, | |
1971 | May 2017, <https://www.rfc-editor.org/info/rfc8174>. | |
1972 | ||
1973 | [TLS13] Rescorla, E., "The Transport Layer Security (TLS) Protocol | |
1974 | Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, | |
1975 | <https://www.rfc-editor.org/info/rfc8446>. | |
1976 | ||
1977 | [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform | |
1978 | Resource Identifier (URI): Generic Syntax", STD 66, | |
1979 | RFC 3986, DOI 10.17487/RFC3986, January 2005, | |
1980 | <https://www.rfc-editor.org/info/rfc3986>. | |
1981 | ||
1982 | [USASCII] American National Standards Institute, "Coded Character | |
1983 | Set -- 7-bit American Standard Code for Information | |
1984 | Interchange", ANSI X3.4, 1986. | |
1985 | ||
1986 | [Welch] Welch, T., "A Technique for High-Performance Data | |
1987 | Compression", IEEE Computer 17(6), | |
1988 | DOI 10.1109/MC.1984.1659158, June 1984, | |
1989 | <https://ieeexplore.ieee.org/document/1659158/>. | |
1990 | ||
1991 | 13.2. Informative References | |
1992 | ||
1993 | [HTTP/1.0] Berners-Lee, T., Fielding, R., and H. Frystyk, "Hypertext | |
1994 | Transfer Protocol -- HTTP/1.0", RFC 1945, | |
1995 | DOI 10.17487/RFC1945, May 1996, | |
1996 | <https://www.rfc-editor.org/info/rfc1945>. | |
1997 | ||
1998 | [Klein] Klein, A., "Divide and Conquer - HTTP Response Splitting, | |
1999 | Web Cache Poisoning Attacks, and Related Topics", March | |
2000 | 2004, <https://packetstormsecurity.com/papers/general/ | |
2001 | whitepaper_httpresponse.pdf>. | |
2002 | ||
2003 | [Linhart] Linhart, C., Klein, A., Heled, R., and S. Orrin, "HTTP | |
2004 | Request Smuggling", June 2005, | |
2005 | <https://www.cgisecurity.com/lib/HTTP-Request- | |
2006 | Smuggling.pdf>. | |
2007 | ||
2008 | [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail | |
2009 | Extensions (MIME) Part One: Format of Internet Message | |
2010 | Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, | |
2011 | <https://www.rfc-editor.org/info/rfc2045>. | |
2012 | ||
2013 | [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail | |
2014 | Extensions (MIME) Part Two: Media Types", RFC 2046, | |
2015 | DOI 10.17487/RFC2046, November 1996, | |
2016 | <https://www.rfc-editor.org/info/rfc2046>. | |
2017 | ||
2018 | [RFC2049] Freed, N. and N. Borenstein, "Multipurpose Internet Mail | |
2019 | Extensions (MIME) Part Five: Conformance Criteria and | |
2020 | Examples", RFC 2049, DOI 10.17487/RFC2049, November 1996, | |
2021 | <https://www.rfc-editor.org/info/rfc2049>. | |
2022 | ||
2023 | [RFC2068] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., and T. | |
2024 | Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", | |
2025 | RFC 2068, DOI 10.17487/RFC2068, January 1997, | |
2026 | <https://www.rfc-editor.org/info/rfc2068>. | |
2027 | ||
2028 | [RFC2557] Palme, J., Hopmann, A., and N. Shelness, "MIME | |
2029 | Encapsulation of Aggregate Documents, such as HTML | |
2030 | (MHTML)", RFC 2557, DOI 10.17487/RFC2557, March 1999, | |
2031 | <https://www.rfc-editor.org/info/rfc2557>. | |
2032 | ||
2033 | [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, | |
2034 | DOI 10.17487/RFC5322, October 2008, | |
2035 | <https://www.rfc-editor.org/info/rfc5322>. | |
2036 | ||
2037 | [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer | |
2038 | Protocol (HTTP/1.1): Message Syntax and Routing", | |
2039 | RFC 7230, DOI 10.17487/RFC7230, June 2014, | |
2040 | <https://www.rfc-editor.org/info/rfc7230>. | |
2041 | ||
2042 | [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for | |
2043 | Writing an IANA Considerations Section in RFCs", BCP 26, | |
2044 | RFC 8126, DOI 10.17487/RFC8126, June 2017, | |
2045 | <https://www.rfc-editor.org/info/rfc8126>. | |
2046 | ||
2047 | Appendix A. Collected ABNF | |
2048 | ||
2049 | In the collected ABNF below, list rules are expanded per | |
2050 | Section 5.6.1 of [HTTP]. | |
2051 | ||
2052 | BWS = <BWS, see [HTTP], Section 5.6.3> | |
2053 | ||
2054 | HTTP-message = start-line CRLF *( field-line CRLF ) CRLF [ | |
2055 | message-body ] | |
2056 | HTTP-name = %x48.54.54.50 ; HTTP | |
2057 | HTTP-version = HTTP-name "/" DIGIT "." DIGIT | |
2058 | ||
2059 | OWS = <OWS, see [HTTP], Section 5.6.3> | |
2060 | ||
2061 | RWS = <RWS, see [HTTP], Section 5.6.3> | |
2062 | ||
2063 | Transfer-Encoding = [ transfer-coding *( OWS "," OWS transfer-coding | |
2064 | ) ] | |
2065 | ||
2066 | absolute-URI = <absolute-URI, see [URI], Section 4.3> | |
2067 | absolute-form = absolute-URI | |
2068 | absolute-path = <absolute-path, see [HTTP], Section 4.1> | |
2069 | asterisk-form = "*" | |
2070 | authority = <authority, see [URI], Section 3.2> | |
2071 | authority-form = uri-host ":" port | |
2072 | ||
2073 | chunk = chunk-size [ chunk-ext ] CRLF chunk-data CRLF | |
2074 | chunk-data = 1*OCTET | |
2075 | chunk-ext = *( BWS ";" BWS chunk-ext-name [ BWS "=" BWS chunk-ext-val | |
2076 | ] ) | |
2077 | chunk-ext-name = token | |
2078 | chunk-ext-val = token / quoted-string | |
2079 | chunk-size = 1*HEXDIG | |
2080 | chunked-body = *chunk last-chunk trailer-section CRLF | |
2081 | ||
2082 | field-line = field-name ":" OWS field-value OWS | |
2083 | field-name = <field-name, see [HTTP], Section 5.1> | |
2084 | field-value = <field-value, see [HTTP], Section 5.5> | |
2085 | ||
2086 | last-chunk = 1*"0" [ chunk-ext ] CRLF | |
2087 | ||
2088 | message-body = *OCTET | |
2089 | method = token | |
2090 | ||
2091 | obs-fold = OWS CRLF RWS | |
2092 | obs-text = <obs-text, see [HTTP], Section 5.6.4> | |
2093 | origin-form = absolute-path [ "?" query ] | |
2094 | ||
2095 | port = <port, see [URI], Section 3.2.3> | |
2096 | ||
2097 | query = <query, see [URI], Section 3.4> | |
2098 | quoted-string = <quoted-string, see [HTTP], Section 5.6.4> | |
2099 | ||
2100 | reason-phrase = 1*( HTAB / SP / VCHAR / obs-text ) | |
2101 | request-line = method SP request-target SP HTTP-version | |
2102 | request-target = origin-form / absolute-form / authority-form / | |
2103 | asterisk-form | |
2104 | ||
2105 | start-line = request-line / status-line | |
2106 | status-code = 3DIGIT | |
2107 | status-line = HTTP-version SP status-code SP [ reason-phrase ] | |
2108 | ||
2109 | token = <token, see [HTTP], Section 5.6.2> | |
2110 | trailer-section = *( field-line CRLF ) | |
2111 | transfer-coding = <transfer-coding, see [HTTP], Section 10.1.4> | |
2112 | ||
2113 | uri-host = <host, see [URI], Section 3.2.2> | |
2114 | ||
2115 | Appendix B. Differences between HTTP and MIME | |
2116 | ||
2117 | HTTP/1.1 uses many of the constructs defined for the Internet Message | |
2118 | Format [RFC5322] and Multipurpose Internet Mail Extensions (MIME) | |
2119 | [RFC2045] to allow a message body to be transmitted in an open | |
2120 | variety of representations and with extensible fields. However, some | |
2121 | of these constructs have been reinterpreted to better fit the needs | |
2122 | of interactive communication, leading to some differences in how MIME | |
2123 | constructs are used within HTTP. These differences were carefully | |
2124 | chosen to optimize performance over binary connections, allow greater | |
2125 | freedom in the use of new media types, ease date comparisons, and | |
2126 | accommodate common implementations. | |
2127 | ||
2128 | This appendix describes specific areas where HTTP differs from MIME. | |
2129 | Proxies and gateways to and from strict MIME environments need to be | |
2130 | aware of these differences and provide the appropriate conversions | |
2131 | where necessary. | |
2132 | ||
2133 | B.1. MIME-Version | |
2134 | ||
2135 | HTTP is not a MIME-compliant protocol. However, messages can include | |
2136 | a single MIME-Version header field to indicate what version of the | |
2137 | MIME protocol was used to construct the message. Use of the MIME- | |
2138 | Version header field indicates that the message is in full | |
2139 | conformance with the MIME protocol (as defined in [RFC2045]). | |
2140 | Senders are responsible for ensuring full conformance (where | |
2141 | possible) when exporting HTTP messages to strict MIME environments. | |
2142 | ||
2143 | B.2. Conversion to Canonical Form | |
2144 | ||
2145 | MIME requires that an Internet mail body part be converted to | |
2146 | canonical form prior to being transferred, as described in Section 4 | |
2147 | of [RFC2049], and that content with a type of "text" represents line | |
2148 | breaks as CRLF, forbidding the use of CR or LF outside of line break | |
2149 | sequences [RFC2046]. In contrast, HTTP does not care whether CRLF, | |
2150 | bare CR, or bare LF are used to indicate a line break within content. | |
2151 | ||
2152 | A proxy or gateway from HTTP to a strict MIME environment ought to | |
2153 | translate all line breaks within text media types to the RFC 2049 | |
2154 | canonical form of CRLF. Note, however, this might be complicated by | |
2155 | the presence of a Content-Encoding and by the fact that HTTP allows | |
2156 | the use of some charsets that do not use octets 13 and 10 to | |
2157 | represent CR and LF, respectively. | |
2158 | ||
2159 | Conversion will break any cryptographic checksums applied to the | |
2160 | original content unless the original content is already in canonical | |
2161 | form. Therefore, the canonical form is recommended for any content | |
2162 | that uses such checksums in HTTP. | |
2163 | ||
2164 | B.3. Conversion of Date Formats | |
2165 | ||
2166 | HTTP/1.1 uses a restricted set of date formats (Section 5.6.7 of | |
2167 | [HTTP]) to simplify the process of date comparison. Proxies and | |
2168 | gateways from other protocols ought to ensure that any Date header | |
2169 | field present in a message conforms to one of the HTTP/1.1 formats | |
2170 | and rewrite the date if necessary. | |
2171 | ||
2172 | B.4. Conversion of Content-Encoding | |
2173 | ||
2174 | MIME does not include any concept equivalent to HTTP's Content- | |
2175 | Encoding header field. Since this acts as a modifier on the media | |
2176 | type, proxies and gateways from HTTP to MIME-compliant protocols | |
2177 | ought to either change the value of the Content-Type header field or | |
2178 | decode the representation before forwarding the message. (Some | |
2179 | experimental applications of Content-Type for Internet mail have used | |
2180 | a media-type parameter of ";conversions=<content-coding>" to perform | |
2181 | a function equivalent to Content-Encoding. However, this parameter | |
2182 | is not part of the MIME standards.) | |
2183 | ||
2184 | B.5. Conversion of Content-Transfer-Encoding | |
2185 | ||
2186 | HTTP does not use the Content-Transfer-Encoding field of MIME. | |
2187 | Proxies and gateways from MIME-compliant protocols to HTTP need to | |
2188 | remove any Content-Transfer-Encoding prior to delivering the response | |
2189 | message to an HTTP client. | |
2190 | ||
2191 | Proxies and gateways from HTTP to MIME-compliant protocols are | |
2192 | responsible for ensuring that the message is in the correct format | |
2193 | and encoding for safe transport on that protocol, where "safe | |
2194 | transport" is defined by the limitations of the protocol being used. | |
2195 | Such a proxy or gateway ought to transform and label the data with an | |
2196 | appropriate Content-Transfer-Encoding if doing so will improve the | |
2197 | likelihood of safe transport over the destination protocol. | |
2198 | ||
2199 | B.6. MHTML and Line Length Limitations | |
2200 | ||
2201 | HTTP implementations that share code with MHTML [RFC2557] | |
2202 | implementations need to be aware of MIME line length limitations. | |
2203 | Since HTTP does not have this limitation, HTTP does not fold long | |
2204 | lines. MHTML messages being transported by HTTP follow all | |
2205 | conventions of MHTML, including line length limitations and folding, | |
2206 | canonicalization, etc., since HTTP transfers message-bodies without | |
2207 | modification and, aside from the "multipart/byteranges" type | |
2208 | (Section 14.6 of [HTTP]), does not interpret the content or any MIME | |
2209 | header lines that might be contained therein. | |
2210 | ||
2211 | Appendix C. Changes from Previous RFCs | |
2212 | ||
2213 | C.1. Changes from HTTP/0.9 | |
2214 | ||
2215 | Since HTTP/0.9 did not support header fields in a request, there is | |
2216 | no mechanism for it to support name-based virtual hosts (selection of | |
2217 | resource by inspection of the Host header field). Any server that | |
2218 | implements name-based virtual hosts ought to disable support for | |
2219 | HTTP/0.9. Most requests that appear to be HTTP/0.9 are, in fact, | |
2220 | badly constructed HTTP/1.x requests caused by a client failing to | |
2221 | properly encode the request-target. | |
2222 | ||
2223 | C.2. Changes from HTTP/1.0 | |
2224 | ||
2225 | C.2.1. Multihomed Web Servers | |
2226 | ||
2227 | The requirements that clients and servers support the Host header | |
2228 | field (Section 7.2 of [HTTP]), report an error if it is missing from | |
2229 | an HTTP/1.1 request, and accept absolute URIs (Section 3.2) are among | |
2230 | the most important changes defined by HTTP/1.1. | |
2231 | ||
2232 | Older HTTP/1.0 clients assumed a one-to-one relationship of IP | |
2233 | addresses and servers; there was no established mechanism for | |
2234 | distinguishing the intended server of a request other than the IP | |
2235 | address to which that request was directed. The Host header field | |
2236 | was introduced during the development of HTTP/1.1 and, though it was | |
2237 | quickly implemented by most HTTP/1.0 browsers, additional | |
2238 | requirements were placed on all HTTP/1.1 requests in order to ensure | |
2239 | complete adoption. At the time of this writing, most HTTP-based | |
2240 | services are dependent upon the Host header field for targeting | |
2241 | requests. | |
2242 | ||
2243 | C.2.2. Keep-Alive Connections | |
2244 | ||
2245 | In HTTP/1.0, each connection is established by the client prior to | |
2246 | the request and closed by the server after sending the response. | |
2247 | However, some implementations implement the explicitly negotiated | |
2248 | ("Keep-Alive") version of persistent connections described in | |
2249 | Section 19.7.1 of [RFC2068]. | |
2250 | ||
2251 | Some clients and servers might wish to be compatible with these | |
2252 | previous approaches to persistent connections, by explicitly | |
2253 | negotiating for them with a "Connection: keep-alive" request header | |
2254 | field. However, some experimental implementations of HTTP/1.0 | |
2255 | persistent connections are faulty; for example, if an HTTP/1.0 proxy | |
2256 | server doesn't understand Connection, it will erroneously forward | |
2257 | that header field to the next inbound server, which would result in a | |
2258 | hung connection. | |
2259 | ||
2260 | One attempted solution was the introduction of a Proxy-Connection | |
2261 | header field, targeted specifically at proxies. In practice, this | |
2262 | was also unworkable, because proxies are often deployed in multiple | |
2263 | layers, bringing about the same problem discussed above. | |
2264 | ||
2265 | As a result, clients are encouraged not to send the Proxy-Connection | |
2266 | header field in any requests. | |
2267 | ||
2268 | Clients are also encouraged to consider the use of "Connection: keep- | |
2269 | alive" in requests carefully; while they can enable persistent | |
2270 | connections with HTTP/1.0 servers, clients using them will need to | |
2271 | monitor the connection for "hung" requests (which indicate that the | |
2272 | client ought to stop sending the header field), and this mechanism | |
2273 | ought not be used by clients at all when a proxy is being used. | |
2274 | ||
2275 | C.2.3. Introduction of Transfer-Encoding | |
2276 | ||
2277 | HTTP/1.1 introduces the Transfer-Encoding header field (Section 6.1). | |
2278 | Transfer codings need to be decoded prior to forwarding an HTTP | |
2279 | message over a MIME-compliant protocol. | |
2280 | ||
2281 | C.3. Changes from RFC 7230 | |
2282 | ||
2283 | Most of the sections introducing HTTP's design goals, history, | |
2284 | architecture, conformance criteria, protocol versioning, URIs, | |
2285 | message routing, and header fields have been moved to [HTTP]. This | |
2286 | document has been reduced to just the messaging syntax and connection | |
2287 | management requirements specific to HTTP/1.1. | |
2288 | ||
2289 | Bare CRs have been prohibited outside of content. (Section 2.2) | |
2290 | ||
2291 | The ABNF definition of authority-form has changed from the more | |
2292 | general authority component of a URI (in which port is optional) to | |
2293 | the specific host:port format that is required by CONNECT. | |
2294 | (Section 3.2.3) | |
2295 | ||
2296 | Recipients are required to avoid smuggling/splitting attacks when | |
2297 | processing an ambiguous message framing. (Section 6.1) | |
2298 | ||
2299 | In the ABNF for chunked extensions, (bad) whitespace around ";" and | |
2300 | "=" has been reintroduced. Whitespace was removed in [RFC7230], but | |
2301 | that change was found to break existing implementations. | |
2302 | (Section 7.1.1) | |
2303 | ||
2304 | Trailer field semantics now transcend the specifics of chunked | |
2305 | transfer coding. The decoding algorithm for chunked (Section 7.1.3) | |
2306 | has been updated to encourage storage/forwarding of trailer fields | |
2307 | separately from the header section, to only allow merging into the | |
2308 | header section if the recipient knows the corresponding field | |
2309 | definition permits and defines how to merge, and otherwise to discard | |
2310 | the trailer fields instead of merging. The trailer part is now | |
2311 | called the trailer section to be more consistent with the header | |
2312 | section and more distinct from a body part. (Section 7.1.2) | |
2313 | ||
2314 | Transfer coding parameters called "q" are disallowed in order to | |
2315 | avoid conflicts with the use of ranks in the TE header field. | |
2316 | (Section 7.3) | |
2317 | ||
2318 | Acknowledgements | |
2319 | ||
2320 | See Appendix "Acknowledgements" of [HTTP], which applies to this | |
2321 | document as well. | |
2322 | ||
2323 | Index | |
2324 | ||
2325 | A C D F G H M O R T X | |
2326 | ||
2327 | A | |
2328 | ||
2329 | absolute-form (of request-target) Section 3.2.2 | |
2330 | application/http Media Type *_Section 10.2_* | |
2331 | asterisk-form (of request-target) Section 3.2.4 | |
2332 | authority-form (of request-target) Section 3.2.3 | |
2333 | ||
2334 | C | |
2335 | ||
2336 | chunked (Coding Format) Section 6.1; Section 6.3 | |
2337 | chunked (transfer coding) *_Section 7.1_* | |
2338 | close Section 9.3; *_Section 9.6_* | |
2339 | compress (transfer coding) *_Section 7.2_* | |
2340 | Connection header field Section 9.6 | |
2341 | Content-Length header field Section 6.2 | |
2342 | Content-Transfer-Encoding header field Appendix B.5 | |
2343 | ||
2344 | D | |
2345 | ||
2346 | deflate (transfer coding) *_Section 7.2_* | |
2347 | ||
2348 | F | |
2349 | ||
2350 | Fields | |
2351 | Close *_Section 9.6, Paragraph 4_* | |
2352 | MIME-Version *_Appendix B.1_* | |
2353 | Transfer-Encoding *_Section 6.1_* | |
2354 | ||
2355 | G | |
2356 | ||
2357 | Grammar | |
2358 | ALPHA *_Section 1.2_* | |
2359 | CR *_Section 1.2_* | |
2360 | CRLF *_Section 1.2_* | |
2361 | CTL *_Section 1.2_* | |
2362 | DIGIT *_Section 1.2_* | |
2363 | DQUOTE *_Section 1.2_* | |
2364 | HEXDIG *_Section 1.2_* | |
2365 | HTAB *_Section 1.2_* | |
2366 | HTTP-message *_Section 2.1_* | |
2367 | HTTP-name *_Section 2.3_* | |
2368 | HTTP-version *_Section 2.3_* | |
2369 | LF *_Section 1.2_* | |
2370 | OCTET *_Section 1.2_* | |
2371 | SP *_Section 1.2_* | |
2372 | Transfer-Encoding *_Section 6.1_* | |
2373 | VCHAR *_Section 1.2_* | |
2374 | absolute-form Section 3.2; *_Section 3.2.2_* | |
2375 | asterisk-form Section 3.2; *_Section 3.2.4_* | |
2376 | authority-form Section 3.2; *_Section 3.2.3_* | |
2377 | chunk *_Section 7.1_* | |
2378 | chunk-data *_Section 7.1_* | |
2379 | chunk-ext Section 7.1; *_Section 7.1.1_* | |
2380 | chunk-ext-name *_Section 7.1.1_* | |
2381 | chunk-ext-val *_Section 7.1.1_* | |
2382 | chunk-size *_Section 7.1_* | |
2383 | chunked-body *_Section 7.1_* | |
2384 | field-line *_Section 5_*; Section 7.1.2 | |
2385 | field-name Section 5 | |
2386 | field-value Section 5 | |
2387 | last-chunk *_Section 7.1_* | |
2388 | message-body *_Section 6_* | |
2389 | method *_Section 3.1_* | |
2390 | obs-fold *_Section 5.2_* | |
2391 | origin-form Section 3.2; *_Section 3.2.1_* | |
2392 | reason-phrase *_Section 4_* | |
2393 | request-line *_Section 3_* | |
2394 | request-target *_Section 3.2_* | |
2395 | start-line *_Section 2.1_* | |
2396 | status-code *_Section 4_* | |
2397 | status-line *_Section 4_* | |
2398 | trailer-section Section 7.1; *_Section 7.1.2_* | |
2399 | gzip (transfer coding) *_Section 7.2_* | |
2400 | ||
2401 | H | |
2402 | ||
2403 | Header Fields | |
2404 | MIME-Version *_Appendix B.1_* | |
2405 | Transfer-Encoding *_Section 6.1_* | |
2406 | header line Section 2.1 | |
2407 | header section Section 2.1 | |
2408 | headers Section 2.1 | |
2409 | ||
2410 | M | |
2411 | ||
2412 | Media Type | |
2413 | application/http *_Section 10.2_* | |
2414 | message/http *_Section 10.1_* | |
2415 | message/http Media Type *_Section 10.1_* | |
2416 | method *_Section 3.1_* | |
2417 | MIME-Version header field *_Appendix B.1_* | |
2418 | ||
2419 | O | |
2420 | ||
2421 | origin-form (of request-target) Section 3.2.1 | |
2422 | ||
2423 | R | |
2424 | ||
2425 | request-target *_Section 3.2_* | |
2426 | ||
2427 | T | |
2428 | ||
2429 | Transfer-Encoding header field *_Section 6.1_* | |
2430 | ||
2431 | X | |
2432 | ||
2433 | x-compress (transfer coding) *_Section 7.2_* | |
2434 | x-gzip (transfer coding) *_Section 7.2_* | |
2435 | ||
2436 | Authors' Addresses | |
2437 | ||
2438 | Roy T. Fielding (editor) | |
2439 | Adobe | |
2440 | 345 Park Ave | |
2441 | San Jose, CA 95110 | |
2442 | United States of America | |
2443 | Email: fielding@gbiv.com | |
2444 | URI: https://roy.gbiv.com/ | |
2445 | ||
2446 | ||
2447 | Mark Nottingham (editor) | |
2448 | Fastly | |
2449 | Prahran | |
2450 | Australia | |
2451 | Email: mnot@mnot.net | |
2452 | URI: https://www.mnot.net/ | |
2453 | ||
2454 | ||
2455 | Julian Reschke (editor) | |
2456 | greenbytes GmbH | |
2457 | Hafenweg 16 | |
2458 | 48155 Münster | |
2459 | Germany | |
2460 | Email: julian.reschke@greenbytes.de | |
2461 | URI: https://greenbytes.de/tech/webdav/ |