frankenRFC723x_sem.txt | draft-ietf-httpbis-semantics-14.txt | |||
---|---|---|---|---|
Internet Engineering Task Force (IETF) R. Fielding, Ed. | HTTP Working Group R. Fielding, Ed. | |||
Request for Comments: 7231 Adobe | Internet-Draft Adobe | |||
Obsoletes: 2616 J. Reschke, Ed. | Obsoletes: 2818, 7230, 7231, 7232, 7233, 7235, M. Nottingham, Ed. | |||
Updates: 2817 greenbytes | 7538, 7615, 7694 (if approved) Fastly | |||
Category: Standards Track June 2014 | Updates: 3864 (if approved) J. Reschke, Ed. | |||
ISSN: 2070-1721 | Intended status: Standards Track greenbytes | |||
Expires: July 17, 2021 January 13, 2021 | ||||
Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content | HTTP Semantics | |||
draft-ietf-httpbis-semantics-14 | ||||
Abstract | Abstract | |||
The Hypertext Transfer Protocol (HTTP) is a stateless application- | The Hypertext Transfer Protocol (HTTP) is a stateless application- | |||
level protocol for distributed, collaborative, hypertext information | level protocol for distributed, collaborative, hypertext information | |||
systems. This document defines the semantics of HTTP/1.1 messages, | systems. This document describes the overall architecture of HTTP, | |||
as expressed by request methods, request header fields, response | establishes common terminology, and defines aspects of the protocol | |||
status codes, and response header fields, along with the payload of | that are shared by all versions. In this definition are core | |||
messages (metadata and body content) and mechanisms for content | protocol elements, extensibility mechanisms, and the "http" and | |||
negotiation. | "https" Uniform Resource Identifier (URI) schemes. | |||
This document obsoletes RFC 2818, RFC 7231, RFC 7232, RFC 7233, RFC | ||||
7235, RFC 7538, RFC 7615, RFC 7694, and portions of RFC 7230. | ||||
Editorial Note | Editorial Note | |||
This note is not in the original RFC. | This note is to be removed before publishing as an RFC. | |||
The purpose of this document is to produce diffs that show just the | Discussion of this draft takes place on the HTTP working group | |||
changes from text in the original RFCs that were input for http-core. | mailing list (ietf-http-wg@w3.org), which is archived at | |||
Hence, the frankenRFC documents show all of the original text (including | <https://lists.w3.org/Archives/Public/ietf-http-wg/>. | |||
stuff that has been deleted) plus some new text [in brackets] or new | ||||
headings to anchor the context, rearranged to minimize the resulting | ||||
diffs when compared to the most recently published version of | ||||
draft-ietf-httpbis-semantics. | ||||
After this document is updated to match any reorg changes in the latest | Working Group information can be found at <https://httpwg.org/>; | |||
version, the franken diffs are saved and published in this directory as | source code and issues list for this draft can be found at | |||
diff_semantics_frfc_to_NN.html (where NN is the I-D draft revision) | <https://github.com/httpwg/http-core>. | |||
The changes in this draft are summarized in Appendix C.15. | ||||
Status of This Memo | Status of This Memo | |||
This is an Internet Standards Track document. | This Internet-Draft is submitted in full conformance with the | |||
provisions of BCP 78 and BCP 79. | ||||
This document is a product of the Internet Engineering Task Force | Internet-Drafts are working documents of the Internet Engineering | |||
(IETF). It represents the consensus of the IETF community. It has | Task Force (IETF). Note that other groups may also distribute | |||
received public review and has been approved for publication by the | working documents as Internet-Drafts. The list of current Internet- | |||
Internet Engineering Steering Group (IESG). Further information on | Drafts is at https://datatracker.ietf.org/drafts/current/. | |||
Internet Standards is available in Section 2 of RFC 5741. | ||||
Information about the current status of this document, any errata, | Internet-Drafts are draft documents valid for a maximum of six months | |||
and how to provide feedback on it may be obtained at | and may be updated, replaced, or obsoleted by other documents at any | |||
http://www.rfc-editor.org/info/rfc7231. | time. It is inappropriate to use Internet-Drafts as reference | |||
material or to cite them other than as "work in progress." | ||||
This Internet-Draft will expire on July 17, 2021. | ||||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2014 IETF Trust and the persons identified as the | Copyright (c) 2021 IETF Trust and the persons identified as the | |||
document authors. All rights reserved. | document authors. All rights reserved. | |||
This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
Provisions Relating to IETF Documents | Provisions Relating to IETF Documents (https://trustee.ietf.org/ | |||
(http://trustee.ietf.org/license-info) in effect on the date of | license-info) in effect on the date of publication of this document. | |||
publication of this document. Please review these documents | Please review these documents carefully, as they describe your rights | |||
carefully, as they describe your rights and restrictions with respect | and restrictions with respect to this document. Code Components | |||
to this document. Code Components extracted from this document must | extracted from this document must include Simplified BSD License text | |||
include Simplified BSD License text as described in Section 4.e of | as described in Section 4.e of the Trust Legal Provisions and are | |||
the Trust Legal Provisions and are provided without warranty as | provided without warranty as described in the Simplified BSD License. | |||
described in the Simplified BSD License. | ||||
This document may contain material from IETF Documents or IETF | This document may contain material from IETF Documents or IETF | |||
Contributions published or made publicly available before November | Contributions published or made publicly available before November | |||
10, 2008. The person(s) controlling the copyright in some of this | 10, 2008. The person(s) controlling the copyright in some of this | |||
material may not have granted the IETF Trust the right to allow | material may not have granted the IETF Trust the right to allow | |||
modifications of such material outside the IETF Standards Process. | modifications of such material outside the IETF Standards Process. | |||
Without obtaining an adequate license from the person(s) controlling | Without obtaining an adequate license from the person(s) controlling | |||
the copyright in such materials, this document may not be modified | the copyright in such materials, this document may not be modified | |||
outside the IETF Standards Process, and derivative works of it may | outside the IETF Standards Process, and derivative works of it may | |||
not be created outside the IETF Standards Process, except to format | not be created outside the IETF Standards Process, except to format | |||
it for publication as an RFC or to translate it into languages other | it for publication as an RFC or to translate it into languages other | |||
than English. | than English. | |||
Table of Contents | Table of Contents | |||
1. Introduction ....................................................6 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 9 | |||
1.1. Conformance and Error Handling .............................6 | 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 9 | |||
1.2. Syntax Notation ............................................6 | 1.2. History and Evolution . . . . . . . . . . . . . . . . . . 10 | |||
2. Resources .......................................................7 | 1.3. Core Semantics . . . . . . . . . . . . . . . . . . . . . 10 | |||
3. Representations .................................................7 | 1.4. Specifications Obsoleted by this Document . . . . . . . . 11 | |||
3.1. Representation Metadata ....................................8 | 2. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 12 | |||
3.1.1. Processing Representation Data ......................8 | 2.1. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 12 | |||
3.1.2. Encoding for Compression or Integrity ..............11 | 2.2. Requirements Notation . . . . . . . . . . . . . . . . . . 12 | |||
3.1.3. Audience Language ..................................13 | 2.3. Length Requirements . . . . . . . . . . . . . . . . . . . 13 | |||
3.1.4. Identification .....................................14 | 2.4. Error Handling . . . . . . . . . . . . . . . . . . . . . 14 | |||
3.2. Representation Data .......................................17 | 2.5. Protocol Version . . . . . . . . . . . . . . . . . . . . 14 | |||
3.3. Payload Semantics .........................................17 | 3. Terminology and Core Concepts . . . . . . . . . . . . . . . . 15 | |||
3.4. Content Negotiation .......................................18 | 3.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 15 | |||
3.4.1. Proactive Negotiation ..............................19 | 3.2. Representations . . . . . . . . . . . . . . . . . . . . . 16 | |||
3.4.2. Reactive Negotiation ...............................20 | 3.3. Connections, Clients and Servers . . . . . . . . . . . . 16 | |||
4. Request Methods ................................................21 | 3.4. Messages . . . . . . . . . . . . . . . . . . . . . . . . 17 | |||
4.1. Overview ..................................................21 | 3.5. User Agents . . . . . . . . . . . . . . . . . . . . . . . 17 | |||
4.2. Common Method Properties ..................................22 | 3.6. Origin Server . . . . . . . . . . . . . . . . . . . . . . 18 | |||
4.2.1. Safe Methods .......................................22 | 3.7. Intermediaries . . . . . . . . . . . . . . . . . . . . . 18 | |||
4.2.2. Idempotent Methods .................................23 | 3.8. Caches . . . . . . . . . . . . . . . . . . . . . . . . . 20 | |||
4.2.3. Cacheable Methods ..................................24 | 3.9. Example Message Exchange . . . . . . . . . . . . . . . . 21 | |||
4.3. Method Definitions ........................................24 | 4. Identifiers in HTTP . . . . . . . . . . . . . . . . . . . . . 22 | |||
4.3.1. GET ................................................24 | 4.1. URI References . . . . . . . . . . . . . . . . . . . . . 22 | |||
4.3.2. HEAD ...............................................25 | 4.2. HTTP-Related URI Schemes . . . . . . . . . . . . . . . . 23 | |||
4.3.3. POST ...............................................25 | 4.2.1. http URI Scheme . . . . . . . . . . . . . . . . . . . 23 | |||
4.3.4. PUT ................................................26 | 4.2.2. https URI Scheme . . . . . . . . . . . . . . . . . . 24 | |||
4.3.5. DELETE .............................................29 | 4.2.3. http(s) Normalization and Comparison . . . . . . . . 25 | |||
4.3.6. CONNECT ............................................30 | 4.2.4. Deprecation of userinfo in http(s) URIs . . . . . . . 25 | |||
4.3.7. OPTIONS ............................................31 | 4.2.5. http(s) References with Fragment Identifiers . . . . 26 | |||
4.3.8. TRACE ..............................................32 | 4.3. Authoritative Access . . . . . . . . . . . . . . . . . . 26 | |||
5. Request Header Fields ..........................................33 | 4.3.1. URI Origin . . . . . . . . . . . . . . . . . . . . . 26 | |||
5.1. Controls ..................................................33 | 4.3.2. http origins . . . . . . . . . . . . . . . . . . . . 27 | |||
5.1.1. Expect .............................................34 | 4.3.3. https origins . . . . . . . . . . . . . . . . . . . . 28 | |||
5.1.2. Max-Forwards .......................................36 | 4.3.4. https certificate verification . . . . . . . . . . . 29 | |||
5.2. Conditionals ..............................................36 | 5. Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 | |||
5.3. Content Negotiation .......................................37 | 5.1. Field Names . . . . . . . . . . . . . . . . . . . . . . . 30 | |||
5.3.1. Quality Values .....................................37 | 5.2. Field Lines and Combined Field Value . . . . . . . . . . 31 | |||
5.3.2. Accept .............................................38 | 5.3. Field Order . . . . . . . . . . . . . . . . . . . . . . . 31 | |||
5.3.3. Accept-Charset .....................................40 | 5.4. Field Limits . . . . . . . . . . . . . . . . . . . . . . 32 | |||
5.3.4. Accept-Encoding ....................................41 | 5.5. Field Values . . . . . . . . . . . . . . . . . . . . . . 33 | |||
5.3.5. Accept-Language ....................................42 | 5.6. Common Rules for Defining Field Values . . . . . . . . . 35 | |||
5.4. Authentication Credentials ................................44 | 5.6.1. Lists (#rule ABNF Extension) . . . . . . . . . . . . 35 | |||
5.5. Request Context ...........................................44 | 5.6.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 36 | |||
5.5.1. From ...............................................44 | 5.6.3. Whitespace . . . . . . . . . . . . . . . . . . . . . 36 | |||
5.5.2. Referer ............................................45 | 5.6.4. Quoted Strings . . . . . . . . . . . . . . . . . . . 37 | |||
5.5.3. User-Agent .........................................46 | 5.6.5. Comments . . . . . . . . . . . . . . . . . . . . . . 38 | |||
6. Response Status Codes ..........................................47 | 5.6.6. Parameters . . . . . . . . . . . . . . . . . . . . . 38 | |||
6.1. Overview of Status Codes ..................................48 | 5.6.7. Date/Time Formats . . . . . . . . . . . . . . . . . . 38 | |||
6.2. Informational 1xx .........................................50 | 6. Message Abstraction . . . . . . . . . . . . . . . . . . . . . 40 | |||
6.2.1. 100 Continue .......................................50 | 6.1. Framing and Completeness . . . . . . . . . . . . . . . . 41 | |||
6.2.2. 101 Switching Protocols ............................50 | 6.2. Control Data . . . . . . . . . . . . . . . . . . . . . . 42 | |||
6.3. Successful 2xx ............................................51 | 6.3. Header Fields . . . . . . . . . . . . . . . . . . . . . . 43 | |||
6.3.1. 200 OK .............................................51 | 6.4. Content . . . . . . . . . . . . . . . . . . . . . . . . . 43 | |||
6.3.2. 201 Created ........................................52 | 6.4.1. Content Semantics . . . . . . . . . . . . . . . . . . 44 | |||
6.3.3. 202 Accepted .......................................52 | 6.4.2. Identifying Content . . . . . . . . . . . . . . . . . 45 | |||
6.3.4. 203 Non-Authoritative Information ..................52 | 6.5. Trailer Fields . . . . . . . . . . . . . . . . . . . . . 46 | |||
6.3.5. 204 No Content .....................................53 | 6.5.1. Limitations on use of Trailers . . . . . . . . . . . 46 | |||
6.3.6. 205 Reset Content ..................................53 | 6.5.2. Processing Trailer Fields . . . . . . . . . . . . . . 47 | |||
6.4. Redirection 3xx ...........................................54 | 7. Routing HTTP Messages . . . . . . . . . . . . . . . . . . . . 48 | |||
6.4.1. 300 Multiple Choices ...............................55 | 7.1. Determining the Target Resource . . . . . . . . . . . . . 48 | |||
6.4.2. 301 Moved Permanently ..............................56 | 7.2. Host and :authority . . . . . . . . . . . . . . . . . . . 49 | |||
6.4.3. 302 Found ..........................................56 | 7.3. Routing Inbound Requests . . . . . . . . . . . . . . . . 50 | |||
6.4.4. 303 See Other ......................................57 | 7.3.1. To a Cache . . . . . . . . . . . . . . . . . . . . . 50 | |||
6.4.5. 305 Use Proxy ......................................58 | 7.3.2. To a Proxy . . . . . . . . . . . . . . . . . . . . . 50 | |||
6.4.6. 306 (Unused) .......................................58 | 7.3.3. To the Origin . . . . . . . . . . . . . . . . . . . . 50 | |||
6.4.7. 307 Temporary Redirect .............................58 | 7.4. Rejecting Misdirected Requests . . . . . . . . . . . . . 50 | |||
6.5. Client Error 4xx ..........................................58 | 7.5. Response Correlation . . . . . . . . . . . . . . . . . . 51 | |||
6.5.1. 400 Bad Request ....................................58 | 7.6. Message Forwarding . . . . . . . . . . . . . . . . . . . 51 | |||
6.5.2. 402 Payment Required ...............................59 | 7.6.1. Connection . . . . . . . . . . . . . . . . . . . . . 51 | |||
6.5.3. 403 Forbidden ......................................59 | 7.6.2. Max-Forwards . . . . . . . . . . . . . . . . . . . . 53 | |||
6.5.4. 404 Not Found ......................................59 | 7.6.3. Via . . . . . . . . . . . . . . . . . . . . . . . . . 54 | |||
6.5.5. 405 Method Not Allowed .............................59 | 7.7. Message Transformations . . . . . . . . . . . . . . . . . 55 | |||
6.5.6. 406 Not Acceptable .................................60 | 7.8. Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . 56 | |||
6.5.7. 408 Request Timeout ................................60 | 8. Representation Data and Metadata . . . . . . . . . . . . . . 59 | |||
6.5.8. 409 Conflict .......................................60 | 8.1. Representation Data . . . . . . . . . . . . . . . . . . . 59 | |||
6.5.9. 410 Gone ...........................................60 | 8.2. Representation Metadata . . . . . . . . . . . . . . . . . 59 | |||
6.5.10. 411 Length Required ...............................61 | 8.3. Content-Type . . . . . . . . . . . . . . . . . . . . . . 59 | |||
6.5.11. 413 Payload Too Large .............................61 | 8.3.1. Media Type . . . . . . . . . . . . . . . . . . . . . 60 | |||
6.5.12. 414 URI Too Long ..................................61 | 8.3.2. Charset . . . . . . . . . . . . . . . . . . . . . . . 61 | |||
6.5.13. 415 Unsupported Media Type ........................62 | 8.3.3. Canonicalization and Text Defaults . . . . . . . . . 61 | |||
6.5.14. 417 Expectation Failed ............................62 | 8.3.4. Multipart Types . . . . . . . . . . . . . . . . . . . 62 | |||
6.5.15. 426 Upgrade Required ..............................62 | 8.4. Content-Encoding . . . . . . . . . . . . . . . . . . . . 62 | |||
6.6. Server Error 5xx ..........................................62 | 8.4.1. Content Codings . . . . . . . . . . . . . . . . . . . 63 | |||
6.6.1. 500 Internal Server Error ..........................63 | 8.5. Content-Language . . . . . . . . . . . . . . . . . . . . 64 | |||
6.6.2. 501 Not Implemented ................................63 | 8.5.1. Language Tags . . . . . . . . . . . . . . . . . . . . 65 | |||
6.6.3. 502 Bad Gateway ....................................63 | 8.6. Content-Length . . . . . . . . . . . . . . . . . . . . . 66 | |||
6.6.4. 503 Service Unavailable ............................63 | 8.7. Content-Location . . . . . . . . . . . . . . . . . . . . 67 | |||
6.6.5. 504 Gateway Timeout ................................63 | 8.8. Validator Fields . . . . . . . . . . . . . . . . . . . . 69 | |||
6.6.6. 505 HTTP Version Not Supported .....................64 | 8.8.1. Weak versus Strong . . . . . . . . . . . . . . . . . 70 | |||
7. Response Header Fields .........................................64 | 8.8.2. Last-Modified . . . . . . . . . . . . . . . . . . . . 71 | |||
7.1. Control Data ..............................................64 | 8.8.3. ETag . . . . . . . . . . . . . . . . . . . . . . . . 73 | |||
7.1.1. Origination Date ...................................65 | 8.8.4. When to Use Entity-Tags and Last-Modified Dates . . . 77 | |||
7.1.2. Location ...........................................68 | 9. Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 | |||
7.1.3. Retry-After ........................................69 | 9.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 77 | |||
7.1.4. Vary ...............................................70 | 9.2. Common Method Properties . . . . . . . . . . . . . . . . 79 | |||
7.2. Validator Header Fields ...................................71 | 9.2.1. Safe Methods . . . . . . . . . . . . . . . . . . . . 80 | |||
7.3. Authentication Challenges .................................72 | 9.2.2. Idempotent Methods . . . . . . . . . . . . . . . . . 81 | |||
7.4. Response Context ..........................................72 | 9.2.3. Methods and Caching . . . . . . . . . . . . . . . . . 82 | |||
7.4.1. Allow ..............................................72 | 9.3. Method Definitions . . . . . . . . . . . . . . . . . . . 82 | |||
7.4.2. Server .............................................73 | 9.3.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 82 | |||
8. IANA Considerations ............................................73 | 9.3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 83 | |||
8.1. Method Registry ...........................................73 | 9.3.3. POST . . . . . . . . . . . . . . . . . . . . . . . . 84 | |||
8.1.1. Procedure ..........................................74 | 9.3.4. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 85 | |||
8.1.2. Considerations for New Methods .....................74 | 9.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 88 | |||
8.1.3. Registrations ......................................75 | 9.3.6. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 89 | |||
8.2. Status Code Registry ......................................75 | 9.3.7. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 90 | |||
8.2.1. Procedure ..........................................75 | 9.3.8. TRACE . . . . . . . . . . . . . . . . . . . . . . . . 91 | |||
8.2.2. Considerations for New Status Codes ................76 | 10. Message Context . . . . . . . . . . . . . . . . . . . . . . . 92 | |||
8.2.3. Registrations ......................................76 | 10.1. Request Context Fields . . . . . . . . . . . . . . . . . 92 | |||
8.3. Header Field Registry .....................................77 | 10.1.1. Expect . . . . . . . . . . . . . . . . . . . . . . . 92 | |||
8.3.1. Considerations for New Header Fields ...............78 | 10.1.2. From . . . . . . . . . . . . . . . . . . . . . . . . 94 | |||
8.3.2. Registrations ......................................80 | 10.1.3. Referer . . . . . . . . . . . . . . . . . . . . . . 95 | |||
8.4. Content Coding Registry ...................................81 | 10.1.4. TE . . . . . . . . . . . . . . . . . . . . . . . . . 96 | |||
8.4.1. Procedure ..........................................81 | 10.1.5. Trailer . . . . . . . . . . . . . . . . . . . . . . 97 | |||
8.4.2. Registrations ......................................81 | 10.1.6. User-Agent . . . . . . . . . . . . . . . . . . . . . 97 | |||
9. Security Considerations ........................................81 | 10.2. Response Context Fields . . . . . . . . . . . . . . . . 98 | |||
9.1. Attacks Based on File and Path Names ......................82 | 10.2.1. Allow . . . . . . . . . . . . . . . . . . . . . . . 99 | |||
9.2. Attacks Based on Command, Code, or Query Injection ........82 | 10.2.2. Date . . . . . . . . . . . . . . . . . . . . . . . . 99 | |||
9.3. Disclosure of Personal Information ........................83 | 10.2.3. Location . . . . . . . . . . . . . . . . . . . . . . 100 | |||
9.4. Disclosure of Sensitive Information in URIs ...............83 | 10.2.4. Retry-After . . . . . . . . . . . . . . . . . . . . 102 | |||
9.5. Disclosure of Fragment after Redirects ....................84 | 10.2.5. Server . . . . . . . . . . . . . . . . . . . . . . . 102 | |||
9.6. Disclosure of Product Information .........................84 | 11. HTTP Authentication . . . . . . . . . . . . . . . . . . . . . 103 | |||
9.7. Browser Fingerprinting ....................................84 | 11.1. Authentication Scheme . . . . . . . . . . . . . . . . . 103 | |||
10. Acknowledgments ...............................................85 | 11.2. Authentication Parameters . . . . . . . . . . . . . . . 103 | |||
11. References ....................................................85 | 11.3. Challenge and Response . . . . . . . . . . . . . . . . . 104 | |||
11.1. Normative References .....................................85 | 11.4. Credentials . . . . . . . . . . . . . . . . . . . . . . 105 | |||
11.2. Informative References ...................................86 | 11.5. Establishing a Protection Space (Realm) . . . . . . . . 105 | |||
Appendix A. Differences between HTTP and MIME .....................89 | 11.6. Authenticating Users to Origin Servers . . . . . . . . . 106 | |||
A.1. MIME-Version ..............................................89 | 11.6.1. WWW-Authenticate . . . . . . . . . . . . . . . . . . 106 | |||
A.2. Conversion to Canonical Form ..............................89 | 11.6.2. Authorization . . . . . . . . . . . . . . . . . . . 107 | |||
A.3. Conversion of Date Formats ................................90 | 11.6.3. Authentication-Info . . . . . . . . . . . . . . . . 108 | |||
A.4. Conversion of Content-Encoding ..........................90 | 11.7. Authenticating Clients to Proxies . . . . . . . . . . . 108 | |||
A.5. Conversion of Content-Transfer-Encoding .................90 | 11.7.1. Proxy-Authenticate . . . . . . . . . . . . . . . . . 108 | |||
A.6. MHTML and Line Length Limitations .........................90 | 11.7.2. Proxy-Authorization . . . . . . . . . . . . . . . . 109 | |||
Appendix B. Changes from RFC 2616 .................................91 | 11.7.3. Proxy-Authentication-Info . . . . . . . . . . . . . 109 | |||
Appendix C. Imported ABNF .........................................93 | 12. Content Negotiation . . . . . . . . . . . . . . . . . . . . . 110 | |||
Appendix D. Collected ABNF ........................................94 | 12.1. Proactive Negotiation . . . . . . . . . . . . . . . . . 111 | |||
Index .............................................................97 | 12.2. Reactive Negotiation . . . . . . . . . . . . . . . . . . 112 | |||
12.3. Request Content Negotiation . . . . . . . . . . . . . . 113 | ||||
12.4. Content Negotiation Field Features . . . . . . . . . . . 113 | ||||
12.4.1. Absence . . . . . . . . . . . . . . . . . . . . . . 113 | ||||
12.4.2. Quality Values . . . . . . . . . . . . . . . . . . . 114 | ||||
12.4.3. Wildcard Values . . . . . . . . . . . . . . . . . . 114 | ||||
12.5. Content Negotiation Fields . . . . . . . . . . . . . . . 114 | ||||
12.5.1. Accept . . . . . . . . . . . . . . . . . . . . . . . 115 | ||||
12.5.2. Accept-Charset . . . . . . . . . . . . . . . . . . . 117 | ||||
12.5.3. Accept-Encoding . . . . . . . . . . . . . . . . . . 118 | ||||
12.5.4. Accept-Language . . . . . . . . . . . . . . . . . . 119 | ||||
12.5.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . 121 | ||||
13. Conditional Requests . . . . . . . . . . . . . . . . . . . . 122 | ||||
13.1. Preconditions . . . . . . . . . . . . . . . . . . . . . 122 | ||||
13.1.1. If-Match . . . . . . . . . . . . . . . . . . . . . . 123 | ||||
13.1.2. If-None-Match . . . . . . . . . . . . . . . . . . . 124 | ||||
13.1.3. If-Modified-Since . . . . . . . . . . . . . . . . . 126 | ||||
13.1.4. If-Unmodified-Since . . . . . . . . . . . . . . . . 128 | ||||
13.1.5. If-Range . . . . . . . . . . . . . . . . . . . . . . 129 | ||||
13.2. Evaluation of Preconditions . . . . . . . . . . . . . . 130 | ||||
13.2.1. When to Evaluate . . . . . . . . . . . . . . . . . . 131 | ||||
13.2.2. Precedence of Preconditions . . . . . . . . . . . . 132 | ||||
14. Range Requests . . . . . . . . . . . . . . . . . . . . . . . 133 | ||||
14.1. Range Units . . . . . . . . . . . . . . . . . . . . . . 133 | ||||
14.1.1. Range Specifiers . . . . . . . . . . . . . . . . . . 134 | ||||
14.1.2. Byte Ranges . . . . . . . . . . . . . . . . . . . . 135 | ||||
14.2. Range . . . . . . . . . . . . . . . . . . . . . . . . . 137 | ||||
14.3. Accept-Ranges . . . . . . . . . . . . . . . . . . . . . 138 | ||||
14.4. Content-Range . . . . . . . . . . . . . . . . . . . . . 139 | ||||
14.5. Partial PUT . . . . . . . . . . . . . . . . . . . . . . 141 | ||||
14.6. Media Type multipart/byteranges . . . . . . . . . . . . 141 | ||||
15. Status Codes . . . . . . . . . . . . . . . . . . . . . . . . 143 | ||||
15.1. Overview of Status Codes . . . . . . . . . . . . . . . . 144 | ||||
15.2. Informational 1xx . . . . . . . . . . . . . . . . . . . 144 | ||||
15.2.1. 100 Continue . . . . . . . . . . . . . . . . . . . . 145 | ||||
15.2.2. 101 Switching Protocols . . . . . . . . . . . . . . 145 | ||||
15.3. Successful 2xx . . . . . . . . . . . . . . . . . . . . . 145 | ||||
15.3.1. 200 OK . . . . . . . . . . . . . . . . . . . . . . . 146 | ||||
15.3.2. 201 Created . . . . . . . . . . . . . . . . . . . . 146 | ||||
15.3.3. 202 Accepted . . . . . . . . . . . . . . . . . . . . 147 | ||||
15.3.4. 203 Non-Authoritative Information . . . . . . . . . 147 | ||||
15.3.5. 204 No Content . . . . . . . . . . . . . . . . . . . 147 | ||||
15.3.6. 205 Reset Content . . . . . . . . . . . . . . . . . 148 | ||||
15.3.7. 206 Partial Content . . . . . . . . . . . . . . . . 148 | ||||
15.4. Redirection 3xx . . . . . . . . . . . . . . . . . . . . 152 | ||||
15.4.1. 300 Multiple Choices . . . . . . . . . . . . . . . . 154 | ||||
15.4.2. 301 Moved Permanently . . . . . . . . . . . . . . . 155 | ||||
15.4.3. 302 Found . . . . . . . . . . . . . . . . . . . . . 155 | ||||
15.4.4. 303 See Other . . . . . . . . . . . . . . . . . . . 156 | ||||
15.4.5. 304 Not Modified . . . . . . . . . . . . . . . . . . 156 | ||||
15.4.6. 305 Use Proxy . . . . . . . . . . . . . . . . . . . 157 | ||||
15.4.7. 306 (Unused) . . . . . . . . . . . . . . . . . . . . 157 | ||||
15.4.8. 307 Temporary Redirect . . . . . . . . . . . . . . . 157 | ||||
15.4.9. 308 Permanent Redirect . . . . . . . . . . . . . . . 158 | ||||
15.5. Client Error 4xx . . . . . . . . . . . . . . . . . . . . 158 | ||||
15.5.1. 400 Bad Request . . . . . . . . . . . . . . . . . . 158 | ||||
15.5.2. 401 Unauthorized . . . . . . . . . . . . . . . . . . 159 | ||||
15.5.3. 402 Payment Required . . . . . . . . . . . . . . . . 159 | ||||
15.5.4. 403 Forbidden . . . . . . . . . . . . . . . . . . . 159 | ||||
15.5.5. 404 Not Found . . . . . . . . . . . . . . . . . . . 159 | ||||
15.5.6. 405 Method Not Allowed . . . . . . . . . . . . . . . 160 | ||||
15.5.7. 406 Not Acceptable . . . . . . . . . . . . . . . . . 160 | ||||
15.5.8. 407 Proxy Authentication Required . . . . . . . . . 160 | ||||
15.5.9. 408 Request Timeout . . . . . . . . . . . . . . . . 160 | ||||
15.5.10. 409 Conflict . . . . . . . . . . . . . . . . . . . . 161 | ||||
15.5.11. 410 Gone . . . . . . . . . . . . . . . . . . . . . . 161 | ||||
15.5.12. 411 Length Required . . . . . . . . . . . . . . . . 162 | ||||
15.5.13. 412 Precondition Failed . . . . . . . . . . . . . . 162 | ||||
15.5.14. 413 Content Too Large . . . . . . . . . . . . . . . 162 | ||||
15.5.15. 414 URI Too Long . . . . . . . . . . . . . . . . . . 162 | ||||
15.5.16. 415 Unsupported Media Type . . . . . . . . . . . . . 163 | ||||
15.5.17. 416 Range Not Satisfiable . . . . . . . . . . . . . 163 | ||||
15.5.18. 417 Expectation Failed . . . . . . . . . . . . . . . 164 | ||||
15.5.19. 418 (Unused) . . . . . . . . . . . . . . . . . . . . 164 | ||||
15.5.20. 421 Misdirected Request . . . . . . . . . . . . . . 164 | ||||
15.5.21. 422 Unprocessable Content . . . . . . . . . . . . . 165 | ||||
15.5.22. 426 Upgrade Required . . . . . . . . . . . . . . . . 165 | ||||
15.6. Server Error 5xx . . . . . . . . . . . . . . . . . . . . 165 | ||||
15.6.1. 500 Internal Server Error . . . . . . . . . . . . . 165 | ||||
15.6.2. 501 Not Implemented . . . . . . . . . . . . . . . . 166 | ||||
15.6.3. 502 Bad Gateway . . . . . . . . . . . . . . . . . . 166 | ||||
15.6.4. 503 Service Unavailable . . . . . . . . . . . . . . 166 | ||||
15.6.5. 504 Gateway Timeout . . . . . . . . . . . . . . . . 166 | ||||
15.6.6. 505 HTTP Version Not Supported . . . . . . . . . . . 166 | ||||
16. Extending HTTP . . . . . . . . . . . . . . . . . . . . . . . 167 | ||||
16.1. Method Extensibility . . . . . . . . . . . . . . . . . . 167 | ||||
16.1.1. Method Registry . . . . . . . . . . . . . . . . . . 167 | ||||
16.1.2. Considerations for New Methods . . . . . . . . . . . 168 | ||||
16.2. Status Code Extensibility . . . . . . . . . . . . . . . 168 | ||||
16.2.1. Status Code Registry . . . . . . . . . . . . . . . . 169 | ||||
16.2.2. Considerations for New Status Codes . . . . . . . . 169 | ||||
16.3. Field Extensibility . . . . . . . . . . . . . . . . . . 170 | ||||
16.3.1. Field Name Registry . . . . . . . . . . . . . . . . 170 | ||||
16.3.2. Considerations for New Fields . . . . . . . . . . . 172 | ||||
16.4. Authentication Scheme Extensibility . . . . . . . . . . 174 | ||||
16.4.1. Authentication Scheme Registry . . . . . . . . . . . 174 | ||||
16.4.2. Considerations for New Authentication Schemes . . . 175 | ||||
16.5. Range Unit Extensibility . . . . . . . . . . . . . . . . 176 | ||||
16.5.1. Range Unit Registry . . . . . . . . . . . . . . . . 176 | ||||
16.5.2. Considerations for New Range Units . . . . . . . . . 176 | ||||
16.6. Content Coding Extensibility . . . . . . . . . . . . . . 176 | ||||
16.6.1. Content Coding Registry . . . . . . . . . . . . . . 177 | ||||
16.6.2. Considerations for New Content Codings . . . . . . . 177 | ||||
16.7. Upgrade Token Registry . . . . . . . . . . . . . . . . . 177 | ||||
17. Security Considerations . . . . . . . . . . . . . . . . . . . 178 | ||||
17.1. Establishing Authority . . . . . . . . . . . . . . . . . 178 | ||||
17.2. Risks of Intermediaries . . . . . . . . . . . . . . . . 179 | ||||
17.3. Attacks Based on File and Path Names . . . . . . . . . . 180 | ||||
17.4. Attacks Based on Command, Code, or Query Injection . . . 181 | ||||
17.5. Attacks via Protocol Element Length . . . . . . . . . . 181 | ||||
17.6. Attacks using Shared-dictionary Compression . . . . . . 182 | ||||
17.7. Disclosure of Personal Information . . . . . . . . . . . 182 | ||||
17.8. Privacy of Server Log Information . . . . . . . . . . . 182 | ||||
17.9. Disclosure of Sensitive Information in URIs . . . . . . 183 | ||||
17.10. Disclosure of Fragment after Redirects . . . . . . . . . 184 | ||||
17.11. Disclosure of Product Information . . . . . . . . . . . 184 | ||||
17.12. Browser Fingerprinting . . . . . . . . . . . . . . . . . 184 | ||||
17.13. Validator Retention . . . . . . . . . . . . . . . . . . 185 | ||||
17.14. Denial-of-Service Attacks Using Range . . . . . . . . . 186 | ||||
17.15. Authentication Considerations . . . . . . . . . . . . . 186 | ||||
17.15.1. Confidentiality of Credentials . . . . . . . . . . 186 | ||||
17.15.2. Credentials and Idle Clients . . . . . . . . . . . 187 | ||||
17.15.3. Protection Spaces . . . . . . . . . . . . . . . . . 187 | ||||
17.15.4. Additional Response Fields . . . . . . . . . . . . 188 | ||||
18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 188 | ||||
18.1. URI Scheme Registration . . . . . . . . . . . . . . . . 188 | ||||
18.2. Method Registration . . . . . . . . . . . . . . . . . . 188 | ||||
18.3. Status Code Registration . . . . . . . . . . . . . . . . 189 | ||||
18.4. Field Name Registration . . . . . . . . . . . . . . . . 190 | ||||
18.5. Authentication Scheme Registration . . . . . . . . . . . 192 | ||||
18.6. Content Coding Registration . . . . . . . . . . . . . . 192 | ||||
18.7. Range Unit Registration . . . . . . . . . . . . . . . . 193 | ||||
18.8. Media Type Registration . . . . . . . . . . . . . . . . 193 | ||||
18.9. Port Registration . . . . . . . . . . . . . . . . . . . 193 | ||||
18.10. Upgrade Token Registration . . . . . . . . . . . . . . . 194 | ||||
19. References . . . . . . . . . . . . . . . . . . . . . . . . . 194 | ||||
19.1. Normative References . . . . . . . . . . . . . . . . . . 194 | ||||
19.2. Informative References . . . . . . . . . . . . . . . . . 196 | ||||
Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 202 | ||||
Appendix B. Changes from previous RFCs . . . . . . . . . . . . . 207 | ||||
B.1. Changes from RFC 2818 . . . . . . . . . . . . . . . . . . 207 | ||||
B.2. Changes from RFC 7230 . . . . . . . . . . . . . . . . . . 207 | ||||
B.3. Changes from RFC 7231 . . . . . . . . . . . . . . . . . . 208 | ||||
B.4. Changes from RFC 7232 . . . . . . . . . . . . . . . . . . 210 | ||||
B.5. Changes from RFC 7233 . . . . . . . . . . . . . . . . . . 210 | ||||
B.6. Changes from RFC 7235 . . . . . . . . . . . . . . . . . . 210 | ||||
B.7. Changes from RFC 7538 . . . . . . . . . . . . . . . . . . 210 | ||||
B.8. Changes from RFC 7615 . . . . . . . . . . . . . . . . . . 211 | ||||
B.9. Changes from RFC 7694 . . . . . . . . . . . . . . . . . . 211 | ||||
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 211 | ||||
C.1. Between RFC723x and draft 00 . . . . . . . . . . . . . . 211 | ||||
C.2. Since draft-ietf-httpbis-semantics-00 . . . . . . . . . . 211 | ||||
C.3. Since draft-ietf-httpbis-semantics-01 . . . . . . . . . . 212 | ||||
C.4. Since draft-ietf-httpbis-semantics-02 . . . . . . . . . . 213 | ||||
C.5. Since draft-ietf-httpbis-semantics-03 . . . . . . . . . . 214 | ||||
C.6. Since draft-ietf-httpbis-semantics-04 . . . . . . . . . . 215 | ||||
C.7. Since draft-ietf-httpbis-semantics-05 . . . . . . . . . . 215 | ||||
C.8. Since draft-ietf-httpbis-semantics-06 . . . . . . . . . . 217 | ||||
C.9. Since draft-ietf-httpbis-semantics-07 . . . . . . . . . . 218 | ||||
C.10. Since draft-ietf-httpbis-semantics-08 . . . . . . . . . . 219 | ||||
C.11. Since draft-ietf-httpbis-semantics-09 . . . . . . . . . . 221 | ||||
C.12. Since draft-ietf-httpbis-semantics-10 . . . . . . . . . . 221 | ||||
C.13. Since draft-ietf-httpbis-semantics-11 . . . . . . . . . . 222 | ||||
C.14. Since draft-ietf-httpbis-semantics-12 . . . . . . . . . . 223 | ||||
C.15. Since draft-ietf-httpbis-semantics-13 . . . . . . . . . . 225 | ||||
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 225 | ||||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 226 | ||||
1. Introduction | 1. Introduction | |||
1.1. Purpose | 1.1. Purpose | |||
[new] | The Hypertext Transfer Protocol (HTTP) is a family of stateless, | |||
application-level, request/response protocols that share a generic | ||||
interface, extensible semantics, and self-descriptive messages to | ||||
enable flexible interaction with network-based hypertext information | ||||
systems. | ||||
HTTP is a generic interface protocol for information systems. It is | HTTP hides the details of how a service is implemented by presenting | |||
designed | ||||
to hide the details of how a service is implemented by presenting | ||||
a uniform interface to clients that is independent of the types of | a uniform interface to clients that is independent of the types of | |||
resources provided. Likewise, servers do not need to be aware of | resources provided. Likewise, servers do not need to be aware of | |||
each client's purpose: an HTTP request can be considered in isolation | each client's purpose: a request can be considered in isolation | |||
rather than being associated with a specific type of client or a | rather than being associated with a specific type of client or a | |||
predetermined sequence of application steps. | predetermined sequence of application steps. This allows general- | |||
The result is a protocol that can be used effectively in many different | purpose implementations to be used effectively in many different | |||
contexts and for which implementations can evolve independently over time. | contexts, reduces interaction complexity, and enables independent | |||
evolution over time. | ||||
HTTP is also designed for use as an intermediation protocol for | HTTP is also designed for use as an intermediation protocol, wherein | |||
translating communication to and from non-HTTP information systems. | proxies and gateways can translate non-HTTP information systems into | |||
HTTP proxies and gateways can provide access to alternative | a more generic interface. | |||
information services by translating their diverse protocols into a | ||||
hypertext format that can be viewed and manipulated by clients in the | ||||
same way as HTTP services. | ||||
One consequence of this flexibility is that the protocol cannot be | One consequence of this flexibility is that the protocol cannot be | |||
defined in terms of what occurs behind the interface. Instead, we | defined in terms of what occurs behind the interface. Instead, we | |||
are limited to defining the syntax of communication, the intent of | are limited to defining the syntax of communication, the intent of | |||
received communication, and the expected behavior of recipients. If | received communication, and the expected behavior of recipients. If | |||
the communication is considered in isolation, then successful actions | the communication is considered in isolation, then successful actions | |||
ought to be reflected in corresponding changes to the observable | ought to be reflected in corresponding changes to the observable | |||
interface provided by servers. However, since multiple clients might | interface provided by servers. However, since multiple clients might | |||
act in parallel and perhaps at cross-purposes, we cannot require that | act in parallel and perhaps at cross-purposes, we cannot require that | |||
such changes be observable beyond the scope of a single response. | such changes be observable beyond the scope of a single response. | |||
1.2. History and Evolution | 1.2. History and Evolution | |||
HTTP has been in use since 1990. The first version, later referred | HTTP has been the primary information transfer protocol for the World | |||
to as HTTP/0.9, was a simple protocol for hypertext data transfer | Wide Web since its introduction in 1990. It began as a trivial | |||
across the Internet, using only a single request method (GET) and no | mechanism for low-latency requests, with a single method (GET) to | |||
metadata. | request transfer of a presumed hypertext document identified by a | |||
given pathname. As the Web grew, HTTP was extended to enclose | ||||
requests and responses within messages, transfer arbitrary data | ||||
formats using MIME-like media types, and route requests through | ||||
intermediaries. These protocols were eventually defined as HTTP/0.9 | ||||
and HTTP/1.0 (see [RFC1945]). | ||||
HTTP/1.0, as defined by [RFC1945], added a range of | HTTP/1.1 was designed to refine the protocol's features while | |||
request methods and MIME-like messaging, allowing for metadata to be | retaining compatibility with the existing text-based messaging | |||
transferred and modifiers placed on the request/response semantics. | syntax, improving its interoperability, scalability, and robustness | |||
However, HTTP/1.0 did not sufficiently take into consideration the | across the Internet. This included length-based data delimiters for | |||
effects of hierarchical proxies, caching, the need for persistent | both fixed and dynamic (chunked) content, a consistent framework for | |||
connections, or name-based virtual hosts. The proliferation of | content negotiation, opaque validators for conditional requests, | |||
incompletely implemented applications calling themselves "HTTP/1.0" | cache controls for better cache consistency, range requests for | |||
further necessitated a protocol version change in order for two | partial updates, and default persistent connections. HTTP/1.1 was | |||
communicating applications to determine each other's true | introduced in 1995 and published on the standards track in 1997 | |||
capabilities. | [RFC2068], revised in 1999 [RFC2616], and revised again in 2014 | |||
([RFC7230] - [RFC7235]). | ||||
[new] | HTTP/2 ([RFC7540]) introduced a multiplexed session layer on top of | |||
the existing TLS and TCP protocols for exchanging concurrent HTTP | ||||
messages with efficient field compression and server push. HTTP/3 | ||||
([HTTP3]) provides greater independence for concurrent messages by | ||||
using QUIC as a secure multiplexed transport over UDP instead of TCP. | ||||
[new] | All three major versions of HTTP rely on the semantics defined by | |||
this document. They have not obsoleted each other because each one | ||||
has specific benefits and limitations depending on the context of | ||||
use. Implementations are expected to choose the most appropriate | ||||
transport and messaging syntax for their particular context. | ||||
[new] | This revision of HTTP separates the definition of semantics (this | |||
document) and caching ([Caching]) from the current HTTP/1.1 messaging | ||||
syntax ([Messaging]) to allow each major protocol version to progress | ||||
independently while referring to the same core semantics. | ||||
1.3. Semantics | 1.3. Core Semantics | |||
HTTP provides a uniform interface for interacting with a resource | HTTP provides a uniform interface for interacting with a resource | |||
(Section 2), regardless of its type, nature, or implementation, via | (Section 3.1) - regardless of its type, nature, or implementation - | |||
the manipulation and transfer of representations (Section 3). | by sending messages that manipulate or transfer representations | |||
(Section 3.2). | ||||
Each Hypertext Transfer Protocol (HTTP) message is either a request | Each message is either a request or a response. A client constructs | |||
or a response. A server listens on a connection for a request, | request messages that communicate its intentions and routes those | |||
parses each message received, interprets the message semantics in | messages toward an identified origin server. A server listens for | |||
relation to the identified request target, and responds to that | requests, parses each message received, interprets the message | |||
request with one or more response messages. A client constructs | semantics in relation to the identified target resource, and responds | |||
request messages to communicate specific intentions, examines | to that request with one or more response messages. The client | |||
received responses to see if the intentions were carried out, and | examines received responses to see if its intentions were carried | |||
determines how to interpret the results. This document defines | out, determining what to do next based on the status codes and | |||
HTTP/1.1 request and response semantics in terms of the architecture | content received. | |||
defined in [RFC7230]. | ||||
HTTP semantics include the intentions defined by each request method | HTTP semantics include the intentions defined by each request method | |||
(Section 4), extensions to those semantics that might be described in | (Section 9), extensions to those semantics that might be described in | |||
request header fields (Section 5), the meaning of status codes to | request header fields, status codes that describe the response | |||
indicate a machine-readable response (Section 6), and the meaning of | (Section 15), and other control data and resource metadata that might | |||
other control data and resource metadata that might be given in | be given in response fields. | |||
response header fields (Section 7). | ||||
This document also defines representation metadata that describe how | Semantics also include representation metadata that describe how | |||
a payload is intended to be interpreted by a recipient, the request | content is intended to be interpreted by a recipient, request header | |||
header fields that might influence content selection, and the various | fields that might influence content selection, and the various | |||
selection algorithms that are collectively referred to as "content | selection algorithms that are collectively referred to as _content | |||
negotiation" (Section 3.4). | negotiation_ (Section 12). | |||
This document defines HTTP/1.1 range requests, partial responses, and | 1.4. Specifications Obsoleted by this Document | |||
the multipart/byteranges media type. | ||||
This document obsoletes the following specifications: | ||||
-------------------------------------------- ----------- --------- | ||||
Title Reference Changes | ||||
-------------------------------------------- ----------- --------- | ||||
HTTP Over TLS [RFC2818] B.1 | ||||
HTTP/1.1 Message Syntax and Routing [*] [RFC7230] B.2 | ||||
HTTP/1.1 Semantics and Content [RFC7231] B.3 | ||||
HTTP/1.1 Conditional Requests [RFC7232] B.4 | ||||
HTTP/1.1 Range Requests [RFC7233] B.5 | ||||
HTTP/1.1 Authentication [RFC7235] B.6 | ||||
HTTP Status Code 308 (Permanent Redirect) [RFC7538] B.7 | ||||
HTTP Authentication-Info and Proxy- [RFC7615] B.8 | ||||
Authentication-Info Response Header Fields | ||||
HTTP Client-Initiated Content-Encoding [RFC7694] B.9 | ||||
-------------------------------------------- ----------- --------- | ||||
Table 1 | ||||
[*] This document only obsoletes the portions of RFC 7230 that are | ||||
independent of the HTTP/1.1 messaging syntax and connection | ||||
management; the remaining bits of RFC 7230 are obsoleted by | ||||
"HTTP/1.1" [Messaging]. | ||||
2. Conformance | 2. Conformance | |||
2.1. Syntax Notation | 2.1. Syntax Notation | |||
This specification uses the Augmented Backus-Naur Form (ABNF) | This specification uses the Augmented Backus-Naur Form (ABNF) | |||
notation of [RFC5234] with a list extension, defined in Section 7 of | notation of [RFC5234], extended with the notation for case- | |||
[RFC7230], that allows for compact definition of comma-separated | sensitivity in strings defined in [RFC7405]. | |||
lists using a '#' operator (similar to how the '*' operator indicates | ||||
repetition). Appendix C describes rules imported from other | It also uses a list extension, defined in Section 5.6.1, that allows | |||
documents. Appendix D shows the collected grammar with all list | for compact definition of comma-separated lists using a "#" operator | |||
operators expanded to standard ABNF notation. | (similar to how the "*" operator indicates repetition). Appendix A | |||
shows the collected grammar with all list operators expanded to | ||||
standard ABNF notation. | ||||
As a convention, ABNF rule names prefixed with "obs-" denote | As a convention, ABNF rule names prefixed with "obs-" denote | |||
"obsolete" grammar rules that appear for historical reasons. | "obsolete" grammar rules that appear for historical reasons. | |||
The following core rules are included by reference, as defined in | The following core rules are included by reference, as defined in | |||
Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), | Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), | |||
CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double | CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double | |||
quote), HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF | quote), HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF | |||
(line feed), OCTET (any 8-bit sequence of data), SP (space), and | (line feed), OCTET (any 8-bit sequence of data), SP (space), and | |||
VCHAR (any visible US-ASCII character). | VCHAR (any visible US-ASCII character). | |||
Section 5.6 defines some generic syntactic components for field | ||||
values. | ||||
This specification uses the terms "character", "character encoding | This specification uses the terms "character", "character encoding | |||
scheme", "charset", and "protocol element" as they are defined in | scheme", "charset", and "protocol element" as they are defined in | |||
[RFC6365]. | [RFC6365]. | |||
2.2. Requirements Notation | 2.2. Requirements Notation | |||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | |||
document are to be interpreted as described in [RFC2119]. | "OPTIONAL" in this document are to be interpreted as described in BCP | |||
14 [RFC2119] [RFC8174] when, and only when, they appear in all | ||||
Conformance criteria and considerations regarding error handling are | capitals, as shown here. | |||
defined in Section 2.5 of [RFC7230]. | ||||
This specification targets conformance criteria according to the role | This specification targets conformance criteria according to the role | |||
of a participant in HTTP communication. Hence, HTTP requirements are | of a participant in HTTP communication. Hence, requirements are | |||
placed on senders, recipients, clients, servers, user agents, | placed on senders, recipients, clients, servers, user agents, | |||
intermediaries, origin servers, proxies, gateways, or caches, | intermediaries, origin servers, proxies, gateways, or caches, | |||
depending on what behavior is being constrained by the requirement. | depending on what behavior is being constrained by the requirement. | |||
Additional (social) requirements are placed on implementations, | Additional (social) requirements are placed on implementations, | |||
resource owners, and protocol element registrations when they apply | resource owners, and protocol element registrations when they apply | |||
beyond the scope of a single communication. | beyond the scope of a single communication. | |||
The verb "generate" is used instead of "send" where a requirement | The verb "generate" is used instead of "send" where a requirement | |||
differentiates between creating a protocol element and merely | applies only to implementations that create the protocol element, | |||
forwarding a received element downstream. | rather than an implementation that forwards a received element | |||
downstream. | ||||
An implementation is considered conformant if it complies with all of | An implementation is considered conformant if it complies with all of | |||
the requirements associated with the roles it partakes in HTTP. | the requirements associated with the roles it partakes in HTTP. | |||
Conformance includes both the syntax and semantics of protocol | Conformance includes both the syntax and semantics of protocol | |||
elements. A sender MUST NOT generate protocol elements that convey a | elements. A sender MUST NOT generate protocol elements that convey a | |||
meaning that is known by that sender to be false. A sender MUST NOT | meaning that is known by that sender to be false. A sender MUST NOT | |||
generate protocol elements that do not match the grammar defined by | generate protocol elements that do not match the grammar defined by | |||
the corresponding ABNF rules. Within a given message, a sender MUST | the corresponding ABNF rules. Within a given message, a sender MUST | |||
NOT generate protocol elements or syntax alternatives that are only | NOT generate protocol elements or syntax alternatives that are only | |||
allowed to be generated by participants in other roles (i.e., a role | allowed to be generated by participants in other roles (i.e., a role | |||
that the sender does not have for that message). | that the sender does not have for that message). | |||
2.3. Length Requirements | 2.3. Length Requirements | |||
When a received protocol element is parsed, the recipient MUST be | A recipient SHOULD parse a received protocol element defensively, | |||
able to parse any value of reasonable length that is applicable to | with only marginal expectations that the element will conform to its | |||
the recipient's role and that matches the grammar defined by the | ABNF grammar and fit within a reasonable buffer size. | |||
corresponding ABNF rules. | ||||
HTTP does not have specific length limitations for many of its | HTTP does not have specific length limitations for many of its | |||
protocol elements because the lengths that might be appropriate will | protocol elements because the lengths that might be appropriate will | |||
vary widely, depending on the deployment context and purpose of the | vary widely, depending on the deployment context and purpose of the | |||
implementation. Hence, interoperability between senders and | implementation. Hence, interoperability between senders and | |||
recipients depends on shared expectations regarding what is a | recipients depends on shared expectations regarding what is a | |||
reasonable length for each protocol element. Furthermore, what is | reasonable length for each protocol element. Furthermore, what is | |||
commonly understood to be a reasonable length for some protocol | commonly understood to be a reasonable length for some protocol | |||
elements has changed over the course of the past two decades of HTTP | elements has changed over the course of the past two decades of HTTP | |||
use and is expected to continue changing in the future. | use and is expected to continue changing in the future. | |||
At a minimum, a recipient MUST be able to parse and process protocol | At a minimum, a recipient MUST be able to parse and process protocol | |||
element lengths that are at least as long as the values that it | element lengths that are at least as long as the values that it | |||
generates for those same protocol elements in other messages. For | generates for those same protocol elements in other messages. For | |||
example, an origin server that publishes very long URI references to | example, an origin server that publishes very long URI references to | |||
its own resources needs to be able to parse and process those same | its own resources needs to be able to parse and process those same | |||
references when received as a request target. | references when received as a target URI. | |||
Note, however, that some received protocol elements might not be parsed. For | Many received protocol elements are only parsed to the extent | |||
example, an intermediary forwarding a message might parse a header-field | necessary to identify and forward that element downstream. For | |||
into generic field-name and field-value components, but then forward the | example, an intermediary might parse a received field into its field | |||
header field without further parsing inside the field-value. | name and field value components, but then forward the field without | |||
further parsing inside the field value. | ||||
2.4. Error Handling | 2.4. Error Handling | |||
A recipient MUST interpret a received protocol element according to | A recipient MUST interpret a received protocol element according to | |||
the semantics defined for it by this specification, including | the semantics defined for it by this specification, including | |||
extensions to this specification, unless the recipient has determined | extensions to this specification, unless the recipient has determined | |||
(through experience or configuration) that the sender incorrectly | (through experience or configuration) that the sender incorrectly | |||
implements what is implied by those semantics. For example, an | implements what is implied by those semantics. For example, an | |||
origin server might disregard the contents of a received | origin server might disregard the contents of a received | |||
Accept-Encoding header field if inspection of the User-Agent header | Accept-Encoding header field if inspection of the User-Agent header | |||
skipping to change at line 422 ¶ | skipping to change at page 14, line 27 ¶ | |||
Unless noted otherwise, a recipient MAY attempt to recover a usable | Unless noted otherwise, a recipient MAY attempt to recover a usable | |||
protocol element from an invalid construct. HTTP does not define | protocol element from an invalid construct. HTTP does not define | |||
specific error handling mechanisms except when they have a direct | specific error handling mechanisms except when they have a direct | |||
impact on security, since different applications of the protocol | impact on security, since different applications of the protocol | |||
require different error handling strategies. For example, a Web | require different error handling strategies. For example, a Web | |||
browser might wish to transparently recover from a response where the | browser might wish to transparently recover from a response where the | |||
Location header field doesn't parse according to the ABNF, whereas a | Location header field doesn't parse according to the ABNF, whereas a | |||
systems control client might consider any form of error recovery to | systems control client might consider any form of error recovery to | |||
be dangerous. | be dangerous. | |||
[new] | Some requests can be automatically retried by a client in the event | |||
of an underlying connection failure, as described in Section 9.2.2. | ||||
2.5. Protocol Version | 2.5. Protocol Version | |||
The HTTP version number consists of two decimal digits separated by a | HTTP's version number consists of two decimal digits separated by a | |||
"." (period or decimal point). The first digit ("major version") | "." (period or decimal point). The first digit ("major version") | |||
indicates the HTTP messaging syntax, whereas the second digit ("minor | indicates the messaging syntax, whereas the second digit ("minor | |||
version") indicates the highest minor version within that major | version") indicates the highest minor version within that major | |||
version to which the sender is conformant and able to understand for | version to which the sender is conformant (able to understand for | |||
future communication. | future communication). | |||
[new] | While HTTP's core semantics don't change between protocol versions, | |||
the expression of them "on the wire" can change, and so the HTTP | ||||
version number changes when incompatible changes are made to the wire | ||||
format. Additionally, HTTP allows incremental, backwards-compatible | ||||
changes to be made to the protocol without changing its version | ||||
through the use of defined extension points (Section 16). | ||||
The protocol version as a whole indicates the sender's conformance with | The protocol version as a whole indicates the sender's conformance | |||
the set of requirements laid out in that version's corresponding | with the set of requirements laid out in that version's corresponding | |||
specification of HTTP. | specification of HTTP. For example, the version "HTTP/1.1" is | |||
defined by the combined specifications of this document, "HTTP | ||||
Caching" [Caching], and "HTTP/1.1" [Messaging]. | ||||
The intention of HTTP's versioning design is that the major number | HTTP's major version number is incremented when an incompatible | |||
will only be incremented if an incompatible message syntax is | message syntax is introduced. The minor number is incremented when | |||
introduced, and that the minor number will only be incremented when | ||||
changes made to the protocol have the effect of adding to the message | changes made to the protocol have the effect of adding to the message | |||
semantics or implying additional capabilities of the sender. | semantics or implying additional capabilities of the sender. | |||
However, the minor version was not incremented for the changes | ||||
introduced between [RFC2068] and [RFC2616], and this revision has | ||||
specifically avoided any such changes to the protocol. | ||||
The minor version advertises the sender's communication capabilities | The minor version advertises the sender's communication capabilities | |||
even when the sender is only using a backwards-compatible subset of | even when the sender is only using a backwards-compatible subset of | |||
the protocol, thereby letting the recipient know that more advanced | the protocol, thereby letting the recipient know that more advanced | |||
features can be used in response (by servers) or in future requests | features can be used in response (by servers) or in future requests | |||
(by clients). | (by clients). | |||
[new] | When a major version of HTTP does not define any minor versions, the | |||
minor version "0" is implied and is used when referring to that | ||||
protocol within a protocol element that requires sending a minor | ||||
version. | ||||
3. Architecture | 3. Terminology and Core Concepts | |||
HTTP was created for the World Wide Web (WWW) architecture and has | HTTP was created for the World Wide Web (WWW) architecture and has | |||
evolved over time to support the scalability needs of a worldwide | evolved over time to support the scalability needs of a worldwide | |||
hypertext system. Much of that architecture is reflected in the | hypertext system. Much of that architecture is reflected in the | |||
terminology and syntax productions used to define HTTP. | terminology and syntax productions used to define HTTP. | |||
3.1. Resources | 3.1. Resources | |||
The target of an HTTP request is called a "resource". HTTP does not | The target of an HTTP request is called a _resource_. HTTP does not | |||
limit the nature of a resource; it merely defines an interface that | limit the nature of a resource; it merely defines an interface that | |||
might be used to interact with resources. Each resource is | might be used to interact with resources. Most resources are | |||
identified by a Uniform Resource Identifier (URI), as described in | identified by a Uniform Resource Identifier (URI), as described in | |||
Section 2.7 of [RFC7230]. | Section 4. | |||
One design goal of HTTP is to separate resource identification from | One design goal of HTTP is to separate resource identification from | |||
request semantics, which is made possible by vesting the request | request semantics, which is made possible by vesting the request | |||
semantics in the request method (Section 4) and a few | semantics in the request method (Section 9) and a few request- | |||
request-modifying header fields (Section 5). If there is a conflict | modifying header fields. If there is a conflict between the method | |||
between the method semantics and any semantic implied by the URI | semantics and any semantic implied by the URI itself, as described in | |||
itself, as described in Section 4.2.1, the method semantics take | Section 9.2.1, the method semantics take precedence. | |||
precedence. | ||||
HTTP relies upon the Uniform Resource Identifier (URI) standard | HTTP relies upon the Uniform Resource Identifier (URI) standard | |||
[RFC3986] to indicate the target resource (Section 5.1) and | [RFC3986] to indicate the target resource (Section 7.1) and | |||
relationships between resources. | relationships between resources. | |||
3.2. Representations | 3.2. Representations | |||
For the purposes of HTTP, a "representation" is information that is | A _representation_ is information that is intended to reflect a past, | |||
intended to reflect a past, current, or desired state of a given | current, or desired state of a given resource, in a format that can | |||
resource, in a format that can be readily communicated via the | be readily communicated via the protocol. A representation consists | |||
protocol, and that consists of a set of representation metadata and a | of a set of representation metadata and a potentially unbounded | |||
potentially unbounded stream of representation data. | stream of representation data (Section 8). | |||
[new] | HTTP allows "information hiding" behind its uniform interface by | |||
defining communication with respect to a transferable representation | ||||
of the resource state, rather than transferring the resource itself. | ||||
This allows the resource identified by a URI to be anything, | ||||
including temporal functions like "the current weather in Laguna | ||||
Beach", while potentially providing information that represents that | ||||
resource at the time a message is generated [REST]. | ||||
Considering that a resource could be anything, and that the uniform | The uniform interface is similar to a window through which one can | |||
interface provided by HTTP is similar to a window through which one | observe and act upon a thing only through the communication of | |||
can observe and act upon such a thing only through the communication | messages to an independent actor on the other side. A shared | |||
of messages to some independent actor on the other side, an | ||||
abstraction is needed to represent ("take the place of") the current | abstraction is needed to represent ("take the place of") the current | |||
or desired state of that thing in our communications. That | or desired state of that thing in our communications. When a | |||
abstraction is called a representation [REST]. | representation is hypertext, it can provide both a representation of | |||
the resource state and processing instructions that help guide the | ||||
recipient's future interactions. | ||||
An origin server might be provided with, or be capable of generating, | A target resource might be provided with, or be capable of | |||
multiple representations that are each intended to reflect the | generating, multiple representations that are each intended to | |||
current state of a target resource. In such cases, some algorithm is | reflect the resource's current state. An algorithm, usually based on | |||
used by the origin server to select one of those representations as | content negotiation (Section 12), would be used to select one of | |||
most applicable to a given request, usually based on content | those representations as being most applicable to a given request. | |||
negotiation. This "selected representation" is used to provide the | This _selected representation_ provides the data and metadata for | |||
data and metadata for evaluating conditional requests [RFC7232] and | evaluating conditional requests (Section 13) and constructing the | |||
constructing the payload for 200 (OK) and 304 (Not Modified) | content for 200 (OK), 206 (Partial Content), and 304 (Not Modified) | |||
responses to GET (Section 4.3.1). | responses to GET (Section 9.3.1). | |||
3.3. Connections | 3.3. Connections, Clients and Servers | |||
HTTP is a stateless request/response protocol that operates by | HTTP is a client/server protocol that operates over a reliable | |||
exchanging messages (Section 3) across a reliable transport- or | transport- or session-layer _connection_. | |||
session-layer "connection" (Section 6). | ||||
An HTTP "client" is a program that establishes a connection to a | An HTTP _client_ is a program that establishes a connection to a | |||
server for the purpose of sending one or more HTTP requests. An HTTP | server for the purpose of sending one or more HTTP requests. An HTTP | |||
"server" is a program that accepts connections in order to service | _server_ is a program that accepts connections in order to service | |||
HTTP requests by sending HTTP responses. | HTTP requests by sending HTTP responses. | |||
The terms "client" and "server" refer only to the roles that these | The terms "client" and "server" refer only to the roles that these | |||
programs perform for a particular connection. The same program might | programs perform for a particular connection. The same program might | |||
act as a client on some connections and a server on others. | act as a client on some connections and a server on others. | |||
A connection might be used for multiple request/response exchanges, | ||||
as defined in Section 6.3. | ||||
3.4. Messages | 3.4. Messages | |||
The terms "sender" and "recipient" | HTTP is a stateless request/response protocol for exchanging | |||
_messages_ across a connection. The terms _sender_ and _recipient_ | ||||
refer to any implementation that sends or receives a given message, | refer to any implementation that sends or receives a given message, | |||
respectively. | respectively. | |||
A client sends an HTTP request to a server in the form of a request | A client sends requests to a server in the form of a _request_ | |||
message, beginning with a request-line that includes a method, URI, | message with a method (Section 9) and request target (Section 7.1). | |||
and protocol version (Section 3.1.1), followed by header fields | The request might also contain header fields (Section 6.3) for | |||
containing request modifiers, client information, and representation | request modifiers, client information, and representation metadata, | |||
metadata (Section 3.2), an empty line to indicate the end of the | content (Section 6.4) intended for processing in accordance with the | |||
header section, and finally a message body containing the payload | method, and trailer fields (Section 6.5) to communicate information | |||
body (if any, Section 3.3). | collected while sending the content. | |||
When a client constructs an HTTP/1.1 request message, it sends the | ||||
target URI in one of various forms, as defined in (Section 5.3 of | ||||
[RFC7230]). When a request is received, the server reconstructs an | ||||
effective request URI for the target resource (Section 5.5 of | ||||
[RFC7230]). | ||||
A server responds to a client's request by sending one or more | A server responds to a client's request by sending one or more | |||
HTTP response messages, each beginning with a status line that includes | _response_ messages, each including a status code (Section 15). The | |||
the protocol version, a success or error code, and textual reason | response might also contain header fields for server information, | |||
phrase (Section 3.1.2), possibly followed by header fields containing | resource metadata, and representation metadata, content to be | |||
server information, resource metadata, and representation metadata | interpreted in accordance with the status code, and trailer fields to | |||
(Section 3.2), an empty line to indicate the end of the header section, | communicate information collected while sending the content. | |||
and finally a message body containing the payload body (if any, Section | ||||
3.3). | ||||
3.5. User Agents | 3.5. User Agents | |||
The term "user agent" refers to any of the various client programs | The term _user agent_ refers to any of the various client programs | |||
that initiate a request, including (but not limited to) browsers, spiders | that initiate a request. | |||
(web-based robots), command-line tools, custom applications, and | ||||
mobile apps. | ||||
When considering the design of HTTP, it is easy to fall into a trap | The most familiar form of user agent is the general-purpose Web | |||
of thinking that all user agents are general-purpose browsers and all | browser, but that's only a small percentage of implementations. | |||
origin servers are large public websites. That is not the case in | Other common user agents include spiders (web-traversing robots), | |||
practice. Common HTTP user agents include household appliances, | command-line tools, billboard screens, household appliances, scales, | |||
stereos, scales, firmware update scripts, command-line programs, | light bulbs, firmware update scripts, mobile apps, and communication | |||
mobile apps, and communication devices in a multitude of shapes and | devices in a multitude of shapes and sizes. | |||
sizes. | ||||
The term "user agent" does not imply that there is a human user | Being a user agent does not imply that there is a human user directly | |||
directly interacting with the software agent at the time of a | interacting with the software agent at the time of a request. In | |||
request. In many cases, a user agent is installed or configured to | many cases, a user agent is installed or configured to run in the | |||
run in the background and save its results for later inspection (or | background and save its results for later inspection (or save only a | |||
save only a subset of those results that might be interesting or | subset of those results that might be interesting or erroneous). | |||
erroneous). Spiders, for example, are typically given a start URI | Spiders, for example, are typically given a start URI and configured | |||
and configured to follow certain behavior while crawling the Web as a | to follow certain behavior while crawling the Web as a hypertext | |||
hypertext graph. | graph. | |||
The implementation diversity of HTTP means that not all user agents | Many user agents cannot, or choose not to, make interactive | |||
can make interactive suggestions to their user or provide adequate | suggestions to their user or provide adequate warning for security or | |||
warning for security or privacy concerns. In the few cases where | privacy concerns. In the few cases where this specification requires | |||
this specification requires reporting of errors to the user, it is | reporting of errors to the user, it is acceptable for such reporting | |||
acceptable for such reporting to only be observable in an error | to only be observable in an error console or log file. Likewise, | |||
console or log file. Likewise, requirements that an automated action | requirements that an automated action be confirmed by the user before | |||
be confirmed by the user before proceeding might be met via advance | proceeding might be met via advance configuration choices, run-time | |||
configuration choices, run-time options, or simple avoidance of the | options, or simple avoidance of the unsafe action; confirmation does | |||
unsafe action; confirmation does not imply any specific user | not imply any specific user interface or interruption of normal | |||
interface or interruption of normal processing if the user has | processing if the user has already made that choice. | |||
already made that choice. | ||||
3.6. Origin Server | 3.6. Origin Server | |||
The term "origin server" refers to the program that can originate | The term _origin server_ refers to a program that can originate | |||
authoritative responses for a given target resource. | authoritative responses for a given target resource. | |||
Likewise, common HTTP | The most familiar form of origin server are large public websites. | |||
origin servers include home automation units, configurable | However, like user agents being equated with browsers, it is easy to | |||
be misled into thinking that all origin servers are alike. Common | ||||
origin servers also include home automation units, configurable | ||||
networking components, office machines, autonomous robots, news | networking components, office machines, autonomous robots, news | |||
feeds, traffic cameras, ad selectors, and video-delivery | feeds, traffic cameras, real-time ad selectors, and video-on-demand | |||
platforms. | platforms. | |||
Most HTTP communication consists of a retrieval request (GET) for a | Most HTTP communication consists of a retrieval request (GET) for a | |||
representation of some resource identified by a URI. In the simplest | representation of some resource identified by a URI. In the simplest | |||
case, this might be accomplished via a single bidirectional | case, this might be accomplished via a single bidirectional | |||
connection (===) between the user agent (UA) and the origin | connection (===) between the user agent (UA) and the origin server | |||
server (O). | (O). | |||
request > | request > | |||
UA ======================================= O | UA ======================================= O | |||
< response | < response | |||
Figure 1 | ||||
3.7. Intermediaries | 3.7. Intermediaries | |||
HTTP enables the use of intermediaries to satisfy requests through a | HTTP enables the use of intermediaries to satisfy requests through a | |||
chain of connections. There are three common forms of HTTP | chain of connections. There are three common forms of HTTP | |||
intermediary: proxy, gateway, and tunnel. In some cases, a single | _intermediary_: proxy, gateway, and tunnel. In some cases, a single | |||
intermediary might act as an origin server, proxy, gateway, or | intermediary might act as an origin server, proxy, gateway, or | |||
tunnel, switching behavior based on the nature of each request. | tunnel, switching behavior based on the nature of each request. | |||
> > > > | > > > > | |||
UA =========== A =========== B =========== C =========== O | UA =========== A =========== B =========== C =========== O | |||
< < < < | < < < < | |||
Figure 2 | ||||
The figure above shows three intermediaries (A, B, and C) between the | The figure above shows three intermediaries (A, B, and C) between the | |||
user agent and origin server. A request or response message that | user agent and origin server. A request or response message that | |||
travels the whole chain will pass through four separate connections. | travels the whole chain will pass through four separate connections. | |||
Some HTTP communication options might apply only to the connection | Some HTTP communication options might apply only to the connection | |||
with the nearest, non-tunnel neighbor, only to the endpoints of the | with the nearest, non-tunnel neighbor, only to the endpoints of the | |||
chain, or to all connections along the chain. Although the diagram | chain, or to all connections along the chain. Although the diagram | |||
is linear, each participant might be engaged in multiple, | is linear, each participant might be engaged in multiple, | |||
simultaneous communications. For example, B might be receiving | simultaneous communications. For example, B might be receiving | |||
requests from many clients other than A, and/or forwarding requests | requests from many clients other than A, and/or forwarding requests | |||
to servers other than C, at the same time that it is handling A's | to servers other than C, at the same time that it is handling A's | |||
request. Likewise, later requests might be sent through a different | request. Likewise, later requests might be sent through a different | |||
path of connections, often based on dynamic configuration for load | path of connections, often based on dynamic configuration for load | |||
balancing. | balancing. | |||
skipping to change at line 641 ¶ | skipping to change at page 19, line 16 ¶ | |||
with the nearest, non-tunnel neighbor, only to the endpoints of the | with the nearest, non-tunnel neighbor, only to the endpoints of the | |||
chain, or to all connections along the chain. Although the diagram | chain, or to all connections along the chain. Although the diagram | |||
is linear, each participant might be engaged in multiple, | is linear, each participant might be engaged in multiple, | |||
simultaneous communications. For example, B might be receiving | simultaneous communications. For example, B might be receiving | |||
requests from many clients other than A, and/or forwarding requests | requests from many clients other than A, and/or forwarding requests | |||
to servers other than C, at the same time that it is handling A's | to servers other than C, at the same time that it is handling A's | |||
request. Likewise, later requests might be sent through a different | request. Likewise, later requests might be sent through a different | |||
path of connections, often based on dynamic configuration for load | path of connections, often based on dynamic configuration for load | |||
balancing. | balancing. | |||
The terms "upstream" and "downstream" are used to describe | The terms _upstream_ and _downstream_ are used to describe | |||
directional requirements in relation to the message flow: all | directional requirements in relation to the message flow: all | |||
messages flow from upstream to downstream. The terms "inbound" and | messages flow from upstream to downstream. The terms "inbound" and | |||
"outbound" are used to describe directional requirements in relation | "outbound" are used to describe directional requirements in relation | |||
to the request route: "inbound" means toward the origin server and | to the request route: _inbound_ means toward the origin server and | |||
"outbound" means toward the user agent. | _outbound_ means toward the user agent. | |||
A "proxy" is a message-forwarding agent that is selected by the | A _proxy_ is a message-forwarding agent that is chosen by the client, | |||
client, usually via local configuration rules, to receive requests | usually via local configuration rules, to receive requests for some | |||
for some type(s) of absolute URI and attempt to satisfy those | type(s) of absolute URI and attempt to satisfy those requests via | |||
requests via translation through the HTTP interface. Some | translation through the HTTP interface. Some translations are | |||
translations are minimal, such as for proxy requests for "http" URIs, | minimal, such as for proxy requests for "http" URIs, whereas other | |||
whereas other requests might require translation to and from entirely | requests might require translation to and from entirely different | |||
different application-level protocols. Proxies are often used to | application-level protocols. Proxies are often used to group an | |||
group an organization's HTTP requests through a common intermediary | organization's HTTP requests through a common intermediary for the | |||
for the sake of security, annotation services, or shared caching. | sake of security, annotation services, or shared caching. Some | |||
Some proxies are designed to apply transformations to selected | proxies are designed to apply transformations to selected messages or | |||
messages or payloads while they are being forwarded, as described in | content while they are being forwarded, as described in Section 7.7. | |||
Section 5.7.2. | ||||
A "gateway" (a.k.a. "reverse proxy") is an intermediary that acts as | A _gateway_ (a.k.a. _reverse proxy_) is an intermediary that acts as | |||
an origin server for the outbound connection but translates received | an origin server for the outbound connection but translates received | |||
requests and forwards them inbound to another server or servers. | requests and forwards them inbound to another server or servers. | |||
Gateways are often used to encapsulate legacy or untrusted | Gateways are often used to encapsulate legacy or untrusted | |||
information services, to improve server performance through | information services, to improve server performance through | |||
"accelerator" caching, and to enable partitioning or load balancing | _accelerator_ caching, and to enable partitioning or load balancing | |||
of HTTP services across multiple machines. | of HTTP services across multiple machines. | |||
All HTTP requirements applicable to an origin server also apply to | All HTTP requirements applicable to an origin server also apply to | |||
the outbound communication of a gateway. A gateway communicates with | the outbound communication of a gateway. A gateway communicates with | |||
inbound servers using any protocol that it desires, including private | inbound servers using any protocol that it desires, including private | |||
extensions to HTTP that are outside the scope of this specification. | extensions to HTTP that are outside the scope of this specification. | |||
However, an HTTP-to-HTTP gateway that wishes to interoperate with | However, an HTTP-to-HTTP gateway that wishes to interoperate with | |||
third-party HTTP servers ought to conform to user agent requirements | third-party HTTP servers ought to conform to user agent requirements | |||
on the gateway's inbound connection. | on the gateway's inbound connection. | |||
A "tunnel" acts as a blind relay between two connections without | A _tunnel_ acts as a blind relay between two connections without | |||
changing the messages. Once active, a tunnel is not considered a | changing the messages. Once active, a tunnel is not considered a | |||
party to the HTTP communication, though the tunnel might have been | party to the HTTP communication, though the tunnel might have been | |||
initiated by an HTTP request. A tunnel ceases to exist when both | initiated by an HTTP request. A tunnel ceases to exist when both | |||
ends of the relayed connection are closed. Tunnels are used to | ends of the relayed connection are closed. Tunnels are used to | |||
extend a virtual connection through an intermediary, such as when | extend a virtual connection through an intermediary, such as when | |||
Transport Layer Security (TLS, [RFC5246]) is used to establish | Transport Layer Security (TLS, [RFC8446]) is used to establish | |||
confidential communication through a shared firewall proxy. | confidential communication through a shared firewall proxy. | |||
The above categories for intermediary only consider those acting as | The above categories for intermediary only consider those acting as | |||
participants in the HTTP communication. There are also | participants in the HTTP communication. There are also | |||
intermediaries that can act on lower layers of the network protocol | intermediaries that can act on lower layers of the network protocol | |||
stack, filtering or redirecting HTTP traffic without the knowledge or | stack, filtering or redirecting HTTP traffic without the knowledge or | |||
permission of message senders. Network intermediaries are | permission of message senders. Network intermediaries are | |||
indistinguishable (at a protocol level) from a man-in-the-middle | indistinguishable (at a protocol level) from an on-path attacker, | |||
attack, often introducing security flaws or interoperability problems | often introducing security flaws or interoperability problems due to | |||
due to mistakenly violating HTTP semantics. | mistakenly violating HTTP semantics. | |||
For example, an "interception proxy" [RFC3040] (also commonly known | For example, an _interception proxy_ [RFC3040] (also commonly known | |||
as a "transparent proxy" [RFC1919] or "captive portal") differs from | as a _transparent proxy_ [RFC1919]) differs from an HTTP proxy | |||
an HTTP proxy because it is not selected by the client. Instead, an | because it is not chosen by the client. Instead, an interception | |||
interception proxy filters or redirects outgoing TCP port 80 packets | proxy filters or redirects outgoing TCP port 80 packets (and | |||
(and occasionally other common port traffic). Interception proxies | occasionally other common port traffic). Interception proxies are | |||
are commonly found on public network access points, as a means of | commonly found on public network access points, as a means of | |||
enforcing account subscription prior to allowing use of non-local | enforcing account subscription prior to allowing use of non-local | |||
Internet services, and within corporate firewalls to enforce network | Internet services, and within corporate firewalls to enforce network | |||
usage policies. | usage policies. | |||
HTTP is defined as a stateless protocol, meaning that each request | HTTP is defined as a stateless protocol, meaning that each request | |||
message can be understood in isolation. Many implementations depend | message can be understood in isolation. Many implementations depend | |||
on HTTP's stateless design in order to reuse proxied connections or | on HTTP's stateless design in order to reuse proxied connections or | |||
dynamically load balance requests across multiple servers. Hence, a | dynamically load balance requests across multiple servers. Hence, a | |||
server MUST NOT assume that two requests on the same connection are | server MUST NOT assume that two requests on the same connection are | |||
from the same user agent unless the connection is secured and | from the same user agent unless the connection is secured and | |||
specific to that agent. Some non-standard HTTP extensions (e.g., | specific to that agent. Some non-standard HTTP extensions (e.g., | |||
[RFC4559]) have been known to violate this requirement, resulting in | [RFC4559]) have been known to violate this requirement, resulting in | |||
security and interoperability problems. | security and interoperability problems. | |||
3.8. Caches | 3.8. Caches | |||
A "cache" is a local store of previous response messages and the | A _cache_ is a local store of previous response messages and the | |||
subsystem that controls its message storage, retrieval, and deletion. | subsystem that controls its message storage, retrieval, and deletion. | |||
A cache stores cacheable responses in order to reduce the response | A cache stores cacheable responses in order to reduce the response | |||
time and network bandwidth consumption on future, equivalent | time and network bandwidth consumption on future, equivalent | |||
requests. Any client or server MAY employ a cache, though a cache | requests. Any client or server MAY employ a cache, though a cache | |||
cannot be used by a server while it is acting as a tunnel. | cannot be used while acting as a tunnel. | |||
The effect of a cache is that the request/response chain is shortened | The effect of a cache is that the request/response chain is shortened | |||
if one of the participants along the chain has a cached response | if one of the participants along the chain has a cached response | |||
applicable to that request. The following illustrates the resulting | applicable to that request. The following illustrates the resulting | |||
chain if B has a cached copy of an earlier response from O (via C) | chain if B has a cached copy of an earlier response from O (via C) | |||
for a request that has not been cached by UA or A. | for a request that has not been cached by UA or A. | |||
> > | > > | |||
UA =========== A =========== B - - - - - - C - - - - - - O | UA =========== A =========== B - - - - - - C - - - - - - O | |||
< < | < < | |||
A response is "cacheable" if a cache is allowed to store a copy of | Figure 3 | |||
A response is _cacheable_ if a cache is allowed to store a copy of | ||||
the response message for use in answering subsequent requests. Even | the response message for use in answering subsequent requests. Even | |||
when a response is cacheable, there might be additional constraints | when a response is cacheable, there might be additional constraints | |||
placed by the client or by the origin server on when that cached | placed by the client or by the origin server on when that cached | |||
response can be used for a particular request. HTTP requirements for | response can be used for a particular request. HTTP requirements for | |||
cache behavior and cacheable responses are defined in Section 2 of | cache behavior and cacheable responses are defined in Section 2 of | |||
[RFC7234]. | [Caching]. | |||
There is a wide variety of architectures and configurations of caches | There is a wide variety of architectures and configurations of caches | |||
deployed across the World Wide Web and inside large organizations. | deployed across the World Wide Web and inside large organizations. | |||
These include national hierarchies of proxy caches to save | These include national hierarchies of proxy caches to save bandwidth | |||
transoceanic bandwidth, collaborative systems that broadcast or | and reduce latency, Content Delivery Networks that use gateway | |||
multicast cache entries, archives of pre-fetched cache entries for | caching to optimise regional and global distribution of popular | |||
use in off-line or high-latency environments, and so on. | sites, collaborative systems that broadcast or multicast cache | |||
entries, archives of pre-fetched cache entries for use in off-line or | ||||
high-latency environments, and so on. | ||||
3.9. Example Request and Response | 3.9. Example Message Exchange | |||
The following example illustrates a typical message exchange for a | The following example illustrates a typical HTTP/1.1 message exchange | |||
GET request (Section 4.3.1 of [RFC7231]) on the URI | for a GET request (Section 9.3.1) on the URI "http://www.example.com/ | |||
"http://www.example.com/hello.txt": | hello.txt": | |||
Client request: | Client request: | |||
GET /hello.txt HTTP/1.1 | GET /hello.txt HTTP/1.1 | |||
User-Agent: curl/7.16.3 libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3 | User-Agent: curl/7.16.3 libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3 | |||
Host: www.example.com | Host: www.example.com | |||
Accept-Language: en, mi | Accept-Language: en, mi | |||
Server response: | Server response: | |||
HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
Date: Mon, 27 Jul 2009 12:28:53 GMT | Date: Mon, 27 Jul 2009 12:28:53 GMT | |||
Server: Apache | Server: Apache | |||
Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT | Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT | |||
ETag: "34aa387-d-1568eb00" | ETag: "34aa387-d-1568eb00" | |||
Accept-Ranges: bytes | Accept-Ranges: bytes | |||
Content-Length: 51 | Content-Length: 51 | |||
Vary: Accept-Encoding | Vary: Accept-Encoding | |||
Content-Type: text/plain | Content-Type: text/plain | |||
Hello World! My payload includes a trailing CRLF. | Hello World! My content includes a trailing CRLF. | |||
4. Identifiers in HTTP | 4. Identifiers in HTTP | |||
Uniform Resource Identifiers (URIs) [RFC3986] are used throughout | Uniform Resource Identifiers (URIs) [RFC3986] are used throughout | |||
HTTP as the means for identifying resources (Section 2 of [RFC7231]). | HTTP as the means for identifying resources (Section 3.1). | |||
4.1. URI References | 4.1. URI References | |||
URI references are used to target requests, indicate redirects, and | URI references are used to target requests, indicate redirects, and | |||
define relationships. | define relationships. | |||
The definitions of "URI-reference", "absolute-URI", "relative-part", | The definitions of "URI-reference", "absolute-URI", "relative-part", | |||
"scheme", "authority", "port", "host", "path-abempty", "segment", | "authority", "port", "host", "path-abempty", "segment", and "query" | |||
"query", and "fragment" are adopted from the URI generic syntax. An | are adopted from the URI generic syntax. An "absolute-path" rule is | |||
"absolute-path" rule is defined for protocol elements that can | defined for protocol elements that can contain a non-empty path | |||
contain a non-empty path component. (This rule differs slightly from | component. (This rule differs slightly from the path-abempty rule of | |||
the path-abempty rule of RFC 3986, which allows for an empty path to | RFC 3986, which allows for an empty path to be used in references, | |||
be used in references, and path-absolute rule, which does not allow | and path-absolute rule, which does not allow paths that begin with | |||
paths that begin with "//".) A "partial-URI" rule is defined for | "//".) A "partial-URI" rule is defined for protocol elements that | |||
protocol elements that can contain a relative URI but not a fragment | can contain a relative URI but not a fragment component. | |||
component. | ||||
URI-reference = <URI-reference, see [RFC3986], Section 4.1> | URI-reference = <URI-reference, see [RFC3986], Section 4.1> | |||
absolute-URI = <absolute-URI, see [RFC3986], Section 4.3> | absolute-URI = <absolute-URI, see [RFC3986], Section 4.3> | |||
relative-part = <relative-part, see [RFC3986], Section 4.2> | relative-part = <relative-part, see [RFC3986], Section 4.2> | |||
scheme = <scheme, see [RFC3986], Section 3.1> | ||||
authority = <authority, see [RFC3986], Section 3.2> | authority = <authority, see [RFC3986], Section 3.2> | |||
uri-host = <host, see [RFC3986], Section 3.2.2> | uri-host = <host, see [RFC3986], Section 3.2.2> | |||
port = <port, see [RFC3986], Section 3.2.3> | port = <port, see [RFC3986], Section 3.2.3> | |||
path-abempty = <path-abempty, see [RFC3986], Section 3.3> | path-abempty = <path-abempty, see [RFC3986], Section 3.3> | |||
segment = <segment, see [RFC3986], Section 3.3> | segment = <segment, see [RFC3986], Section 3.3> | |||
query = <query, see [RFC3986], Section 3.4> | query = <query, see [RFC3986], Section 3.4> | |||
fragment = <fragment, see [RFC3986], Section 3.5> | ||||
absolute-path = 1*( "/" segment ) | absolute-path = 1*( "/" segment ) | |||
partial-URI = relative-part [ "?" query ] | partial-URI = relative-part [ "?" query ] | |||
Each protocol element in HTTP that allows a URI reference will | Each protocol element in HTTP that allows a URI reference will | |||
indicate in its ABNF production whether the element allows any form | indicate in its ABNF production whether the element allows any form | |||
of reference (URI-reference), only a URI in absolute form | of reference (URI-reference), only a URI in absolute form (absolute- | |||
(absolute-URI), only the path and optional query components, or some | URI), only the path and optional query components, or some | |||
combination of the above. Unless otherwise indicated, URI references | combination of the above. Unless otherwise indicated, URI references | |||
are parsed relative to the effective request URI (Section 5.5). | are parsed relative to the target URI (Section 7.1). | |||
[new] | It is RECOMMENDED that all senders and recipients support, at a | |||
minimum, URIs with lengths of 8000 octets in protocol elements. Note | ||||
that this implies some structures and on-wire representations (for | ||||
example, the request line in HTTP/1.1) will necessarily be larger in | ||||
some cases. | ||||
4.2. URI Schemes | 4.2. HTTP-Related URI Schemes | |||
IANA maintains the registry of URI Schemes [BCP115] at | IANA maintains the registry of URI Schemes [BCP35] at | |||
<http://www.iana.org/assignments/uri-schemes/>. | <https://www.iana.org/assignments/uri-schemes/>. Although requests | |||
might target any URI scheme, the following schemes are inherent to | ||||
HTTP servers: | ||||
This document defines the following URI schemes. | ------------ ------------------------------------ ------- | |||
URI Scheme Description Ref. | ||||
------------ ------------------------------------ ------- | ||||
http Hypertext Transfer Protocol 4.2.1 | ||||
https Hypertext Transfer Protocol Secure 4.2.2 | ||||
------------ ------------------------------------ ------- | ||||
+------------+------------------------------------+---------------+ | Table 2 | |||
| URI Scheme | Description | Reference | | ||||
+------------+------------------------------------+---------------+ | ||||
| http | Hypertext Transfer Protocol | Section 2.7.1 | | ||||
| https | Hypertext Transfer Protocol Secure | Section 2.7.2 | | ||||
+------------+------------------------------------+---------------+ | ||||
Note that the presence of a URI with a given authority component does | Note that the presence of an "http" or "https" URI does not imply | |||
not imply that there is always an HTTP server listening for | that there is always an HTTP server at the identified origin | |||
connections on that host and port. Anyone can mint a URI. What the | listening for connections. Anyone can mint a URI, whether or not a | |||
authority component determines is who has the right to respond | server exists and whether or not that server currently maps that | |||
authoritatively to requests that target the identified resource. The | identifier to a resource. The delegated nature of registered names | |||
delegated nature of registered names and IP addresses creates a | and IP addresses creates a federated namespace whether or not an HTTP | |||
federated namespace, based on control over the indicated host and | server is present. | |||
port, whether or not an HTTP server is present. | ||||
4.2.1. http URI Scheme | 4.2.1. http URI Scheme | |||
The "http" URI scheme is hereby defined for the purpose of minting | The "http" URI scheme is hereby defined for minting identifiers | |||
identifiers according to their association with the hierarchical | within the hierarchical namespace governed by a potential HTTP origin | |||
namespace governed by a potential HTTP origin server listening for | server listening for TCP ([RFC0793]) connections on a given port. | |||
TCP ([RFC0793]) connections on a given port. | ||||
http-URI = "http:" "//" authority path-abempty [ "?" query ] | http-URI = "http" "://" authority path-abempty [ "?" query ] | |||
[ "#" fragment ] | ||||
The origin server for an "http" URI is identified by the authority | The origin server for an "http" URI is identified by the authority | |||
component, which includes a host identifier and optional TCP port | component, which includes a host identifier and optional port number | |||
([RFC3986], Section 3.2.2). If the port subcomponent is empty or not | ([RFC3986], Section 3.2.2). If the port subcomponent is empty or not | |||
given, TCP port 80 (the reserved port for WWW services) is the | given, TCP port 80 (the reserved port for WWW services) is the | |||
default. | default. The origin determines who has the right to respond | |||
authoritatively to requests that target the identified resource, as | ||||
defined in Section 4.3.2. | ||||
A sender MUST NOT generate an "http" URI with an empty host | A sender MUST NOT generate an "http" URI with an empty host | |||
identifier. A recipient that processes such a URI reference MUST | identifier. A recipient that processes such a URI reference MUST | |||
reject it as invalid. | reject it as invalid. | |||
The hierarchical path component and optional query component serve | The hierarchical path component and optional query component identify | |||
as an identifier for a potential target resource within that | the target resource within that origin server's name space. | |||
origin server's name space. | ||||
4.2.2. https URI Scheme | 4.2.2. https URI Scheme | |||
The "https" URI scheme is hereby defined for the purpose of minting | The "https" URI scheme is hereby defined for minting identifiers | |||
identifiers according to their association with the hierarchical | within the hierarchical namespace governed by a potential origin | |||
namespace governed by a potential HTTP origin server listening to a | server listening for TCP connections on a given port and capable of | |||
given TCP port for TLS-secured connections ([RFC5246]). | establishing a TLS ([RFC8446]) connection that has been secured for | |||
HTTP communication. In this context, _secured_ specifically means | ||||
that the server has been authenticated as acting on behalf of the | ||||
identified authority and all HTTP communication with that server has | ||||
been protected for confidentiality and integrity through the use of | ||||
strong encryption. | ||||
https-URI = "https:" "//" authority path-abempty [ "?" query ] | https-URI = "https" "://" authority path-abempty [ "?" query ] | |||
[ "#" fragment ] | ||||
All of the requirements listed above for the "http" scheme are also | The origin server for an "https" URI is identified by the authority | |||
requirements for the "https" scheme, except that TCP port 443 is the | component, which includes a host identifier and optional port number | |||
default if the port subcomponent is empty or not given, and the user | ([RFC3986], Section 3.2.2). If the port subcomponent is empty or not | |||
agent MUST ensure that its connection to the origin server is secured | given, TCP port 443 (the reserved port for HTTP over TLS) is the | |||
through the use of strong encryption, end-to-end, prior to sending | default. The origin determines who has the right to respond | |||
the first HTTP request. | authoritatively to requests that target the identified resource, as | |||
defined in Section 4.3.3. | ||||
Note that the "https" URI scheme depends on both TLS and TCP for | A sender MUST NOT generate an "https" URI with an empty host | |||
establishing authority. | identifier. A recipient that processes such a URI reference MUST | |||
reject it as invalid. | ||||
The process for authoritative access to an "https" identified | The hierarchical path component and optional query component identify | |||
resource is defined in [RFC2818]. | the target resource within that origin server's name space. | |||
A client MUST ensure that its HTTP requests for an "https" resource | ||||
are secured, prior to being communicated, and that it only accepts | ||||
secured responses to those requests. | ||||
Resources made available via the "https" scheme have no shared | Resources made available via the "https" scheme have no shared | |||
identity with the "http" scheme even if their resource identifiers | identity with the "http" scheme. They are distinct origins with | |||
indicate the same authority (the same host listening to the same TCP | separate namespaces. However, an extension to HTTP that is defined | |||
port). They are distinct namespaces and are considered to be distinct | to apply to all origins with the same host, such as the Cookie | |||
origin servers. However, an extension to HTTP that is defined | ||||
to apply to entire host domains, such as the Cookie | ||||
protocol [RFC6265], can allow information set by one service to | protocol [RFC6265], can allow information set by one service to | |||
impact communication with other services within a matching group of | impact communication with other services within a matching group of | |||
host domains. | host domains. | |||
4.2.3. http and https URI Normalization and Comparison | 4.2.3. http(s) Normalization and Comparison | |||
Since the "http" and "https" schemes conform to the URI generic | Since the "http" and "https" schemes conform to the URI generic | |||
syntax, such URIs are normalized and compared according to the | syntax, such URIs are normalized and compared according to the | |||
algorithm defined in Section 6 of [RFC3986], using the defaults | algorithm defined in Section 6 of [RFC3986], using the defaults | |||
described above for each scheme. | described above for each scheme. | |||
If the port is equal to the default port for a scheme, the normal | If the port is equal to the default port for a scheme, the normal | |||
form is to omit the port subcomponent. When not being used in | form is to omit the port subcomponent. When not being used as the | |||
absolute form as the request target of an OPTIONS request, an empty | target of an OPTIONS request, an empty path component is equivalent | |||
path component is equivalent to an absolute path of "/", so the | to an absolute path of "/", so the normal form is to provide a path | |||
normal form is to provide a path of "/" instead. The scheme and host | of "/" instead. The scheme and host are case-insensitive and | |||
are case-insensitive and normally provided in lowercase; all other | normally provided in lowercase; all other components are compared in | |||
components are compared in a case-sensitive manner. Characters other | a case-sensitive manner. Characters other than those in the | |||
than those in the "reserved" set are equivalent to their | "reserved" set are equivalent to their percent-encoded octets: the | |||
percent-encoded octets: the normal form is to not encode them (see | normal form is to not encode them (see Sections 2.1 and 2.2 of | |||
Sections 2.1 and 2.2 of [RFC3986]). | [RFC3986]). | |||
For example, the following three URIs are equivalent: | For example, the following three URIs are equivalent: | |||
http://example.com:80/~smith/home.html | http://example.com:80/~smith/home.html | |||
http://EXAMPLE.com/%7Esmith/home.html | http://EXAMPLE.com/%7Esmith/home.html | |||
http://EXAMPLE.com:/%7esmith/home.html | http://EXAMPLE.com:/%7esmith/home.html | |||
4.2.4. Deprecated userinfo | 4.2.4. Deprecation of userinfo in http(s) URIs | |||
The URI generic syntax for authority also includes a deprecated | The URI generic syntax for authority also includes a userinfo | |||
userinfo subcomponent ([RFC3986], Section 3.2.1) for including user | subcomponent ([RFC3986], Section 3.2.1) for including user | |||
authentication information in the URI. | authentication information in the URI. In that subcomponent, the use | |||
of the format "user:password" is deprecated. | ||||
Some implementations make use of the userinfo component for internal | Some implementations make use of the userinfo component for internal | |||
configuration of authentication information, such as within command | configuration of authentication information, such as within command | |||
invocation options, configuration files, or bookmark lists, even | invocation options, configuration files, or bookmark lists, even | |||
though such usage might expose a user identifier or password. | though such usage might expose a user identifier or password. | |||
A sender MUST NOT generate the userinfo subcomponent (and its "@" | A sender MUST NOT generate the userinfo subcomponent (and its "@" | |||
delimiter) when an "http" URI reference is generated | delimiter) when an "http" or "https" URI reference is generated | |||
within a message as a request target or header field value. | within a message as a target URI or field value. | |||
Before making use of an "http" URI reference received from | Before making use of an "http" or "https" URI reference received from | |||
an untrusted source, a recipient SHOULD parse for userinfo and treat | an untrusted source, a recipient SHOULD parse for userinfo and treat | |||
its presence as an error; it is likely being used to obscure the | its presence as an error; it is likely being used to obscure the | |||
authority for the sake of phishing attacks. | authority for the sake of phishing attacks. | |||
4.2.5. Fragment Identifiers on http(s) URI References | 4.2.5. http(s) References with Fragment Identifiers | |||
The optional fragment component allows for indirect identification of a | Fragment identifiers allow for indirect identification of a secondary | |||
secondary resource, independent of the URI scheme, as defined in Section | resource, independent of the URI scheme, as defined in Section 3.5 of | |||
3.5 of [RFC3986]. | [RFC3986]. Some protocol elements that refer to a URI allow | |||
inclusion of a fragment, while others do not. They are distinguished | ||||
by use of the ABNF rule for elements where fragment is allowed; | ||||
otherwise, a specific rule that excludes fragments is used. | ||||
[new] | | *Note:* The fragment identifier component is not part of the | |||
| scheme definition for a URI scheme (see Section 4.3 of | ||||
| [RFC3986]), thus does not appear in the ABNF definitions for | ||||
| the "http" and "https" URI schemes above. | ||||
4.3. Authoritative Access | 4.3. Authoritative Access | |||
[new] | Authoritative access refers to dereferencing a given identifier, for | |||
the sake of access to the identified resource, in a way that the | ||||
client believes is authoritative (controlled by the resource owner). | ||||
The process for determining that access is defined by the URI scheme | ||||
and often uses data within the URI components, such as the authority | ||||
component when the generic syntax is used. However, authoritative | ||||
access is not limited to the identified mechanism. | ||||
[new] | Section 4.3.1 defines the concept of an origin as an aid to such | |||
uses, and the subsequent subsections explain how to establish a | ||||
peer's association with an authority to represent an origin. | ||||
See Section 9.1 for security considerations related to establishing | See Section 17.1 for security considerations related to establishing | |||
authority. | authority. | |||
4.3.1. URI Origin | 4.3.1. URI Origin | |||
[new] | The _origin_ for a given URI is the triple of scheme, host, and port | |||
after normalizing the scheme and host to lowercase and normalizing | ||||
the port to remove any leading zeros. If port is elided from the | ||||
URI, the default port for that scheme is used. For example, the URI | ||||
[new] | https://Example.Com/happy.js | |||
[new] | would have the origin | |||
[new] | { "https", "example.com", "443" } | |||
[new] | which can also be described as the normalized URI prefix with port | |||
always present: | ||||
[new] | https://example.com:443 | |||
[new] | Each origin defines its own namespace and controls how identifiers | |||
within that namespace are mapped to resources. In turn, how the | ||||
origin responds to valid requests, consistently over time, determines | ||||
the semantics that users will associate with a URI, and the | ||||
usefulness of those semantics is what ultimately transforms these | ||||
mechanisms into a "resource" for users to reference and access in the | ||||
future. | ||||
[new] | Two origins are distinct if they differ in scheme, host, or port. | |||
Even when it can be verified that the same entity controls two | ||||
distinct origins, the two namespaces under those origins are distinct | ||||
unless explicitly aliased by a server authoritative for that origin. | ||||
Origin is also used within HTML and related Web protocols, beyond the | ||||
scope of this document, as described in [RFC6454]. | ||||
4.3.2. http origins | 4.3.2. http origins | |||
Although HTTP is independent of the transport protocol, the "http" | Although HTTP is independent of the transport protocol, the "http" | |||
scheme is specific to TCP-based services because the name delegation | scheme (Section 4.2.1) is specific to associating authority with | |||
process depends on TCP for establishing authority. An HTTP service | whomever controls the origin server listening for TCP connections on | |||
based on some other underlying connection protocol would presumably | the indicated port of whatever host is identified within the | |||
be identified using a different URI scheme, just as the "https" | authority component. This is a very weak sense of authority because | |||
scheme (below) is used for resources that require an end-to-end | it depends on both client-specific name resolution mechanisms and | |||
secured connection. Other protocols might also be used to provide | communication that might not be secured from an on-path attacker. | |||
access to "http" identified resources -- it is only the authoritative | Nevertheless, it is a sufficient minimum for binding "http" | |||
interface that is specific to TCP. | identifiers to an origin server for consistent resolution within a | |||
trusted environment. | ||||
If the host identifier is provided as an IP address, the origin | If the host identifier is provided as an IP address, the origin | |||
server is the listener (if any) on the indicated TCP port at that IP | server is the listener (if any) on the indicated TCP port at that IP | |||
address. If host is a registered name, the registered name is an | address. If host is a registered name, the registered name is an | |||
indirect identifier for use with a name resolution service, such as | indirect identifier for use with a name resolution service, such as | |||
DNS, to find an address for that origin server. | DNS, to find an address for an appropriate origin server. | |||
When an "http" URI is used within a context that calls for access to | When an "http" URI is used within a context that calls for access to | |||
the indicated resource, a client MAY attempt access by resolving the | the indicated resource, a client MAY attempt access by resolving the | |||
host to an IP address, establishing a TCP connection to that address | host identifier to an IP address, establishing a TCP connection to | |||
on the indicated port, and sending an HTTP request message | that address on the indicated port, and sending an HTTP request | |||
(Section 3) containing the URI's identifying data (Section 5) to the | message to the server containing the URI's identifying data. | |||
server. | ||||
If the server responds to that request with a non-interim HTTP | If the server responds to such a request with a non-interim HTTP | |||
response message, as described in Section 6 of [RFC7231], then that response | response message, as described in Section 15, then that response is | |||
is | ||||
considered an authoritative answer to the client's request. | considered an authoritative answer to the client's request. | |||
[new] | Note, however, that the above is not the only means for obtaining an | |||
authoritative response, nor does it imply that an authoritative | ||||
response is always necessary (see [Caching]). For example, the Alt- | ||||
Svc header field [RFC7838] allows an origin server to identify other | ||||
services that are also authoritative for that origin. Access to | ||||
"http" identified resources might also be provided by protocols | ||||
outside the scope of this document. | ||||
4.3.3. https origins | 4.3.3. https origins | |||
[new] | The "https" scheme (Section 4.2.2) associates authority based on the | |||
ability of a server to use the private key corresponding to a | ||||
certificate that the client considers to be trustworthy for the | ||||
identified origin server. The client usually relies upon a chain of | ||||
trust, conveyed from some prearranged or configured trust anchor, to | ||||
deem a certificate trustworthy (Section 4.3.4). | ||||
[new] | In HTTP/1.1 and earlier, a client will only attribute authority to a | |||
server when they are communicating over a successfully established | ||||
and secured connection specifically to that URI origin's host. The | ||||
connection establishment and certificate verification are used as | ||||
proof of authority. | ||||
[new] | In HTTP/2 and HTTP/3, a client will attribute authority to a server | |||
when they are communicating over a successfully established and | ||||
secured connection if the URI origin's host matches any of the hosts | ||||
present in the server's certificate and the client believes that it | ||||
could open a connection to that host for that URI. In practice, a | ||||
client will make a DNS query to check that the origin's host contains | ||||
the same server IP address as the established connection. This | ||||
restriction can be removed by the origin server sending an equivalent | ||||
ORIGIN frame [RFC8336]. | ||||
[new] | The request target's host and port value are passed within each HTTP | |||
request, identifying the origin and distinguishing it from other | ||||
namespaces that might be controlled by the same server (Section 7.2). | ||||
It is the origin's responsibility to ensure that any services | ||||
provided with control over its certificate's private key are equally | ||||
responsible for managing the corresponding "https" namespaces, or at | ||||
least prepared to reject requests that appear to have been | ||||
misdirected. A server might be unwilling to serve as the origin for | ||||
some hosts even when they have the authority to do so. | ||||
[new] | For example, if a network attacker causes connections for port N to | |||
be received at port Q, checking the target URI is necessary to ensure | ||||
that the attacker can't cause "https://example.com:N/foo" to be | ||||
replaced by "https://example.com:Q/foo" without consent. | ||||
[new] | Note that the "https" scheme does not rely on TCP and the connected | |||
port number for associating authority, since both are outside the | ||||
secured communication and thus cannot be trusted as definitive. | ||||
Hence, the HTTP communication might take place over any channel that | ||||
has been secured, as defined in Section 4.2.2, including protocols | ||||
that don't use TCP. | ||||
[new] | When an "https" URI is used within a context that calls for access to | |||
the indicated resource, a client MAY attempt access by resolving the | ||||
host identifier to an IP address, establishing a TCP connection to | ||||
that address on the indicated port, securing the connection end-to- | ||||
end by successfully initiating TLS over TCP with confidentiality and | ||||
integrity protection, and sending an HTTP request message over that | ||||
connection containing the URI's identifying data. | ||||
[new] | If the server responds to such a request with a non-interim HTTP | |||
response message, as described in Section 15, then that response is | ||||
considered an authoritative answer to the client's request. | ||||
[new] | Note, however, that the above is not the only means for obtaining an | |||
authoritative response, nor does it imply that an authoritative | ||||
response is always necessary (see [Caching]). | ||||
4.3.4. https certificate verification | 4.3.4. https certificate verification | |||
In general, HTTP/TLS requests are generated by dereferencing a URI. | To establish a secured connection to dereference a URI, a client MUST | |||
As a consequence, the hostname for the server is known to the client. | verify that the service's identity is an acceptable match for the | |||
If the hostname is available, the client MUST check it against the | URI's origin server. Certificate verification is used to prevent | |||
server's identity as presented in the server's Certificate message, | server impersonation by an on-path attacker or by an attacker that | |||
in order to prevent man-in-the-middle attacks. | controls name resolution. This process requires that a client be | |||
If a subjectAltName extension of type dNSName is present, that MUST | configured with a set of trust anchors. | |||
be used as the identity. Otherwise, the (most specific) Common Name | ||||
field in the Subject field of the certificate MUST be used. Although | ||||
the use of the Common Name is existing practice, it is deprecated and | ||||
Certification Authorities are encouraged to use the dNSName instead. | ||||
Matching is performed using the matching rules specified by | In general, a client MUST verify the service identity using the | |||
[RFC2459]. If more than one identity of a given type is present in | verification process defined in Section 6 of [RFC6125] (for a | |||
the certificate (e.g., more than one dNSName name, a match in any one | reference identifier of type URI-ID) unless the client has been | |||
of the set is considered acceptable.) Names may contain the wildcard | specifically configured to accept some other form of verification. | |||
character * which is considered to match any single domain name | For example, a client might be connecting to a server whose address | |||
component or component fragment. E.g., *.a.com matches foo.a.com but | and hostname are dynamic, with an expectation that the service will | |||
not bar.foo.a.com. f*.com matches foo.com but not bar.com. | present a specific certificate (or a certificate matching some | |||
In some cases, the URI is specified as an IP address rather than a | externally defined reference identity) rather than one matching the | |||
hostname. In this case, the iPAddress subjectAltName must be present | dynamic URI's origin server identifier. | |||
in the certificate and must exactly match the IP in the URI. | ||||
If the client has external information as to the expected identity of | ||||
the server, the hostname check MAY be omitted. | ||||
(For instance, a client may be connecting to a machine whose address | ||||
and hostname are dynamic but the client knows the certificate that | ||||
the server will present.) In such cases, it is important to narrow | ||||
the scope of acceptable certificates as much as possible in order | ||||
to prevent man in the middle attacks. | ||||
In special cases, it may be appropriate for the client to simply | In special cases, it might be appropriate for a client to simply | |||
ignore the server's identity, but it must be understood that this | ignore the server's identity, but it must be understood that this | |||
leaves the connection open to active attack. | leaves a connection open to active attack. | |||
If the hostname does not match the identity in the certificate, user | If the certificate is not valid for the URI's origin server, a user | |||
oriented clients MUST either notify the user (clients MAY give the | agent MUST either notify the user (user agents MAY give the user an | |||
user the opportunity to continue with the connection in any case) or | option to continue with the connection in any case) or terminate the | |||
terminate the connection with a bad certificate error. Automated | connection with a bad certificate error. Automated clients MUST log | |||
clients MUST log the error to an appropriate audit log (if available) | the error to an appropriate audit log (if available) and SHOULD | |||
and SHOULD terminate the connection (with a bad certificate error). | terminate the connection (with a bad certificate error). Automated | |||
Automated clients MAY provide a configuration setting that disables | clients MAY provide a configuration setting that disables this check, | |||
this check, but MUST provide a setting which enables it. | but MUST provide a setting which enables it. | |||
Note that in many cases the URI itself comes from an untrusted | ||||
source. The above-described check provides no protection against | ||||
attacks where this source is compromised. For example, if the URI was | ||||
obtained by clicking on an HTML page which was itself obtained | ||||
without using HTTP/TLS, a man in the middle could have replaced the | ||||
URI. In order to prevent this form of attack, users should carefully | ||||
examine the certificate presented by the server to determine if it | ||||
meets their expectations. | ||||
*3.2. Client Identity [paras squished together to anchor context]* | ||||
Typically, the server has no external knowledge of what the client's | ||||
identity ought to be and so checks (other than that the client has a | ||||
certificate chain rooted in an appropriate CA) are not possible. If a | ||||
server has such knowledge (typically from some source external to | ||||
HTTP or TLS) it SHOULD check the identity as described above. | ||||
5. Fields | 5. Fields | |||
Header fields are key:value pairs that can be used to communicate | HTTP uses _fields_ to provide data in the form of extensible key/ | |||
data about the message, its payload, the target resource, or the | value pairs with a registered key namespace. Fields are sent and | |||
connection (i.e., control data). See Section 3.2 of [RFC7230] for a | received within the header and trailer sections of messages | |||
general definition of header field syntax in HTTP messages. | (Section 6). | |||
5.1. Field Names | 5.1. Field Names | |||
The field-name token labels the corresponding field-value as having | A field name labels the corresponding field value as having the | |||
the semantics defined by that header field. For example, the Date | semantics defined by that name. For example, the Date header field | |||
header field is defined in Section 7.1.1.2 of [RFC7231] as containing | is defined in Section 10.2.2 as containing the origination timestamp | |||
the origination timestamp for the message in which it appears. | for the message in which it appears. | |||
field-name = token | field-name = token | |||
The requirements for header field names are defined in [BCP90]. | Field names are case-insensitive and ought to be registered within | |||
the "Hypertext Transfer Protocol (HTTP) Field Name Registry"; see | ||||
Section 16.3.1. | ||||
The interpretation of a header field does not change between minor versions | The interpretation of a field does not change between minor versions | |||
of the same major HTTP version, though the default behavior of a | of the same major HTTP version, though the default behavior of a | |||
recipient in the absence of such a field can change. Unless | recipient in the absence of such a field can change. Unless | |||
specified otherwise, header fields defined in HTTP/1.1 are defined | specified otherwise, fields are defined for all versions of HTTP. In | |||
for all versions of HTTP/1.x. In | particular, the Host and Connection fields ought to be recognized by | |||
particular, the Host and Connection header fields ought to be implemented by | all HTTP implementations whether or not they advertise conformance | |||
all HTTP/1.x implementations whether or not they advertise conformance | ||||
with HTTP/1.1. | with HTTP/1.1. | |||
New header fields can be introduced without changing the protocol version if | New fields can be introduced without changing the protocol version if | |||
their defined semantics allow them to be safely ignored by recipients | their defined semantics allow them to be safely ignored by recipients | |||
that do not recognize them. Header field extensibility is | that do not recognize them; see Section 16.3. | |||
discussed in Section 3.2.1. | ||||
A proxy MUST forward unrecognized header fields unless the field-name | A proxy MUST forward unrecognized header fields unless the field name | |||
is listed in the Connection header field (Section 6.1) or the proxy | is listed in the Connection header field (Section 7.6.1) or the proxy | |||
is specifically configured to block, or otherwise transform, such | is specifically configured to block, or otherwise transform, such | |||
fields. Other recipients SHOULD ignore unrecognized header fields. | fields. Other recipients SHOULD ignore unrecognized header and | |||
These requirements allow HTTP's functionality to be enhanced without | trailer fields. Adhering to these requirements allows HTTP's | |||
requiring prior update of deployed intermediaries. | functionality to be extended without updating or removing deployed | |||
intermediaries. | ||||
5.2. Field Lines and Combined Field Value | ||||
Field sections are composed of any number of _field lines_, each with | ||||
a _field name_ (see Section 5.1) identifying the field, and a _field | ||||
line value_ that conveys data for that instance of the field. | ||||
When a field name is only present once in a section, the combined | ||||
_field value_ for that field consists of the corresponding field line | ||||
value. When a field name is repeated within a section, its combined | ||||
field value consists of the list of corresponding field line values | ||||
within that section, concatenated in order, with each non-empty field | ||||
line value separated by a comma. | ||||
For example, this section: | ||||
Example-Field: Foo, Bar | ||||
Example-Field: Baz | ||||
contains two field lines, both with the field name "Example-Field". | ||||
The first field line has a field line value of "Foo, Bar", while the | ||||
second field line value is "Baz". The field value for "Example- | ||||
Field" is a list with three members: "Foo", "Bar", and "Baz". | ||||
5.3. Field Order | 5.3. Field Order | |||
A recipient MAY combine multiple header fields with the same field | A recipient MAY combine multiple field lines within a field section | |||
name into one "field-name: field-value" pair, without changing the | that have the same field name into one field line, without changing | |||
semantics of the message, by appending each subsequent field value to | the semantics of the message, by appending each subsequent field line | |||
the combined field value in order, separated by a comma. | value to the initial field line value in order, separated by a comma | |||
and OWS (optional whitespace). For consistency, use comma SP. | ||||
The order in which header fields with the same field name are received is | The order in which field lines with the same name are received is | |||
therefore significant to the interpretation of the combined field value; a | therefore significant to the interpretation of the field value; a | |||
proxy MUST NOT change the order of these field values when | proxy MUST NOT change the order of these field line values when | |||
forwarding a message. | forwarding a message. | |||
A sender MUST NOT generate multiple header fields with the same field | This means that, aside from the well-known exception noted below, a | |||
name in a message unless either the entire field value for that | sender MUST NOT generate multiple field lines with the same name in a | |||
header field is defined as a comma-separated list [i.e., #(values)] | message (whether in the headers or trailers), or append a field line | |||
or the header field is a well-known exception (as noted below). | when a field line of the same name already exists in the message, | |||
unless that field's definition allows multiple field line values to | ||||
be recombined as a comma-separated list [i.e., at least one | ||||
alternative of the field's definition allows a comma-separated list, | ||||
such as an ABNF rule of #(values) defined in Section 5.6.1]. | ||||
Note: In practice, the "Set-Cookie" header field ([RFC6265]) often | | *Note:* In practice, the "Set-Cookie" header field ([RFC6265]) | |||
appears multiple times in a response message and does not use the | | often appears in a response message across multiple field lines | |||
list syntax, violating the above requirements on multiple header | | and does not use the list syntax, violating the above | |||
fields with the same name. Since it cannot be combined into a | | requirements on multiple field lines with the same field name. | |||
single field-value, recipients ought to handle "Set-Cookie" as a | | Since it cannot be combined into a single field value, | |||
special case while processing header fields. (See Appendix A.2.3 | | recipients ought to handle "Set-Cookie" as a special case while | |||
of [Kri2001] for details.) | | processing fields. (See Appendix A.2.3 of [Kri2001] for | |||
| details.) | ||||
The order in which header fields with differing field names are | The order in which field lines with differing field names are | |||
received is not significant. However, it is good practice to send | received in a section is not significant. However, it is good | |||
header fields that contain control data first, such as Host on | practice to send header fields that contain additional control data | |||
requests and Date on responses, so that implementations can decide | first, such as Host on requests and Date on responses, so that | |||
when not to handle a message as early as possible. | implementations can decide when not to handle a message as early as | |||
possible. | ||||
A server MUST NOT apply a request to the target resource until the | A server MUST NOT apply a request to the target resource until the | |||
entire request header section is received, since later header fields | entire request header section is received, since later header field | |||
might include conditionals, authentication credentials, or | lines might include conditionals, authentication credentials, or | |||
deliberately misleading duplicate header fields that would impact | deliberately misleading duplicate header fields that would impact | |||
request processing. | request processing. | |||
5.4. Field Limits | 5.4. Field Limits | |||
HTTP does not place a predefined limit on the length of each header | HTTP does not place a predefined limit on the length of each field | |||
field or on the length of the header section as a whole, as described | line, field value, or on the length of a header or trailer section as | |||
in Section 2.5. Various ad hoc limitations on individual header | a whole, as described in Section 2. Various ad hoc limitations on | |||
field length are found in practice, often depending on the specific | individual lengths are found in practice, often depending on the | |||
field semantics. | specific field's semantics. | |||
A server that receives a request header field, or set of fields, | A server that receives a request header field line, field value, or | |||
larger than it wishes to process MUST respond with an appropriate 4xx | set of fields larger than it wishes to process MUST respond with an | |||
(Client Error) status code. Ignoring such header fields would | appropriate 4xx (Client Error) status code. Ignoring such header | |||
increase the server's vulnerability to request smuggling attacks | fields would increase the server's vulnerability to request smuggling | |||
(Section 9.5). | attacks (Section 11.2 of [Messaging]). | |||
A client MAY discard or truncate received header fields that are | A client MAY discard or truncate received field lines that are larger | |||
larger than the client wishes to process if the field semantics are | than the client wishes to process if the field semantics are such | |||
such that the dropped value(s) can be safely ignored without changing | that the dropped value(s) can be safely ignored without changing the | |||
the message framing or response semantics. | message framing or response semantics. | |||
5.5. Field Values | 5.5. Field Values | |||
New header field values typically have their syntax defined using | HTTP field values typically have their syntax defined using ABNF | |||
ABNF ([RFC5234]), using the extension defined in Section 7 of | ([RFC5234]), using the extension defined in Section 5.6.1 as | |||
[RFC7230] as necessary, and are usually constrained to the range of | necessary, and are usually constrained to the range of US-ASCII | |||
US-ASCII characters. Header fields needing a greater range of | characters. Fields needing a greater range of characters can use an | |||
characters can use an encoding such as the one defined in [RFC5987]. | encoding such as the one defined in [RFC8187]. | |||
field-value = *( field-content / obs-fold ) | field-value = *field-content | |||
field-content = field-vchar [ 1*( SP / HTAB ) field-vchar ] | field-content = field-vchar | |||
[ 1*( SP / HTAB / field-vchar ) field-vchar ] | ||||
field-vchar = VCHAR / obs-text | field-vchar = VCHAR / obs-text | |||
Historically, HTTP has allowed field content with text in the | Historically, HTTP allowed field content with text in the ISO-8859-1 | |||
ISO-8859-1 charset [ISO-8859-1], supporting other charsets only | charset [ISO-8859-1], supporting other charsets only through use of | |||
through use of [RFC2047] encoding. In practice, most HTTP header | [RFC2047] encoding. In practice, most HTTP field values use only a | |||
field values use only a subset of the US-ASCII charset [USASCII]. | subset of the US-ASCII charset [USASCII]. Newly defined fields | |||
Newly defined header fields SHOULD limit their field values to | SHOULD limit their values to US-ASCII octets. A recipient SHOULD | |||
US-ASCII octets. A recipient SHOULD treat other octets in field | treat other octets in field content (obs-text) as opaque data. | |||
content (obs-text) as opaque data. | ||||
Field values containing control (CTL) characters such as CR or LF are | ||||
invalid; recipients MUST either reject a field value containing | ||||
control characters, or convert them to SP before processing or | ||||
forwarding the message. | ||||
Leading and trailing whitespace in raw field values is removed upon | Leading and trailing whitespace in raw field values is removed upon | |||
field parsing (Section 3.2.4 of [RFC7230]). Field definitions where | field parsing (e.g., Section 5.1 of [Messaging]). Field definitions | |||
leading or trailing whitespace in values is significant will have to | where leading or trailing whitespace in values is significant will | |||
use a container syntax such as quoted-string (Section 3.2.6 of | have to use a container syntax such as quoted-string (Section 5.6.4). | |||
[RFC7230]). | ||||
[new] | Commas (",") often are used to separate members in field values. | |||
Fields that allow multiple members are referred to as _list-based | ||||
fields_. Fields that only anticipate a single member are referred to | ||||
as _singleton fields_. | ||||
Because commas (",") are used as a generic delimiter between | Because commas are used as a generic delimiter between members, they | |||
field-values, they need to be treated with care if they are allowed | need to be treated with care if they are allowed as data within a | |||
in the field-value. Typically, components that might contain a comma | member. This is true for both list-based and singleton fields, since | |||
are protected with double-quotes using the quoted-string ABNF | a singleton field might be sent with multiple members erroneously; | |||
production. | being able to detect this condition improves interoperability. | |||
Fields that expect to contain a comma within a member, such as an | ||||
HTTP-date or URI-reference element, ought to be defined with | ||||
delimiters around that element to distinguish any comma within that | ||||
data from potential list separators. | ||||
For example, a textual date and a URI (either of which might contain | For example, a textual date and a URI (either of which might contain | |||
a comma) could be safely carried in field-values like these: | a comma) could be safely carried in list-based field values like | |||
these: | ||||
Example-URI-Field: "http://example.com/a.html,foo", | Example-URI-Field: "http://example.com/a.html,foo", | |||
"http://without-a-comma.example.com/" | "http://without-a-comma.example.com/" | |||
Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005" | Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005" | |||
Note that double-quote delimiters almost always are used with the | Note that double-quote delimiters almost always are used with the | |||
quoted-string production; using a different syntax inside | quoted-string production; using a different syntax inside double- | |||
double-quotes will likely cause unnecessary confusion. | quotes will likely cause unnecessary confusion. | |||
Many header fields use a format including (case-insensitively) named | Many fields (such as Content-Type, defined in Section 8.3) use a | |||
parameters (for instance, Content-Type, defined in Section 3.1.1.5). | common syntax for parameters that allows both unquoted (token) and | |||
Allowing both unquoted (token) and quoted (quoted-string) syntax for | quoted (quoted-string) syntax for a parameter value (Section 5.6.6). | |||
the parameter value enables recipients to use existing parser | Use of common syntax allows recipients to reuse existing parser | |||
components. When allowing both forms, the meaning of a parameter | components. When allowing both forms, the meaning of a parameter | |||
value ought to be independent of the syntax used for it (for an | value ought to be the same whether it was received as a token or a | |||
example, see the notes on parameter handling for media types in | quoted string. | |||
Section 3.1.1.1). | ||||
Historically, HTTP header field values could be extended over | Historically, HTTP field values could be extended over multiple lines | |||
multiple lines by preceding each extra line with at least one space | by preceding each extra line with at least one space or horizontal | |||
or horizontal tab (obs-fold). | tab (obs-fold). This document assumes that any such obsolete line | |||
folding has been replaced with one or more SP octets prior to | ||||
interpreting the field value, as described in Section 5.2 of | ||||
[Messaging]. | ||||
Consequently, this specification does not use ABNF rules | | *Note:* This specification does not use ABNF rules to define | |||
to define each "Field-Name: Field Value" pair, as was done in | | each "Field Name: Field Value" pair, as was done in earlier | |||
previous editions. Instead, this specification uses ABNF rules that | | editions (published before [RFC7230]). Instead, ABNF rules are | |||
are named according to each registered field name, wherein the rule | | named according to each registered field name, wherein the rule | |||
defines the valid grammar for that field's corresponding field values | | defines the valid grammar for that field's corresponding field | |||
(i.e., after the field-value has been extracted from the header | | values (i.e., after the field value has been extracted by a | |||
section by a generic field parser). | | generic field parser). | |||
5.6. Field Value Components | 5.6. Common Rules for Defining Field Values | |||
5.6.1. ABNF List Extension: #rule | 5.6.1. Lists (#rule ABNF Extension) | |||
A #rule extension to the ABNF rules of [RFC5234] is used to improve | A #rule extension to the ABNF rules of [RFC5234] is used to improve | |||
readability in the definitions of some header field values. | readability in the definitions of some list-based field values. | |||
A construct "#" is defined, similar to "*", for defining | A construct "#" is defined, similar to "*", for defining comma- | |||
comma-delimited lists of elements. The full form is "<n>#<m>element" | delimited lists of elements. The full form is "<n>#<m>element" | |||
indicating at least <n> and at most <m> elements, each separated by a | indicating at least <n> and at most <m> elements, each separated by a | |||
single comma (",") and optional whitespace (OWS). | single comma (",") and optional whitespace (OWS). | |||
5.6.1.1. Sender Requirements | 5.6.1.1. Sender Requirements | |||
In any production that uses the list construct, a sender MUST NOT | In any production that uses the list construct, a sender MUST NOT | |||
generate empty list elements. In other words, a sender MUST generate | generate empty list elements. In other words, a sender MUST generate | |||
lists that satisfy the following syntax: | lists that satisfy the following syntax: | |||
1#element => element *( OWS "," OWS element ) | 1#element => element *( OWS "," OWS element ) | |||
and: | and: | |||
#element => [ 1#element ] | #element => [ 1#element ] | |||
and for n >= 1 and m > 1: | and for n >= 1 and m > 1: | |||
<n>#<m>element => element <n-1>*<m-1>( OWS "," OWS element ) | <n>#<m>element => element <n-1>*<m-1>( OWS "," OWS element ) | |||
Appendix B shows the collected ABNF for recipients after the list | Appendix A shows the collected ABNF for senders after the list | |||
constructs have been expanded. | constructs have been expanded. | |||
5.6.1.2. Recipient Requirements | 5.6.1.2. Recipient Requirements | |||
For compatibility with legacy list rules, a | Empty elements do not contribute to the count of elements present. A | |||
recipient MUST parse and ignore a reasonable number of empty list | recipient MUST parse and ignore a reasonable number of empty list | |||
elements: enough to handle common mistakes by senders that merge | elements: enough to handle common mistakes by senders that merge | |||
values, but not so much that they could be used as a denial-of- | values, but not so much that they could be used as a denial-of- | |||
service mechanism. In other words, a recipient MUST accept lists | service mechanism. In other words, a recipient MUST accept lists | |||
that satisfy the following syntax: | that satisfy the following syntax: | |||
#element => [ ( "," / element ) *( OWS "," [ OWS element ] ) ] | #element => [ element ] *( OWS "," OWS [ element ] ) | |||
1#element => *( "," OWS ) element *( OWS "," [ OWS element ] ) | ||||
Empty elements do not contribute to the count of elements present. | Note that because of the potential presence of empty list elements, | |||
the RFC 5234 ABNF cannot enforce the cardinality of list elements, | ||||
and consequently all cases are mapped as if there was no cardinality | ||||
specified. | ||||
For example, given these ABNF productions: | For example, given these ABNF productions: | |||
example-list = 1#example-list-elmt | example-list = 1#example-list-elmt | |||
example-list-elmt = token ; see Section 3.2.6 | example-list-elmt = token ; see Section 5.6.2 | |||
Then the following are valid values for example-list (not including | Then the following are valid values for example-list (not including | |||
the double quotes, which are present for delimitation only): | the double quotes, which are present for delimitation only): | |||
"foo,bar" | "foo,bar" | |||
"foo ,bar," | "foo ,bar," | |||
"foo , ,bar,charlie " | "foo , ,bar,charlie" | |||
In contrast, the following values would be invalid, since at least | In contrast, the following values would be invalid, since at least | |||
one non-empty element is required by the example-list production: | one non-empty element is required by the example-list production: | |||
"" | "" | |||
"," | "," | |||
", ," | ", ," | |||
5.6.2. Tokens | 5.6.2. Tokens | |||
Most HTTP header field values are defined using common syntax | Many HTTP field values are defined using common syntax components, | |||
components (token, quoted-string, and comment) separated by | separated by whitespace or specific delimiting characters. | |||
whitespace or specific delimiting characters. Delimiters are chosen | Delimiters are chosen from the set of US-ASCII visual characters not | |||
from the set of US-ASCII visual characters not allowed in a token | allowed in a token (DQUOTE and "(),/:;<=>?@[\]{}"). | |||
(DQUOTE and "(),/:;<=>?@[\]{}"). | ||||
Tokens are short textual identifiers that do not include whitespace | ||||
or delimiters. | ||||
token = 1*tchar | token = 1*tchar | |||
tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" | tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" | |||
/ "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" | / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" | |||
/ DIGIT / ALPHA | / DIGIT / ALPHA | |||
; any VCHAR, except delimiters | ; any VCHAR, except delimiters | |||
5.6.3. Whitespace | 5.6.3. Whitespace | |||
skipping to change at line 1347 ¶ | skipping to change at page 37, line 9 ¶ | |||
might appear. For protocol elements where optional whitespace is | might appear. For protocol elements where optional whitespace is | |||
preferred to improve readability, a sender SHOULD generate the | preferred to improve readability, a sender SHOULD generate the | |||
optional whitespace as a single SP; otherwise, a sender SHOULD NOT | optional whitespace as a single SP; otherwise, a sender SHOULD NOT | |||
generate optional whitespace except as needed to white out invalid or | generate optional whitespace except as needed to white out invalid or | |||
unwanted protocol elements during in-place message filtering. | unwanted protocol elements during in-place message filtering. | |||
The RWS rule is used when at least one linear whitespace octet is | The RWS rule is used when at least one linear whitespace octet is | |||
required to separate field tokens. A sender SHOULD generate RWS as a | required to separate field tokens. A sender SHOULD generate RWS as a | |||
single SP. | single SP. | |||
OWS and RWS have the same semantics as a single SP. Any content | ||||
known to be defined as OWS or RWS MAY be replaced with a single SP | ||||
before interpreting it or forwarding the message downstream. | ||||
The BWS rule is used where the grammar allows optional whitespace | The BWS rule is used where the grammar allows optional whitespace | |||
only for historical reasons. A sender MUST NOT generate BWS in | only for historical reasons. A sender MUST NOT generate BWS in | |||
messages. A recipient MUST parse for such bad whitespace and remove | messages. A recipient MUST parse for such bad whitespace and remove | |||
it before interpreting the protocol element. | it before interpreting the protocol element. | |||
BWS has no semantics. Any content known to be defined as BWS MAY be | ||||
removed before interpreting it or forwarding the message downstream. | ||||
OWS = *( SP / HTAB ) | OWS = *( SP / HTAB ) | |||
; optional whitespace | ; optional whitespace | |||
RWS = 1*( SP / HTAB ) | RWS = 1*( SP / HTAB ) | |||
; required whitespace | ; required whitespace | |||
BWS = OWS | BWS = OWS | |||
; "bad" whitespace | ; "bad" whitespace | |||
5.6.4. Quoted Strings | 5.6.4. Quoted Strings | |||
A string of text is parsed as a single value if it is quoted using | A string of text is parsed as a single value if it is quoted using | |||
double-quote marks. | double-quote marks. | |||
quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE | quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE | |||
qdtext = HTAB / SP /%x21 / %x23-5B / %x5D-7E / obs-text | qdtext = HTAB / SP / %x21 / %x23-5B / %x5D-7E / obs-text | |||
obs-text = %x80-FF | obs-text = %x80-FF | |||
The backslash octet ("\") can be used as a single-octet quoting | The backslash octet ("\") can be used as a single-octet quoting | |||
mechanism within quoted-string and comment constructs. Recipients | mechanism within quoted-string and comment constructs. Recipients | |||
that process the value of a quoted-string MUST handle a quoted-pair | that process the value of a quoted-string MUST handle a quoted-pair | |||
as if it were replaced by the octet following the backslash. | as if it were replaced by the octet following the backslash. | |||
quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) | quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) | |||
A sender SHOULD NOT generate a quoted-pair in a quoted-string except | A sender SHOULD NOT generate a quoted-pair in a quoted-string except | |||
where necessary to quote DQUOTE and backslash octets occurring within | where necessary to quote DQUOTE and backslash octets occurring within | |||
that string. A sender SHOULD NOT generate a quoted-pair in a comment | that string. A sender SHOULD NOT generate a quoted-pair in a comment | |||
except where necessary to quote parentheses ["(" and ")"] and | except where necessary to quote parentheses ["(" and ")"] and | |||
backslash octets occurring within that comment. | backslash octets occurring within that comment. | |||
5.6.5. Comments | 5.6.5. Comments | |||
Comments can be included in some HTTP header fields by surrounding | Comments can be included in some HTTP fields by surrounding the | |||
the comment text with parentheses. Comments are only allowed in | comment text with parentheses. Comments are only allowed in fields | |||
fields containing "comment" as part of their field value definition. | containing "comment" as part of their field value definition. | |||
comment = "(" *( ctext / quoted-pair / comment ) ")" | comment = "(" *( ctext / quoted-pair / comment ) ")" | |||
ctext = HTAB / SP / %x21-27 / %x2A-5B / %x5D-7E / obs-text | ctext = HTAB / SP / %x21-27 / %x2A-5B / %x5D-7E / obs-text | |||
5.6.6. Parameters | 5.6.6. Parameters | |||
[new] | Parameters are instances of name=value pairs; they are often used in | |||
field values as a common syntax for appending auxiliary information | ||||
to an item. Each parameter is usually delimited by an immediately | ||||
preceding semicolon. | ||||
parameter = token "=" ( token / quoted-string ) | parameters = *( OWS ";" OWS [ parameter ] ) | |||
parameter = parameter-name "=" parameter-value | ||||
parameter-name = token | ||||
parameter-value = ( token / quoted-string ) | ||||
The parameter name tokens are case-insensitive. | Parameter names are case-insensitive. Parameter values might or | |||
Parameter values might or might not be case-sensitive, depending on | might not be case-sensitive, depending on the semantics of the | |||
the semantics of the parameter name. | parameter name. Examples of parameters and some equivalent forms can | |||
be seen in media types (Section 8.3.1) and the Accept header field | ||||
(Section 12.5.1). | ||||
A parameter value that matches the token production can be | A parameter value that matches the token production can be | |||
transmitted either as a token or within a quoted-string. The quoted | transmitted either as a token or within a quoted-string. The quoted | |||
and unquoted values are equivalent. | and unquoted values are equivalent. | |||
Note: Unlike some similar constructs in other header fields, media | | *Note:* Parameters do not allow whitespace (not even "bad" | |||
type parameters do not allow whitespace (even "bad" whitespace) | | whitespace) around the "=" character. | |||
around the "=" character. | ||||
5.6.7. Date/Time Formats | 5.6.7. Date/Time Formats | |||
Prior to 1995, there were three different formats commonly used by | Prior to 1995, there were three different formats commonly used by | |||
servers to communicate timestamps. For compatibility with old | servers to communicate timestamps. For compatibility with old | |||
implementations, all three are defined here. The preferred format is | implementations, all three are defined here. The preferred format is | |||
a fixed-length and single-zone subset of the date and time | a fixed-length and single-zone subset of the date and time | |||
specification used by the Internet Message Format [RFC5322]. | specification used by the Internet Message Format [RFC5322]. | |||
HTTP-date = IMF-fixdate / obs-date | HTTP-date = IMF-fixdate / obs-date | |||
An example of the preferred format is | An example of the preferred format is | |||
Sun, 06 Nov 1994 08:49:37 GMT ; IMF-fixdate | Sun, 06 Nov 1994 08:49:37 GMT ; IMF-fixdate | |||
Examples of the two obsolete formats are | Examples of the two obsolete formats are | |||
Sunday, 06-Nov-94 08:49:37 GMT ; obsolete RFC 850 format | Sunday, 06-Nov-94 08:49:37 GMT ; obsolete RFC 850 format | |||
Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format | Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format | |||
A recipient that parses a timestamp value in an HTTP header field | A recipient that parses a timestamp value in an HTTP field MUST | |||
MUST accept all three HTTP-date formats. When a sender generates a | accept all three HTTP-date formats. When a sender generates a field | |||
header field that contains one or more timestamps defined as | that contains one or more timestamps defined as HTTP-date, the sender | |||
HTTP-date, the sender MUST generate those timestamps in the | MUST generate those timestamps in the IMF-fixdate format. | |||
IMF-fixdate format. | ||||
An HTTP-date value represents time as an instance of Coordinated | An HTTP-date value represents time as an instance of Coordinated | |||
Universal Time (UTC). The first two formats indicate UTC by the | Universal Time (UTC). The first two formats indicate UTC by the | |||
three-letter abbreviation for Greenwich Mean Time, "GMT", a | three-letter abbreviation for Greenwich Mean Time, "GMT", a | |||
predecessor of the UTC name; values in the asctime format are assumed | predecessor of the UTC name; values in the asctime format are assumed | |||
to be in UTC. A sender that generates HTTP-date values from a local | to be in UTC. A sender that generates HTTP-date values from a local | |||
clock ought to use NTP ([RFC5905]) or some similar protocol to | clock ought to use NTP ([RFC5905]) or some similar protocol to | |||
synchronize its clock to UTC. | synchronize its clock to UTC. | |||
Preferred format: | Preferred format: | |||
IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT | IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT | |||
; fixed length/zone/capitalization subset of the format | ; fixed length/zone/capitalization subset of the format | |||
; see Section 3.3 of [RFC5322] | ; see Section 3.3 of [RFC5322] | |||
day-name = %x4D.6F.6E ; "Mon", case-sensitive | day-name = %s"Mon" / %s"Tue" / %s"Wed" | |||
/ %x54.75.65 ; "Tue", case-sensitive | / %s"Thu" / %s"Fri" / %s"Sat" / %s"Sun" | |||
/ %x57.65.64 ; "Wed", case-sensitive | ||||
/ %x54.68.75 ; "Thu", case-sensitive | ||||
/ %x46.72.69 ; "Fri", case-sensitive | ||||
/ %x53.61.74 ; "Sat", case-sensitive | ||||
/ %x53.75.6E ; "Sun", case-sensitive | ||||
date1 = day SP month SP year | date1 = day SP month SP year | |||
; e.g., 02 Jun 1982 | ; e.g., 02 Jun 1982 | |||
day = 2DIGIT | day = 2DIGIT | |||
month = %x4A.61.6E ; "Jan", case-sensitive | month = %s"Jan" / %s"Feb" / %s"Mar" / %s"Apr" | |||
/ %x46.65.62 ; "Feb", case-sensitive | / %s"May" / %s"Jun" / %s"Jul" / %s"Aug" | |||
/ %x4D.61.72 ; "Mar", case-sensitive | / %s"Sep" / %s"Oct" / %s"Nov" / %s"Dec" | |||
/ %x41.70.72 ; "Apr", case-sensitive | ||||
/ %x4D.61.79 ; "May", case-sensitive | ||||
/ %x4A.75.6E ; "Jun", case-sensitive | ||||
/ %x4A.75.6C ; "Jul", case-sensitive | ||||
/ %x41.75.67 ; "Aug", case-sensitive | ||||
/ %x53.65.70 ; "Sep", case-sensitive | ||||
/ %x4F.63.74 ; "Oct", case-sensitive | ||||
/ %x4E.6F.76 ; "Nov", case-sensitive | ||||
/ %x44.65.63 ; "Dec", case-sensitive | ||||
year = 4DIGIT | year = 4DIGIT | |||
GMT = %x47.4D.54 ; "GMT", case-sensitive | GMT = %s"GMT" | |||
time-of-day = hour ":" minute ":" second | time-of-day = hour ":" minute ":" second | |||
; 00:00:00 - 23:59:60 (leap second) | ; 00:00:00 - 23:59:60 (leap second) | |||
hour = 2DIGIT | hour = 2DIGIT | |||
minute = 2DIGIT | minute = 2DIGIT | |||
second = 2DIGIT | second = 2DIGIT | |||
Obsolete formats: | Obsolete formats: | |||
skipping to change at line 1485 ¶ | skipping to change at page 40, line 4 ¶ | |||
time-of-day = hour ":" minute ":" second | time-of-day = hour ":" minute ":" second | |||
; 00:00:00 - 23:59:60 (leap second) | ; 00:00:00 - 23:59:60 (leap second) | |||
hour = 2DIGIT | hour = 2DIGIT | |||
minute = 2DIGIT | minute = 2DIGIT | |||
second = 2DIGIT | second = 2DIGIT | |||
Obsolete formats: | Obsolete formats: | |||
obs-date = rfc850-date / asctime-date | obs-date = rfc850-date / asctime-date | |||
rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT | rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT | |||
date2 = day "-" month "-" 2DIGIT | date2 = day "-" month "-" 2DIGIT | |||
; e.g., 02-Jun-82 | ; e.g., 02-Jun-82 | |||
day-name-l = %x4D.6F.6E.64.61.79 ; "Monday", case-sensitive | day-name-l = %s"Monday" / %s"Tuesday" / %s"Wednesday" | |||
/ %x54.75.65.73.64.61.79 ; "Tuesday", case-sensitive | / %s"Thursday" / %s"Friday" / %s"Saturday" | |||
/ %x57.65.64.6E.65.73.64.61.79 ; "Wednesday", case-sensitive | / %s"Sunday" | |||
/ %x54.68.75.72.73.64.61.79 ; "Thursday", case-sensitive | ||||
/ %x46.72.69.64.61.79 ; "Friday", case-sensitive | ||||
/ %x53.61.74.75.72.64.61.79 ; "Saturday", case-sensitive | ||||
/ %x53.75.6E.64.61.79 ; "Sunday", case-sensitive | ||||
asctime-date = day-name SP date3 SP time-of-day SP year | asctime-date = day-name SP date3 SP time-of-day SP year | |||
date3 = month SP ( 2DIGIT / ( SP 1DIGIT )) | date3 = month SP ( 2DIGIT / ( SP 1DIGIT )) | |||
; e.g., Jun 2 | ; e.g., Jun 2 | |||
HTTP-date is case sensitive. A sender MUST NOT generate additional | HTTP-date is case sensitive. Note that Section 4.2 of [Caching] | |||
whitespace in an HTTP-date beyond that specifically included as SP in | relaxes this for cache recipients. | |||
the grammar. The semantics of day-name, day, month, year, and | ||||
time-of-day are the same as those defined for the Internet Message | A sender MUST NOT generate additional whitespace in an HTTP-date | |||
Format constructs with the corresponding name ([RFC5322], Section | beyond that specifically included as SP in the grammar. The | |||
3.3). | semantics of day-name, day, month, year, and time-of-day are the same | |||
as those defined for the Internet Message Format constructs with the | ||||
corresponding name ([RFC5322], Section 3.3). | ||||
Recipients of a timestamp value in rfc850-date format, which uses a | Recipients of a timestamp value in rfc850-date format, which uses a | |||
two-digit year, MUST interpret a timestamp that appears to be more | two-digit year, MUST interpret a timestamp that appears to be more | |||
than 50 years in the future as representing the most recent year in | than 50 years in the future as representing the most recent year in | |||
the past that had the same last two digits. | the past that had the same last two digits. | |||
Recipients of timestamp values are encouraged to be robust in parsing | Recipients of timestamp values are encouraged to be robust in parsing | |||
timestamps unless otherwise restricted by the field definition. For | timestamps unless otherwise restricted by the field definition. For | |||
example, messages are occasionally forwarded over HTTP from a | example, messages are occasionally forwarded over HTTP from a non- | |||
non-HTTP source that might generate any of the date and time | HTTP source that might generate any of the date and time | |||
specifications defined by the Internet Message Format. | specifications defined by the Internet Message Format. | |||
Note: HTTP requirements for the date/time stamp format apply only | | *Note:* HTTP requirements for the date/time stamp format apply | |||
to their usage within the protocol stream. Implementations are | | only to their usage within the protocol stream. | |||
not required to use these formats for user presentation, request | | Implementations are not required to use these formats for user | |||
logging, etc. | | presentation, request logging, etc. | |||
6. Message Abstraction | 6. Message Abstraction | |||
[new] | Each major version of HTTP defines its own syntax for communicating | |||
messages. This section defines an abstract data type for HTTP | ||||
messages based on a generalization of those message characteristics, | ||||
common structure, and capacity for conveying semantics. This | ||||
abstraction is used to define requirements on senders and recipients | ||||
that are independent of the HTTP version, such that a message in one | ||||
version can be relayed through other versions without changing its | ||||
meaning. | ||||
A _message_ consists of control data to describe and route the | ||||
message, a headers lookup table of key/value pairs for extending that | ||||
control data and conveying additional information about the sender, | ||||
message, content, or context, a potentially unbounded stream of | ||||
content, and a trailers lookup table of key/value pairs for | ||||
communicating information obtained while sending the content. | ||||
Framing and control data is sent first, followed by a header section | ||||
containing fields for the headers table. When a message includes | ||||
content, the content is sent after the header section and potentially | ||||
interleaved with zero or more trailer sections containing fields for | ||||
the trailers table. | ||||
Messages are expected to be processed as a stream, wherein the | ||||
purpose of that stream and its continued processing is revealed while | ||||
being read. Hence, control data describes what the recipient needs | ||||
to know immediately, header fields describe what needs to be known | ||||
before receiving content, the content (when present) presumably | ||||
contains what the recipient wants or needs to fulfill the message | ||||
semantics, and trailer fields provide additional metadata that can be | ||||
dropped (safely ignored) when not desired. | ||||
Messages are intended to be _self-descriptive_: everything a | ||||
recipient needs to know about the message can be determined by | ||||
looking at the message itself, after decoding or reconstituting parts | ||||
that have been compressed or elided in transit, without requiring an | ||||
understanding of the sender's current application state (established | ||||
via prior messages). | ||||
Note that this message abstraction is a generalization across many | ||||
versions of HTTP, including features that might not be found in some | ||||
versions. For example, trailers were introduced within the HTTP/1.1 | ||||
chunked transfer coding as a single trailer section after the | ||||
content. An equivalent feature is present in HTTP/2 and HTTP/3 | ||||
within the header block that terminates each stream. However, | ||||
multiple trailer sections interleaved with content have only been | ||||
deployed as frame extensions. | ||||
6.1. Framing and Completeness | 6.1. Framing and Completeness | |||
[new] | Message framing indicates how each message begins and ends, such that | |||
each message can be distinguished from other messages or noise on the | ||||
same connection. Each major version of HTTP defines its own framing | ||||
mechanism. | ||||
[new] | HTTP/0.9 and early deployments of HTTP/1.0 used closure of the | |||
underlying connection to end a response. For backwards | ||||
compatibility, this implicit framing is also allowed in HTTP/1.1. | ||||
However, implicit framing can fail to distinguish an incomplete | ||||
response if the connection closes early. For that reason, almost all | ||||
modern implementations use explicit framing in the form of length- | ||||
delimited sequences of message data. | ||||
A message is considered _complete_ when all of the octets indicated | ||||
by its framing are available. Note that, when no explicit framing is | ||||
used, a response message that is ended by the underlying connection's | ||||
close is considered complete even though it might be | ||||
indistinguishable from an incomplete response, unless a transport- | ||||
level error indicates that it is not complete. | ||||
6.2. Control Data | 6.2. Control Data | |||
HTTP communication is initiated by a user agent for some purpose. | Messages start with control data that describe its primary purpose. | |||
The purpose is a combination of request semantics, which are defined | Request message control data includes a request method (Section 9), | |||
in [RFC7231], and a target resource upon which to apply those | request target (Section 7.1), and protocol version (Section 2.5). | |||
semantics. | Response message control data includes a status code (Section 15), | |||
optional reason phrase, and protocol version. | ||||
In HTTP/1.1 [Messaging] and earlier, control data is sent as the | ||||
first line of a message. In HTTP/2 ([RFC7540]) and HTTP/3 ([HTTP3]), | ||||
control data is sent as pseudo-header fields with a reserved name | ||||
prefix (e.g., ":authority"). | ||||
Every HTTP message has a protocol version. Depending on the version | ||||
in use, it might be identified within the message explicitly or | ||||
inferred by the connection over which the message is received. | ||||
Recipients use that version information to determine limitations or | ||||
potential for later communication with that sender. | ||||
When a message is forwarded by an intermediary, the protocol version | ||||
is updated to reflect the version used by that intermediary. The Via | ||||
header field (Section 7.6.3) is used to communicate upstream protocol | ||||
information within a forwarded message. | ||||
A client SHOULD send a request version equal to the highest version | A client SHOULD send a request version equal to the highest version | |||
to which the client is conformant and whose major version is no | to which the client is conformant and whose major version is no | |||
higher than the highest version supported by the server, if this is | higher than the highest version supported by the server, if this is | |||
known. A client MUST NOT send a version to which it is not | known. A client MUST NOT send a version to which it is not | |||
conformant. | conformant. | |||
A client MAY send a lower request version if it is known that the | A client MAY send a lower request version if it is known that the | |||
server incorrectly implements the HTTP specification, but only after | server incorrectly implements the HTTP specification, but only after | |||
the client has attempted at least one normal request and determined | the client has attempted at least one normal request and determined | |||
skipping to change at line 1573 ¶ | skipping to change at page 43, line 24 ¶ | |||
recipient implements, the recipient SHOULD process the message as if | recipient implements, the recipient SHOULD process the message as if | |||
it were in the highest minor version within that major version to | it were in the highest minor version within that major version to | |||
which the recipient is conformant. A recipient can assume that a | which the recipient is conformant. A recipient can assume that a | |||
message with a higher minor version, when sent to a recipient that | message with a higher minor version, when sent to a recipient that | |||
has not yet indicated support for that higher version, is | has not yet indicated support for that higher version, is | |||
sufficiently backwards-compatible to be safely processed by any | sufficiently backwards-compatible to be safely processed by any | |||
implementation of the same major version. | implementation of the same major version. | |||
6.3. Header Fields | 6.3. Header Fields | |||
[new] | Fields (Section 5) that are sent/received before the content are | |||
referred to as "header fields" (or just "headers", colloquially). | ||||
The _header section_ of a message consists of a sequence of of header | ||||
field lines. Each header field might modify or extend message | ||||
semantics, describe the sender, define the content, or provide | ||||
additional context. | ||||
| *Note:* We refer to named fields specifically as a "header | ||||
| field" when they are only allowed to be sent in the header | ||||
| section. | ||||
6.4. Content | 6.4. Content | |||
Some HTTP messages transfer a complete or partial representation as | HTTP messages often transfer a complete or partial representation as | |||
the message "payload". In some cases, a payload might contain only | the message _content_: a stream of octets sent after the header | |||
the associated representation's header fields (e.g., responses to | section, as delineated by the message framing. | |||
HEAD) or only some part(s) of the representation data (e.g., the 206 | ||||
(Partial Content) status code). | ||||
[new] | This abstract definition of content reflects the data after it has | |||
been extracted from the message framing. For example, an HTTP/1.1 | ||||
message body (Section 6 of [Messaging]) might consist of a stream of | ||||
data encoded with the chunked transfer coding - a sequence of data | ||||
chunks, one zero-length chunk, and a trailer section - whereas the | ||||
content of that same message includes only the data stream after the | ||||
transfer coding has been decoded; it does not include the chunk | ||||
lengths, chunked framing syntax, nor the trailer fields | ||||
(Section 6.5). | ||||
6.4.1. Content Semantics | 6.4.1. Content Semantics | |||
The purpose of a payload in a request is defined by the method | The purpose of content in a request is defined by the method | |||
semantics. | semantics (Section 9). | |||
For example, a representation in the payload of a PUT request | For example, a representation in the content of a PUT request | |||
(Section 4.3.4) represents the desired state of the target resource | (Section 9.3.4) represents the desired state of the target resource | |||
if the request is successfully applied, whereas a representation | after the request is successfully applied, whereas a representation | |||
in the payload of a POST request (Section 4.3.3) represents | in the content of a POST request (Section 9.3.3) represents | |||
information to be processed by the target resource. | information to be processed by the target resource. | |||
In a response, the payload's purpose is defined by both the request | In a response, the content's purpose is defined by both the request | |||
method and the response status code. For example, the payload of a | method and the response status code (Section 15). For example, the | |||
200 (OK) response to GET (Section 4.3.1) represents the current state | content of a 200 (OK) response to GET (Section 9.3.1) represents the | |||
of the target resource, as observed at the time of the message | current state of the target resource, as observed at the time of the | |||
origination date (Section 7.1.1.2), whereas the payload of the same | message origination date (Section 10.2.2), whereas the content of the | |||
status code in a response to POST might represent either the | same status code in a response to POST might represent either the | |||
processing result or the new state of the target resource after | processing result or the new state of the target resource after | |||
applying the processing. | applying the processing. | |||
Response messages with an error status code usually contain a payload | The content of a 206 (Partial Content) response to GET contains | |||
that represents the error condition, such that it describes | either a single part of the selected representation or a multipart | |||
the error state and what next steps are suggested for resolving it. | message body containing multiple parts of that representation, as | |||
described in Section 15.3.7. | ||||
Responses to the HEAD request method (Section 4.3.2 | Response messages with an error status code usually contain content | |||
of [RFC7231]) never include a message body because the associated | that represents the error condition, such that the content describes | |||
response header fields (e.g., Transfer-Encoding, Content-Length, | the error state and what steps are suggested for resolving it. | |||
etc.), if present, indicate only what their values would have been if | ||||
the request method had been GET (Section 4.3.1 of [RFC7231]). | Responses to the HEAD request method (Section 9.3.2) never include | |||
content; the associated response header fields indicate only what | ||||
their values would have been if the request method had been GET | ||||
(Section 9.3.1). | ||||
2xx (Successful) responses to a CONNECT request method | 2xx (Successful) responses to a CONNECT request method | |||
(Section 4.3.6 of [RFC7231]) switch to tunnel mode instead of | (Section 9.3.6) switch the connection to tunnel mode instead of | |||
having a message body. | having content. | |||
All 1xx (Informational), 204 (No Content), and 304 (Not Modified) | All 1xx (Informational), 204 (No Content), and 304 (Not Modified) | |||
responses do not include a message body. | responses do not include content. | |||
All other responses do include a message body, although the body | All other responses do include content, although that content might | |||
might be of zero length. | be of zero length. | |||
6.4.2. Identifying Content | 6.4.2. Identifying Content | |||
When a complete or partial representation is transferred in a message | When a complete or partial representation is transferred as message | |||
payload, it is often desirable for the sender to supply, or the | content, it is often desirable for the sender to supply, or the | |||
recipient to determine, an identifier for a resource corresponding to | recipient to determine, an identifier for a resource corresponding to | |||
that representation. | that representation. | |||
For a request message: | For a request message: | |||
o If the request has a Content-Location header field, then the | o If the request has a Content-Location header field, then the | |||
sender asserts that the payload is a representation of the | sender asserts that the content is a representation of the | |||
resource identified by the Content-Location field-value. However, | resource identified by the Content-Location field value. However, | |||
such an assertion cannot be trusted unless it can be verified by | such an assertion cannot be trusted unless it can be verified by | |||
other means (not defined by this specification). The information | other means (not defined by this specification). The information | |||
might still be useful for revision history links. | might still be useful for revision history links. | |||
o Otherwise, the payload is unidentified. | o Otherwise, the content is unidentified. | |||
For a response message, the following rules are applied in order | For a response message, the following rules are applied in order | |||
until a match is found: | until a match is found: | |||
1. If the request method is GET or HEAD and the response status code | 1. If the request method is HEAD or the response status code is 204 | |||
is 200 (OK), 204 (No Content), 206 (Partial Content), or 304 (Not | (No Content) or 304 (Not Modified), there is no content in the | |||
Modified), the payload is a representation of the resource | response. | |||
identified by the effective request URI (Section 5.5 of | ||||
[RFC7230]). | ||||
2. If the request method is GET or HEAD and the response status code | 2. If the request method is GET and the response status code is 200 | |||
is 203 (Non-Authoritative Information), the payload is a potentially | (OK), the content is a representation of the resource identified | |||
by the target URI (Section 7.1). | ||||
3. If the request method is GET and the response status code is 203 | ||||
(Non-Authoritative Information), the content is a potentially | ||||
modified or enhanced representation of the target resource as | modified or enhanced representation of the target resource as | |||
provided by an intermediary. | provided by an intermediary. | |||
3. If the response has a Content-Location header field and its | 4. If the request method is GET and the response status code is 206 | |||
field-value is a reference to the same URI as the effective | (Partial Content), the content is one or more parts of a | |||
request URI, the payload is a representation of the resource | representation of the resource identified by the target URI | |||
identified by the effective request URI. | (Section 7.1). | |||
4. If the response has a Content-Location header field and its | 5. If the response has a Content-Location header field and its field | |||
field-value is a reference to a URI different from the effective | value is a reference to the same URI as the target URI, the | |||
request URI, then the sender asserts that the | content is a representation of the target resource. | |||
payload is a representation of the resource identified by the | ||||
Content-Location field-value. | 6. If the response has a Content-Location header field and its field | |||
value is a reference to a URI different from the target URI, then | ||||
the sender asserts that the content is a representation of the | ||||
resource identified by the Content-Location field value. | ||||
However, such an assertion cannot be trusted unless it can be | However, such an assertion cannot be trusted unless it can be | |||
verified by other means (not defined by this specification). | verified by other means (not defined by this specification). | |||
5. Otherwise, the payload is unidentified. | 7. Otherwise, the content is unidentified. | |||
6.4.3. Payload Metadata | ||||
Header fields that specifically describe the payload, rather than the | ||||
associated representation, are referred to as "payload header | ||||
fields". Payload header fields are defined in other parts of this | ||||
specification, due to their impact on message parsing. | ||||
6.5. Trailer Fields | 6.5. Trailer Fields | |||
A trailer allows the sender to include additional fields at the end | Fields (Section 5) that are sent/received after the header section | |||
of a chunked message in order to supply metadata that might be | has ended (usually after the content begins to stream) are referred | |||
dynamically generated while the message body is sent, such as a | to as "trailer fields" (or just "trailers", colloquially) and located | |||
message integrity check, digital signature, or post-processing | within a _trailer section_. Trailer fields can be useful for | |||
status. The trailer fields are identical to header fields, except | supplying message integrity checks, digital signatures, delivery | |||
they are sent in a chunked trailer instead of the message's header | metrics, or post-processing status information. | |||
section. | ||||
Trailer fields ought to be processed and stored separately from the | ||||
fields in the header section to avoid contradicting message semantics | ||||
known at the time the header section was complete. The presence or | ||||
absence of certain header fields might impact choices made for the | ||||
routing or processing of the message as a whole before the trailers | ||||
are received; those choices cannot be unmade by the later discovery | ||||
of trailer fields. | ||||
6.5.1. Limitations on use of Trailers | 6.5.1. Limitations on use of Trailers | |||
A sender MUST NOT generate a trailer that contains a field necessary | Trailer sections are only possible when supported by the version of | |||
for message framing (e.g., Transfer-Encoding and Content-Length), | HTTP in use and enabled by an explicit framing mechanism. For | |||
routing (e.g., Host), request modifiers (e.g., controls and | example, the chunked coding in HTTP/1.1 allows a trailer section to | |||
conditionals in Section 5 of [RFC7231]), authentication (e.g., see | be sent after the content (Section 7.1.2 of [Messaging]). | |||
[RFC7235] and [RFC6265]), response control data (e.g., see Section | ||||
7.1 of [RFC7231]), or determining how to process the payload (e.g., | ||||
Content-Encoding, Content-Type, Content-Range, and Trailer). | ||||
When a chunked message containing a non-empty trailer is received, | Many fields cannot be processed outside the header section because | |||
the recipient MAY process the fields (aside from those forbidden | their evaluation is necessary prior to receiving the content, such as | |||
above) as if they were appended to the message's header section. A | those that describe message framing, routing, authentication, request | |||
recipient MUST ignore (or consider as an error) any fields that are | modifiers, response controls, or content format. A sender MUST NOT | |||
forbidden to be sent in a trailer, since processing them as if they | generate a trailer field unless the sender knows the corresponding | |||
were present in the header section might bypass external security | header field name's definition permits the field to be sent in | |||
filters. | trailers. | |||
[new] | Trailer fields can be difficult to process by intermediaries that | |||
forward messages from one protocol version to another. If the entire | ||||
message can be buffered in transit, some intermediaries could merge | ||||
trailer fields into the header section (as appropriate) before it is | ||||
forwarded. However, in most cases, the trailers are simply | ||||
discarded. A recipient MUST NOT merge a trailer field into a header | ||||
section unless the recipient understands the corresponding header | ||||
field definition and that definition explicitly permits and defines | ||||
how trailer field values can be safely merged. | ||||
[new] | The presence of the keyword "trailers" in the TE header field | |||
(Section 10.1.4) indicates that the client is willing to accept | ||||
trailer fields, on behalf of itself and any downstream clients. For | ||||
requests from an intermediary, this implies that all downstream | ||||
clients are willing to accept trailer fields in the forwarded | ||||
response. Note that the presence of "trailers" does not mean that | ||||
the client(s) will process any particular trailer field in the | ||||
response; only that the trailer section(s) will not be dropped by any | ||||
of the clients. | ||||
Unless the request includes a TE header field indicating "trailers" | Because of the potential for trailer fields to be discarded in | |||
is acceptable, as described in Section 4.3, a server SHOULD NOT | transit, a server SHOULD NOT generate trailer fields that it believes | |||
generate trailer fields that it believes are necessary for the user | are necessary for the user agent to receive. | |||
agent to receive. Without a TE containing "trailers", the server | ||||
ought to assume that the trailer fields might be silently discarded | ||||
along the path to the user agent. This requirement allows | ||||
intermediaries to forward a de-chunked message to an HTTP/1.0 | ||||
recipient without buffering the entire response. | ||||
6.5.2. Processing Trailer Fields | 6.5.2. Processing Trailer Fields | |||
[new] | Like header fields, trailer fields with the same name are processed | |||
in the order received; multiple trailer field lines with the same | ||||
name have the equivalent semantics as appending the multiple values | ||||
as a list of members, even when the field lines are received in | ||||
separate trailer sections. Trailer fields that might be generated | ||||
more than once during a message MUST be defined as a list-based field | ||||
even if each member value is only processed once per field line | ||||
received. | ||||
[new] | Trailer fields are expected (but not required) to be processed one | |||
trailer section at a time. That is, for each trailer section | ||||
received, a recipient that is looking for trailer fields will parse | ||||
the received section into fields, invoke any associated processing | ||||
for those fields at that point in the message processing, and then | ||||
append those fields to the set of trailer fields received for the | ||||
overall message. | ||||
[new] | This behavior allows for iterative processing of trailer fields that | |||
contain incremental signatures or mid-stream status information, and | ||||
fields that might refer to each other's values within the same | ||||
section. However, there is no guarantee that trailer sections won't | ||||
shift in relation to the content stream, or won't be recombined (or | ||||
dropped) in transit. Trailer fields that refer to data outside the | ||||
present trailer section need to use self-descriptive references | ||||
(i.e., refer to the data by name, ordinal position, or an octet | ||||
range) rather than assume it is the data most recently received. | ||||
[new] | Likewise, at the end of a message, a recipient MAY treat the entire | |||
set of received trailer fields as one data structure to be considered | ||||
as the message concludes. Additional processing expectations, if | ||||
any, can be defined within the field specification for a field | ||||
intended for use in trailers. | ||||
7. Routing HTTP Messages | 7. Routing HTTP Messages | |||
HTTP request message routing is determined by each client based on | HTTP request message routing is determined by each client based on | |||
the target resource, the client's proxy configuration, and | the target resource, the client's proxy configuration, and | |||
establishment or reuse of an inbound connection. The corresponding | establishment or reuse of an inbound connection. The corresponding | |||
response routing follows the same connection chain back to the | response routing follows the same connection chain back to the | |||
client. | client. | |||
7.1. Determining the Target Resource | 7.1. Determining the Target Resource | |||
HTTP is used in a wide variety of applications, ranging from | Although HTTP is used in a wide variety of applications, most clients | |||
general-purpose computers to home appliances. In some cases, | rely on the same resource identification mechanism and configuration | |||
communication options are hard-coded in a client's configuration. | techniques as general-purpose Web browsers. Even when communication | |||
However, most HTTP clients rely on the same resource identification | options are hard-coded in a client's configuration, we can think of | |||
mechanism and configuration techniques as general-purpose Web | their combined effect as a URI reference (Section 4.1). | |||
browsers. | ||||
A URI reference (Section 2.7) is typically used as an | A URI reference is resolved to its absolute form in order to obtain | |||
identifier for the "target resource", which a user agent would | the _target URI_. The target URI excludes the reference's fragment | |||
resolve to its absolute form in order to obtain the "target URI". | component, if any, since fragment identifiers are reserved for | |||
The target URI excludes the reference's fragment component, if any, | client-side processing ([RFC3986], Section 3.5). | |||
since fragment identifiers are reserved for client-side processing | ||||
([RFC3986], Section 3.5). | ||||
[new] | To perform an action on a _target resource_, the client sends a | |||
request message containing enough components of its parsed target URI | ||||
to enable recipients to identify that same resource. For historical | ||||
reasons, the parsed target URI components, collectively referred to | ||||
as the _request target_, are sent within the message control data and | ||||
the Host header field (Section 7.2). | ||||
6.1.3. Reconstructing the Target URI | There are two unusual cases for which the request target components | |||
are in a method-specific form: | ||||
Once an inbound connection is obtained, the client sends an HTTP | o For CONNECT (Section 9.3.6), the request target is the host name | |||
request message (Section 3) with a request-target derived from the | and port number of the tunnel destination, separated by a colon. | |||
target URI. | ||||
Since the request-target often contains only part of the user agent's | o For OPTIONS (Section 9.3.7), the request target can be a single | |||
target URI, a server reconstructs the intended target as an | asterisk ("*"). | |||
"effective request URI" to properly service the request. This | ||||
reconstruction involves both the server's local configuration and | ||||
information communicated in the request-target, Host header field, | ||||
and connection context. | ||||
For a user agent, the effective request URI is the target URI. | See the respective method definitions for details. These forms MUST | |||
NOT be used with other methods. | ||||
Once the effective request URI has been constructed, an origin server | Upon receipt of a client's request, a server reconstructs the target | |||
needs to decide whether or not to provide service for that URI via | URI from the received components in accordance with their local | |||
the connection in which the request was received. For example, the | configuration and incoming connection context. This reconstruction | |||
request might have been misdirected, deliberately or accidentally, | is specific to each major protocol version. For example, Appendix of | |||
such that the information within a received request-target or Host | [Messaging] defines how a server determines the target URI of an | |||
header field differs from the host or port upon which the connection | HTTP/1.1 request. | |||
has been made. If the connection is from a trusted gateway, that | ||||
inconsistency might be expected; otherwise, it might indicate an | | *Note:* Previous specifications defined the recomposed target | |||
attempt to bypass security filters, trick the server into delivering | | URI as a distinct concept, the _effective request URI_. | |||
non-public content, or poison a cache. See Section 9 for security | ||||
considerations regarding message routing. | ||||
7.2. Host and :authority | 7.2. Host and :authority | |||
The "Host" header field in a request provides the host and port | The "Host" header field in a request provides the host and port | |||
information from the target URI, enabling the origin server to | information from the target URI, enabling the origin server to | |||
distinguish among resources while servicing requests for multiple | distinguish among resources while servicing requests for multiple | |||
host names on a single IP address. | host names. | |||
[new] | In HTTP/2 [RFC7540] and HTTP/3 [HTTP3], the Host header field is, in | |||
some cases, supplanted by the ":authority" pseudo-header field of a | ||||
request's control data. | ||||
Host = uri-host [ ":" port ] ; Section 2.7.1 | Host = uri-host [ ":" port ] ; Section 4 | |||
Since the Host field-value is critical information for handling a | The target URI's authority information is critical for handling a | |||
request, a user agent SHOULD generate Host as the first header field | request. A user agent SHOULD generate Host as the first field in the | |||
following the request-line. | header section of a request unless it has already generated that | |||
information as an ":authority" pseudo-header field. | ||||
For example, a GET request to the origin server for | For example, a GET request to the origin server for | |||
<http://www.example.org/pub/WWW/> would begin with: | <http://www.example.org/pub/WWW/> would begin with: | |||
GET /pub/WWW/ HTTP/1.1 | GET /pub/WWW/ HTTP/1.1 | |||
Host: www.example.org | Host: www.example.org | |||
Since the Host header field acts as an application-level routing | Since the host and port information acts as an application-level | |||
mechanism, it is a frequent target for malware seeking to poison a | routing mechanism, it is a frequent target for malware seeking to | |||
shared cache or redirect a request to an unintended server. An | poison a shared cache or redirect a request to an unintended server. | |||
interception proxy is particularly vulnerable if it relies on the | An interception proxy is particularly vulnerable if it relies on the | |||
Host field-value for redirecting requests to internal servers, or for | host and port information for redirecting requests to internal | |||
use as a cache key in a shared cache, without first verifying that | servers, or for use as a cache key in a shared cache, without first | |||
the intercepted connection is targeting a valid IP address for that | verifying that the intercepted connection is targeting a valid IP | |||
host. | address for that host. | |||
7.3. Routing Inbound | 7.3. Routing Inbound Requests | |||
Once the target URI is determined, a client needs to decide whether a | Once the target URI and its origin are determined, a client decides | |||
network request is necessary to accomplish the desired semantics and, | whether a network request is necessary to accomplish the desired | |||
if so, where that request is to be directed. | semantics and, if so, where that request is to be directed. | |||
If the client has a cache [RFC7234] and the request can be satisfied | 7.3.1. To a Cache | |||
If the client has a cache [Caching] and the request can be satisfied | ||||
by it, then the request is usually directed there first. | by it, then the request is usually directed there first. | |||
7.3.2. To a Proxy | ||||
If the request is not satisfied by a cache, then a typical client | If the request is not satisfied by a cache, then a typical client | |||
will check its configuration to determine whether a proxy is to be | will check its configuration to determine whether a proxy is to be | |||
used to satisfy the request. Proxy configuration is implementation- | used to satisfy the request. Proxy configuration is implementation- | |||
dependent, but is often based on URI prefix matching, selective | dependent, but is often based on URI prefix matching, selective | |||
authority matching, or both, and the proxy itself is usually | authority matching, or both, and the proxy itself is usually | |||
identified by an "http" or "https" URI. If a proxy is applicable, | identified by an "http" or "https" URI. If a proxy is applicable, | |||
the client connects inbound by establishing (or reusing) a connection | the client connects inbound by establishing (or reusing) a connection | |||
to that proxy. | to that proxy. | |||
7.3.3. To the Origin | ||||
If no proxy is applicable, a typical client will invoke a handler | If no proxy is applicable, a typical client will invoke a handler | |||
routine, usually specific to the target URI's scheme, to connect | routine, usually specific to the target URI's scheme, to connect | |||
directly to an authority for the target resource. How that is | directly to an origin for the target resource. How that is | |||
accomplished is dependent on the target URI scheme and defined by its | accomplished is dependent on the target URI scheme and defined by its | |||
associated specification, similar to how this specification defines | associated specification. | |||
origin server access for resolution of the "http" (Section 2.7.1) and | ||||
"https" (Section 2.7.2) schemes. | ||||
HTTP requirements regarding connection management are defined in | ||||
Section 6. | ||||
7.4. Rejecting Misdirected Requests | 7.4. Rejecting Misdirected Requests | |||
[new] | Before performing a request, a server decides whether or not to | |||
provide service for the target URI via the connection in which the | ||||
request is received. For example, a request might have been | ||||
misdirected, deliberately or accidentally, such that the information | ||||
within a received Host header field differs from the connection's | ||||
host or port. | ||||
[new] | If the connection is from a trusted gateway, such inconsistency might | |||
be expected; otherwise, it might indicate an attempt to bypass | ||||
security filters, trick the server into delivering non-public | ||||
content, or poison a cache. See Section 17 for security | ||||
considerations regarding message routing. | ||||
[new] | The 421 (Misdirected Request) status code in a response indicates | |||
that the origin server has rejected the request because it appears to | ||||
have been misdirected (Section 15.5.20). | ||||
7.5. Response Correlation | 7.5. Response Correlation | |||
[new] | A connection might be used for multiple request/response exchanges. | |||
The mechanism used to correlate between request and response messages | ||||
is version dependent; some versions of HTTP use implicit ordering of | ||||
messages, while others use an explicit identifier. | ||||
[new] | Responses (both final and interim) can be sent at any time after a | |||
request is received, even if it is not yet complete. However, | ||||
clients (including intermediaries) might abandon a request if the | ||||
response is not forthcoming within a reasonable period of time. | ||||
7.6. Message Forwarding | 7.6. Message Forwarding | |||
As described in Section 2.3, intermediaries can serve a variety of | As described in Section 3.7, intermediaries can serve a variety of | |||
roles in the processing of HTTP requests and responses. Some | roles in the processing of HTTP requests and responses. Some | |||
intermediaries are used to improve performance or availability. | intermediaries are used to improve performance or availability. | |||
Others are used for access control or to filter content. Since an | Others are used for access control or to filter content. Since an | |||
HTTP stream has characteristics similar to a pipe-and-filter | HTTP stream has characteristics similar to a pipe-and-filter | |||
architecture, there are no inherent limits to the extent an | architecture, there are no inherent limits to the extent an | |||
intermediary can enhance (or interfere) with either direction of the | intermediary can enhance (or interfere) with either direction of the | |||
stream. | stream. | |||
An intermediary not acting as a tunnel MUST implement the Connection | An intermediary not acting as a tunnel MUST implement the Connection | |||
header field, as specified in Section 6.1, and exclude fields from | header field, as specified in Section 7.6.1, and exclude fields from | |||
being forwarded that are only intended for the incoming connection. | being forwarded that are only intended for the incoming connection. | |||
An intermediary MUST NOT forward a message to itself unless it is | An intermediary MUST NOT forward a message to itself unless it is | |||
protected from an infinite request loop. In general, an intermediary | protected from an infinite request loop. In general, an intermediary | |||
ought to recognize its own server names, including any aliases, local | ought to recognize its own server names, including any aliases, local | |||
variations, or literal IP addresses, and respond to such requests | variations, or literal IP addresses, and respond to such requests | |||
directly. | directly. | |||
An HTTP message can be parsed as a stream for incremental processing | An HTTP message can be parsed as a stream for incremental processing | |||
or forwarding downstream. However, recipients cannot rely on | or forwarding downstream. However, recipients cannot rely on | |||
incremental delivery of partial messages, since some implementations | incremental delivery of partial messages, since some implementations | |||
will buffer or delay message forwarding for the sake of network | will buffer or delay message forwarding for the sake of network | |||
efficiency, security checks, or payload transformations. | efficiency, security checks, or content transformations. | |||
7.6.1. Connection | 7.6.1. Connection | |||
The "Connection" header field allows the sender to indicate desired | The "Connection" header field allows the sender to list desired | |||
control options for the current connection. In order to avoid | control options for the current connection. | |||
confusing downstream recipients, a proxy or gateway MUST remove or | ||||
replace any received connection options before forwarding the | ||||
message. | ||||
When a header field aside from Connection is used to supply control | When a field aside from Connection is used to supply control | |||
information for or about the current connection, the sender MUST list | information for or about the current connection, the sender MUST list | |||
the corresponding field-name within the Connection header field. | the corresponding field name within the Connection header field. | |||
Note that some versions of HTTP prohibit the use of fields for such | ||||
information, and therefore do not allow the Connection field. | ||||
A proxy or gateway MUST parse a received Connection header field before a | Intermediaries MUST parse a received Connection header field before a | |||
message is forwarded and, for each connection-option in this field, | message is forwarded and, for each connection-option in this field, | |||
remove any header field(s) from the message with the same | remove any header or trailer field(s) from the message with the same | |||
name as the connection-option, and then remove the Connection header | name as the connection-option, and then remove the Connection header | |||
field itself (or replace it with the intermediary's own connection | field itself (or replace it with the intermediary's own connection | |||
options for the forwarded message). | options for the forwarded message). | |||
Hence, the Connection header field provides a declarative way of | Hence, the Connection header field provides a declarative way of | |||
distinguishing header fields that are only intended for the immediate | distinguishing fields that are only intended for the immediate | |||
recipient ("hop-by-hop") from those fields that are intended for all | recipient ("hop-by-hop") from those fields that are intended for all | |||
recipients on the chain ("end-to-end"), enabling the message to be | recipients on the chain ("end-to-end"), enabling the message to be | |||
self-descriptive and allowing future connection-specific extensions | self-descriptive and allowing future connection-specific extensions | |||
to be deployed without fear that they will be blindly forwarded by | to be deployed without fear that they will be blindly forwarded by | |||
older intermediaries. | older intermediaries. | |||
[new] | Furthermore, intermediaries SHOULD remove or replace field(s) whose | |||
semantics are known to require removal before forwarding, whether or | ||||
not they appear as a Connection option, after applying those fields' | ||||
semantics. This includes but is not limited to: | ||||
[new] | o Proxy-Connection (Appendix C.2.2 of [Messaging]) | |||
[new] | o Keep-Alive (Section 19.7.1 of [RFC2068]) | |||
[new] | o TE (Section 10.1.4) | |||
[new] | o Trailer (Section 10.1.5) | |||
o Transfer-Encoding (Section 6.1 of [Messaging]) | ||||
o Upgrade (Section 7.8) | ||||
The Connection header field's value has the following grammar: | The Connection header field's value has the following grammar: | |||
Connection = 1#connection-option | Connection = #connection-option | |||
connection-option = token | connection-option = token | |||
Connection options are case-insensitive. | Connection options are case-insensitive. | |||
A sender MUST NOT send a connection option corresponding to a header | A sender MUST NOT send a connection option corresponding to a field | |||
field that is intended for all recipients of the payload. For | that is intended for all recipients of the content. For example, | |||
example, Cache-Control is never appropriate as a connection option | Cache-Control is never appropriate as a connection option | |||
(Section 5.2 of [RFC7234]). | (Section 5.2 of [Caching]). | |||
The connection options do not always correspond to a header field | The connection options do not always correspond to a field present in | |||
present in the message, since a connection-specific header field | the message, since a connection-specific field might not be needed if | |||
might not be needed if there are no parameters associated with a | there are no parameters associated with a connection option. In | |||
connection option. In contrast, a connection-specific header field | contrast, a connection-specific field that is received without a | |||
that is received without a corresponding connection option usually | corresponding connection option usually indicates that the field has | |||
indicates that the field has been improperly forwarded by an | been improperly forwarded by an intermediary and ought to be ignored | |||
intermediary and ought to be ignored by the recipient. | by the recipient. | |||
When defining new connection options, specification authors ought to | When defining new connection options, specification authors ought to | |||
survey existing header field names and ensure that the new connection | document it as reserved field name and register that definition in | |||
option does not share the same name as an already deployed header | the Hypertext Transfer Protocol (HTTP) Field Name Registry | |||
field. Defining a new connection option essentially reserves that | (Section 16.3.1), to avoid collisions. | |||
potential field-name for carrying additional information related to | ||||
the connection option, since it would be unwise for senders to use | ||||
that field-name for anything else. | ||||
The "close" connection option is defined for a sender to signal that | ||||
this connection will be closed after completion of the response. For | ||||
example, | ||||
Connection: close | ||||
in either the request or the response header fields indicates that | ||||
the sender is going to close the connection after the current | ||||
request/response is complete (Section 6.6). | ||||
7.6.2. Max-Forwards | 7.6.2. Max-Forwards | |||
The "Max-Forwards" header field provides a mechanism with the TRACE | The "Max-Forwards" header field provides a mechanism with the TRACE | |||
(Section 4.3.8) and OPTIONS (Section 4.3.7) request methods to limit | (Section 9.3.8) and OPTIONS (Section 9.3.7) request methods to limit | |||
the number of times that the request is forwarded by proxies. This | the number of times that the request is forwarded by proxies. This | |||
can be useful when the client is attempting to trace a request that | can be useful when the client is attempting to trace a request that | |||
appears to be failing or looping mid-chain. | appears to be failing or looping mid-chain. | |||
Max-Forwards = 1*DIGIT | Max-Forwards = 1*DIGIT | |||
The Max-Forwards value is a decimal integer indicating the remaining | The Max-Forwards value is a decimal integer indicating the remaining | |||
number of times this request message can be forwarded. | number of times this request message can be forwarded. | |||
Each intermediary that receives a TRACE or OPTIONS request containing | Each intermediary that receives a TRACE or OPTIONS request containing | |||
a Max-Forwards header field MUST check and update its value prior to | a Max-Forwards header field MUST check and update its value prior to | |||
forwarding the request. If the received value is zero (0), the | forwarding the request. If the received value is zero (0), the | |||
intermediary MUST NOT forward the request; instead, the intermediary | intermediary MUST NOT forward the request; instead, the intermediary | |||
MUST respond as the final recipient. If the received Max-Forwards | MUST respond as the final recipient. If the received Max-Forwards | |||
value is greater than zero, the intermediary MUST generate an updated | value is greater than zero, the intermediary MUST generate an updated | |||
Max-Forwards field in the forwarded message with a field-value that | Max-Forwards field in the forwarded message with a field value that | |||
is the lesser of a) the received value decremented by one (1) or b) | is the lesser of a) the received value decremented by one (1) or b) | |||
the recipient's maximum supported value for Max-Forwards. | the recipient's maximum supported value for Max-Forwards. | |||
A recipient MAY ignore a Max-Forwards header field received with any | A recipient MAY ignore a Max-Forwards header field received with any | |||
other request methods. | other request methods. | |||
7.6.3. Via | 7.6.3. Via | |||
The "Via" header field indicates the presence of intermediate | The "Via" header field indicates the presence of intermediate | |||
protocols and recipients between the user agent and the server (on | protocols and recipients between the user agent and the server (on | |||
requests) or between the origin server and the client (on responses), | requests) or between the origin server and the client (on responses), | |||
similar to the "Received" header field in email (Section 3.6.7 of | similar to the "Received" header field in email (Section 3.6.7 of | |||
[RFC5322]). Via can be used for tracking message forwards, avoiding | [RFC5322]). Via can be used for tracking message forwards, avoiding | |||
request loops, and identifying the protocol capabilities of senders | request loops, and identifying the protocol capabilities of senders | |||
along the request/response chain. | along the request/response chain. | |||
Via = 1#( received-protocol RWS received-by [ RWS comment ] ) | Via = #( received-protocol RWS received-by [ RWS comment ] ) | |||
received-protocol = [ protocol-name "/" ] protocol-version | received-protocol = [ protocol-name "/" ] protocol-version | |||
; see Section 6.7 | ; see Section 7.8 | |||
received-by = ( uri-host [ ":" port ] ) / pseudonym | received-by = pseudonym [ ":" port ] | |||
pseudonym = token | pseudonym = token | |||
Multiple Via field values represent each proxy or gateway that has | Each member of the Via field value represents a proxy or gateway that | |||
forwarded the message. Each intermediary appends its own information | has forwarded the message. Each intermediary appends its own | |||
about how the message was received, such that the end result is | information about how the message was received, such that the end | |||
ordered according to the sequence of forwarding recipients. | result is ordered according to the sequence of forwarding recipients. | |||
A proxy MUST send an appropriate Via header field, as described | A proxy MUST send an appropriate Via header field, as described | |||
below, in each message that it forwards. An HTTP-to-HTTP gateway | below, in each message that it forwards. An HTTP-to-HTTP gateway | |||
MUST send an appropriate Via header field in each inbound request | MUST send an appropriate Via header field in each inbound request | |||
message and MAY send a Via header field in forwarded response | message and MAY send a Via header field in forwarded response | |||
messages. | messages. | |||
For each intermediary, the received-protocol indicates the protocol | For each intermediary, the received-protocol indicates the protocol | |||
and protocol version used by the upstream sender of the message. | and protocol version used by the upstream sender of the message. | |||
Hence, the Via field value records the advertised protocol | Hence, the Via field value records the advertised protocol | |||
capabilities of the request/response chain such that they remain | capabilities of the request/response chain such that they remain | |||
visible to downstream recipients; this can be useful for determining | visible to downstream recipients; this can be useful for determining | |||
what backwards-incompatible features might be safe to use in | what backwards-incompatible features might be safe to use in | |||
response, or within a later request, as described in Section 2.6. | response, or within a later request, as described in Section 2.5. | |||
For brevity, the protocol-name is omitted when the received protocol | For brevity, the protocol-name is omitted when the received protocol | |||
is HTTP. | is HTTP. | |||
The received-by portion of the field value is normally the host and | The received-by portion is normally the host and optional port number | |||
optional port number of a recipient server or client that | of a recipient server or client that subsequently forwarded the | |||
subsequently forwarded the message. However, if the real host is | message. However, if the real host is considered to be sensitive | |||
considered to be sensitive information, a sender MAY replace it with | information, a sender MAY replace it with a pseudonym. If a port is | |||
a pseudonym. If a port is not provided, a recipient MAY interpret | not provided, a recipient MAY interpret that as meaning it was | |||
that as meaning it was received on the default TCP port, if any, for | received on the default TCP port, if any, for the received-protocol. | |||
the received-protocol. | ||||
A sender MAY generate comments in the Via header field to identify | A sender MAY generate comments to identify the software of each | |||
the software of each recipient, analogous to the User-Agent and | recipient, analogous to the User-Agent and Server header fields. | |||
Server header fields. However, all comments in the Via field are | However, comments in Via are optional, and a recipient MAY remove | |||
optional, and a recipient MAY remove them prior to forwarding the | them prior to forwarding the message. | |||
message. | ||||
For example, a request message could be sent from an HTTP/1.0 user | For example, a request message could be sent from an HTTP/1.0 user | |||
agent to an internal proxy code-named "fred", which uses HTTP/1.1 to | agent to an internal proxy code-named "fred", which uses HTTP/1.1 to | |||
forward the request to a public proxy at p.example.net, which | forward the request to a public proxy at p.example.net, which | |||
completes the request by forwarding it to the origin server at | completes the request by forwarding it to the origin server at | |||
www.example.com. The request received by www.example.com would then | www.example.com. The request received by www.example.com would then | |||
have the following Via header field: | have the following Via header field: | |||
Via: 1.0 fred, 1.1 p.example.net | Via: 1.0 fred, 1.1 p.example.net | |||
An intermediary used as a portal through a network firewall SHOULD | An intermediary used as a portal through a network firewall SHOULD | |||
NOT forward the names and ports of hosts within the firewall region | NOT forward the names and ports of hosts within the firewall region | |||
unless it is explicitly enabled to do so. If not enabled, such an | unless it is explicitly enabled to do so. If not enabled, such an | |||
intermediary SHOULD replace each received-by host of any host behind | intermediary SHOULD replace each received-by host of any host behind | |||
the firewall by an appropriate pseudonym for that host. | the firewall by an appropriate pseudonym for that host. | |||
An intermediary MAY combine an ordered subsequence of Via header | An intermediary MAY combine an ordered subsequence of Via header | |||
field entries into a single such entry if the entries have identical | field list members into a single member if the entries have identical | |||
received-protocol values. For example, | received-protocol values. For example, | |||
Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy | Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy | |||
could be collapsed to | could be collapsed to | |||
Via: 1.0 ricky, 1.1 mertz, 1.0 lucy | Via: 1.0 ricky, 1.1 mertz, 1.0 lucy | |||
A sender SHOULD NOT combine multiple entries unless they are all | A sender SHOULD NOT combine multiple list members unless they are all | |||
under the same organizational control and the hosts have already been | under the same organizational control and the hosts have already been | |||
replaced by pseudonyms. A sender MUST NOT combine entries that have | replaced by pseudonyms. A sender MUST NOT combine members that have | |||
different received-protocol values. | different received-protocol values. | |||
7.7. Message Transformations | 7.7. Message Transformations | |||
Some intermediaries include features for transforming messages and | Some intermediaries include features for transforming messages and | |||
their payloads. A proxy might, for example, convert between image | their content. A proxy might, for example, convert between image | |||
formats in order to save cache space or to reduce the amount of | formats in order to save cache space or to reduce the amount of | |||
traffic on a slow link. However, operational problems might occur | traffic on a slow link. However, operational problems might occur | |||
when these transformations are applied to payloads intended for | when these transformations are applied to content intended for | |||
critical applications, such as medical imaging or scientific data | critical applications, such as medical imaging or scientific data | |||
analysis, particularly when integrity checks or digital signatures | analysis, particularly when integrity checks or digital signatures | |||
are used to ensure that the payload received is identical to the | are used to ensure that the content received is identical to the | |||
original. | original. | |||
An HTTP-to-HTTP proxy is called a "transforming proxy" if it is | An HTTP-to-HTTP proxy is called a _transforming proxy_ if it is | |||
designed or configured to modify messages in a semantically | designed or configured to modify messages in a semantically | |||
meaningful way (i.e., modifications, beyond those required by normal | meaningful way (i.e., modifications, beyond those required by normal | |||
HTTP processing, that change the message in a way that would be | HTTP processing, that change the message in a way that would be | |||
significant to the original sender or potentially significant to | significant to the original sender or potentially significant to | |||
downstream recipients). For example, a transforming proxy might be | downstream recipients). For example, a transforming proxy might be | |||
acting as a shared annotation server (modifying responses to include | acting as a shared annotation server (modifying responses to include | |||
references to a local annotation database), a malware filter, a | references to a local annotation database), a malware filter, a | |||
format transcoder, or a privacy filter. Such transformations are | format transcoder, or a privacy filter. Such transformations are | |||
presumed to be desired by whichever client (or client organization) | presumed to be desired by whichever client (or client organization) | |||
selected the proxy. | chose the proxy. | |||
If a proxy receives a request-target with a host name that is not a | If a proxy receives a target URI with a host name that is not a fully | |||
fully qualified domain name, it MAY add its own domain to the host | qualified domain name, it MAY add its own domain to the host name it | |||
name it received when forwarding the request. A proxy MUST NOT | received when forwarding the request. A proxy MUST NOT change the | |||
change the host name if the request-target contains a fully qualified | host name if the target URI contains a fully qualified domain name. | |||
domain name. | ||||
A proxy MUST NOT modify the "absolute-path" and "query" parts of the | A proxy MUST NOT modify the "absolute-path" and "query" parts of the | |||
received request-target when forwarding it to the next inbound | received target URI when forwarding it to the next inbound server, | |||
server, except as noted above to replace an empty path with "/" or | except as noted above to replace an empty path with "/" or "*". | |||
"*". | ||||
A proxy MAY modify the message body through application or removal of | ||||
a transfer coding (Section 4). | ||||
A proxy MUST NOT transform the payload (Section 3.3 of [RFC7231]) of | A proxy MUST NOT transform the content (Section 6.4) of a message | |||
a message that contains a no-transform cache-control directive | that contains a no-transform cache-control response directive | |||
(Section 5.2 of [RFC7234]). | (Section 5.2 of [Caching]). Note that this does not include changes | |||
to the message body that do not affect the content, such as transfer | ||||
codings (Section 7 of [Messaging]). | ||||
A proxy MAY transform the payload of a message that does not contain | A proxy MAY transform the content of a message that does not contain | |||
a no-transform cache-control directive. A proxy that transforms a | a no-transform cache-control directive. A proxy that transforms the | |||
payload MUST add a Warning header field with the warn-code of 214 | content of a 200 (OK) response can inform downstream recipients that | |||
("Transformation Applied") if one is not already in the message (see | a transformation has been applied by changing the response status | |||
Section 5.5 of [RFC7234]). A proxy that transforms the payload of a | code to 203 (Non-Authoritative Information) (Section 15.3.4). | |||
200 (OK) response can further inform downstream recipients that a | ||||
transformation has been applied by changing the response status code | ||||
to 203 (Non-Authoritative Information) (Section 6.3.4 of [RFC7231]). | ||||
A proxy SHOULD NOT modify header fields that provide information | A proxy SHOULD NOT modify header fields that provide information | |||
about the endpoints of the communication chain, the resource state, | about the endpoints of the communication chain, the resource state, | |||
or the selected representation (other than the payload) unless the | or the selected representation (other than the content) unless the | |||
field's definition specifically allows such modification or the | field's definition specifically allows such modification or the | |||
modification is deemed necessary for privacy or security. | modification is deemed necessary for privacy or security. | |||
7.8. Upgrade | 7.8. Upgrade | |||
The "Upgrade" header field is intended to provide a simple mechanism | The "Upgrade" header field is intended to provide a simple mechanism | |||
for transitioning from HTTP/1.1 to some other protocol on the same | for transitioning from HTTP/1.1 to some other protocol on the same | |||
connection. A client MAY send a list of protocols in the Upgrade | connection. | |||
header field of a request to invite the server to switch to one or | ||||
more of those protocols, in order of descending preference, before | A client MAY send a list of protocol names in the Upgrade header | |||
field of a request to invite the server to switch to one or more of | ||||
the named protocols, in order of descending preference, before | ||||
sending the final response. A server MAY ignore a received Upgrade | sending the final response. A server MAY ignore a received Upgrade | |||
header field if it wishes to continue using the current protocol on | header field if it wishes to continue using the current protocol on | |||
that connection. Upgrade cannot be used to insist on a protocol | that connection. Upgrade cannot be used to insist on a protocol | |||
change. | change. | |||
Upgrade = 1#protocol | Upgrade = #protocol | |||
protocol = protocol-name ["/" protocol-version] | protocol = protocol-name ["/" protocol-version] | |||
protocol-name = token | protocol-name = token | |||
protocol-version = token | protocol-version = token | |||
Although protocol names are registered with a preferred case, | ||||
recipients SHOULD use case-insensitive comparison when matching each | ||||
protocol-name to supported protocols. | ||||
A server that sends a 101 (Switching Protocols) response MUST send an | A server that sends a 101 (Switching Protocols) response MUST send an | |||
Upgrade header field to indicate the new protocol(s) to which the | Upgrade header field to indicate the new protocol(s) to which the | |||
connection is being switched; if multiple protocol layers are being | connection is being switched; if multiple protocol layers are being | |||
switched, the sender MUST list the protocols in layer-ascending | switched, the sender MUST list the protocols in layer-ascending | |||
order. A server MUST NOT switch to a protocol that was not indicated | order. A server MUST NOT switch to a protocol that was not indicated | |||
by the client in the corresponding request's Upgrade header field. A | by the client in the corresponding request's Upgrade header field. A | |||
server MAY choose to ignore the order of preference indicated by the | server MAY choose to ignore the order of preference indicated by the | |||
client and select the new protocol(s) based on other factors, such as | client and select the new protocol(s) based on other factors, such as | |||
the nature of the request or the current load on the server. | the nature of the request or the current load on the server. | |||
skipping to change at line 2162 ¶ | skipping to change at page 57, line 40 ¶ | |||
Upgrade header field to indicate the acceptable protocols, in order | Upgrade header field to indicate the acceptable protocols, in order | |||
of descending preference. | of descending preference. | |||
A server MAY send an Upgrade header field in any other response to | A server MAY send an Upgrade header field in any other response to | |||
advertise that it implements support for upgrading to the listed | advertise that it implements support for upgrading to the listed | |||
protocols, in order of descending preference, when appropriate for a | protocols, in order of descending preference, when appropriate for a | |||
future request. | future request. | |||
The following is a hypothetical example sent by a client: | The following is a hypothetical example sent by a client: | |||
GET /hello.txt HTTP/1.1 | GET /hello HTTP/1.1 | |||
Host: www.example.com | Host: www.example.com | |||
Connection: upgrade | Connection: upgrade | |||
Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11 | Upgrade: websocket, IRC/6.9, RTA/x11 | |||
The capabilities and nature of the application-level communication | The capabilities and nature of the application-level communication | |||
after the protocol change is entirely dependent upon the new | after the protocol change is entirely dependent upon the new | |||
protocol(s) chosen. However, immediately after sending the 101 | protocol(s) chosen. However, immediately after sending the 101 | |||
(Switching Protocols) response, the server is expected to continue | (Switching Protocols) response, the server is expected to continue | |||
responding to the original request as if it had received its | responding to the original request as if it had received its | |||
equivalent within the new protocol (i.e., the server still has an | equivalent within the new protocol (i.e., the server still has an | |||
outstanding request to satisfy after the protocol has been changed, | outstanding request to satisfy after the protocol has been changed, | |||
and is expected to do so without requiring the request to be | and is expected to do so without requiring the request to be | |||
repeated). | repeated). | |||
skipping to change at line 2192 ¶ | skipping to change at page 58, line 23 ¶ | |||
to protocols with the same semantics as HTTP without the latency cost | to protocols with the same semantics as HTTP without the latency cost | |||
of an additional round trip. A server MUST NOT switch protocols | of an additional round trip. A server MUST NOT switch protocols | |||
unless the received message semantics can be honored by the new | unless the received message semantics can be honored by the new | |||
protocol; an OPTIONS request can be honored by any protocol. | protocol; an OPTIONS request can be honored by any protocol. | |||
The following is an example response to the above hypothetical | The following is an example response to the above hypothetical | |||
request: | request: | |||
HTTP/1.1 101 Switching Protocols | HTTP/1.1 101 Switching Protocols | |||
Connection: upgrade | Connection: upgrade | |||
Upgrade: HTTP/2.0 | Upgrade: websocket | |||
[... data stream switches to HTTP/2.0 with an appropriate response | [... data stream switches to websocket with an appropriate response | |||
(as defined by new protocol) to the "GET /hello.txt" request ...] | (as defined by new protocol) to the "GET /hello" request ...] | |||
When Upgrade is sent, the sender MUST also send a Connection header | When Upgrade is sent, the sender MUST also send a Connection header | |||
field (Section 6.1) that contains an "upgrade" connection option, in | field (Section 7.6.1) that contains an "upgrade" connection option, | |||
order to prevent Upgrade from being accidentally forwarded by | in order to prevent Upgrade from being accidentally forwarded by | |||
intermediaries that might not implement the listed protocols. A | intermediaries that might not implement the listed protocols. A | |||
server MUST ignore an Upgrade header field that is received in an | server MUST ignore an Upgrade header field that is received in an | |||
HTTP/1.0 request. | HTTP/1.0 request. | |||
A client cannot begin using an upgraded protocol on the connection | A client cannot begin using an upgraded protocol on the connection | |||
until it has completely sent the request message (i.e., the client | until it has completely sent the request message (i.e., the client | |||
can't change the protocol it is sending in the middle of a message). | can't change the protocol it is sending in the middle of a message). | |||
If a server receives both an Upgrade and an Expect header field with | If a server receives both an Upgrade and an Expect header field with | |||
the "100-continue" expectation (Section 5.1.1 of [RFC7231]), the | the "100-continue" expectation (Section 10.1.1), the server MUST send | |||
server MUST send a 100 (Continue) response before sending a 101 | a 100 (Continue) response before sending a 101 (Switching Protocols) | |||
(Switching Protocols) response. | response. | |||
The Upgrade header field only applies to switching protocols on top | The Upgrade header field only applies to switching protocols on top | |||
of the existing connection; it cannot be used to switch the | of the existing connection; it cannot be used to switch the | |||
underlying connection (transport) protocol, nor to switch the | underlying connection (transport) protocol, nor to switch the | |||
existing communication to a different connection. For those | existing communication to a different connection. For those | |||
purposes, it is more appropriate to use a 3xx (Redirection) response | purposes, it is more appropriate to use a 3xx (Redirection) response | |||
(Section 6.4 of [RFC7231]). | (Section 15.4). | |||
This specification only defines the protocol name "HTTP" for use by | This specification only defines the protocol name "HTTP" for use by | |||
the family of Hypertext Transfer Protocols, as defined by the HTTP | the family of Hypertext Transfer Protocols, as defined by the HTTP | |||
version rules of Section 2.6 and future updates to this | version rules of Section 2.5 and future updates to this | |||
specification. Additional tokens ought to be registered with IANA | specification. Additional protocol names ought to be registered | |||
using the registration procedure defined in Section 8.6. | using the registration procedure defined in Section 16.7. | |||
8. Representation Data and Metadata | 8. Representation Data and Metadata | |||
8.1. Representation Data | 8.1. Representation Data | |||
The representation data associated with an HTTP message is either | The representation data associated with an HTTP message is either | |||
provided as the payload body of the message or referred to by the | provided as the content of the message or referred to by the message | |||
message semantics and the effective request URI. The representation | semantics and the target URI. The representation data is in a format | |||
data is in a format and encoding defined by the representation | and encoding defined by the representation metadata header fields. | |||
metadata header fields. | ||||
The data type of the representation data is determined via the header | The data type of the representation data is determined via the header | |||
fields Content-Type and Content-Encoding. These define a two-layer, | fields Content-Type and Content-Encoding. These define a two-layer, | |||
ordered encoding model: | ordered encoding model: | |||
representation-data := Content-Encoding( Content-Type( bits ) ) | representation-data := Content-Encoding( Content-Type( bits ) ) | |||
8.2. Representation Metadata | 8.2. Representation Metadata | |||
Representation header fields provide metadata about the | Representation header fields provide metadata about the | |||
representation. When a message includes a payload body, the | representation. When a message includes content, the representation | |||
representation header fields describe how to interpret the | header fields describe how to interpret that data. In a response to | |||
representation data enclosed in the payload body. In a response to a | a HEAD request, the representation header fields describe the | |||
HEAD request, the representation header fields describe the | representation data that would have been enclosed in the content if | |||
representation data that would have been enclosed in the payload body | the same request had been a GET. | |||
if the same request had been a GET. | ||||
The following header fields convey representation metadata: | ||||
8.3. Content-Type | 8.3. Content-Type | |||
The "Content-Type" header field indicates the media type of the | The "Content-Type" header field indicates the media type of the | |||
associated representation: either the representation enclosed in the | associated representation: either the representation enclosed in the | |||
message payload or the selected representation, as determined by the | message content or the selected representation, as determined by the | |||
message semantics. The indicated media type defines both the data | message semantics. The indicated media type defines both the data | |||
format and how that data is intended to be processed by a recipient, | format and how that data is intended to be processed by a recipient, | |||
within the scope of the received message semantics, after any content | within the scope of the received message semantics, after any content | |||
codings indicated by Content-Encoding are decoded. | codings indicated by Content-Encoding are decoded. | |||
Content-Type = media-type | Content-Type = media-type | |||
Media types are defined in Section 3.1.1.1. An example of the field | Media types are defined in Section 8.3.1. An example of the field is | |||
is | ||||
Content-Type: text/html; charset=ISO-8859-4 | Content-Type: text/html; charset=ISO-8859-4 | |||
A sender that generates a message containing a payload body SHOULD | A sender that generates a message containing content SHOULD generate | |||
generate a Content-Type header field in that message unless the | a Content-Type header field in that message unless the intended media | |||
intended media type of the enclosed representation is unknown to the | type of the enclosed representation is unknown to the sender. If a | |||
sender. If a Content-Type header field is not present, the recipient | Content-Type header field is not present, the recipient MAY either | |||
MAY either assume a media type of "application/octet-stream" | assume a media type of "application/octet-stream" ([RFC2046], | |||
([RFC2046], Section 4.5.1) or examine the data to determine its type. | Section 4.5.1) or examine the data to determine its type. | |||
In practice, resource owners do not always properly configure their | In practice, resource owners do not always properly configure their | |||
origin server to provide the correct Content-Type for a given | origin server to provide the correct Content-Type for a given | |||
representation, with the result that some clients will examine a | representation. Some user agents examine the content and, in certain | |||
payload's content and override the specified type. Clients that do | cases, override the received type (for example, see [Sniffing]). | |||
so risk drawing incorrect conclusions, which might expose additional | This "MIME sniffing" risks drawing incorrect conclusions about the | |||
security risks (e.g., "privilege escalation"). Furthermore, it is | data, which might expose the user to additional security risks (e.g., | |||
impossible to determine the sender's intent by examining the data | "privilege escalation"). Furthermore, it is impossible to determine | |||
format: many data formats match multiple media types that differ only | the sender's intended processing model by examining the data format: | |||
in processing semantics. Implementers are encouraged to provide a | many data formats match multiple media types that differ only in | |||
means of disabling such "content sniffing" when it is used. | processing semantics. Implementers are encouraged to provide a means | |||
to disable such sniffing. | ||||
Furthermore, although Content-Type is defined as a singleton field, | ||||
it is sometimes incorrectly generated multiple times, resulting in a | ||||
combined field value that appears to be a list. Recipients often | ||||
attempt to handle this error by using the last syntactically valid | ||||
member of the list, but note that some implementations might have | ||||
different error handling behaviors, leading to interoperability and/ | ||||
or security issues. | ||||
8.3.1. Media Type | 8.3.1. Media Type | |||
HTTP uses Internet media types [RFC2046] in the Content-Type | HTTP uses media types [RFC2046] in the Content-Type (Section 8.3) and | |||
(Section 3.1.1.5) and Accept (Section 5.3.2) header fields in order | Accept (Section 12.5.1) header fields in order to provide open and | |||
to provide open and extensible data typing and type negotiation. | extensible data typing and type negotiation. Media types define both | |||
Media types define both a data format and various processing models: | a data format and various processing models: how to process that data | |||
how to process that data in accordance with each context in which it | in accordance with each context in which it is received. | |||
is received. | ||||
media-type = type "/" subtype *( OWS ";" OWS parameter ) | media-type = type "/" subtype parameters | |||
type = token | type = token | |||
subtype = token | subtype = token | |||
The type/subtype MAY be followed by parameters in the form of | The type and subtype tokens are case-insensitive. | |||
name=value pairs. | ||||
The type, subtype, and parameter name tokens are case-insensitive. | The type/subtype MAY be followed by semicolon-delimited parameters | |||
Parameter values might or might not be case-sensitive, depending on | (Section 5.6.6) in the form of name=value pairs. The presence or | |||
the semantics of the parameter name. The presence or absence of a | absence of a parameter might be significant to the processing of a | |||
parameter might be significant to the processing of a media-type, | media type, depending on its definition within the media type | |||
depending on its definition within the media type registry. | registry. Parameter values might or might not be case-sensitive, | |||
depending on the semantics of the parameter name. | ||||
For example, the following | For example, the following media types are equivalent in describing | |||
examples are all equivalent, but the first is preferred for | HTML text data encoded in the UTF-8 character encoding scheme, but | |||
consistency: | the first is preferred for consistency (the "charset" parameter value | |||
is defined as being case-insensitive in [RFC2046], Section 4.1.2): | ||||
text/html;charset=utf-8 | text/html;charset=utf-8 | |||
text/html;charset=UTF-8 | ||||
Text/HTML;Charset="utf-8" | Text/HTML;Charset="utf-8" | |||
text/html; charset="utf-8" | text/html; charset="utf-8" | |||
text/html;charset=UTF-8 | ||||
Internet media types ought to be registered with IANA according to | Media types ought to be registered with IANA according to the | |||
the procedures defined in [BCP13]. | procedures defined in [BCP13]. | |||
8.3.2. Charset | 8.3.2. Charset | |||
HTTP uses charset names to indicate or negotiate the character | HTTP uses _charset_ names to indicate or negotiate the character | |||
encoding scheme of a textual representation [RFC6365]. A charset is | encoding scheme of a textual representation [RFC6365]. A charset is | |||
identified by a case-insensitive token. | identified by a case-insensitive token. | |||
charset = token | charset = token | |||
Charset names ought to be registered in the IANA "Character Sets" | Charset names ought to be registered in the IANA "Character Sets" | |||
registry (<http://www.iana.org/assignments/character-sets>) according | registry (<https://www.iana.org/assignments/character-sets>) | |||
to the procedures defined in [RFC2978]. | according to the procedures defined in Section 2 of [RFC2978]. | |||
| *Note:* In theory, charset names are defined by the "mime- | ||||
| charset" ABNF rule defined in Section 2.3 of [RFC2978] (as | ||||
| corrected in [Err1912]). That rule allows two characters that | ||||
| are not included in "token" ("{" and "}"), but no charset name | ||||
| registered at the time of this writing includes braces (see | ||||
| [Err5433]). | ||||
8.3.3. Canonicalization and Text Defaults | 8.3.3. Canonicalization and Text Defaults | |||
Internet media types are registered with a canonical form in order to | Media types are registered with a canonical form in order to be | |||
be interoperable among systems with varying native encoding formats. | interoperable among systems with varying native encoding formats. | |||
Representations selected or transferred via HTTP ought to be in | Representations selected or transferred via HTTP ought to be in | |||
canonical form, for many of the same reasons described by the | canonical form, for many of the same reasons described by the | |||
Multipurpose Internet Mail Extensions (MIME) [RFC2045]. However, the | Multipurpose Internet Mail Extensions (MIME) [RFC2045]. However, the | |||
performance characteristics of email deployments (i.e., store and | performance characteristics of email deployments (i.e., store and | |||
forward messages to peers) are significantly different from those | forward messages to peers) are significantly different from those | |||
common to HTTP and the Web (server-based information services). | common to HTTP and the Web (server-based information services). | |||
Furthermore, MIME's constraints for the sake of compatibility with | Furthermore, MIME's constraints for the sake of compatibility with | |||
older mail transfer protocols do not apply to HTTP (see Appendix A). | older mail transfer protocols do not apply to HTTP (see Appendix B of | |||
[Messaging]). | ||||
MIME's canonical form requires that media subtypes of the "text" type | MIME's canonical form requires that media subtypes of the "text" type | |||
use CRLF as the text line break. HTTP allows the transfer of text | use CRLF as the text line break. HTTP allows the transfer of text | |||
media with plain CR or LF alone representing a line break, when such | media with plain CR or LF alone representing a line break, when such | |||
line breaks are consistent for an entire representation. An HTTP | line breaks are consistent for an entire representation. An HTTP | |||
sender MAY generate, and a recipient MUST be able to parse, line | sender MAY generate, and a recipient MUST be able to parse, line | |||
breaks in text media that consist of CRLF, bare CR, or bare LF. In | breaks in text media that consist of CRLF, bare CR, or bare LF. In | |||
addition, text media in HTTP is not limited to charsets that use | addition, text media in HTTP is not limited to charsets that use | |||
octets 13 and 10 for CR and LF, respectively. This flexibility | octets 13 and 10 for CR and LF, respectively. This flexibility | |||
regarding line breaks applies only to text within a representation | regarding line breaks applies only to text within a representation | |||
that has been assigned a "text" media type; it does not apply to | that has been assigned a "text" media type; it does not apply to | |||
"multipart" types or HTTP elements outside the payload body (e.g., | "multipart" types or HTTP elements outside the content (e.g., header | |||
header fields). | fields). | |||
If a representation is encoded with a content-coding, the underlying | If a representation is encoded with a content-coding, the underlying | |||
data ought to be in a form defined above prior to being encoded. | data ought to be in a form defined above prior to being encoded. | |||
8.3.4. Multipart Types | 8.3.4. Multipart Types | |||
MIME provides for a number of "multipart" types -- encapsulations of | MIME provides for a number of "multipart" types - encapsulations of | |||
one or more representations within a single message body. All | one or more representations within a single message body. All | |||
multipart types share a common syntax, as defined in Section 5.1.1 of | multipart types share a common syntax, as defined in Section 5.1.1 of | |||
[RFC2046], and include a boundary parameter as part of the media type | [RFC2046], and include a boundary parameter as part of the media type | |||
value. The message body is itself a protocol element; a sender MUST | value. The message body is itself a protocol element; a sender MUST | |||
generate only CRLF to represent line breaks between body parts. | generate only CRLF to represent line breaks between body parts. | |||
HTTP message framing does not use the multipart boundary as an | HTTP message framing does not use the multipart boundary as an | |||
indicator of message body length, though it might be used by | indicator of message body length, though it might be used by | |||
implementations that generate or process the payload. For example, | implementations that generate or process the content. For example, | |||
the "multipart/form-data" type is often used for carrying form data | the "multipart/form-data" type is often used for carrying form data | |||
in a request, as described in [RFC2388], and the "multipart/ | in a request, as described in [RFC7578], and the "multipart/ | |||
byteranges" type is defined by this specification for use in some 206 | byteranges" type is defined by this specification for use in some 206 | |||
(Partial Content) responses [RFC7233]. | (Partial Content) responses (see Section 15.3.7). | |||
8.4. Content-Encoding | 8.4. Content-Encoding | |||
The "Content-Encoding" header field indicates what content codings | The "Content-Encoding" header field indicates what content codings | |||
have been applied to the representation, beyond those inherent in the | have been applied to the representation, beyond those inherent in the | |||
media type, and thus what decoding mechanisms have to be applied in | media type, and thus what decoding mechanisms have to be applied in | |||
order to obtain data in the media type referenced by the Content-Type | order to obtain data in the media type referenced by the Content-Type | |||
header field. Content-Encoding is primarily used to allow a | header field. Content-Encoding is primarily used to allow a | |||
representation's data to be compressed without losing the identity of | representation's data to be compressed without losing the identity of | |||
its underlying media type. | its underlying media type. | |||
Content-Encoding = 1#content-coding | Content-Encoding = #content-coding | |||
An example of its use is | An example of its use is | |||
Content-Encoding: gzip | Content-Encoding: gzip | |||
If one or more encodings have been applied to a representation, the | If one or more encodings have been applied to a representation, the | |||
sender that applied the encodings MUST generate a Content-Encoding | sender that applied the encodings MUST generate a Content-Encoding | |||
header field that lists the content codings in the order in which | header field that lists the content codings in the order in which | |||
they were applied. Additional information about the encoding | they were applied. Note that the coding named "identity" is reserved | |||
parameters can be provided by other header fields not defined by this | for its special role in Accept-Encoding, and thus SHOULD NOT be | |||
specification. | included. | |||
[new] | Additional information about the encoding parameters can be provided | |||
by other header fields not defined by this specification. | ||||
Unlike Transfer-Encoding (Section 3.3.1 of [RFC7230]), the codings | Unlike Transfer-Encoding (Section 6.1 of [Messaging]), the codings | |||
listed in Content-Encoding are a characteristic of the | listed in Content-Encoding are a characteristic of the | |||
representation; the representation is defined in terms of the coded | representation; the representation is defined in terms of the coded | |||
form, and all other metadata about the representation is about the | form, and all other metadata about the representation is about the | |||
coded form unless otherwise noted in the metadata definition. | coded form unless otherwise noted in the metadata definition. | |||
Typically, the representation is only decoded just prior to rendering | Typically, the representation is only decoded just prior to rendering | |||
or analogous usage. | or analogous usage. | |||
If the media type includes an inherent encoding, such as a data | If the media type includes an inherent encoding, such as a data | |||
format that is always compressed, then that encoding would not be | format that is always compressed, then that encoding would not be | |||
restated in Content-Encoding even if it happens to be the same | restated in Content-Encoding even if it happens to be the same | |||
skipping to change at line 2441 ¶ | skipping to change at page 64, line 5 ¶ | |||
Content coding values indicate an encoding transformation that has | Content coding values indicate an encoding transformation that has | |||
been or can be applied to a representation. Content codings are | been or can be applied to a representation. Content codings are | |||
primarily used to allow a representation to be compressed or | primarily used to allow a representation to be compressed or | |||
otherwise usefully transformed without losing the identity of its | otherwise usefully transformed without losing the identity of its | |||
underlying media type and without loss of information. Frequently, | underlying media type and without loss of information. Frequently, | |||
the representation is stored in coded form, transmitted directly, and | the representation is stored in coded form, transmitted directly, and | |||
only decoded by the final recipient. | only decoded by the final recipient. | |||
content-coding = token | content-coding = token | |||
All content-coding values are case-insensitive and ought to be | All content codings are case-insensitive and ought to be registered | |||
registered within the "HTTP Content Coding Registry", as defined in | within the "HTTP Content Coding Registry", as described in | |||
Section 8.4. | Section 16.6 | |||
The following content-coding values are defined by this | ||||
specification: | ||||
compress (and x-compress): See Section 4.2.1 of [RFC7230]. | ||||
deflate: See Section 4.2.2 of [RFC7230]. | ||||
gzip (and x-gzip): See Section 4.2.3 of [RFC7230]. | ||||
The codings defined below can be used to compress the payload of a | Content-coding values are used in the Accept-Encoding | |||
message. They are used in the Accept-Encoding | (Section 12.5.3) and Content-Encoding (Section 8.4) header fields. | |||
(Section 5.3.4) and Content-Encoding (Section 3.1.2.2) header fields. | ||||
8.4.1.1. Compress Coding | 8.4.1.1. Compress Coding | |||
The "compress" coding is an adaptive Lempel-Ziv-Welch (LZW) coding | The "compress" coding is an adaptive Lempel-Ziv-Welch (LZW) coding | |||
[Welch] that is commonly produced by the UNIX file compression | [Welch] that is commonly produced by the UNIX file compression | |||
program "compress". A recipient SHOULD consider "x-compress" to be | program "compress". A recipient SHOULD consider "x-compress" to be | |||
equivalent to "compress". | equivalent to "compress". | |||
8.4.1.2. Deflate Coding | 8.4.1.2. Deflate Coding | |||
The "deflate" coding is a "zlib" data format [RFC1950] containing a | The "deflate" coding is a "zlib" data format [RFC1950] containing a | |||
"deflate" compressed data stream [RFC1951] that uses a combination of | "deflate" compressed data stream [RFC1951] that uses a combination of | |||
the Lempel-Ziv (LZ77) compression algorithm and Huffman coding. | the Lempel-Ziv (LZ77) compression algorithm and Huffman coding. | |||
Note: Some non-conformant implementations send the "deflate" | | *Note:* Some non-conformant implementations send the "deflate" | |||
compressed data without the zlib wrapper. | | compressed data without the zlib wrapper. | |||
8.4.1.3. Gzip Coding | 8.4.1.3. Gzip Coding | |||
The "gzip" coding is an LZ77 coding with a 32-bit Cyclic Redundancy | The "gzip" coding is an LZ77 coding with a 32-bit Cyclic Redundancy | |||
Check (CRC) that is commonly produced by the gzip file compression | Check (CRC) that is commonly produced by the gzip file compression | |||
program [RFC1952]. A recipient SHOULD consider "x-gzip" to be | program [RFC1952]. A recipient SHOULD consider "x-gzip" to be | |||
equivalent to "gzip". | equivalent to "gzip". | |||
8.5. Content-Language | 8.5. Content-Language | |||
The "Content-Language" header field describes the natural language(s) | The "Content-Language" header field describes the natural language(s) | |||
of the intended audience for the representation. Note that this | of the intended audience for the representation. Note that this | |||
might not be equivalent to all the languages used within the | might not be equivalent to all the languages used within the | |||
representation. | representation. | |||
Content-Language = 1#language-tag | Content-Language = #language-tag | |||
Language tags are defined in Section 3.1.3.1. The primary purpose of | Language tags are defined in Section 8.5.1. The primary purpose of | |||
Content-Language is to allow a user to identify and differentiate | Content-Language is to allow a user to identify and differentiate | |||
representations according to the users' own preferred language. | representations according to the users' own preferred language. | |||
Thus, if the content is intended only for a Danish-literate audience, | Thus, if the content is intended only for a Danish-literate audience, | |||
the appropriate field is | the appropriate field is | |||
Content-Language: da | Content-Language: da | |||
If no Content-Language is specified, the default is that the content | If no Content-Language is specified, the default is that the content | |||
is intended for all language audiences. This might mean that the | is intended for all language audiences. This might mean that the | |||
sender does not consider it to be specific to any natural language, | sender does not consider it to be specific to any natural language, | |||
skipping to change at line 2517 ¶ | skipping to change at page 65, line 24 ¶ | |||
Content-Language: mi, en | Content-Language: mi, en | |||
However, just because multiple languages are present within a | However, just because multiple languages are present within a | |||
representation does not mean that it is intended for multiple | representation does not mean that it is intended for multiple | |||
linguistic audiences. An example would be a beginner's language | linguistic audiences. An example would be a beginner's language | |||
primer, such as "A First Lesson in Latin", which is clearly intended | primer, such as "A First Lesson in Latin", which is clearly intended | |||
to be used by an English-literate audience. In this case, the | to be used by an English-literate audience. In this case, the | |||
Content-Language would properly only include "en". | Content-Language would properly only include "en". | |||
Content-Language MAY be applied to any media type -- it is not | Content-Language MAY be applied to any media type - it is not limited | |||
limited to textual documents. | to textual documents. | |||
8.5.1. Language Tags | 8.5.1. Language Tags | |||
A language tag, as defined in [RFC5646], identifies a natural | A language tag, as defined in [RFC5646], identifies a natural | |||
language spoken, written, or otherwise conveyed by human beings for | language spoken, written, or otherwise conveyed by human beings for | |||
communication of information to other human beings. Computer | communication of information to other human beings. Computer | |||
languages are explicitly excluded. | languages are explicitly excluded. | |||
HTTP uses language tags within the Accept-Language and | HTTP uses language tags within the Accept-Language and | |||
Content-Language header fields. Accept-Language uses the broader | Content-Language header fields. Accept-Language uses the broader | |||
language-range production defined in Section 5.3.5, whereas | language-range production defined in Section 12.5.4, whereas | |||
Content-Language uses the language-tag production defined below. | Content-Language uses the language-tag production defined below. | |||
language-tag = <Language-Tag, see [RFC5646], Section 2.1> | language-tag = <Language-Tag, see [RFC5646], Section 2.1> | |||
A language tag is a sequence of one or more case-insensitive subtags, | A language tag is a sequence of one or more case-insensitive subtags, | |||
each separated by a hyphen character ("-", %x2D). In most cases, a | each separated by a hyphen character ("-", %x2D). In most cases, a | |||
language tag consists of a primary language subtag that identifies a | language tag consists of a primary language subtag that identifies a | |||
broad family of related languages (e.g., "en" = English), which is | broad family of related languages (e.g., "en" = English), which is | |||
optionally followed by a series of subtags that refine or narrow that | optionally followed by a series of subtags that refine or narrow that | |||
language's range (e.g., "en-CA" = the variety of English as | language's range (e.g., "en-CA" = the variety of English as | |||
communicated in Canada). Whitespace is not allowed within a language | communicated in Canada). Whitespace is not allowed within a language | |||
tag. Example tags include: | tag. Example tags include: | |||
fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN | fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN | |||
See [RFC5646] for further information. | See [RFC5646] for further information. | |||
8.6. Content-Length | 8.6. Content-Length | |||
The "Content-Length" header field indicates the associated | ||||
representation's data length as a decimal non-negative integer number | ||||
of octets. When transferring a representation as content, Content- | ||||
Length refers specifically to the amount of data enclosed so that it | ||||
can be used to delimit framing (e.g., Section 6.2 of [Messaging]). | ||||
In other cases, Content-Length indicates the selected | ||||
representation's current length, which can be used by recipients to | ||||
estimate transfer time or compare to previously stored | ||||
representations. | ||||
Content-Length = 1*DIGIT | Content-Length = 1*DIGIT | |||
An example is | An example is | |||
Content-Length: 3495 | Content-Length: 3495 | |||
A sender MUST NOT send a Content-Length header field in any message | A sender MUST NOT send a Content-Length header field in any message | |||
that contains a Transfer-Encoding header field. | that contains a Transfer-Encoding header field. | |||
A user agent SHOULD send a Content-Length in a request message when | A user agent SHOULD send a Content-Length in a request message when | |||
no Transfer-Encoding is sent and the request method defines a meaning | no Transfer-Encoding is sent and the request method defines a meaning | |||
for an enclosed payload body. For example, a Content-Length header | for enclosed content. For example, a Content-Length header field is | |||
field is normally sent in a POST request even when the value is 0 | normally sent in a POST request even when the value is 0 (indicating | |||
(indicating an empty payload body). A user agent SHOULD NOT send a | empty content). A user agent SHOULD NOT send a Content-Length header | |||
Content-Length header field when the request message does not contain | field when the request message does not contain content and the | |||
a payload body and the method semantics do not anticipate such a | method semantics do not anticipate such data. | |||
body. | ||||
A server MAY send a Content-Length header field in a response to a | A server MAY send a Content-Length header field in a response to a | |||
HEAD request (Section 4.3.2 of [RFC7231]); a server MUST NOT send | HEAD request (Section 9.3.2); a server MUST NOT send Content-Length | |||
Content-Length in such a response unless its field-value equals the | in such a response unless its field value equals the decimal number | |||
decimal number of octets that would have been sent in the payload | of octets that would have been sent in the content of a response if | |||
body of a response if the same request had used the GET method. | the same request had used the GET method. | |||
A server MAY send a Content-Length header field in a 304 (Not | A server MAY send a Content-Length header field in a 304 (Not | |||
Modified) response to a conditional GET request (Section 4.1 of | Modified) response to a conditional GET request (Section 15.4.5); a | |||
[RFC7232]); a server MUST NOT send Content-Length in such a response | server MUST NOT send Content-Length in such a response unless its | |||
unless its field-value equals the decimal number of octets that would | field value equals the decimal number of octets that would have been | |||
have been sent in the payload body of a 200 (OK) response to the same | sent in the content of a 200 (OK) response to the same request. | |||
request. | ||||
A server MUST NOT send a Content-Length header field in any response | A server MUST NOT send a Content-Length header field in any response | |||
with a status code of 1xx (Informational) or 204 (No Content). A | with a status code of 1xx (Informational) or 204 (No Content). A | |||
server MUST NOT send a Content-Length header field in any 2xx | server MUST NOT send a Content-Length header field in any 2xx | |||
(Successful) response to a CONNECT request (Section 4.3.6 of | (Successful) response to a CONNECT request (Section 9.3.6). | |||
[RFC7231]). | ||||
Aside from the cases defined above, in the absence of | Aside from the cases defined above, in the absence of Transfer- | |||
Transfer-Encoding, an origin server SHOULD send a Content-Length | Encoding, an origin server SHOULD send a Content-Length header field | |||
header field when the payload body size is known prior to sending the | when the content size is known prior to sending the complete header | |||
complete header section. This will allow downstream recipients to | section. This will allow downstream recipients to measure transfer | |||
measure transfer progress, know when a received message is complete, | progress, know when a received message is complete, and potentially | |||
and potentially reuse the connection for additional requests. | reuse the connection for additional requests. | |||
Any Content-Length field value greater than or equal to zero is | Any Content-Length field value greater than or equal to zero is | |||
valid. Since there is no predefined limit to the length of a | valid. Since there is no predefined limit to the length of content, | |||
payload, a recipient MUST anticipate potentially large decimal | a recipient MUST anticipate potentially large decimal numerals and | |||
numerals and prevent parsing errors due to integer conversion | prevent parsing errors due to integer conversion overflows | |||
overflows (Section 9.3). | (Section 17.5). | |||
If a message is received that has multiple Content-Length header | If a message is received that has a Content-Length header field value | |||
fields with field-values consisting of the same decimal value, or a | consisting of the same decimal value as a comma-separated list | |||
single Content-Length header field with a field value containing a | (Section 5.6.1) - for example, "Content-Length: 42, 42" - indicating | |||
list of identical decimal values (e.g., "Content-Length: 42, 42"), | ||||
indicating | ||||
that duplicate Content-Length header fields have been generated or | that duplicate Content-Length header fields have been generated or | |||
combined by an upstream message processor, then the recipient MUST | combined by an upstream message processor, then the recipient MUST | |||
either reject the message as invalid or replace the duplicated | either reject the message as invalid or replace the duplicated field | |||
field-values with a single valid Content-Length field containing that | values with a single valid Content-Length field containing that | |||
decimal value prior to determining the message body length or | decimal value. | |||
forwarding the message. | ||||
8.7. Content-Location | 8.7. Content-Location | |||
The "Content-Location" header field references a URI that can be used | The "Content-Location" header field references a URI that can be used | |||
as an identifier for a specific resource corresponding to the | as an identifier for a specific resource corresponding to the | |||
representation in this message's payload. In other words, if one | representation in this message's content. In other words, if one | |||
were to perform a GET request on this URI at the time of this | were to perform a GET request on this URI at the time of this | |||
message's generation, then a 200 (OK) response would contain the same | message's generation, then a 200 (OK) response would contain the same | |||
representation that is enclosed as payload in this message. | representation that is enclosed as content in this message. | |||
Content-Location = absolute-URI / partial-URI | Content-Location = absolute-URI / partial-URI | |||
The Content-Location value is not a replacement for the effective | The field value is either an absolute-URI or a partial-URI. In the | |||
Request URI (Section 5.5 of [RFC7230]). It is representation | latter case (Section 4), the referenced URI is relative to the target | |||
metadata. It has the same syntax and semantics as the header field | URI ([RFC3986], Section 5). | |||
of the same name defined for MIME body parts in Section 4 of | ||||
[RFC2557]. However, its appearance in an HTTP message has some | The Content-Location value is not a replacement for the target URI | |||
special implications for HTTP recipients. | (Section 7.1). It is representation metadata. It has the same | |||
syntax and semantics as the header field of the same name defined for | ||||
MIME body parts in Section 4 of [RFC2557]. However, its appearance | ||||
in an HTTP message has some special implications for HTTP recipients. | ||||
If Content-Location is included in a 2xx (Successful) response | If Content-Location is included in a 2xx (Successful) response | |||
message and its value refers (after conversion to absolute form) to a | message and its value refers (after conversion to absolute form) to a | |||
URI that is the same as the effective request URI, then the recipient | URI that is the same as the target URI, then the recipient MAY | |||
MAY consider the payload to be a current representation of that | consider the content to be a current representation of that resource | |||
resource at the time indicated by the message origination date. For | at the time indicated by the message origination date. For a GET | |||
a GET (Section 4.3.1) or HEAD (Section 4.3.2) request, this is the | (Section 9.3.1) or HEAD (Section 9.3.2) request, this is the same as | |||
same as the default semantics when no Content-Location is provided by | the default semantics when no Content-Location is provided by the | |||
the server. For a state-changing request like PUT (Section 4.3.4) or | server. For a state-changing request like PUT (Section 9.3.4) or | |||
POST (Section 4.3.3), it implies that the server's response contains | POST (Section 9.3.3), it implies that the server's response contains | |||
the new representation of that resource, thereby distinguishing it | the new representation of that resource, thereby distinguishing it | |||
from representations that might only report about the action (e.g., | from representations that might only report about the action (e.g., | |||
"It worked!"). This allows authoring applications to update their | "It worked!"). This allows authoring applications to update their | |||
local copies without the need for a subsequent GET request. | local copies without the need for a subsequent GET request. | |||
If Content-Location is included in a 2xx (Successful) response | If Content-Location is included in a 2xx (Successful) response | |||
message and its field-value refers to a URI that differs from the | message and its field value refers to a URI that differs from the | |||
effective request URI, then the origin server claims that the URI is | target URI, then the origin server claims that the URI is an | |||
an identifier for a different resource corresponding to the enclosed | identifier for a different resource corresponding to the enclosed | |||
representation. Such a claim can only be trusted if both identifiers | representation. Such a claim can only be trusted if both identifiers | |||
share the same resource owner, which cannot be programmatically | share the same resource owner, which cannot be programmatically | |||
determined via HTTP. | determined via HTTP. | |||
o For a response to a GET or HEAD request, this is an indication | o For a response to a GET or HEAD request, this is an indication | |||
that the effective request URI refers to a resource that is | that the target URI refers to a resource that is subject to | |||
subject to content negotiation and the Content-Location | content negotiation and the Content-Location field value is a more | |||
field-value is a more specific identifier for the selected | specific identifier for the selected representation. | |||
representation. | ||||
o For a 201 (Created) response to a state-changing method, a | o For a 201 (Created) response to a state-changing method, a | |||
Content-Location field-value that is identical to the Location | Content-Location field value that is identical to the Location | |||
field-value indicates that this payload is a current | field value indicates that this content is a current | |||
representation of the newly created resource. | representation of the newly created resource. | |||
o Otherwise, such a Content-Location indicates that this payload is | o Otherwise, such a Content-Location indicates that this content is | |||
a representation reporting on the requested action's status and | a representation reporting on the requested action's status and | |||
that the same report is available (for future access with GET) at | that the same report is available (for future access with GET) at | |||
the given URI. For example, a purchase transaction made via a | the given URI. For example, a purchase transaction made via a | |||
POST request might include a receipt document as the payload of | POST request might include a receipt document as the content of | |||
the 200 (OK) response; the Content-Location field-value provides | the 200 (OK) response; the Content-Location field value provides | |||
an identifier for retrieving a copy of that same receipt in the | an identifier for retrieving a copy of that same receipt in the | |||
future. | future. | |||
A user agent that sends Content-Location in a request message is | A user agent that sends Content-Location in a request message is | |||
stating that its value refers to where the user agent originally | stating that its value refers to where the user agent originally | |||
obtained the content of the enclosed representation (prior to any | obtained the content of the enclosed representation (prior to any | |||
modifications made by that user agent). In other words, the user | modifications made by that user agent). In other words, the user | |||
agent is providing a back link to the source of the original | agent is providing a back link to the source of the original | |||
representation. | representation. | |||
skipping to change at line 2695 ¶ | skipping to change at page 69, line 22 ¶ | |||
For example, if a client makes a PUT request on a negotiated resource | For example, if a client makes a PUT request on a negotiated resource | |||
and the origin server accepts that PUT (without redirection), then | and the origin server accepts that PUT (without redirection), then | |||
the new state of that resource is expected to be consistent with the | the new state of that resource is expected to be consistent with the | |||
one representation supplied in that PUT; the Content-Location cannot | one representation supplied in that PUT; the Content-Location cannot | |||
be used as a form of reverse content selection identifier to update | be used as a form of reverse content selection identifier to update | |||
only one of the negotiated representations. If the user agent had | only one of the negotiated representations. If the user agent had | |||
wanted the latter semantics, it would have applied the PUT directly | wanted the latter semantics, it would have applied the PUT directly | |||
to the Content-Location URI. | to the Content-Location URI. | |||
8.8. Validator Header Fields | 8.8. Validator Fields | |||
Validator header fields convey metadata about the selected | Validator fields convey metadata about the selected representation | |||
representation (Section 3). In responses to safe requests, validator | (Section 3.2). In responses to safe requests, validator fields | |||
fields describe the selected representation chosen by the origin | describe the selected representation chosen by the origin server | |||
server while handling the response. Note that, depending on the | while handling the response. Note that, depending on the status code | |||
status code semantics, the selected representation for a given | semantics, the selected representation for a given response is not | |||
response is not necessarily the same as the representation enclosed | necessarily the same as the representation enclosed as response | |||
as response payload. | content. | |||
In a successful response to a state-changing request, validator | In a successful response to a state-changing request, validator | |||
fields describe the new representation that has replaced the prior | fields describe the new representation that has replaced the prior | |||
selected representation as a result of processing the request. | selected representation as a result of processing the request. | |||
For example, an ETag header field in a 201 (Created) response | For example, an ETag field in a 201 (Created) response communicates | |||
communicates the entity-tag of the newly created resource's | the entity-tag of the newly created resource's representation, so | |||
representation, so that it can be used in later conditional requests | that it can be used in later conditional requests to prevent the | |||
to prevent the "lost update" problem [RFC7232]. | "lost update" problem Section 13.1. | |||
This specification defines two forms of metadata that are commonly | This specification defines two forms of metadata that are commonly | |||
used to observe resource state and test for preconditions: | used to observe resource state and test for preconditions: | |||
modification dates (Section 2.2) and opaque entity tags | modification dates (Section 8.8.2) and opaque entity tags | |||
(Section 2.3). Additional metadata that reflects resource state has | (Section 8.8.3). Additional metadata that reflects resource state | |||
been defined by various extensions of HTTP, such as Web Distributed | has been defined by various extensions of HTTP, such as Web | |||
Authoring and Versioning (WebDAV, [RFC4918]), that are beyond the | Distributed Authoring and Versioning (WebDAV, [RFC4918]), that are | |||
scope of this specification. A resource metadata value is referred | beyond the scope of this specification. A resource metadata value is | |||
to as a "validator" when it is used within a precondition. | referred to as a _validator_ when it is used within a precondition. | |||
8.8.1. Weak versus Strong | 8.8.1. Weak versus Strong | |||
Validators come in two flavors: strong or weak. Weak validators are | Validators come in two flavors: strong or weak. Weak validators are | |||
easy to generate but are far less useful for comparisons. Strong | easy to generate but are far less useful for comparisons. Strong | |||
validators are ideal for comparisons but can be very difficult (and | validators are ideal for comparisons but can be very difficult (and | |||
occasionally impossible) to generate efficiently. Rather than impose | occasionally impossible) to generate efficiently. Rather than impose | |||
that all forms of resource adhere to the same strength of validator, | that all forms of resource adhere to the same strength of validator, | |||
HTTP exposes the type of validator in use and imposes restrictions on | HTTP exposes the type of validator in use and imposes restrictions on | |||
when weak validators can be used as preconditions. | when weak validators can be used as preconditions. | |||
A "strong validator" is representation metadata that changes value | A _strong validator_ is representation metadata that changes value | |||
whenever a change occurs to the representation data that would be | whenever a change occurs to the representation data that would be | |||
observable in the payload body of a 200 (OK) response to GET. | observable in the content of a 200 (OK) response to GET. | |||
A strong validator might change for reasons other than a change to | A strong validator might change for reasons other than a change to | |||
the representation data, such as when a semantically significant part | the representation data, such as when a semantically significant part | |||
of the representation metadata is changed (e.g., Content-Type), but | of the representation metadata is changed (e.g., Content-Type), but | |||
it is in the best interests of the origin server to only change the | it is in the best interests of the origin server to only change the | |||
value when it is necessary to invalidate the stored responses held by | value when it is necessary to invalidate the stored responses held by | |||
remote caches and authoring tools. | remote caches and authoring tools. | |||
Cache entries might persist for arbitrarily long periods, regardless | Cache entries might persist for arbitrarily long periods, regardless | |||
of expiration times. Thus, a cache might attempt to validate an | of expiration times. Thus, a cache might attempt to validate an | |||
skipping to change at line 2768 ¶ | skipping to change at page 70, line 50 ¶ | |||
accessible to GET. A collision-resistant hash function applied to | accessible to GET. A collision-resistant hash function applied to | |||
the representation data is also sufficient if the data is available | the representation data is also sufficient if the data is available | |||
prior to the response header fields being sent and the digest does | prior to the response header fields being sent and the digest does | |||
not need to be recalculated every time a validation request is | not need to be recalculated every time a validation request is | |||
received. However, if a resource has distinct representations that | received. However, if a resource has distinct representations that | |||
differ only in their metadata, such as might occur with content | differ only in their metadata, such as might occur with content | |||
negotiation over media types that happen to share the same data | negotiation over media types that happen to share the same data | |||
format, then the origin server needs to incorporate additional | format, then the origin server needs to incorporate additional | |||
information in the validator to distinguish those representations. | information in the validator to distinguish those representations. | |||
In contrast, a "weak validator" is representation metadata that might | In contrast, a _weak validator_ is representation metadata that might | |||
not change for every change to the representation data. This | not change for every change to the representation data. This | |||
weakness might be due to limitations in how the value is calculated, | weakness might be due to limitations in how the value is calculated, | |||
such as clock resolution, an inability to ensure uniqueness for all | such as clock resolution, an inability to ensure uniqueness for all | |||
possible representations of the resource, or a desire of the resource | possible representations of the resource, or a desire of the resource | |||
owner to group representations by some self-determined set of | owner to group representations by some self-determined set of | |||
equivalency rather than unique sequences of data. An origin server | equivalency rather than unique sequences of data. An origin server | |||
SHOULD change a weak entity-tag whenever it considers prior | SHOULD change a weak entity-tag whenever it considers prior | |||
representations to be unacceptable as a substitute for the current | representations to be unacceptable as a substitute for the current | |||
representation. In other words, a weak entity-tag ought to change | representation. In other words, a weak entity-tag ought to change | |||
whenever the origin server wants caches to invalidate old responses. | whenever the origin server wants caches to invalidate old responses. | |||
skipping to change at line 2818 ¶ | skipping to change at page 72, line 4 ¶ | |||
8.8.2. Last-Modified | 8.8.2. Last-Modified | |||
The "Last-Modified" header field in a response provides a timestamp | The "Last-Modified" header field in a response provides a timestamp | |||
indicating the date and time at which the origin server believes the | indicating the date and time at which the origin server believes the | |||
selected representation was last modified, as determined at the | selected representation was last modified, as determined at the | |||
conclusion of handling the request. | conclusion of handling the request. | |||
Last-Modified = HTTP-date | Last-Modified = HTTP-date | |||
An example of its use is | An example of its use is | |||
Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT | Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT | |||
8.8.2.1. Generation | 8.8.2.1. Generation | |||
An origin server SHOULD send Last-Modified for any selected | An origin server SHOULD send Last-Modified for any selected | |||
representation for which a last modification date can be reasonably | representation for which a last modification date can be reasonably | |||
and consistently determined, since its use in conditional requests | and consistently determined, since its use in conditional requests | |||
and evaluating cache freshness ([RFC7234]) results in a substantial | and evaluating cache freshness ([Caching]) results in a substantial | |||
reduction of HTTP traffic on the Internet and can be a significant | reduction of HTTP traffic on the Internet and can be a significant | |||
factor in improving service scalability and reliability. | factor in improving service scalability and reliability. | |||
A representation is typically the sum of many parts behind the | A representation is typically the sum of many parts behind the | |||
resource interface. The last-modified time would usually be the most | resource interface. The last-modified time would usually be the most | |||
recent time that any of those parts were changed. How that value is | recent time that any of those parts were changed. How that value is | |||
determined for any given resource is an implementation detail beyond | determined for any given resource is an implementation detail beyond | |||
the scope of this specification. What matters to HTTP is how | the scope of this specification. What matters to HTTP is how | |||
recipients of the Last-Modified header field can use its value to | recipients of the Last-Modified header field can use its value to | |||
make conditional requests and test the validity of locally cached | make conditional requests and test the validity of locally cached | |||
skipping to change at line 2869 ¶ | skipping to change at page 73, line 7 ¶ | |||
A Last-Modified time, when used as a validator in a request, is | A Last-Modified time, when used as a validator in a request, is | |||
implicitly weak unless it is possible to deduce that it is strong, | implicitly weak unless it is possible to deduce that it is strong, | |||
using the following rules: | using the following rules: | |||
o The validator is being compared by an origin server to the actual | o The validator is being compared by an origin server to the actual | |||
current validator for the representation and, | current validator for the representation and, | |||
o That origin server reliably knows that the associated | o That origin server reliably knows that the associated | |||
representation did not change twice during the second covered by | representation did not change twice during the second covered by | |||
the presented validator. | the presented validator; | |||
or | or | |||
o The validator is about to be used by a client in an | o The validator is about to be used by a client in an | |||
If-Modified-Since, If-Unmodified-Since, or If-Range header field, | If-Modified-Since, If-Unmodified-Since, or If-Range header field, | |||
because the client has a cache entry for the associated | because the client has a cache entry for the associated | |||
representation, and | representation, and | |||
o That cache entry includes a Date value, which gives the time when | o That cache entry includes a Date value which is at least one | |||
the origin server sent the original response, and | second after the Last-Modified value and the client has reason to | |||
believe that they were generated by the same clock or that there | ||||
o The presented Last-Modified time is at least 60 seconds before the | is enough difference between the Last-Modified and Date values to | |||
Date value. | make clock synchronization issues unlikely; | |||
or | or | |||
o The validator is being compared by an intermediate cache to the | o The validator is being compared by an intermediate cache to the | |||
validator stored in its cache entry for the representation, and | validator stored in its cache entry for the representation, and | |||
o That cache entry includes a Date value, which gives the time when | o That cache entry includes a Date value which is at least one | |||
the origin server sent the original response, and | second after the Last-Modified value and the cache has reason to | |||
believe that they were generated by the same clock or that there | ||||
o The presented Last-Modified time is at least 60 seconds before the | is enough difference between the Last-Modified and Date values to | |||
Date value. | make clock synchronization issues unlikely. | |||
This method relies on the fact that if two different responses were | This method relies on the fact that if two different responses were | |||
sent by the origin server during the same second, but both had the | sent by the origin server during the same second, but both had the | |||
same Last-Modified time, then at least one of those responses would | same Last-Modified time, then at least one of those responses would | |||
have a Date value equal to its Last-Modified time. The arbitrary | have a Date value equal to its Last-Modified time. | |||
60-second limit guards against the possibility that the Date and | ||||
Last-Modified values are generated from different clocks or at | ||||
somewhat different times during the preparation of the response. An | ||||
implementation MAY use a value larger than 60 seconds, if it is | ||||
believed that 60 seconds is too short. | ||||
8.8.3. ETag | 8.8.3. ETag | |||
The "ETag" header field in a response provides the current entity-tag | The "ETag" field in a response provides the current entity-tag for | |||
for the selected representation, as determined at the conclusion of | the selected representation, as determined at the conclusion of | |||
handling the request. An entity-tag is an opaque validator for | handling the request. An entity-tag is an opaque validator for | |||
differentiating between multiple representations of the same | differentiating between multiple representations of the same | |||
resource, regardless of whether those multiple representations are | resource, regardless of whether those multiple representations are | |||
due to resource state changes over time, content negotiation | due to resource state changes over time, content negotiation | |||
resulting in multiple representations being valid at the same time, | resulting in multiple representations being valid at the same time, | |||
or both. An entity-tag consists of an opaque quoted string, possibly | or both. An entity-tag consists of an opaque quoted string, possibly | |||
prefixed by a weakness indicator. | prefixed by a weakness indicator. | |||
ETag = entity-tag | ETag = entity-tag | |||
entity-tag = [ weak ] opaque-tag | entity-tag = [ weak ] opaque-tag | |||
weak = %x57.2F ; "W/", case-sensitive | weak = %s"W/" | |||
opaque-tag = DQUOTE *etagc DQUOTE | opaque-tag = DQUOTE *etagc DQUOTE | |||
etagc = %x21 / %x23-7E / obs-text | etagc = %x21 / %x23-7E / obs-text | |||
; VCHAR except double quotes, plus obs-text | ; VCHAR except double quotes, plus obs-text | |||
Note: Previously, opaque-tag was defined to be a quoted-string | | *Note:* Previously, opaque-tag was defined to be a quoted- | |||
([RFC2616], Section 3.11); thus, some recipients might perform | | string ([RFC2616], Section 3.11); thus, some recipients might | |||
backslash unescaping. Servers therefore ought to avoid backslash | | perform backslash unescaping. Servers therefore ought to avoid | |||
characters in entity tags. | | backslash characters in entity tags. | |||
An entity-tag can be more reliable for validation than a modification | An entity-tag can be more reliable for validation than a modification | |||
date in situations where it is inconvenient to store modification | date in situations where it is inconvenient to store modification | |||
dates, where the one-second resolution of HTTP date values is not | dates, where the one-second resolution of HTTP date values is not | |||
sufficient, or where modification dates are not consistently | sufficient, or where modification dates are not consistently | |||
maintained. | maintained. | |||
Examples: | Examples: | |||
ETag: "xyzzy" | ETag: "xyzzy" | |||
ETag: W/"xyzzy" | ETag: W/"xyzzy" | |||
ETag: "" | ETag: "" | |||
An entity-tag can be either a weak or strong validator, with strong | An entity-tag can be either a weak or strong validator, with strong | |||
being the default. If an origin server provides an entity-tag for a | being the default. If an origin server provides an entity-tag for a | |||
representation and the generation of that entity-tag does not satisfy | representation and the generation of that entity-tag does not satisfy | |||
all of the characteristics of a strong validator (Section 2.1), then | all of the characteristics of a strong validator (Section 8.8.1), | |||
the origin server MUST mark the entity-tag as weak by prefixing its | then the origin server MUST mark the entity-tag as weak by prefixing | |||
opaque value with "W/" (case-sensitive). | its opaque value with "W/" (case-sensitive). | |||
A sender MAY send the Etag field in a trailer section (see | ||||
Section 6.5). However, since trailers are often ignored, it is | ||||
preferable to send Etag as a header field unless the entity-tag is | ||||
generated while sending the content. | ||||
8.8.3.1. Generation | 8.8.3.1. Generation | |||
The principle behind entity-tags is that only the service author | The principle behind entity-tags is that only the service author | |||
knows the implementation of a resource well enough to select the most | knows the implementation of a resource well enough to select the most | |||
accurate and efficient validation mechanism for that resource, and | accurate and efficient validation mechanism for that resource, and | |||
that any such mechanism can be mapped to a simple sequence of octets | that any such mechanism can be mapped to a simple sequence of octets | |||
for easy comparison. Since the value is opaque, there is no need for | for easy comparison. Since the value is opaque, there is no need for | |||
the client to be aware of how each entity-tag is constructed. | the client to be aware of how each entity-tag is constructed. | |||
skipping to change at line 2969 ¶ | skipping to change at page 75, line 16 ¶ | |||
applied to all changes might use an internal revision number, perhaps | applied to all changes might use an internal revision number, perhaps | |||
combined with a variance identifier for content negotiation, to | combined with a variance identifier for content negotiation, to | |||
accurately differentiate between representations. Other | accurately differentiate between representations. Other | |||
implementations might use a collision-resistant hash of | implementations might use a collision-resistant hash of | |||
representation content, a combination of various file attributes, or | representation content, a combination of various file attributes, or | |||
a modification timestamp that has sub-second resolution. | a modification timestamp that has sub-second resolution. | |||
An origin server SHOULD send an ETag for any selected representation | An origin server SHOULD send an ETag for any selected representation | |||
for which detection of changes can be reasonably and consistently | for which detection of changes can be reasonably and consistently | |||
determined, since the entity-tag's use in conditional requests and | determined, since the entity-tag's use in conditional requests and | |||
evaluating cache freshness ([RFC7234]) can result in a substantial | evaluating cache freshness ([Caching]) can result in a substantial | |||
reduction of HTTP network traffic and can be a significant factor in | reduction of HTTP network traffic and can be a significant factor in | |||
improving service scalability and reliability. | improving service scalability and reliability. | |||
8.8.3.2. Comparison | 8.8.3.2. Comparison | |||
There are two entity-tag comparison functions, depending on whether | There are two entity-tag comparison functions, depending on whether | |||
or not the comparison context allows the use of weak validators: | or not the comparison context allows the use of weak validators: | |||
o Strong comparison: two entity-tags are equivalent if both are not | _Strong comparison_: two entity-tags are equivalent if both are not | |||
weak and their opaque-tags match character-by-character. | weak and their opaque-tags match character-by-character. | |||
o Weak comparison: two entity-tags are equivalent if their | _Weak comparison_: two entity-tags are equivalent if their opaque- | |||
opaque-tags match character-by-character, regardless of either or | tags match character-by-character, regardless of either or both | |||
both being tagged as "weak". | being tagged as "weak". | |||
The example below shows the results for a set of entity-tag pairs and | The example below shows the results for a set of entity-tag pairs and | |||
both the weak and strong comparison function results: | both the weak and strong comparison function results: | |||
+--------+--------+-------------------+-----------------+ | -------- -------- ------------------- ----------------- | |||
| ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | | ETag 1 ETag 2 Strong Comparison Weak Comparison | |||
+--------+--------+-------------------+-----------------+ | -------- -------- ------------------- ----------------- | |||
| W/"1" | W/"1" | no match | match | | W/"1" W/"1" no match match | |||
| W/"1" | W/"2" | no match | no match | | W/"1" W/"2" no match no match | |||
| W/"1" | "1" | no match | match | | W/"1" "1" no match match | |||
| "1" | "1" | match | match | | "1" "1" match match | |||
+--------+--------+-------------------+-----------------+ | -------- -------- ------------------- ----------------- | |||
Table 3 | ||||
8.8.3.3. Example: Entity-Tags Varying on Content-Negotiated Resources | 8.8.3.3. Example: Entity-Tags Varying on Content-Negotiated Resources | |||
Consider a resource that is subject to content negotiation (Section | Consider a resource that is subject to content negotiation | |||
3.4 of [RFC7231]), and where the representations sent in response to | (Section 12), and where the representations sent in response to a GET | |||
a GET request vary based on the Accept-Encoding request header field | request vary based on the Accept-Encoding request header field | |||
(Section 5.3.4 of [RFC7231]): | (Section 12.5.3): | |||
>> Request: | >> Request: | |||
GET /index HTTP/1.1 | GET /index HTTP/1.1 | |||
Host: www.example.com | Host: www.example.com | |||
Accept-Encoding: gzip | Accept-Encoding: gzip | |||
In this case, the response might or might not use the gzip content | In this case, the response might or might not use the gzip content | |||
coding. If it does not, the response might look like: | coding. If it does not, the response might look like: | |||
skipping to change at line 3043 ¶ | skipping to change at page 76, line 44 ¶ | |||
HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
Date: Fri, 26 Mar 2010 00:05:00 GMT | Date: Fri, 26 Mar 2010 00:05:00 GMT | |||
ETag: "123-b" | ETag: "123-b" | |||
Content-Length: 43 | Content-Length: 43 | |||
Vary: Accept-Encoding | Vary: Accept-Encoding | |||
Content-Type: text/plain | Content-Type: text/plain | |||
Content-Encoding: gzip | Content-Encoding: gzip | |||
...binary data... | ...binary data... | |||
Note: Content codings are a property of the representation data, | | *Note:* Content codings are a property of the representation | |||
so a strong entity-tag for a content-encoded representation has to | | data, so a strong entity-tag for a content-encoded | |||
be distinct from the entity tag of an unencoded representation to | | representation has to be distinct from the entity tag of an | |||
prevent potential conflicts during cache updates and range | | unencoded representation to prevent potential conflicts during | |||
requests. In contrast, transfer codings (Section 4 of [RFC7230]) | | cache updates and range requests. In contrast, transfer | |||
apply only during message transfer and do not result in distinct | | codings (Section 7 of [Messaging]) apply only during message | |||
entity-tags. | | transfer and do not result in distinct entity-tags. | |||
8.8.4. When to Use Entity-Tags and Last-Modified Dates | 8.8.4. When to Use Entity-Tags and Last-Modified Dates | |||
In 200 (OK) responses to GET or HEAD, an origin server: | In 200 (OK) responses to GET or HEAD, an origin server: | |||
o SHOULD send an entity-tag validator unless it is not feasible to | o SHOULD send an entity-tag validator unless it is not feasible to | |||
generate one. | generate one. | |||
o MAY send a weak entity-tag instead of a strong entity-tag, if | o MAY send a weak entity-tag instead of a strong entity-tag, if | |||
performance considerations support the use of weak entity-tags, or | performance considerations support the use of weak entity-tags, or | |||
skipping to change at line 3075 ¶ | skipping to change at page 77, line 29 ¶ | |||
send both a strong entity-tag and a Last-Modified value in successful | send both a strong entity-tag and a Last-Modified value in successful | |||
responses to a retrieval request. | responses to a retrieval request. | |||
A client: | A client: | |||
o MUST send that entity-tag in any cache validation request (using | o MUST send that entity-tag in any cache validation request (using | |||
If-Match or If-None-Match) if an entity-tag has been provided by | If-Match or If-None-Match) if an entity-tag has been provided by | |||
the origin server. | the origin server. | |||
o SHOULD send the Last-Modified value in non-subrange cache | o SHOULD send the Last-Modified value in non-subrange cache | |||
validation requests (using If-Modified-Since) if only a | validation requests (using If-Modified-Since) if only a Last- | |||
Last-Modified value has been provided by the origin server. | Modified value has been provided by the origin server. | |||
o MAY send the Last-Modified value in subrange cache validation | o MAY send the Last-Modified value in subrange cache validation | |||
requests (using If-Unmodified-Since) if only a Last-Modified value | requests (using If-Unmodified-Since) if only a Last-Modified value | |||
has been provided by an HTTP/1.0 origin server. The user agent | has been provided by an HTTP/1.0 origin server. The user agent | |||
SHOULD provide a way to disable this, in case of difficulty. | SHOULD provide a way to disable this, in case of difficulty. | |||
o SHOULD send both validators in cache validation requests if both | o SHOULD send both validators in cache validation requests if both | |||
an entity-tag and a Last-Modified value have been provided by the | an entity-tag and a Last-Modified value have been provided by the | |||
origin server. This allows both HTTP/1.0 and HTTP/1.1 caches to | origin server. This allows both HTTP/1.0 and HTTP/1.1 caches to | |||
respond appropriately. | respond appropriately. | |||
9. Methods | 9. Methods | |||
9.1. Overview | 9.1. Overview | |||
The request method token is the primary source of request semantics; | The request method token is the primary source of request semantics; | |||
it indicates the purpose for which the client has made this request | it indicates the purpose for which the client has made this request | |||
and what is expected by the client as a successful result. | and what is expected by the client as a successful result. | |||
The request method's semantics might be further specialized by the | The request method's semantics might be further specialized by the | |||
semantics of some header fields when present in a request (Section 5) | semantics of some header fields when present in a request if those | |||
if those additional semantics do not conflict with the method. For | additional semantics do not conflict with the method. For example, a | |||
example, a client can send conditional request header fields | client can send conditional request header fields (Section 13.1) to | |||
(Section 5.2) to make the requested action conditional on the current | make the requested action conditional on the current state of the | |||
state of the target resource ([RFC7232]). | target resource. | |||
method = token | ||||
HTTP was originally designed to be usable as an interface to | HTTP was originally designed to be usable as an interface to | |||
distributed object systems. The request method was envisioned as | distributed object systems. The request method was envisioned as | |||
applying semantics to a target resource in much the same way as | applying semantics to a target resource in much the same way as | |||
invoking a defined method on an identified object would apply | invoking a defined method on an identified object would apply | |||
semantics. | semantics. | |||
method = token | ||||
The method token is case-sensitive because it might be used as a | The method token is case-sensitive because it might be used as a | |||
gateway to object-based systems with case-sensitive method names. | gateway to object-based systems with case-sensitive method names. By | |||
By convention, standardized methods are defined in all-uppercase | convention, standardized methods are defined in all-uppercase US- | |||
US-ASCII letters. | ASCII letters. | |||
Unlike distributed objects, the standardized request methods in HTTP | Unlike distributed objects, the standardized request methods in HTTP | |||
are not resource-specific, since uniform interfaces provide for | are not resource-specific, since uniform interfaces provide for | |||
better visibility and reuse in network-based systems [REST]. Once | better visibility and reuse in network-based systems [REST]. Once | |||
defined, a standardized method ought to have the same semantics when | defined, a standardized method ought to have the same semantics when | |||
applied to any resource, though each resource determines for itself | applied to any resource, though each resource determines for itself | |||
whether those semantics are implemented or allowed. | whether those semantics are implemented or allowed. | |||
This specification defines a number of standardized methods that are | This specification defines a number of standardized methods that are | |||
commonly used in HTTP, as outlined by the following table. | commonly used in HTTP, as outlined by the following table. | |||
+---------+-------------------------------------------------+-------+ | --------- -------------------------------------------- ------- | |||
| Method | Description | Sec. | | Method Description Ref. | |||
+---------+-------------------------------------------------+-------+ | --------- -------------------------------------------- ------- | |||
| GET | Transfer a current representation of the target | 4.3.1 | | GET Transfer a current representation of the 9.3.1 | |||
| | resource. | | | target resource. | |||
| HEAD | Same as GET, but only transfer the status line | 4.3.2 | | HEAD Same as GET, but do not transfer the 9.3.2 | |||
| | and header section. | | | response content. | |||
| POST | Perform resource-specific processing on the | 4.3.3 | | POST Perform resource-specific processing on 9.3.3 | |||
| | request payload. | | | the request content. | |||
| PUT | Replace all current representations of the | 4.3.4 | | PUT Replace all current representations of the 9.3.4 | |||
| | target resource with the request payload. | | | target resource with the request content. | |||
| DELETE | Remove all current representations of the | 4.3.5 | | DELETE Remove all current representations of the 9.3.5 | |||
| | target resource. | | | target resource. | |||
| CONNECT | Establish a tunnel to the server identified by | 4.3.6 | | CONNECT Establish a tunnel to the server 9.3.6 | |||
| | the target resource. | | | identified by the target resource. | |||
| OPTIONS | Describe the communication options for the | 4.3.7 | | OPTIONS Describe the communication options for the 9.3.7 | |||
| | target resource. | | | target resource. | |||
| TRACE | Perform a message loop-back test along the path | 4.3.8 | | TRACE Perform a message loop-back test along the 9.3.8 | |||
| | to the target resource. | | | path to the target resource. | |||
+---------+-------------------------------------------------+-------+ | --------- -------------------------------------------- ------- | |||
Table 4 | ||||
All general-purpose servers MUST support the methods GET and HEAD. | All general-purpose servers MUST support the methods GET and HEAD. | |||
All other methods are OPTIONAL. | All other methods are OPTIONAL. | |||
The set of methods allowed by a target resource can be listed in an | The set of methods allowed by a target resource can be listed in an | |||
Allow header field (Section 7.4.1). However, the set of allowed | Allow header field (Section 10.2.1). However, the set of allowed | |||
methods can change dynamically. When a request method is received | methods can change dynamically. When a request method is received | |||
that is unrecognized or not implemented by an origin server, the | that is unrecognized or not implemented by an origin server, the | |||
origin server SHOULD respond with the 501 (Not Implemented) status | origin server SHOULD respond with the 501 (Not Implemented) status | |||
code. When a request method is received that is known by an origin | code. When a request method is received that is known by an origin | |||
server but not allowed for the target resource, the origin server | server but not allowed for the target resource, the origin server | |||
SHOULD respond with the 405 (Method Not Allowed) status code. | SHOULD respond with the 405 (Method Not Allowed) status code. | |||
Additional methods, outside the scope of this specification, have | Additional methods, outside the scope of this specification, have | |||
been standardized for use in HTTP. All such methods ought to be | been specified for use in HTTP. All such methods ought to be | |||
registered within the "Hypertext Transfer Protocol (HTTP) Method | registered within the "Hypertext Transfer Protocol (HTTP) Method | |||
Registry" maintained by IANA, as defined in Section 8.1. | Registry", as described in Section 16.1. | |||
9.2. Common Method Properties | 9.2. Common Method Properties | |||
9.2.1. Safe Methods | 9.2.1. Safe Methods | |||
Request methods are considered "safe" if their defined semantics are | Request methods are considered _safe_ if their defined semantics are | |||
essentially read-only; i.e., the client does not request, and does | essentially read-only; i.e., the client does not request, and does | |||
not expect, any state change on the origin server as a result of | not expect, any state change on the origin server as a result of | |||
applying a safe method to a target resource. Likewise, reasonable | applying a safe method to a target resource. Likewise, reasonable | |||
use of a safe method is not expected to cause any harm, loss of | use of a safe method is not expected to cause any harm, loss of | |||
property, or unusual burden on the origin server. | property, or unusual burden on the origin server. | |||
This definition of safe methods does not prevent an implementation | This definition of safe methods does not prevent an implementation | |||
from including behavior that is potentially harmful, that is not | from including behavior that is potentially harmful, that is not | |||
entirely read-only, or that causes side effects while invoking a safe | entirely read-only, or that causes side effects while invoking a safe | |||
method. What is important, however, is that the client did not | method. What is important, however, is that the client did not | |||
skipping to change at line 3201 ¶ | skipping to change at page 80, line 39 ¶ | |||
allow automated retrieval processes (spiders) and cache performance | allow automated retrieval processes (spiders) and cache performance | |||
optimization (pre-fetching) to work without fear of causing harm. In | optimization (pre-fetching) to work without fear of causing harm. In | |||
addition, it allows a user agent to apply appropriate constraints on | addition, it allows a user agent to apply appropriate constraints on | |||
the automated use of unsafe methods when processing potentially | the automated use of unsafe methods when processing potentially | |||
untrusted content. | untrusted content. | |||
A user agent SHOULD distinguish between safe and unsafe methods when | A user agent SHOULD distinguish between safe and unsafe methods when | |||
presenting potential actions to a user, such that the user can be | presenting potential actions to a user, such that the user can be | |||
made aware of an unsafe action before it is requested. | made aware of an unsafe action before it is requested. | |||
When a resource is constructed such that parameters within the | When a resource is constructed such that parameters within the target | |||
effective request URI have the effect of selecting an action, it is | URI have the effect of selecting an action, it is the resource | |||
the resource owner's responsibility to ensure that the action is | owner's responsibility to ensure that the action is consistent with | |||
consistent with the request method semantics. For example, it is | the request method semantics. For example, it is common for Web- | |||
common for Web-based content editing software to use actions within | based content editing software to use actions within query | |||
query parameters, such as "page?do=delete". If the purpose of such a | parameters, such as "page?do=delete". If the purpose of such a | |||
resource is to perform an unsafe action, then the resource owner MUST | resource is to perform an unsafe action, then the resource owner MUST | |||
disable or disallow that action when it is accessed using a safe | disable or disallow that action when it is accessed using a safe | |||
request method. Failure to do so will result in unfortunate side | request method. Failure to do so will result in unfortunate side | |||
effects when automated processes perform a GET on every URI reference | effects when automated processes perform a GET on every URI reference | |||
for the sake of link maintenance, pre-fetching, building a search | for the sake of link maintenance, pre-fetching, building a search | |||
index, etc. | index, etc. | |||
9.2.2. Idempotent Methods | 9.2.2. Idempotent Methods | |||
A request method is considered "idempotent" if the intended effect on | A request method is considered _idempotent_ if the intended effect on | |||
the server of multiple identical requests with that method is the | the server of multiple identical requests with that method is the | |||
same as the effect for a single such request. Of the request methods | same as the effect for a single such request. Of the request methods | |||
defined by this specification, PUT, DELETE, and safe request methods | defined by this specification, PUT, DELETE, and safe request methods | |||
are idempotent. | are idempotent. | |||
Like the definition of safe, the idempotent property only applies to | Like the definition of safe, the idempotent property only applies to | |||
what has been requested by the user; a server is free to log each | what has been requested by the user; a server is free to log each | |||
request separately, retain a revision control history, or implement | request separately, retain a revision control history, or implement | |||
other non-idempotent side effects for each idempotent request. | other non-idempotent side effects for each idempotent request. | |||
Idempotent methods are distinguished because the request can be | Idempotent methods are distinguished because the request can be | |||
repeated automatically if a communication failure occurs before the | repeated automatically if a communication failure occurs before the | |||
client is able to read the server's response. For example, if a | client is able to read the server's response. For example, if a | |||
client sends a PUT request and the underlying connection is closed | client sends a PUT request and the underlying connection is closed | |||
before any response is received, then the client can establish a new | before any response is received, then the client can establish a new | |||
connection and retry the idempotent request. It knows that repeating | connection and retry the idempotent request. It knows that repeating | |||
the request will have the same intended effect, even if the original | the request will have the same intended effect, even if the original | |||
request succeeded, though the response might differ. | request succeeded, though the response might differ. | |||
A user agent MUST NOT automatically retry a request with a non- | A client SHOULD NOT automatically retry a request with a non- | |||
idempotent method unless it has some means to know that the request | idempotent method unless it has some means to know that the request | |||
semantics are actually idempotent, regardless of the method, or some | semantics are actually idempotent, regardless of the method, or some | |||
means to detect that the original request was never applied. | means to detect that the original request was never applied. | |||
For example, a user agent that knows (through design or | For example, a user agent that knows (through design or | |||
configuration) that a POST request to a given resource is safe can | configuration) that a POST request to a given resource is safe can | |||
repeat that request automatically. Likewise, a user agent designed | repeat that request automatically. Likewise, a user agent designed | |||
specifically to operate on a version control repository might be able | specifically to operate on a version control repository might be able | |||
to recover from partial failure conditions by checking the target | to recover from partial failure conditions by checking the target | |||
resource revision(s) after a failed connection, reverting or fixing | resource revision(s) after a failed connection, reverting or fixing | |||
any changes that were partially applied, and then automatically | any changes that were partially applied, and then automatically | |||
retrying the requests that failed. | retrying the requests that failed. | |||
Some clients use weaker signals to initiate automatic retries. For | ||||
example, when a POST request is sent, but the underlying transport | ||||
connection is closed before any part of the response is received. | ||||
Although this is commonly implemented, it is not recommended. | ||||
A proxy MUST NOT automatically retry non-idempotent requests. A | A proxy MUST NOT automatically retry non-idempotent requests. A | |||
client SHOULD NOT automatically retry a failed automatic retry. | client SHOULD NOT automatically retry a failed automatic retry. | |||
9.2.3. Methods and Caching | 9.2.3. Methods and Caching | |||
Request methods can be defined as "cacheable" to indicate that | For a cache to store and use a response, the associated method needs | |||
responses to them are allowed to be stored for future reuse; for | to explicitly allow caching, and detail under what conditions a | |||
specific requirements see [RFC7234]. In general, safe methods that | response can be used to satisfy subsequent requests; a method | |||
do not depend on a current or authoritative response are defined as | definition which does not do so cannot be cached. For additional | |||
cacheable; this specification defines GET, HEAD, and POST as | requirements see [Caching]. | |||
cacheable, although the overwhelming majority of cache | ||||
implementations only support GET and HEAD. | This specification defines caching semantics for GET, HEAD, and POST, | |||
although the overwhelming majority of cache implementations only | ||||
support GET and HEAD. | ||||
9.3. Method Definitions | 9.3. Method Definitions | |||
9.3.1. GET | 9.3.1. GET | |||
The GET method requests transfer of a current selected representation | The GET method requests transfer of a current selected representation | |||
for the target resource. GET is the primary mechanism of information | for the target resource. | |||
retrieval and the focus of almost all performance optimizations. | ||||
Hence, when people speak of retrieving some identifiable information | GET is the primary mechanism of information retrieval and the focus | |||
via HTTP, they are generally referring to making a GET request. | of almost all performance optimizations. Hence, when people speak of | |||
retrieving some identifiable information via HTTP, they are generally | ||||
referring to making a GET request. A successful response reflects | ||||
the quality of "sameness" identified by the target URI. In turn, | ||||
constructing applications such that they produce a URI for each | ||||
important resource results in more resources being available for | ||||
other applications, producing a network effect that promotes further | ||||
expansion of the Web. | ||||
It is tempting to think of resource identifiers as remote file system | It is tempting to think of resource identifiers as remote file system | |||
pathnames and of representations as being a copy of the contents of | pathnames and of representations as being a copy of the contents of | |||
such files. In fact, that is how many resources are implemented (see | such files. In fact, that is how many resources are implemented (see | |||
Section 9.1 for related security considerations). However, there are | Section 17.3 for related security considerations). However, there | |||
no such limitations in practice. The HTTP interface for a resource | are no such limitations in practice. | |||
is just as likely to be implemented as a tree of content objects, a | ||||
programmatic view on various database records, or a gateway to other | The HTTP interface for a resource is just as likely to be implemented | |||
information systems. Even when the URI mapping mechanism is tied to | as a tree of content objects, a programmatic view on various database | |||
a file system, an origin server might be configured to execute the | records, or a gateway to other information systems. Even when the | |||
files with the request as input and send the output as the | URI mapping mechanism is tied to a file system, an origin server | |||
representation rather than transfer the files directly. Regardless, | might be configured to execute the files with the request as input | |||
only the origin server needs to know how each of its resource | and send the output as the representation rather than transfer the | |||
identifiers corresponds to an implementation and how each | files directly. Regardless, only the origin server needs to know how | |||
implementation manages to select and send a current representation of | each of its resource identifiers corresponds to an implementation and | |||
the target resource in a response to GET. | how each implementation manages to select and send a current | |||
representation of the target resource in a response to GET. | ||||
A client can alter the semantics of GET to be a "range request", | A client can alter the semantics of GET to be a "range request", | |||
requesting transfer of only some part(s) of the selected | requesting transfer of only some part(s) of the selected | |||
representation, by sending a Range header field in the request | representation, by sending a Range header field in the request | |||
([RFC7233]). | (Section 14.2). | |||
A payload within a GET request message has no defined semantics; | A client SHOULD NOT generate content in a GET request. Content | |||
sending a payload body on a GET request might cause some existing | received in a GET request has no defined semantics, cannot alter the | |||
implementations to reject the request. | meaning or target of the request, and might lead some implementations | |||
to reject the request and close the connection because of its | ||||
potential as a request smuggling attack (Section 11.2 of | ||||
[Messaging]). | ||||
The response to a GET request is cacheable; a cache MAY use it to | The response to a GET request is cacheable; a cache MAY use it to | |||
satisfy subsequent GET and HEAD requests unless otherwise indicated | satisfy subsequent GET and HEAD requests unless otherwise indicated | |||
by the Cache-Control header field (Section 5.2 of [RFC7234]). | by the Cache-Control header field (Section 5.2 of [Caching]). | |||
When information retrieval is performed with a mechanism that | ||||
constructs a target URI from user-provided information, such as the | ||||
query fields of a form using GET, potentially sensitive data might be | ||||
provided that would not be appropriate for disclosure within a URI | ||||
(see Section 17.9). In some cases, the data can be filtered or | ||||
transformed such that it would not reveal such information. In | ||||
others, particularly when there is no benefit from caching a | ||||
response, using the POST method (Section 9.3.3) instead of GET can | ||||
transmit such information in the request content rather than within | ||||
the target URI. | ||||
9.3.2. HEAD | 9.3.2. HEAD | |||
The HEAD method is identical to GET except that the server MUST NOT | The HEAD method is identical to GET except that the server MUST NOT | |||
send a message body in the response (i.e., the response terminates at | send content in the response and the response always terminates at | |||
the end of the header section). | the end of the header section. HEAD is used to obtain metadata about | |||
This method can be used for obtaining metadata about | the selected representation without transferring its representation | |||
the selected representation without transferring the representation | data, often for the sake of testing hypertext links or finding recent | |||
data and is often used for testing hypertext links | modifications. | |||
for validity, accessibility, and recent modification. | ||||
The server SHOULD send the same header fields in response to a HEAD | The server SHOULD send the same header fields in response to a HEAD | |||
request as it would have sent if the request had been a GET, except | request as it would have sent if the request method had been GET. | |||
that the payload header fields (Section 3.3) MAY be omitted. | However, a server MAY omit header fields for which a value is | |||
determined only while generating the content. For example, some | ||||
servers buffer a dynamic response to GET until a minimum amount of | ||||
data is generated so that they can more efficiently delimit small | ||||
responses or make late decisions with regard to content selection. | ||||
Such a response to GET might contain Content-Length and Vary fields, | ||||
for example, that are not generated within a HEAD response. These | ||||
minor inconsistencies are considered preferable to generating and | ||||
discarding the content for a HEAD request, since HEAD is usually | ||||
requested for the sake of efficiency. | ||||
A payload within a HEAD request message has no defined semantics; | A content within a HEAD request message has no defined semantics; | |||
sending a payload body on a HEAD request might cause some existing | sending content in a HEAD request might cause some existing | |||
implementations to reject the request. | implementations to reject the request. | |||
The response to a HEAD request is cacheable; a cache MAY use it to | The response to a HEAD request is cacheable; a cache MAY use it to | |||
satisfy subsequent HEAD requests unless otherwise indicated by the | satisfy subsequent HEAD requests unless otherwise indicated by the | |||
Cache-Control header field (Section 5.2 of [RFC7234]). A HEAD | Cache-Control header field (Section 5.2 of [Caching]). A HEAD | |||
response might also have an effect on previously cached responses to | response might also affect previously cached responses to GET; see | |||
GET; see Section 4.3.5 of [RFC7234]. | Section 4.3.5 of [Caching]. | |||
9.3.3. POST | 9.3.3. POST | |||
The POST method requests that the target resource process the | The POST method requests that the target resource process the | |||
representation enclosed in the request according to the resource's | representation enclosed in the request according to the resource's | |||
own specific semantics. For example, POST is used for the following | own specific semantics. For example, POST is used for the following | |||
functions (among others): | functions (among others): | |||
o Providing a block of data, such as the fields entered into an HTML | o Providing a block of data, such as the fields entered into an HTML | |||
form, to a data-handling process; | form, to a data-handling process; | |||
skipping to change at line 3347 ¶ | skipping to change at page 84, line 36 ¶ | |||
blog, or similar group of articles; | blog, or similar group of articles; | |||
o Creating a new resource that has yet to be identified by the | o Creating a new resource that has yet to be identified by the | |||
origin server; and | origin server; and | |||
o Appending data to a resource's existing representation(s). | o Appending data to a resource's existing representation(s). | |||
An origin server indicates response semantics by choosing an | An origin server indicates response semantics by choosing an | |||
appropriate status code depending on the result of processing the | appropriate status code depending on the result of processing the | |||
POST request; almost all of the status codes defined by this | POST request; almost all of the status codes defined by this | |||
specification might be received in a response to POST (the exceptions | specification could be received in a response to POST (the exceptions | |||
being 206 (Partial Content), 304 (Not Modified), and 416 (Range Not | being 206 (Partial Content), 304 (Not Modified), and 416 (Range Not | |||
Satisfiable)). | Satisfiable)). | |||
If one or more resources has been created on the origin server as a | If one or more resources has been created on the origin server as a | |||
result of successfully processing a POST request, the origin server | result of successfully processing a POST request, the origin server | |||
SHOULD send a 201 (Created) response containing a Location header | SHOULD send a 201 (Created) response containing a Location header | |||
field that provides an identifier for the primary resource created | field that provides an identifier for the primary resource created | |||
(Section 7.1.2) and a representation that describes the status of the | (Section 10.2.3) and a representation that describes the status of | |||
request while referring to the new resource(s). | the request while referring to the new resource(s). | |||
Responses to POST requests are only cacheable when they include | Responses to POST requests are only cacheable when they include | |||
explicit freshness information (see Section 4.2.1 of [RFC7234]). | explicit freshness information (see Section 4.2.1 of [Caching]) and a | |||
However, POST caching is not widely implemented. For cases where an | ||||
origin server wishes the client to be able to cache the result of a | ||||
POST in a way that can be reused by a later GET, the origin server | ||||
MAY send a 200 (OK) response containing the result and a | ||||
Content-Location header field that has the same value as the POST's | Content-Location header field that has the same value as the POST's | |||
effective request URI (Section 3.1.4.2). | target URI (Section 8.7). A cached POST response can be reused to | |||
satisfy a later GET or HEAD request, but not a POST request, since | ||||
POST is required to be written through to the origin server, because | ||||
it is unsafe; see Section 4 of [Caching]. | ||||
If the result of processing a POST would be equivalent to a | If the result of processing a POST would be equivalent to a | |||
representation of an existing resource, an origin server MAY redirect | representation of an existing resource, an origin server MAY redirect | |||
the user agent to that resource by sending a 303 (See Other) response | the user agent to that resource by sending a 303 (See Other) response | |||
with the existing resource's identifier in the Location field. This | with the existing resource's identifier in the Location field. This | |||
has the benefits of providing the user agent a resource identifier | has the benefits of providing the user agent a resource identifier | |||
and transferring the representation via a method more amenable to | and transferring the representation via a method more amenable to | |||
shared caching, though at the cost of an extra request if the user | shared caching, though at the cost of an extra request if the user | |||
agent does not already have the representation cached. | agent does not already have the representation cached. | |||
9.3.4. PUT | 9.3.4. PUT | |||
The PUT method requests that the state of the target resource be | The PUT method requests that the state of the target resource be | |||
created or replaced with the state defined by the representation | created or replaced with the state defined by the representation | |||
enclosed in the request message payload. A successful PUT of a given | enclosed in the request message content. A successful PUT of a given | |||
representation would suggest that a subsequent GET on that same | representation would suggest that a subsequent GET on that same | |||
target resource will result in an equivalent representation being | target resource will result in an equivalent representation being | |||
sent in a 200 (OK) response. However, there is no guarantee that | sent in a 200 (OK) response. However, there is no guarantee that | |||
such a state change will be observable, since the target resource | such a state change will be observable, since the target resource | |||
might be acted upon by other user agents in parallel, or might be | might be acted upon by other user agents in parallel, or might be | |||
subject to dynamic processing by the origin server, before any | subject to dynamic processing by the origin server, before any | |||
subsequent GET is received. A successful response only implies that | subsequent GET is received. A successful response only implies that | |||
the user agent's intent was achieved at the time of its processing by | the user agent's intent was achieved at the time of its processing by | |||
the origin server. | the origin server. | |||
skipping to change at line 3439 ¶ | skipping to change at page 86, line 36 ¶ | |||
origin server beyond what can be expressed by the intent of the user | origin server beyond what can be expressed by the intent of the user | |||
agent request and the semantics of the origin server response. It | agent request and the semantics of the origin server response. It | |||
does not define what a resource might be, in any sense of that word, | does not define what a resource might be, in any sense of that word, | |||
beyond the interface provided via HTTP. It does not define how | beyond the interface provided via HTTP. It does not define how | |||
resource state is "stored", nor how such storage might change as a | resource state is "stored", nor how such storage might change as a | |||
result of a change in resource state, nor how the origin server | result of a change in resource state, nor how the origin server | |||
translates resource state into representations. Generally speaking, | translates resource state into representations. Generally speaking, | |||
all implementation details behind the resource interface are | all implementation details behind the resource interface are | |||
intentionally hidden by the server. | intentionally hidden by the server. | |||
An origin server SHOULD ignore unrecognized header fields received in | This extends to how header and trailer fields are stored; while | |||
a PUT request (i.e., do not save them as part of the resource state). | common header fields like Content-Type will typically be stored and | |||
returned upon subsequent GET requests, header and trailer field | ||||
handling is specific to the resource that received the request. As a | ||||
result, an origin server SHOULD ignore unrecognized header and | ||||
trailer fields received in a PUT request (i.e., do not save them as | ||||
part of the resource state). | ||||
An origin server MUST NOT send a validator header field | An origin server MUST NOT send a validator field (Section 8.8), such | |||
(Section 7.2), such as an ETag or Last-Modified field, in a | as an ETag or Last-Modified field, in a successful response to PUT | |||
successful response to PUT unless the request's representation data | unless the request's representation data was saved without any | |||
was saved without any transformation applied to the body (i.e., the | transformation applied to the content (i.e., the resource's new | |||
resource's new representation data is identical to the representation | representation data is identical to the content received in the PUT | |||
data received in the PUT request) and the validator field value | request) and the validator field value reflects the new | |||
reflects the new representation. This requirement allows a user | representation. This requirement allows a user agent to know when | |||
agent to know when the representation body it has in memory remains | the representation it has in memory remains current as a result of | |||
current as a result of the PUT, thus not in need of being retrieved | the PUT, thus not in need of being retrieved again from the origin | |||
again from the origin server, and that the new validator(s) received | server, and that the new validator(s) received in the response can be | |||
in the response can be used for future conditional requests in order | used for future conditional requests in order to prevent accidental | |||
to prevent accidental overwrites (Section 5.2). | overwrites (Section 13.1). | |||
The fundamental difference between the POST and PUT methods is | The fundamental difference between the POST and PUT methods is | |||
highlighted by the different intent for the enclosed representation. | highlighted by the different intent for the enclosed representation. | |||
The target resource in a POST request is intended to handle the | The target resource in a POST request is intended to handle the | |||
enclosed representation according to the resource's own semantics, | enclosed representation according to the resource's own semantics, | |||
whereas the enclosed representation in a PUT request is defined as | whereas the enclosed representation in a PUT request is defined as | |||
replacing the state of the target resource. Hence, the intent of PUT | replacing the state of the target resource. Hence, the intent of PUT | |||
is idempotent and visible to intermediaries, even though the exact | is idempotent and visible to intermediaries, even though the exact | |||
effect is only known by the origin server. | effect is only known by the origin server. | |||
skipping to change at line 3485 ¶ | skipping to change at page 87, line 39 ¶ | |||
A PUT request applied to the target resource can have side effects on | A PUT request applied to the target resource can have side effects on | |||
other resources. For example, an article might have a URI for | other resources. For example, an article might have a URI for | |||
identifying "the current version" (a resource) that is separate from | identifying "the current version" (a resource) that is separate from | |||
the URIs identifying each particular version (different resources | the URIs identifying each particular version (different resources | |||
that at one point shared the same state as the current version | that at one point shared the same state as the current version | |||
resource). A successful PUT request on "the current version" URI | resource). A successful PUT request on "the current version" URI | |||
might therefore create a new version resource in addition to changing | might therefore create a new version resource in addition to changing | |||
the state of the target resource, and might also cause links to be | the state of the target resource, and might also cause links to be | |||
added between the related resources. | added between the related resources. | |||
An origin server that allows PUT on a given target resource MUST send | Some origin servers support use of the Content-Range header field | |||
a 400 (Bad Request) response to a PUT request that contains a | (Section 14.4) as a request modifier to perform a partial PUT, as | |||
Content-Range header field (Section 4.2 of [RFC7233]), since the | described in Section 14.5. | |||
payload is likely to be partial content that has been mistakenly PUT | ||||
as a full representation. | ||||
Responses to the PUT method are not cacheable. If a successful PUT | Responses to the PUT method are not cacheable. If a successful PUT | |||
request passes through a cache that has one or more stored responses | request passes through a cache that has one or more stored responses | |||
for the effective request URI, those stored responses will be | for the target URI, those stored responses will be invalidated (see | |||
invalidated (see Section 4.4 of [RFC7234]). | Section 4.4 of [Caching]). | |||
9.3.5. DELETE | 9.3.5. DELETE | |||
The DELETE method requests that the origin server remove the | The DELETE method requests that the origin server remove the | |||
association between the target resource and its current | association between the target resource and its current | |||
functionality. In effect, this method is similar to the rm command | functionality. In effect, this method is similar to the "rm" command | |||
in UNIX: it expresses a deletion operation on the URI mapping of the | in UNIX: it expresses a deletion operation on the URI mapping of the | |||
origin server rather than an expectation that the previously | origin server rather than an expectation that the previously | |||
associated information be deleted. | associated information be deleted. | |||
If the target resource has one or more current representations, they | If the target resource has one or more current representations, they | |||
might or might not be destroyed by the origin server, and the | might or might not be destroyed by the origin server, and the | |||
associated storage might or might not be reclaimed, depending | associated storage might or might not be reclaimed, depending | |||
entirely on the nature of the resource and its implementation by the | entirely on the nature of the resource and its implementation by the | |||
origin server (which are beyond the scope of this specification). | origin server (which are beyond the scope of this specification). | |||
Likewise, other implementation aspects of a resource might need to be | Likewise, other implementation aspects of a resource might need to be | |||
deactivated or archived as a result of a DELETE, such as database or | deactivated or archived as a result of a DELETE, such as database or | |||
gateway connections. In general, it is assumed that the origin | gateway connections. In general, it is assumed that the origin | |||
server will only allow DELETE on resources for which it has a | server will only allow DELETE on resources for which it has a | |||
prescribed mechanism for accomplishing the deletion. | prescribed mechanism for accomplishing the deletion. | |||
Relatively few resources allow the DELETE method -- its primary use | Relatively few resources allow the DELETE method - its primary use is | |||
is for remote authoring environments, where the user has some | for remote authoring environments, where the user has some direction | |||
direction regarding its effect. For example, a resource that was | regarding its effect. For example, a resource that was previously | |||
previously created using a PUT request, or identified via the | created using a PUT request, or identified via the Location header | |||
Location header field after a 201 (Created) response to a POST | field after a 201 (Created) response to a POST request, might allow a | |||
request, might allow a corresponding DELETE request to undo those | corresponding DELETE request to undo those actions. Similarly, | |||
actions. Similarly, custom user agent implementations that implement | custom user agent implementations that implement an authoring | |||
an authoring function, such as revision control clients using HTTP | function, such as revision control clients using HTTP for remote | |||
for remote operations, might use DELETE based on an assumption that | operations, might use DELETE based on an assumption that the server's | |||
the server's URI space has been crafted to correspond to a version | URI space has been crafted to correspond to a version repository. | |||
repository. | ||||
If a DELETE method is successfully applied, the origin server SHOULD | If a DELETE method is successfully applied, the origin server SHOULD | |||
send | send | |||
a 202 (Accepted) status code if the action will likely succeed but | o a 202 (Accepted) status code if the action will likely succeed but | |||
has not yet been enacted, | has not yet been enacted, | |||
a 204 (No Content) status code if the action has been enacted and | o a 204 (No Content) status code if the action has been enacted and | |||
no further information is to be supplied, or | no further information is to be supplied, or | |||
a 200 (OK) status code if the action has been enacted and the | o a 200 (OK) status code if the action has been enacted and the | |||
response message includes a representation describing the status. | response message includes a representation describing the status. | |||
A payload within a DELETE request message has no defined semantics; | A client SHOULD NOT generate content in a DELETE request. Content | |||
sending a payload body on a DELETE request might cause some existing | received in a DELETE request has no defined semantics, cannot alter | |||
the meaning or target of the request, and might lead some | ||||
implementations to reject the request. | implementations to reject the request. | |||
Responses to the DELETE method are not cacheable. If a DELETE | Responses to the DELETE method are not cacheable. If a successful | |||
request passes through a cache that has one or more stored responses | DELETE request passes through a cache that has one or more stored | |||
for the effective request URI, those stored responses will be | responses for the target URI, those stored responses will be | |||
invalidated (see Section 4.4 of [RFC7234]). | invalidated (see Section 4.4 of [Caching]). | |||
9.3.6. CONNECT | 9.3.6. CONNECT | |||
The CONNECT method requests that the recipient establish a tunnel to | The CONNECT method requests that the recipient establish a tunnel to | |||
the destination origin server identified by the request-target and, | the destination origin server identified by the request target and, | |||
if successful, thereafter restrict its behavior to blind forwarding | if successful, thereafter restrict its behavior to blind forwarding | |||
of packets, in both directions, until the tunnel is closed. Tunnels | of data, in both directions, until the tunnel is closed. Tunnels are | |||
are commonly used to create an end-to-end virtual connection, through | commonly used to create an end-to-end virtual connection, through one | |||
one or more proxies, which can then be secured using TLS (Transport | or more proxies, which can then be secured using TLS (Transport Layer | |||
Layer Security, [RFC5246]). | Security, [RFC8446]). | |||
Because CONNECT changes the request/response nature of an HTTP | ||||
connection, specific HTTP versions might have different ways of | ||||
mapping its semantics into the protocol's wire format. | ||||
CONNECT is intended only for use in requests to a proxy. An origin | CONNECT is intended only for use in requests to a proxy. An origin | |||
server that receives a CONNECT request for itself MAY respond with a | server that receives a CONNECT request for itself MAY respond with a | |||
2xx (Successful) status code to indicate that a connection is | 2xx (Successful) status code to indicate that a connection is | |||
established. However, most origin servers do not implement CONNECT. | established. However, most origin servers do not implement CONNECT. | |||
A client sending a CONNECT request MUST send the authority form of | A client sending a CONNECT request MUST send the authority component | |||
request-target (Section 5.3 of [RFC7230]); i.e., the request-target | (described in Section 3.2 of [RFC3986]) as the request target; i.e., | |||
consists of only the host name and port number of the tunnel | the request target consists of only the host name and port number of | |||
destination, separated by a colon. For example, | the tunnel destination, separated by a colon. For example, | |||
CONNECT server.example.com:80 HTTP/1.1 | CONNECT server.example.com:80 HTTP/1.1 | |||
Host: server.example.com:80 | Host: server.example.com:80 | |||
The recipient proxy can establish a tunnel either by directly | The recipient proxy can establish a tunnel either by directly | |||
connecting to the request-target or, if configured to use another | connecting to the request target or, if configured to use another | |||
proxy, by forwarding the CONNECT request to the next inbound proxy. | proxy, by forwarding the CONNECT request to the next inbound proxy. | |||
Any 2xx (Successful) response indicates that the sender (and all | Any 2xx (Successful) response indicates that the sender (and all | |||
inbound proxies) will switch to tunnel mode immediately after the | inbound proxies) will switch to tunnel mode immediately after the | |||
blank line that concludes the successful response's header section; | blank line that concludes the successful response's header section; | |||
data received after that blank line is from the server identified by | data received after that blank line is from the server identified by | |||
the request-target. Any response other than a successful response | the request target. Any response other than a successful response | |||
indicates that the tunnel has not yet been formed and that the | indicates that the tunnel has not yet been formed and that the | |||
connection remains governed by HTTP. | connection remains governed by HTTP. | |||
A tunnel is closed when a tunnel intermediary detects that either | A tunnel is closed when a tunnel intermediary detects that either | |||
side has closed its connection: the intermediary MUST attempt to send | side has closed its connection: the intermediary MUST attempt to send | |||
any outstanding data that came from the closed side to the other | any outstanding data that came from the closed side to the other | |||
side, close both connections, and then discard any remaining data | side, close both connections, and then discard any remaining data | |||
left undelivered. | left undelivered. | |||
Proxy authentication might be used to establish the authority to | Proxy authentication might be used to establish the authority to | |||
create a tunnel. For example, | create a tunnel. For example, | |||
CONNECT server.example.com:80 HTTP/1.1 | CONNECT server.example.com:80 HTTP/1.1 | |||
Host: server.example.com:80 | Host: server.example.com:80 | |||
Proxy-Authorization: basic aGVsbG86d29ybGQ= | Proxy-Authorization: basic aGVsbG86d29ybGQ= | |||
There are significant risks in establishing a tunnel to arbitrary | There are significant risks in establishing a tunnel to arbitrary | |||
servers, particularly when the destination is a well-known or | servers, particularly when the destination is a well-known or | |||
reserved TCP port that is not intended for Web traffic. For example, | reserved TCP port that is not intended for Web traffic. For example, | |||
a CONNECT to a request-target of "example.com:25" would suggest that | a CONNECT to "example.com:25" would suggest that the proxy connect to | |||
the proxy connect to the reserved port for SMTP traffic; if allowed, | the reserved port for SMTP traffic; if allowed, that could trick the | |||
that could trick the proxy into relaying spam email. Proxies that | proxy into relaying spam email. Proxies that support CONNECT SHOULD | |||
support CONNECT SHOULD restrict its use to a limited set of known | restrict its use to a limited set of known ports or a configurable | |||
ports or a configurable whitelist of safe request targets. | whitelist of safe request targets. | |||
A server MUST NOT send any Transfer-Encoding or Content-Length header | A server MUST NOT send any Transfer-Encoding or Content-Length header | |||
fields in a 2xx (Successful) response to CONNECT. A client MUST | fields in a 2xx (Successful) response to CONNECT. A client MUST | |||
ignore any Content-Length or Transfer-Encoding header fields received | ignore any Content-Length or Transfer-Encoding header fields received | |||
in a successful response to CONNECT. | in a successful response to CONNECT. | |||
A payload within a CONNECT request message has no defined semantics; | Content within a CONNECT request message has no defined semantics; | |||
sending a payload body on a CONNECT request might cause some existing | sending content in a CONNECT request might cause some existing | |||
implementations to reject the request. | implementations to reject the request. | |||
Responses to the CONNECT method are not cacheable. | Responses to the CONNECT method are not cacheable. | |||
9.3.7. OPTIONS | 9.3.7. OPTIONS | |||
The OPTIONS method requests information about the communication | The OPTIONS method requests information about the communication | |||
options available for the target resource, at either the origin | options available for the target resource, at either the origin | |||
server or an intervening intermediary. This method allows a client | server or an intervening intermediary. This method allows a client | |||
to determine the options and/or requirements associated with a | to determine the options and/or requirements associated with a | |||
resource, or the capabilities of a server, without implying a | resource, or the capabilities of a server, without implying a | |||
resource action. | resource action. | |||
An OPTIONS request with an asterisk ("*") as the request-target | An OPTIONS request with an asterisk ("*") as the request target | |||
(Section 5.3 of [RFC7230]) applies to the server in general rather | (Section 7.1) applies to the server in general rather than to a | |||
than to a specific resource. Since a server's communication options | specific resource. Since a server's communication options typically | |||
typically depend on the resource, the "*" request is only useful as a | depend on the resource, the "*" request is only useful as a "ping" or | |||
"ping" or "no-op" type of method; it does nothing beyond allowing the | "no-op" type of method; it does nothing beyond allowing the client to | |||
client to test the capabilities of the server. For example, this can | test the capabilities of the server. For example, this can be used | |||
be used to test a proxy for HTTP/1.1 conformance (or lack thereof). | to test a proxy for HTTP/1.1 conformance (or lack thereof). | |||
If the request-target is not an asterisk, the OPTIONS request applies | If the request target is not an asterisk, the OPTIONS request applies | |||
to the options that are available when communicating with the target | to the options that are available when communicating with the target | |||
resource. | resource. | |||
A server generating a successful response to OPTIONS SHOULD send any | A server generating a successful response to OPTIONS SHOULD send any | |||
header fields that might indicate optional features implemented by | header that might indicate optional features implemented by the | |||
the server and applicable to the target resource (e.g., Allow), | server and applicable to the target resource (e.g., Allow), including | |||
including potential extensions not defined by this specification. | potential extensions not defined by this specification. The response | |||
The response payload, if any, might also describe the communication | content, if any, might also describe the communication options in a | |||
options in a machine or human-readable representation. A standard | machine or human-readable representation. A standard format for such | |||
format for such a representation is not defined by this | a representation is not defined by this specification, but might be | |||
specification, but might be defined by future extensions to HTTP. A | defined by future extensions to HTTP. | |||
server MUST generate a Content-Length field with a value of "0" if no | ||||
payload body is to be sent in the response. | ||||
A client MAY send a Max-Forwards header field in an OPTIONS request | A client MAY send a Max-Forwards header field in an OPTIONS request | |||
to target a specific recipient in the request chain (see | to target a specific recipient in the request chain (see | |||
Section 5.1.2). A proxy MUST NOT generate a Max-Forwards header | Section 7.6.2). A proxy MUST NOT generate a Max-Forwards header | |||
field while forwarding a request unless that request was received | field while forwarding a request unless that request was received | |||
with a Max-Forwards field. | with a Max-Forwards field. | |||
A client that generates an OPTIONS request containing a payload body | A client that generates an OPTIONS request containing content MUST | |||
MUST send a valid Content-Type header field describing the | send a valid Content-Type header field describing the representation | |||
representation media type. Although this specification does not | media type. Note that this specification does not define any use for | |||
define any use for such a payload, future extensions to HTTP might | such content. | |||
use the OPTIONS body to make more detailed queries about the target | ||||
resource. | ||||
Responses to the OPTIONS method are not cacheable. | Responses to the OPTIONS method are not cacheable. | |||
9.3.8. TRACE | 9.3.8. TRACE | |||
The TRACE method requests a remote, application-level loop-back of | The TRACE method requests a remote, application-level loop-back of | |||
the request message. The final recipient of the request SHOULD | the request message. The final recipient of the request SHOULD | |||
reflect the message received, excluding some fields described below, | reflect the message received, excluding some fields described below, | |||
back to the client as the message body of a 200 (OK) response with a | back to the client as the content of a 200 (OK) response with a | |||
Content-Type of "message/http" (Section 8.3.1 of [RFC7230]). The | Content-Type of "message/http" (Section 10.1 of [Messaging]). The | |||
final recipient is either the origin server or the first server to | final recipient is either the origin server or the first server to | |||
receive a Max-Forwards value of zero (0) in the request | receive a Max-Forwards value of zero (0) in the request | |||
(Section 5.1.2). | (Section 7.6.2). | |||
A client MUST NOT generate header fields in a TRACE request | A client MUST NOT generate fields in a TRACE request containing | |||
containing sensitive data that might be disclosed by the response. | sensitive data that might be disclosed by the response. For example, | |||
For example, it would be foolish for a user agent to send stored user | it would be foolish for a user agent to send stored user credentials | |||
credentials [RFC7235] or cookies [RFC6265] in a TRACE request. The | (Section 11) or cookies [RFC6265] in a TRACE request. The final | |||
final recipient of the request SHOULD exclude any request header | recipient of the request SHOULD exclude any request fields that are | |||
fields that are likely to contain sensitive data when that recipient | likely to contain sensitive data when that recipient generates the | |||
generates the response body. | response content. | |||
TRACE allows the client to see what is being received at the other | TRACE allows the client to see what is being received at the other | |||
end of the request chain and use that data for testing or diagnostic | end of the request chain and use that data for testing or diagnostic | |||
information. The value of the Via header field (Section 5.7.1 of | information. The value of the Via header field (Section 7.6.3) is of | |||
[RFC7230]) is of particular interest, since it acts as a trace of the | particular interest, since it acts as a trace of the request chain. | |||
request chain. Use of the Max-Forwards header field allows the | Use of the Max-Forwards header field allows the client to limit the | |||
client to limit the length of the request chain, which is useful for | length of the request chain, which is useful for testing a chain of | |||
testing a chain of proxies forwarding messages in an infinite loop. | proxies forwarding messages in an infinite loop. | |||
A client MUST NOT send a message body in a TRACE request. | A client MUST NOT send content in a TRACE request. | |||
Responses to the TRACE method are not cacheable. | Responses to the TRACE method are not cacheable. | |||
10. Message Context | 10. Message Context | |||
10.1. Request Context Fields | 10.1. Request Context Fields | |||
A client sends request header fields to provide more information | The request header fields below provide additional information about | |||
about the request context, make the request conditional based on the | the request context, including information about the user, user | |||
target resource state, suggest preferred formats for the response, | ||||
supply authentication credentials, or modify the expected request | ||||
processing. These fields act as request modifiers, similar to the | ||||
parameters on a programming language method invocation. | ||||
Controls are request header fields that direct specific handling of | ||||
the request. | ||||
The following request header fields provide additional information | ||||
about the request context, including information about the user, user | ||||
agent, and resource behind the request. | agent, and resource behind the request. | |||
10.1.1. Expect | 10.1.1. Expect | |||
The "Expect" header field in a request indicates a certain set of | The "Expect" header field in a request indicates a certain set of | |||
behaviors (expectations) that need to be supported by the server in | behaviors (expectations) that need to be supported by the server in | |||
order to properly handle this request. The only such expectation | order to properly handle this request. | |||
defined by this specification is 100-continue. | ||||
Expect = "100-continue" | Expect = #expectation | |||
expectation = token [ "=" ( token / quoted-string ) parameters ] | ||||
The Expect field-value is case-insensitive. | The Expect field value is case-insensitive. | |||
[new] | The only expectation defined by this specification is "100-continue" | |||
(with no defined parameters). | ||||
A server that receives an Expect field-value other than 100-continue | A server that receives an Expect field value containing a member | |||
MAY respond with a 417 (Expectation Failed) status code to indicate | other than 100-continue MAY respond with a 417 (Expectation Failed) | |||
that the unexpected expectation cannot be met. | status code to indicate that the unexpected expectation cannot be | |||
met. | ||||
A 100-continue expectation informs recipients that the client is | A _100-continue_ expectation informs recipients that the client is | |||
about to send a (presumably large) message body in this request and | about to send (presumably large) content in this request and wishes | |||
wishes to receive a 100 (Continue) interim response if the | to receive a 100 (Continue) interim response if the method, target | |||
request-line and header fields are not sufficient to cause an | URI, and header fields are not sufficient to cause an immediate | |||
immediate success, redirect, or error response. This allows the | success, redirect, or error response. This allows the client to wait | |||
client to wait for an indication that it is worthwhile to send the | for an indication that it is worthwhile to send the content before | |||
message body before actually doing so, which can improve efficiency | actually doing so, which can improve efficiency when the data is huge | |||
when the message body is huge or when the client anticipates that an | or when the client anticipates that an error is likely (e.g., when | |||
error is likely (e.g., when sending a state-changing method, for the | sending a state-changing method, for the first time, without | |||
first time, without previously verified authentication credentials). | previously verified authentication credentials). | |||
For example, a request that begins with | For example, a request that begins with | |||
PUT /somewhere/fun HTTP/1.1 | PUT /somewhere/fun HTTP/1.1 | |||
Host: origin.example.com | Host: origin.example.com | |||
Content-Type: video/h264 | Content-Type: video/h264 | |||
Content-Length: 1234567890987 | Content-Length: 1234567890987 | |||
Expect: 100-continue | Expect: 100-continue | |||
allows the origin server to immediately respond with an error | allows the origin server to immediately respond with an error | |||
message, such as 401 (Unauthorized) or 405 (Method Not Allowed), | message, such as 401 (Unauthorized) or 405 (Method Not Allowed), | |||
before the client starts filling the pipes with an unnecessary data | before the client starts filling the pipes with an unnecessary data | |||
transfer. | transfer. | |||
Requirements for clients: | Requirements for clients: | |||
o A client MUST NOT generate a 100-continue expectation in a request | o A client MUST NOT generate a 100-continue expectation in a request | |||
that does not include a message body. | that does not include content. | |||
o A client that will wait for a 100 (Continue) response before | o A client that will wait for a 100 (Continue) response before | |||
sending the request message body MUST send an Expect header field | sending the request content MUST send an Expect header field | |||
containing a 100-continue expectation. | containing a 100-continue expectation. | |||
o A client that sends a 100-continue expectation is not required to | o A client that sends a 100-continue expectation is not required to | |||
wait for any specific length of time; such a client MAY proceed to | wait for any specific length of time; such a client MAY proceed to | |||
send the message body even if it has not yet received a response. | send the content even if it has not yet received a response. | |||
Furthermore, since 100 (Continue) responses cannot be sent through | Furthermore, since 100 (Continue) responses cannot be sent through | |||
an HTTP/1.0 intermediary, such a client SHOULD NOT wait for an | an HTTP/1.0 intermediary, such a client SHOULD NOT wait for an | |||
indefinite period before sending the message body. | indefinite period before sending the content. | |||
o A client that receives a 417 (Expectation Failed) status code in | o A client that receives a 417 (Expectation Failed) status code in | |||
response to a request containing a 100-continue expectation SHOULD | response to a request containing a 100-continue expectation SHOULD | |||
repeat that request without a 100-continue expectation, since the | repeat that request without a 100-continue expectation, since the | |||
417 response merely indicates that the response chain does not | 417 response merely indicates that the response chain does not | |||
support expectations (e.g., it passes through an HTTP/1.0 server). | support expectations (e.g., it passes through an HTTP/1.0 server). | |||
Requirements for servers: | Requirements for servers: | |||
o A server that receives a 100-continue expectation in an HTTP/1.0 | o A server that receives a 100-continue expectation in an HTTP/1.0 | |||
request MUST ignore that expectation. | request MUST ignore that expectation. | |||
o A server MAY omit sending a 100 (Continue) response if it has | o A server MAY omit sending a 100 (Continue) response if it has | |||
already received some or all of the message body for the | already received some or all of the content for the corresponding | |||
corresponding request, or if the framing indicates that there is | request, or if the framing indicates that there is no content. | |||
no message body. | ||||
o A server that sends a 100 (Continue) response MUST ultimately send | o A server that sends a 100 (Continue) response MUST ultimately send | |||
a final status code, once the message body is received and | a final status code, once the request content is received and | |||
processed, unless the connection is closed prematurely. | processed, unless the connection is closed prematurely. | |||
o A server that responds with a final status code before reading the | o A server that responds with a final status code before reading the | |||
entire message body SHOULD indicate in that response whether it | entire request content SHOULD indicate whether it intends to close | |||
intends to close the connection or continue reading and discarding | the connection (e.g., see Section 9.6 of [Messaging]) or continue | |||
the request message (see Section 6.6 of [RFC7230]). | reading the request content. | |||
An origin server MUST, upon receiving an HTTP/1.1 (or later) | An origin server MUST, upon receiving an HTTP/1.1 (or later) request | |||
request-line and a complete header section that | that has a method, target URI, and complete header section that | |||
contains a 100-continue expectation and indicates a request message | contains a 100-continue expectation and an indication that request | |||
body will follow, either send an immediate response with a final | content will follow, either send an immediate response with a final | |||
status code, if that status can be determined by examining just the | status code, if that status can be determined by examining just the | |||
request-line and header fields, or send an immediate 100 | method, target URI, and header fields, or send an immediate 100 | |||
(Continue) response to encourage the client to send the request's | (Continue) response to encourage the client to send the request | |||
message body. The origin server MUST NOT wait for the message body | content. The origin server MUST NOT wait for the content before | |||
before sending the 100 (Continue) response. | sending the 100 (Continue) response. | |||
A proxy MUST, upon receiving an HTTP/1.1 (or later) request-line and | A proxy MUST, upon receiving an HTTP/1.1 (or later) request that has | |||
a complete header section that contains a 100-continue expectation and | a method, target URI, and complete header section that contains a | |||
indicates a request message body will follow, | 100-continue expectation and indicates a request content will follow, | |||
either send an immediate response with a final status code, if that | either send an immediate response with a final status code, if that | |||
status can be determined by examining just the request-line and header | status can be determined by examining just the method, target URI, | |||
fields, or begin forwarding the request toward the origin | and header fields, or begin forwarding the request toward the origin | |||
server by sending a corresponding request-line and header section to | server by sending a corresponding request-line and header section to | |||
the next inbound server. If the proxy believes (from configuration | the next inbound server. If the proxy believes (from configuration | |||
or past interaction) that the next inbound server only supports | or past interaction) that the next inbound server only supports | |||
HTTP/1.0, the proxy MAY generate an immediate 100 (Continue) response | HTTP/1.0, the proxy MAY generate an immediate 100 (Continue) response | |||
to encourage the client to begin sending the message body. | to encourage the client to begin sending the content. | |||
Note: The Expect header field was added after the original | ||||
publication of HTTP/1.1 [RFC2068] as both the means to request an | ||||
interim 100 (Continue) response and the general mechanism for | ||||
indicating must-understand extensions. However, the extension | ||||
mechanism has not been used by clients and the must-understand | ||||
requirements have not been implemented by many servers, rendering | ||||
the extension mechanism useless. This specification has removed | ||||
the extension mechanism in order to simplify the definition and | ||||
processing of 100-continue. | ||||
10.1.2. From | 10.1.2. From | |||
The "From" header field contains an Internet email address for a | The "From" header field contains an Internet email address for a | |||
human user who controls the requesting user agent. The address ought | human user who controls the requesting user agent. The address ought | |||
to be machine-usable, as defined by "mailbox" in Section 3.4 of | to be machine-usable, as defined by "mailbox" in Section 3.4 of | |||
[RFC5322]: | [RFC5322]: | |||
From = mailbox | From = mailbox | |||
skipping to change at line 3866 ¶ | skipping to change at page 95, line 32 ¶ | |||
The "Referer" [sic] header field allows the user agent to specify a | The "Referer" [sic] header field allows the user agent to specify a | |||
URI reference for the resource from which the target URI was obtained | URI reference for the resource from which the target URI was obtained | |||
(i.e., the "referrer", though the field name is misspelled). A user | (i.e., the "referrer", though the field name is misspelled). A user | |||
agent MUST NOT include the fragment and userinfo components of the | agent MUST NOT include the fragment and userinfo components of the | |||
URI reference [RFC3986], if any, when generating the Referer field | URI reference [RFC3986], if any, when generating the Referer field | |||
value. | value. | |||
Referer = absolute-URI / partial-URI | Referer = absolute-URI / partial-URI | |||
The field value is either an absolute-URI or a partial-URI. In the | ||||
latter case (Section 4), the referenced URI is relative to the target | ||||
URI ([RFC3986], Section 5). | ||||
The Referer header field allows servers to generate back-links to | The Referer header field allows servers to generate back-links to | |||
other resources for simple analytics, logging, optimized caching, | other resources for simple analytics, logging, optimized caching, | |||
etc. It also allows obsolete or mistyped links to be found for | etc. It also allows obsolete or mistyped links to be found for | |||
maintenance. Some servers use the Referer header field as a means of | maintenance. Some servers use the Referer header field as a means of | |||
denying links from other sites (so-called "deep linking") or | denying links from other sites (so-called "deep linking") or | |||
restricting cross-site request forgery (CSRF), but not all requests | restricting cross-site request forgery (CSRF), but not all requests | |||
contain it. | contain it. | |||
Example: | Example: | |||
Referer: http://www.example.org/hypertext/Overview.html | Referer: http://www.example.org/hypertext/Overview.html | |||
If the target URI was obtained from a source that does not have its | If the target URI was obtained from a source that does not have its | |||
own URI (e.g., input from the user keyboard, or an entry within the | own URI (e.g., input from the user keyboard, or an entry within the | |||
user's bookmarks/favorites), the user agent MUST either exclude the | user's bookmarks/favorites), the user agent MUST either exclude the | |||
Referer field or send it with a value of "about:blank". | Referer header field or send it with a value of "about:blank". | |||
The Referer field has the potential to reveal information about the | The Referer header field has the potential to reveal information | |||
request context or browsing history of the user, which is a privacy | about the request context or browsing history of the user, which is a | |||
concern if the referring resource's identifier reveals personal | privacy concern if the referring resource's identifier reveals | |||
information (such as an account name) or a resource that is supposed | personal information (such as an account name) or a resource that is | |||
to be confidential (such as behind a firewall or internal to a | supposed to be confidential (such as b |