idnits 2.17.1 draft-ietf-httpbis-semantics-13.txt: -(10254): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 7 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 5 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. -- The draft header indicates that this document obsoletes RFC7230, but the abstract doesn't seem to directly say this. It does mention RFC7230 though, so this could be OK. -- The abstract seems to indicate that this document obsoletes RFC7615, but the header doesn't have an 'Obsoletes:' line to match this. -- The abstract seems to indicate that this document obsoletes RFC7538, but the header doesn't have an 'Obsoletes:' line to match this. -- The abstract seems to indicate that this document obsoletes RFC7694, but the header doesn't have an 'Obsoletes:' line to match this. -- The draft header indicates that this document updates RFC3864, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 6608 has weird spacing: '... method resp...' == Line 8547 has weird spacing: '... yes yes...' == Line 8548 has weird spacing: '... yes yes...' == Line 8549 has weird spacing: '...S yes yes...' == Line 8552 has weird spacing: '... yes yes...' == (1 more instance...) (Using the creation date from RFC3864, updated by this document, for RFC5378 checks: 2001-09-27) -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (December 14, 2020) is 1229 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC2145' is defined on line 8990, but no explicit reference was found in the text == Unused Reference: 'RFC7617' is defined on line 9135, but no explicit reference was found in the text == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-cache-13 -- Possible downref: Normative reference to a draft: ref. 'Caching' == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-messaging-13 -- Possible downref: Normative reference to a draft: ref. 'Messaging' ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Downref: Normative reference to an Informational RFC: RFC 1950 ** Downref: Normative reference to an Informational RFC: RFC 1951 ** Downref: Normative reference to an Informational RFC: RFC 1952 ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' -- Possible downref: Non-RFC (?) normative reference: ref. 'Welch' -- Duplicate reference: RFC2978, mentioned in 'Err5433', was also mentioned in 'Err1912'. == Outdated reference: A later version (-34) exists of draft-ietf-quic-http-32 -- Obsolete informational reference (is this intentional?): RFC 2068 (Obsoleted by RFC 2616) -- Obsolete informational reference (is this intentional?): RFC 2145 (Obsoleted by RFC 7230) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) -- Duplicate reference: RFC2978, mentioned in 'RFC2978', was also mentioned in 'Err5433'. -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7232 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7233 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7235 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7538 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) -- Obsolete informational reference (is this intentional?): RFC 7615 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7694 (Obsoleted by RFC 9110) Summary: 5 errors (**), 0 flaws (~~), 14 warnings (==), 28 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP Working Group R. Fielding, Ed. 3 Internet-Draft Adobe 4 Obsoletes: 2818, 7230, 7231, 7232, 7233, 7235, M. Nottingham, Ed. 5 7538, 7615, 7694 (if approved) Fastly 6 Updates: 3864 (if approved) J. Reschke, Ed. 7 Intended status: Standards Track greenbytes 8 Expires: June 17, 2021 December 14, 2020 10 HTTP Semantics 11 draft-ietf-httpbis-semantics-13 13 Abstract 15 The Hypertext Transfer Protocol (HTTP) is a stateless application- 16 level protocol for distributed, collaborative, hypertext information 17 systems. This document defines the semantics shared by all versions 18 of HTTP, including its architecture, terminology, core protocol 19 elements, and extensibility mechanisms, along with the "http" and 20 "https" Uniform Resource Identifier (URI) schemes. 22 This document obsoletes RFC 2818, RFC 7231, RFC 7232, RFC 7233, RFC 23 7235, RFC 7538, RFC 7615, RFC 7694, and portions of RFC 7230. 25 Editorial Note 27 This note is to be removed before publishing as an RFC. 29 Discussion of this draft takes place on the HTTP working group 30 mailing list (ietf-http-wg@w3.org), which is archived at 31 . 33 Working Group information can be found at ; 34 source code and issues list for this draft can be found at 35 . 37 The changes in this draft are summarized in Appendix C.14. 39 Status of This Memo 41 This Internet-Draft is submitted in full conformance with the 42 provisions of BCP 78 and BCP 79. 44 Internet-Drafts are working documents of the Internet Engineering 45 Task Force (IETF). Note that other groups may also distribute 46 working documents as Internet-Drafts. The list of current Internet- 47 Drafts is at https://datatracker.ietf.org/drafts/current/. 49 Internet-Drafts are draft documents valid for a maximum of six months 50 and may be updated, replaced, or obsoleted by other documents at any 51 time. It is inappropriate to use Internet-Drafts as reference 52 material or to cite them other than as "work in progress." 54 This Internet-Draft will expire on June 17, 2021. 56 Copyright Notice 58 Copyright (c) 2020 IETF Trust and the persons identified as the 59 document authors. All rights reserved. 61 This document is subject to BCP 78 and the IETF Trust's Legal 62 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 63 license-info) in effect on the date of publication of this document. 64 Please review these documents carefully, as they describe your rights 65 and restrictions with respect to this document. Code Components 66 extracted from this document must include Simplified BSD License text 67 as described in Section 4.e of the Trust Legal Provisions and are 68 provided without warranty as described in the Simplified BSD License. 70 This document may contain material from IETF Documents or IETF 71 Contributions published or made publicly available before November 72 10, 2008. The person(s) controlling the copyright in some of this 73 material may not have granted the IETF Trust the right to allow 74 modifications of such material outside the IETF Standards Process. 75 Without obtaining an adequate license from the person(s) controlling 76 the copyright in such materials, this document may not be modified 77 outside the IETF Standards Process, and derivative works of it may 78 not be created outside the IETF Standards Process, except to format 79 it for publication as an RFC or to translate it into languages other 80 than English. 82 Table of Contents 84 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 9 85 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 9 86 1.2. History and Evolution . . . . . . . . . . . . . . . . . . 9 87 1.3. Core Semantics . . . . . . . . . . . . . . . . . . . . . 10 88 1.4. Specifications Obsoleted by this Document . . . . . . . . 11 89 2. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 11 90 2.1. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 11 91 2.2. Requirements Notation . . . . . . . . . . . . . . . . . . 12 92 2.3. Length Requirements . . . . . . . . . . . . . . . . . . . 13 93 2.4. Error Handling . . . . . . . . . . . . . . . . . . . . . 13 94 2.5. Protocol Version . . . . . . . . . . . . . . . . . . . . 14 95 3. Terminology and Core Concepts . . . . . . . . . . . . . . . . 15 96 3.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 15 97 3.2. Connections . . . . . . . . . . . . . . . . . . . . . . . 15 98 3.3. Messages . . . . . . . . . . . . . . . . . . . . . . . . 16 99 3.4. User Agent . . . . . . . . . . . . . . . . . . . . . . . 16 100 3.5. Origin Server . . . . . . . . . . . . . . . . . . . . . . 17 101 3.6. Intermediaries . . . . . . . . . . . . . . . . . . . . . 17 102 3.7. Caches . . . . . . . . . . . . . . . . . . . . . . . . . 19 103 3.8. Example Message Exchange . . . . . . . . . . . . . . . . 20 104 4. Identifiers in HTTP . . . . . . . . . . . . . . . . . . . . . 21 105 4.1. URI References . . . . . . . . . . . . . . . . . . . . . 21 106 4.2. HTTP-Related URI Schemes . . . . . . . . . . . . . . . . 22 107 4.2.1. http URI Scheme . . . . . . . . . . . . . . . . . . . 22 108 4.2.2. https URI Scheme . . . . . . . . . . . . . . . . . . 23 109 4.2.3. http(s) Normalization and Comparison . . . . . . . . 24 110 4.2.4. Deprecation of userinfo in http(s) URIs . . . . . . . 24 111 4.2.5. http(s) References with Fragment Identifiers . . . . 25 112 4.3. Authoritative Access . . . . . . . . . . . . . . . . . . 25 113 4.3.1. URI Origin . . . . . . . . . . . . . . . . . . . . . 25 114 4.3.2. http origins . . . . . . . . . . . . . . . . . . . . 26 115 4.3.3. https origins . . . . . . . . . . . . . . . . . . . . 27 116 4.3.4. https certificate verification . . . . . . . . . . . 28 117 5. Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 118 5.1. Field Names . . . . . . . . . . . . . . . . . . . . . . . 29 119 5.2. Field Lines and Combined Field Value . . . . . . . . . . 30 120 5.3. Field Order . . . . . . . . . . . . . . . . . . . . . . . 30 121 5.4. Field Limits . . . . . . . . . . . . . . . . . . . . . . 31 122 5.5. Field Values . . . . . . . . . . . . . . . . . . . . . . 32 123 5.6. Common Rules for Defining Field Values . . . . . . . . . 34 124 5.6.1. Lists (#rule ABNF Extension) . . . . . . . . . . . . 34 125 5.6.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 35 126 5.6.3. Whitespace . . . . . . . . . . . . . . . . . . . . . 35 127 5.6.4. Quoted Strings . . . . . . . . . . . . . . . . . . . 36 128 5.6.5. Comments . . . . . . . . . . . . . . . . . . . . . . 37 129 5.6.6. Parameters . . . . . . . . . . . . . . . . . . . . . 37 130 5.6.7. Date/Time Formats . . . . . . . . . . . . . . . . . . 37 131 6. Message Abstraction . . . . . . . . . . . . . . . . . . . . . 39 132 6.1. Framing and Completeness . . . . . . . . . . . . . . . . 40 133 6.2. Control Data . . . . . . . . . . . . . . . . . . . . . . 41 134 6.3. Header Fields . . . . . . . . . . . . . . . . . . . . . . 42 135 6.4. Payload . . . . . . . . . . . . . . . . . . . . . . . . . 42 136 6.4.1. Payload Semantics . . . . . . . . . . . . . . . . . . 43 137 6.4.2. Identifying Payloads . . . . . . . . . . . . . . . . 44 138 6.5. Trailer Fields . . . . . . . . . . . . . . . . . . . . . 45 139 6.5.1. Limitations on use of Trailers . . . . . . . . . . . 45 140 6.5.2. Processing Trailer Fields . . . . . . . . . . . . . . 46 141 7. Routing HTTP Messages . . . . . . . . . . . . . . . . . . . . 47 142 7.1. Determining the Target Resource . . . . . . . . . . . . . 47 143 7.2. Host and :authority . . . . . . . . . . . . . . . . . . . 48 144 7.3. Routing Inbound Requests . . . . . . . . . . . . . . . . 48 145 7.3.1. To a Cache . . . . . . . . . . . . . . . . . . . . . 48 146 7.3.2. To a Proxy . . . . . . . . . . . . . . . . . . . . . 49 147 7.3.3. To the Origin . . . . . . . . . . . . . . . . . . . . 49 148 7.4. Rejecting Misdirected Requests . . . . . . . . . . . . . 49 149 7.5. Response Correlation . . . . . . . . . . . . . . . . . . 49 150 7.6. Message Forwarding . . . . . . . . . . . . . . . . . . . 50 151 7.6.1. Connection . . . . . . . . . . . . . . . . . . . . . 50 152 7.6.2. Max-Forwards . . . . . . . . . . . . . . . . . . . . 52 153 7.6.3. Via . . . . . . . . . . . . . . . . . . . . . . . . . 52 154 7.7. Message Transformations . . . . . . . . . . . . . . . . . 54 155 7.8. Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . 55 156 8. Representations . . . . . . . . . . . . . . . . . . . . . . . 57 157 8.1. Selected Representations . . . . . . . . . . . . . . . . 58 158 8.2. Representation Data . . . . . . . . . . . . . . . . . . . 58 159 8.3. Representation Metadata . . . . . . . . . . . . . . . . . 58 160 8.4. Content-Type . . . . . . . . . . . . . . . . . . . . . . 59 161 8.4.1. Media Type . . . . . . . . . . . . . . . . . . . . . 60 162 8.4.2. Charset . . . . . . . . . . . . . . . . . . . . . . . 60 163 8.4.3. Canonicalization and Text Defaults . . . . . . . . . 61 164 8.4.4. Multipart Types . . . . . . . . . . . . . . . . . . . 61 165 8.5. Content-Encoding . . . . . . . . . . . . . . . . . . . . 62 166 8.5.1. Content Codings . . . . . . . . . . . . . . . . . . . 63 167 8.6. Content-Language . . . . . . . . . . . . . . . . . . . . 64 168 8.6.1. Language Tags . . . . . . . . . . . . . . . . . . . . 65 169 8.7. Content-Length . . . . . . . . . . . . . . . . . . . . . 65 170 8.8. Content-Location . . . . . . . . . . . . . . . . . . . . 67 171 8.9. Validator Fields . . . . . . . . . . . . . . . . . . . . 68 172 8.9.1. Weak versus Strong . . . . . . . . . . . . . . . . . 69 173 8.9.2. Last-Modified . . . . . . . . . . . . . . . . . . . . 71 174 8.9.3. ETag . . . . . . . . . . . . . . . . . . . . . . . . 73 175 8.9.4. When to Use Entity-Tags and Last-Modified Dates . . . 76 176 9. Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 177 9.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 77 178 9.2. Common Method Properties . . . . . . . . . . . . . . . . 78 179 9.2.1. Safe Methods . . . . . . . . . . . . . . . . . . . . 79 180 9.2.2. Idempotent Methods . . . . . . . . . . . . . . . . . 80 181 9.2.3. Methods and Caching . . . . . . . . . . . . . . . . . 81 182 9.3. Method Definitions . . . . . . . . . . . . . . . . . . . 81 183 9.3.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 81 184 9.3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 82 185 9.3.3. POST . . . . . . . . . . . . . . . . . . . . . . . . 83 186 9.3.4. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 84 187 9.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 87 188 9.3.6. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 88 189 9.3.7. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 90 190 9.3.8. TRACE . . . . . . . . . . . . . . . . . . . . . . . . 91 191 10. Message Context . . . . . . . . . . . . . . . . . . . . . . . 91 192 10.1. Request Context Fields . . . . . . . . . . . . . . . . . 91 193 10.1.1. Expect . . . . . . . . . . . . . . . . . . . . . . . 91 194 10.1.2. From . . . . . . . . . . . . . . . . . . . . . . . . 94 195 10.1.3. Referer . . . . . . . . . . . . . . . . . . . . . . 94 196 10.1.4. TE . . . . . . . . . . . . . . . . . . . . . . . . . 95 197 10.1.5. Trailer . . . . . . . . . . . . . . . . . . . . . . 96 198 10.1.6. User-Agent . . . . . . . . . . . . . . . . . . . . . 96 199 10.2. Response Context Fields . . . . . . . . . . . . . . . . 97 200 10.2.1. Allow . . . . . . . . . . . . . . . . . . . . . . . 98 201 10.2.2. Date . . . . . . . . . . . . . . . . . . . . . . . . 98 202 10.2.3. Location . . . . . . . . . . . . . . . . . . . . . . 99 203 10.2.4. Retry-After . . . . . . . . . . . . . . . . . . . . 101 204 10.2.5. Server . . . . . . . . . . . . . . . . . . . . . . . 101 205 11. HTTP Authentication . . . . . . . . . . . . . . . . . . . . . 102 206 11.1. Authentication Scheme . . . . . . . . . . . . . . . . . 102 207 11.2. Authentication Parameters . . . . . . . . . . . . . . . 102 208 11.3. Challenge and Response . . . . . . . . . . . . . . . . . 103 209 11.4. Credentials . . . . . . . . . . . . . . . . . . . . . . 104 210 11.5. Establishing a Protection Space (Realm) . . . . . . . . 104 211 11.6. Authenticating Users to Origin Servers . . . . . . . . . 105 212 11.6.1. WWW-Authenticate . . . . . . . . . . . . . . . . . . 105 213 11.6.2. Authorization . . . . . . . . . . . . . . . . . . . 106 214 11.6.3. Authentication-Info . . . . . . . . . . . . . . . . 107 215 11.7. Authenticating Clients to Proxies . . . . . . . . . . . 107 216 11.7.1. Proxy-Authenticate . . . . . . . . . . . . . . . . . 107 217 11.7.2. Proxy-Authorization . . . . . . . . . . . . . . . . 108 218 11.7.3. Proxy-Authentication-Info . . . . . . . . . . . . . 108 219 12. Content Negotiation . . . . . . . . . . . . . . . . . . . . . 109 220 12.1. Proactive Negotiation . . . . . . . . . . . . . . . . . 110 221 12.2. Reactive Negotiation . . . . . . . . . . . . . . . . . . 111 222 12.3. Request Payload Negotiation . . . . . . . . . . . . . . 112 223 12.4. Content Negotiation Field Features . . . . . . . . . . . 112 224 12.4.1. Absence . . . . . . . . . . . . . . . . . . . . . . 112 225 12.4.2. Quality Values . . . . . . . . . . . . . . . . . . . 113 226 12.4.3. Wildcard Values . . . . . . . . . . . . . . . . . . 113 227 12.5. Content Negotiation Fields . . . . . . . . . . . . . . . 113 228 12.5.1. Accept . . . . . . . . . . . . . . . . . . . . . . . 114 229 12.5.2. Accept-Charset . . . . . . . . . . . . . . . . . . . 116 230 12.5.3. Accept-Encoding . . . . . . . . . . . . . . . . . . 116 231 12.5.4. Accept-Language . . . . . . . . . . . . . . . . . . 118 232 12.5.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . 119 233 13. Conditional Requests . . . . . . . . . . . . . . . . . . . . 121 234 13.1. Preconditions . . . . . . . . . . . . . . . . . . . . . 121 235 13.1.1. If-Match . . . . . . . . . . . . . . . . . . . . . . 121 236 13.1.2. If-None-Match . . . . . . . . . . . . . . . . . . . 123 237 13.1.3. If-Modified-Since . . . . . . . . . . . . . . . . . 124 238 13.1.4. If-Unmodified-Since . . . . . . . . . . . . . . . . 126 239 13.1.5. If-Range . . . . . . . . . . . . . . . . . . . . . . 127 240 13.2. Evaluation of Preconditions . . . . . . . . . . . . . . 129 241 13.3. Precedence of Preconditions . . . . . . . . . . . . . . 130 242 14. Range Requests . . . . . . . . . . . . . . . . . . . . . . . 131 243 14.1. Range Units . . . . . . . . . . . . . . . . . . . . . . 131 244 14.1.1. Range Specifiers . . . . . . . . . . . . . . . . . . 132 245 14.1.2. Byte Ranges . . . . . . . . . . . . . . . . . . . . 133 246 14.2. Range . . . . . . . . . . . . . . . . . . . . . . . . . 135 247 14.3. Accept-Ranges . . . . . . . . . . . . . . . . . . . . . 136 248 14.4. Content-Range . . . . . . . . . . . . . . . . . . . . . 137 249 14.5. Media Type multipart/byteranges . . . . . . . . . . . . 139 250 15. Status Codes . . . . . . . . . . . . . . . . . . . . . . . . 140 251 15.1. Overview of Status Codes . . . . . . . . . . . . . . . . 141 252 15.2. Informational 1xx . . . . . . . . . . . . . . . . . . . 142 253 15.2.1. 100 Continue . . . . . . . . . . . . . . . . . . . . 142 254 15.2.2. 101 Switching Protocols . . . . . . . . . . . . . . 143 255 15.3. Successful 2xx . . . . . . . . . . . . . . . . . . . . . 143 256 15.3.1. 200 OK . . . . . . . . . . . . . . . . . . . . . . . 143 257 15.3.2. 201 Created . . . . . . . . . . . . . . . . . . . . 144 258 15.3.3. 202 Accepted . . . . . . . . . . . . . . . . . . . . 144 259 15.3.4. 203 Non-Authoritative Information . . . . . . . . . 145 260 15.3.5. 204 No Content . . . . . . . . . . . . . . . . . . . 145 261 15.3.6. 205 Reset Content . . . . . . . . . . . . . . . . . 146 262 15.3.7. 206 Partial Content . . . . . . . . . . . . . . . . 146 263 15.4. Redirection 3xx . . . . . . . . . . . . . . . . . . . . 149 264 15.4.1. 300 Multiple Choices . . . . . . . . . . . . . . . . 152 265 15.4.2. 301 Moved Permanently . . . . . . . . . . . . . . . 153 266 15.4.3. 302 Found . . . . . . . . . . . . . . . . . . . . . 153 267 15.4.4. 303 See Other . . . . . . . . . . . . . . . . . . . 154 268 15.4.5. 304 Not Modified . . . . . . . . . . . . . . . . . . 154 269 15.4.6. 305 Use Proxy . . . . . . . . . . . . . . . . . . . 155 270 15.4.7. 306 (Unused) . . . . . . . . . . . . . . . . . . . . 155 271 15.4.8. 307 Temporary Redirect . . . . . . . . . . . . . . . 155 272 15.4.9. 308 Permanent Redirect . . . . . . . . . . . . . . . 156 273 15.5. Client Error 4xx . . . . . . . . . . . . . . . . . . . . 156 274 15.5.1. 400 Bad Request . . . . . . . . . . . . . . . . . . 156 275 15.5.2. 401 Unauthorized . . . . . . . . . . . . . . . . . . 156 276 15.5.3. 402 Payment Required . . . . . . . . . . . . . . . . 157 277 15.5.4. 403 Forbidden . . . . . . . . . . . . . . . . . . . 157 278 15.5.5. 404 Not Found . . . . . . . . . . . . . . . . . . . 157 279 15.5.6. 405 Method Not Allowed . . . . . . . . . . . . . . . 158 280 15.5.7. 406 Not Acceptable . . . . . . . . . . . . . . . . . 158 281 15.5.8. 407 Proxy Authentication Required . . . . . . . . . 158 282 15.5.9. 408 Request Timeout . . . . . . . . . . . . . . . . 158 283 15.5.10. 409 Conflict . . . . . . . . . . . . . . . . . . . . 159 284 15.5.11. 410 Gone . . . . . . . . . . . . . . . . . . . . . . 159 285 15.5.12. 411 Length Required . . . . . . . . . . . . . . . . 159 286 15.5.13. 412 Precondition Failed . . . . . . . . . . . . . . 160 287 15.5.14. 413 Payload Too Large . . . . . . . . . . . . . . . 160 288 15.5.15. 414 URI Too Long . . . . . . . . . . . . . . . . . . 160 289 15.5.16. 415 Unsupported Media Type . . . . . . . . . . . . . 160 290 15.5.17. 416 Range Not Satisfiable . . . . . . . . . . . . . 161 291 15.5.18. 417 Expectation Failed . . . . . . . . . . . . . . . 161 292 15.5.19. 418 (Unused) . . . . . . . . . . . . . . . . . . . . 162 293 15.5.20. 422 Unprocessable Payload . . . . . . . . . . . . . 162 294 15.5.21. 426 Upgrade Required . . . . . . . . . . . . . . . . 162 295 15.6. Server Error 5xx . . . . . . . . . . . . . . . . . . . . 163 296 15.6.1. 500 Internal Server Error . . . . . . . . . . . . . 163 297 15.6.2. 501 Not Implemented . . . . . . . . . . . . . . . . 163 298 15.6.3. 502 Bad Gateway . . . . . . . . . . . . . . . . . . 163 299 15.6.4. 503 Service Unavailable . . . . . . . . . . . . . . 163 300 15.6.5. 504 Gateway Timeout . . . . . . . . . . . . . . . . 164 301 15.6.6. 505 HTTP Version Not Supported . . . . . . . . . . . 164 302 16. Extending HTTP . . . . . . . . . . . . . . . . . . . . . . . 164 303 16.1. Method Extensibility . . . . . . . . . . . . . . . . . . 165 304 16.1.1. Method Registry . . . . . . . . . . . . . . . . . . 165 305 16.1.2. Considerations for New Methods . . . . . . . . . . . 165 306 16.2. Status Code Extensibility . . . . . . . . . . . . . . . 166 307 16.2.1. Status Code Registry . . . . . . . . . . . . . . . . 166 308 16.2.2. Considerations for New Status Codes . . . . . . . . 166 309 16.3. Field Extensibility . . . . . . . . . . . . . . . . . . 167 310 16.3.1. Field Name Registry . . . . . . . . . . . . . . . . 168 311 16.3.2. Considerations for New Field Names . . . . . . . . . 169 312 16.3.3. Considerations for New Field Values . . . . . . . . 169 313 16.4. Authentication Scheme Extensibility . . . . . . . . . . 171 314 16.4.1. Authentication Scheme Registry . . . . . . . . . . . 171 315 16.4.2. Considerations for New Authentication Schemes . . . 171 316 16.5. Range Unit Extensibility . . . . . . . . . . . . . . . . 172 317 16.5.1. Range Unit Registry . . . . . . . . . . . . . . . . 173 318 16.5.2. Considerations for New Range Units . . . . . . . . . 173 319 16.6. Content Coding Extensibility . . . . . . . . . . . . . . 173 320 16.6.1. Content Coding Registry . . . . . . . . . . . . . . 173 321 16.6.2. Considerations for New Content Codings . . . . . . . 174 322 16.7. Upgrade Token Registry . . . . . . . . . . . . . . . . . 174 323 17. Security Considerations . . . . . . . . . . . . . . . . . . . 175 324 17.1. Establishing Authority . . . . . . . . . . . . . . . . . 175 325 17.2. Risks of Intermediaries . . . . . . . . . . . . . . . . 176 326 17.3. Attacks Based on File and Path Names . . . . . . . . . . 177 327 17.4. Attacks Based on Command, Code, or Query Injection . . . 177 328 17.5. Attacks via Protocol Element Length . . . . . . . . . . 178 329 17.6. Attacks using Shared-dictionary Compression . . . . . . 178 330 17.7. Disclosure of Personal Information . . . . . . . . . . . 179 331 17.8. Privacy of Server Log Information . . . . . . . . . . . 179 332 17.9. Disclosure of Sensitive Information in URIs . . . . . . 180 333 17.10. Disclosure of Fragment after Redirects . . . . . . . . . 180 334 17.11. Disclosure of Product Information . . . . . . . . . . . 181 335 17.12. Browser Fingerprinting . . . . . . . . . . . . . . . . . 181 336 17.13. Validator Retention . . . . . . . . . . . . . . . . . . 182 337 17.14. Denial-of-Service Attacks Using Range . . . . . . . . . 182 338 17.15. Authentication Considerations . . . . . . . . . . . . . 183 339 17.15.1. Confidentiality of Credentials . . . . . . . . . . 183 340 17.15.2. Credentials and Idle Clients . . . . . . . . . . . 183 341 17.15.3. Protection Spaces . . . . . . . . . . . . . . . . . 184 342 17.15.4. Additional Response Fields . . . . . . . . . . . . 184 343 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 184 344 18.1. URI Scheme Registration . . . . . . . . . . . . . . . . 185 345 18.2. Method Registration . . . . . . . . . . . . . . . . . . 185 346 18.3. Status Code Registration . . . . . . . . . . . . . . . . 185 347 18.4. Field Name Registration . . . . . . . . . . . . . . . . 187 348 18.5. Authentication Scheme Registration . . . . . . . . . . . 189 349 18.6. Content Coding Registration . . . . . . . . . . . . . . 189 350 18.7. Range Unit Registration . . . . . . . . . . . . . . . . 189 351 18.8. Media Type Registration . . . . . . . . . . . . . . . . 190 352 18.9. Port Registration . . . . . . . . . . . . . . . . . . . 190 353 18.10. Upgrade Token Registration . . . . . . . . . . . . . . . 190 354 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 190 355 19.1. Normative References . . . . . . . . . . . . . . . . . . 190 356 19.2. Informative References . . . . . . . . . . . . . . . . . 192 357 Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 199 358 Appendix B. Changes from previous RFCs . . . . . . . . . . . . . 203 359 B.1. Changes from RFC 2818 . . . . . . . . . . . . . . . . . . 203 360 B.2. Changes from RFC 7230 . . . . . . . . . . . . . . . . . . 204 361 B.3. Changes from RFC 7231 . . . . . . . . . . . . . . . . . . 205 362 B.4. Changes from RFC 7232 . . . . . . . . . . . . . . . . . . 206 363 B.5. Changes from RFC 7233 . . . . . . . . . . . . . . . . . . 206 364 B.6. Changes from RFC 7235 . . . . . . . . . . . . . . . . . . 206 365 B.7. Changes from RFC 7538 . . . . . . . . . . . . . . . . . . 207 366 B.8. Changes from RFC 7615 . . . . . . . . . . . . . . . . . . 207 367 B.9. Changes from RFC 7694 . . . . . . . . . . . . . . . . . . 207 368 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 207 369 C.1. Between RFC723x and draft 00 . . . . . . . . . . . . . . 207 370 C.2. Since draft-ietf-httpbis-semantics-00 . . . . . . . . . . 207 371 C.3. Since draft-ietf-httpbis-semantics-01 . . . . . . . . . . 208 372 C.4. Since draft-ietf-httpbis-semantics-02 . . . . . . . . . . 209 373 C.5. Since draft-ietf-httpbis-semantics-03 . . . . . . . . . . 210 374 C.6. Since draft-ietf-httpbis-semantics-04 . . . . . . . . . . 211 375 C.7. Since draft-ietf-httpbis-semantics-05 . . . . . . . . . . 211 376 C.8. Since draft-ietf-httpbis-semantics-06 . . . . . . . . . . 213 377 C.9. Since draft-ietf-httpbis-semantics-07 . . . . . . . . . . 214 378 C.10. Since draft-ietf-httpbis-semantics-08 . . . . . . . . . . 215 379 C.11. Since draft-ietf-httpbis-semantics-09 . . . . . . . . . . 217 380 C.12. Since draft-ietf-httpbis-semantics-10 . . . . . . . . . . 217 381 C.13. Since draft-ietf-httpbis-semantics-11 . . . . . . . . . . 219 382 C.14. Since draft-ietf-httpbis-semantics-12 . . . . . . . . . . 219 383 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 221 384 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 222 386 1. Introduction 388 1.1. Purpose 390 The Hypertext Transfer Protocol (HTTP) is a family of stateless, 391 application-level, request/response protocols that share a generic 392 interface, extensible semantics, and self-descriptive messages to 393 enable flexible interaction with network-based hypertext information 394 systems. 396 HTTP hides the details of how a service is implemented by presenting 397 a uniform interface to clients that is independent of the types of 398 resources provided. Likewise, servers do not need to be aware of 399 each client's purpose: a request can be considered in isolation 400 rather than being associated with a specific type of client or a 401 predetermined sequence of application steps. This allows general- 402 purpose implementations to be used effectively in many different 403 contexts, reduces interaction complexity, and enables independent 404 evolution over time. 406 HTTP is also designed for use as an intermediation protocol, wherein 407 proxies and gateways can translate non-HTTP information systems into 408 a more generic interface. 410 One consequence of this flexibility is that the protocol cannot be 411 defined in terms of what occurs behind the interface. Instead, we 412 are limited to defining the syntax of communication, the intent of 413 received communication, and the expected behavior of recipients. If 414 the communication is considered in isolation, then successful actions 415 ought to be reflected in corresponding changes to the observable 416 interface provided by servers. However, since multiple clients might 417 act in parallel and perhaps at cross-purposes, we cannot require that 418 such changes be observable beyond the scope of a single response. 420 1.2. History and Evolution 422 HTTP has been the primary information transfer protocol for the World 423 Wide Web since its introduction in 1990. It began as a trivial 424 mechanism for low-latency requests, with a single method (GET) to 425 request transfer of a presumed hypertext document identified by a 426 given pathname. This original protocol is now referred to as 427 HTTP/0.9 (see [HTTP/0.9]). 429 As the Web grew, HTTP was extended to enclose requests and responses 430 within messages, transfer arbitrary data formats using MIME-like 431 media types, and route requests through intermediaries, eventually 432 being defined as HTTP/1.0 [RFC1945]. 434 HTTP/1.1 was designed to refine the protocol's features while 435 retaining compatibility with the existing text-based messaging 436 syntax, improving its interoperability, scalability, and robustness 437 across the Internet. This included length-based payload delimiters 438 for both fixed and dynamic (chunked) content, a consistent framework 439 for content negotiation, opaque validators for conditional requests, 440 cache controls for better cache consistency, range requests for 441 partial updates, and default persistent connections. HTTP/1.1 was 442 introduced in 1995 and published on the standards track in 1997 443 [RFC2068], 1999 [RFC2616], and 2014 ([RFC7230] - [RFC7235]). 445 HTTP/2 ([RFC7540]) introduced a multiplexed session layer on top of 446 the existing TLS and TCP protocols for exchanging concurrent HTTP 447 messages with efficient field compression and server push. HTTP/3 448 ([HTTP3]) provides greater independence for concurrent messages by 449 using QUIC as a secure multiplexed transport over UDP instead of TCP. 451 All three major versions of HTTP rely on the semantics defined by 452 this document. They have not obsoleted each other because each one 453 has specific benefits and limitations depending on the context of 454 use. Implementations are expected to choose the most appropriate 455 transport and messaging syntax for their particular context. 457 This revision of HTTP separates the definition of semantics (this 458 document) and caching ([Caching]) from the current HTTP/1.1 messaging 459 syntax ([Messaging]) to allow each major protocol version to progress 460 independently while referring to the same core semantics. 462 1.3. Core Semantics 464 HTTP provides a uniform interface for interacting with a resource 465 (Section 3.1), regardless of its type, nature, or implementation, by 466 sending messages that manipulate or transfer representations 467 (Section 8). 469 Each message is either a request or a response. A client constructs 470 request messages that communicate its intentions and routes those 471 messages toward an identified origin server. A server listens for 472 requests, parses each message received, interprets the message 473 semantics in relation to the identified target resource, and responds 474 to that request with one or more response messages. The client 475 examines received responses to see if its intentions were carried 476 out, determining what to do next based on the received status and 477 payloads. 479 HTTP semantics include the intentions defined by each request method 480 (Section 9), extensions to those semantics that might be described in 481 request header fields, status codes that describe the response 482 (Section 15), and other control data and resource metadata that might 483 be given in response fields. 485 Semantics also include representation metadata that describe how a 486 payload is intended to be interpreted by a recipient, request header 487 fields that might influence content selection, and the various 488 selection algorithms that are collectively referred to as "_content 489 negotiation_" (Section 12). 491 1.4. Specifications Obsoleted by this Document 493 This document obsoletes the following specifications: 495 -------------------------------------------- ----------- --------- 496 Title Reference Changes 497 -------------------------------------------- ----------- --------- 498 HTTP Over TLS [RFC2818] B.1 499 HTTP/1.1 Message Syntax and Routing [*] [RFC7230] B.2 500 HTTP/1.1 Semantics and Content [RFC7231] B.3 501 HTTP/1.1 Conditional Requests [RFC7232] B.4 502 HTTP/1.1 Range Requests [RFC7233] B.5 503 HTTP/1.1 Authentication [RFC7235] B.6 504 HTTP Status Code 308 (Permanent Redirect) [RFC7538] B.7 505 HTTP Authentication-Info and Proxy- [RFC7615] B.8 506 Authentication-Info Response Header Fields 507 HTTP Client-Initiated Content-Encoding [RFC7694] B.9 508 -------------------------------------------- ----------- --------- 510 Table 1 512 [*] This document only obsoletes the portions of RFC 7230 that are 513 independent of the HTTP/1.1 messaging syntax and connection 514 management; the remaining bits of RFC 7230 are obsoleted by 515 "HTTP/1.1" [Messaging]. 517 2. Conformance 519 2.1. Syntax Notation 521 This specification uses the Augmented Backus-Naur Form (ABNF) 522 notation of [RFC5234], extended with the notation for case- 523 sensitivity in strings defined in [RFC7405]. 525 It also uses a list extension, defined in Section 5.6.1, that allows 526 for compact definition of comma-separated lists using a '#' operator 527 (similar to how the '*' operator indicates repetition). Appendix A 528 shows the collected grammar with all list operators expanded to 529 standard ABNF notation. 531 As a convention, ABNF rule names prefixed with "obs-" denote 532 "obsolete" grammar rules that appear for historical reasons. 534 The following core rules are included by reference, as defined in 535 Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), 536 CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double 537 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF 538 (line feed), OCTET (any 8-bit sequence of data), SP (space), and 539 VCHAR (any visible US-ASCII character). 541 Section 5.6 defines some generic syntactic components for field 542 values. 544 This specification uses the terms "character", "character encoding 545 scheme", "charset", and "protocol element" as they are defined in 546 [RFC6365]. 548 2.2. Requirements Notation 550 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 551 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 552 "OPTIONAL" in this document are to be interpreted as described in BCP 553 14 [RFC2119] [RFC8174] when, and only when, they appear in all 554 capitals, as shown here. 556 This specification targets conformance criteria according to the role 557 of a participant in HTTP communication. Hence, requirements are 558 placed on senders, recipients, clients, servers, user agents, 559 intermediaries, origin servers, proxies, gateways, or caches, 560 depending on what behavior is being constrained by the requirement. 561 Additional (social) requirements are placed on implementations, 562 resource owners, and protocol element registrations when they apply 563 beyond the scope of a single communication. 565 The verb "generate" is used instead of "send" where a requirement 566 applies only to implementations that create the protocol element, 567 rather than an implementation that forwards a received element 568 downstream. 570 An implementation is considered conformant if it complies with all of 571 the requirements associated with the roles it partakes in HTTP. 573 Conformance includes both the syntax and semantics of protocol 574 elements. A sender MUST NOT generate protocol elements that convey a 575 meaning that is known by that sender to be false. A sender MUST NOT 576 generate protocol elements that do not match the grammar defined by 577 the corresponding ABNF rules. Within a given message, a sender MUST 578 NOT generate protocol elements or syntax alternatives that are only 579 allowed to be generated by participants in other roles (i.e., a role 580 that the sender does not have for that message). 582 2.3. Length Requirements 584 When a received protocol element is parsed, the recipient MUST be 585 able to parse any value of reasonable length that is applicable to 586 the recipient's role and that matches the grammar defined by the 587 corresponding ABNF rules. Note, however, that some received protocol 588 elements might not be parsed. For example, an intermediary 589 forwarding a message might parse a field into generic field name and 590 field value components, but then forward the field without further 591 parsing inside the field value. 593 HTTP does not have specific length limitations for many of its 594 protocol elements because the lengths that might be appropriate will 595 vary widely, depending on the deployment context and purpose of the 596 implementation. Hence, interoperability between senders and 597 recipients depends on shared expectations regarding what is a 598 reasonable length for each protocol element. Furthermore, what is 599 commonly understood to be a reasonable length for some protocol 600 elements has changed over the course of the past two decades of HTTP 601 use and is expected to continue changing in the future. 603 At a minimum, a recipient MUST be able to parse and process protocol 604 element lengths that are at least as long as the values that it 605 generates for those same protocol elements in other messages. For 606 example, an origin server that publishes very long URI references to 607 its own resources needs to be able to parse and process those same 608 references when received as a target URI. 610 2.4. Error Handling 612 A recipient MUST interpret a received protocol element according to 613 the semantics defined for it by this specification, including 614 extensions to this specification, unless the recipient has determined 615 (through experience or configuration) that the sender incorrectly 616 implements what is implied by those semantics. For example, an 617 origin server might disregard the contents of a received 618 Accept-Encoding header field if inspection of the User-Agent header 619 field indicates a specific implementation version that is known to 620 fail on receipt of certain content codings. 622 Unless noted otherwise, a recipient MAY attempt to recover a usable 623 protocol element from an invalid construct. HTTP does not define 624 specific error handling mechanisms except when they have a direct 625 impact on security, since different applications of the protocol 626 require different error handling strategies. For example, a Web 627 browser might wish to transparently recover from a response where the 628 Location header field doesn't parse according to the ABNF, whereas a 629 systems control client might consider any form of error recovery to 630 be dangerous. 632 Some requests can be automatically retried by a client in the event 633 of an underlying connection failure, as described in Section 9.2.2. 635 2.5. Protocol Version 637 HTTP's version number consists of two decimal digits separated by a 638 "." (period or decimal point). The first digit ("major version") 639 indicates the messaging syntax, whereas the second digit ("minor 640 version") indicates the highest minor version within that major 641 version to which the sender is conformant (able to understand for 642 future communication). 644 While HTTP's core semantics don't change between protocol versions, 645 the expression of them "on the wire" can change, and so the HTTP 646 version number changes when incompatible changes are made to the wire 647 format. Additionally, HTTP allows incremental, backwards-compatible 648 changes to be made to the protocol without changing its version 649 through the use of defined extension points (Section 16). 651 The protocol version as a whole indicates the sender's conformance 652 with the set of requirements laid out in that version's corresponding 653 specification of HTTP. For example, the version "HTTP/1.1" is 654 defined by the combined specifications of this document, "HTTP 655 Caching" [Caching], and "HTTP/1.1" [Messaging]. 657 HTTP's major version number is incremented when an incompatible 658 message syntax is introduced. The minor number is incremented when 659 changes made to the protocol have the effect of adding to the message 660 semantics or implying additional capabilities of the sender. 662 The minor version advertises the sender's communication capabilities 663 even when the sender is only using a backwards-compatible subset of 664 the protocol, thereby letting the recipient know that more advanced 665 features can be used in response (by servers) or in future requests 666 (by clients). 668 When a major version of HTTP does not define any minor versions, the 669 minor version "0" is implied and is used when referring to that 670 protocol within a protocol element that requires sending a minor 671 version. 673 3. Terminology and Core Concepts 675 HTTP was created for the World Wide Web (WWW) architecture and has 676 evolved over time to support the scalability needs of a worldwide 677 hypertext system. Much of that architecture is reflected in the 678 terminology and syntax productions used to define HTTP. 680 3.1. Resources 682 The target of an HTTP request is called a "_resource_". HTTP does 683 not limit the nature of a resource; it merely defines an interface 684 that might be used to interact with resources. Most resources are 685 identified by a Uniform Resource Identifier (URI), as described in 686 Section 4. 688 One design goal of HTTP is to separate resource identification from 689 request semantics, which is made possible by vesting the request 690 semantics in the request method (Section 9) and a few request- 691 modifying header fields. If there is a conflict between the method 692 semantics and any semantic implied by the URI itself, as described in 693 Section 9.2.1, the method semantics take precedence. 695 HTTP relies upon the Uniform Resource Identifier (URI) standard 696 [RFC3986] to indicate the target resource (Section 7.1) and 697 relationships between resources. 699 3.2. Connections 701 HTTP is a client/server protocol that operates over a reliable 702 transport- or session-layer "_connection_". 704 An HTTP "_client_" is a program that establishes a connection to a 705 server for the purpose of sending one or more HTTP requests. An HTTP 706 "_server_" is a program that accepts connections in order to service 707 HTTP requests by sending HTTP responses. 709 The terms "client" and "server" refer only to the roles that these 710 programs perform for a particular connection. The same program might 711 act as a client on some connections and a server on others. 713 3.3. Messages 715 HTTP is a stateless request/response protocol for exchanging 716 "_messages_" across a connection. The terms "_sender_" and 717 "_recipient_" refer to any implementation that sends or receives a 718 given message, respectively. 720 A client sends requests to a server in the form of a _request_ 721 message with a method (Section 9) and request target (Section 7.1). 722 The request might also contain header fields (Section 6.3) for 723 request modifiers, client information, and representation metadata, a 724 payload (Section 6.4) to be processed in accordance with the method, 725 and trailer fields (Section 6.5) for metadata collected while sending 726 the payload. 728 A server responds to a client's request by sending one or more 729 _response_ messages, each including a status code (Section 15). The 730 response might also contain header fields for server information, 731 resource metadata, and representation metadata, payload data to be 732 interpreted in accordance with the status code, and trailer fields 733 for metadata collected while sending the payload. 735 3.4. User Agent 737 The term "_user agent_" refers to any of the various client programs 738 that initiate a request. 740 The most familiar form of user agent is the general-purpose Web 741 browser, but that's only a small percentage of implementations. 742 Other common user agents include spiders (web-traversing robots), 743 command-line tools, billboard screens, household appliances, scales, 744 light bulbs, firmware update scripts, mobile apps, and communication 745 devices in a multitude of shapes and sizes. 747 Being a user agent does not imply that there is a human user directly 748 interacting with the software agent at the time of a request. In 749 many cases, a user agent is installed or configured to run in the 750 background and save its results for later inspection (or save only a 751 subset of those results that might be interesting or erroneous). 752 Spiders, for example, are typically given a start URI and configured 753 to follow certain behavior while crawling the Web as a hypertext 754 graph. 756 Many user agents cannot, or choose not to, make interactive 757 suggestions to their user or provide adequate warning for security or 758 privacy concerns. In the few cases where this specification requires 759 reporting of errors to the user, it is acceptable for such reporting 760 to only be observable in an error console or log file. Likewise, 761 requirements that an automated action be confirmed by the user before 762 proceeding might be met via advance configuration choices, run-time 763 options, or simple avoidance of the unsafe action; confirmation does 764 not imply any specific user interface or interruption of normal 765 processing if the user has already made that choice. 767 3.5. Origin Server 769 The term "_origin server_" refers to a program that can originate 770 authoritative responses for a given target resource. 772 The most familiar form of origin server are large public websites. 773 However, like user agents being equated with browsers, it is easy to 774 be misled into thinking that all origin servers are alike. Common 775 origin servers also include home automation units, configurable 776 networking components, office machines, autonomous robots, news 777 feeds, traffic cameras, real-time ad selectors, and video-on-demand 778 platforms. 780 Most HTTP communication consists of a retrieval request (GET) for a 781 representation of some resource identified by a URI. In the simplest 782 case, this might be accomplished via a single bidirectional 783 connection (===) between the user agent (UA) and the origin server 784 (O). 786 request > 787 UA ======================================= O 788 < response 790 Figure 1 792 3.6. Intermediaries 794 HTTP enables the use of intermediaries to satisfy requests through a 795 chain of connections. There are three common forms of HTTP 796 _intermediary_: proxy, gateway, and tunnel. In some cases, a single 797 intermediary might act as an origin server, proxy, gateway, or 798 tunnel, switching behavior based on the nature of each request. 800 > > > > 801 UA =========== A =========== B =========== C =========== O 802 < < < < 804 Figure 2 806 The figure above shows three intermediaries (A, B, and C) between the 807 user agent and origin server. A request or response message that 808 travels the whole chain will pass through four separate connections. 810 Some HTTP communication options might apply only to the connection 811 with the nearest, non-tunnel neighbor, only to the endpoints of the 812 chain, or to all connections along the chain. Although the diagram 813 is linear, each participant might be engaged in multiple, 814 simultaneous communications. For example, B might be receiving 815 requests from many clients other than A, and/or forwarding requests 816 to servers other than C, at the same time that it is handling A's 817 request. Likewise, later requests might be sent through a different 818 path of connections, often based on dynamic configuration for load 819 balancing. 821 The terms "_upstream_" and "_downstream_" are used to describe 822 directional requirements in relation to the message flow: all 823 messages flow from upstream to downstream. The terms "inbound" and 824 "outbound" are used to describe directional requirements in relation 825 to the request route: "_inbound_" means toward the origin server and 826 "_outbound_" means toward the user agent. 828 A "_proxy_" is a message-forwarding agent that is chosen by the 829 client, usually via local configuration rules, to receive requests 830 for some type(s) of absolute URI and attempt to satisfy those 831 requests via translation through the HTTP interface. Some 832 translations are minimal, such as for proxy requests for "http" URIs, 833 whereas other requests might require translation to and from entirely 834 different application-level protocols. Proxies are often used to 835 group an organization's HTTP requests through a common intermediary 836 for the sake of security, annotation services, or shared caching. 837 Some proxies are designed to apply transformations to selected 838 messages or payloads while they are being forwarded, as described in 839 Section 7.7. 841 A "_gateway_" (a.k.a. "_reverse proxy_") is an intermediary that acts 842 as an origin server for the outbound connection but translates 843 received requests and forwards them inbound to another server or 844 servers. Gateways are often used to encapsulate legacy or untrusted 845 information services, to improve server performance through 846 "_accelerator_" caching, and to enable partitioning or load balancing 847 of HTTP services across multiple machines. 849 All HTTP requirements applicable to an origin server also apply to 850 the outbound communication of a gateway. A gateway communicates with 851 inbound servers using any protocol that it desires, including private 852 extensions to HTTP that are outside the scope of this specification. 853 However, an HTTP-to-HTTP gateway that wishes to interoperate with 854 third-party HTTP servers ought to conform to user agent requirements 855 on the gateway's inbound connection. 857 A "_tunnel_" acts as a blind relay between two connections without 858 changing the messages. Once active, a tunnel is not considered a 859 party to the HTTP communication, though the tunnel might have been 860 initiated by an HTTP request. A tunnel ceases to exist when both 861 ends of the relayed connection are closed. Tunnels are used to 862 extend a virtual connection through an intermediary, such as when 863 Transport Layer Security (TLS, [RFC8446]) is used to establish 864 confidential communication through a shared firewall proxy. 866 The above categories for intermediary only consider those acting as 867 participants in the HTTP communication. There are also 868 intermediaries that can act on lower layers of the network protocol 869 stack, filtering or redirecting HTTP traffic without the knowledge or 870 permission of message senders. Network intermediaries are 871 indistinguishable (at a protocol level) from an on-path attacker, 872 often introducing security flaws or interoperability problems due to 873 mistakenly violating HTTP semantics. 875 For example, an "_interception proxy_" [RFC3040] (also commonly known 876 as a "_transparent proxy_" [RFC1919] or "_captive portal_") differs 877 from an HTTP proxy because it is not chosen by the client. Instead, 878 an interception proxy filters or redirects outgoing TCP port 80 879 packets (and occasionally other common port traffic). Interception 880 proxies are commonly found on public network access points, as a 881 means of enforcing account subscription prior to allowing use of non- 882 local Internet services, and within corporate firewalls to enforce 883 network usage policies. 885 HTTP is defined as a stateless protocol, meaning that each request 886 message can be understood in isolation. Many implementations depend 887 on HTTP's stateless design in order to reuse proxied connections or 888 dynamically load balance requests across multiple servers. Hence, a 889 server MUST NOT assume that two requests on the same connection are 890 from the same user agent unless the connection is secured and 891 specific to that agent. Some non-standard HTTP extensions (e.g., 892 [RFC4559]) have been known to violate this requirement, resulting in 893 security and interoperability problems. 895 3.7. Caches 897 A "_cache_" is a local store of previous response messages and the 898 subsystem that controls its message storage, retrieval, and deletion. 899 A cache stores cacheable responses in order to reduce the response 900 time and network bandwidth consumption on future, equivalent 901 requests. Any client or server MAY employ a cache, though a cache 902 cannot be used by a server while it is acting as a tunnel. 904 The effect of a cache is that the request/response chain is shortened 905 if one of the participants along the chain has a cached response 906 applicable to that request. The following illustrates the resulting 907 chain if B has a cached copy of an earlier response from O (via C) 908 for a request that has not been cached by UA or A. 910 > > 911 UA =========== A =========== B - - - - - - C - - - - - - O 912 < < 914 Figure 3 916 A response is "_cacheable_" if a cache is allowed to store a copy of 917 the response message for use in answering subsequent requests. Even 918 when a response is cacheable, there might be additional constraints 919 placed by the client or by the origin server on when that cached 920 response can be used for a particular request. HTTP requirements for 921 cache behavior and cacheable responses are defined in Section 2 of 922 [Caching]. 924 There is a wide variety of architectures and configurations of caches 925 deployed across the World Wide Web and inside large organizations. 926 These include national hierarchies of proxy caches to save 927 transoceanic bandwidth, collaborative systems that broadcast or 928 multicast cache entries, archives of pre-fetched cache entries for 929 use in off-line or high-latency environments, and so on. 931 3.8. Example Message Exchange 933 The following example illustrates a typical HTTP/1.1 message exchange 934 for a GET request (Section 9.3.1) on the URI "http://www.example.com/ 935 hello.txt": 937 Client request: 939 GET /hello.txt HTTP/1.1 940 User-Agent: curl/7.16.3 libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3 941 Host: www.example.com 942 Accept-Language: en, mi 944 Server response: 946 HTTP/1.1 200 OK 947 Date: Mon, 27 Jul 2009 12:28:53 GMT 948 Server: Apache 949 Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT 950 ETag: "34aa387-d-1568eb00" 951 Accept-Ranges: bytes 952 Content-Length: 51 953 Vary: Accept-Encoding 954 Content-Type: text/plain 956 Hello World! My payload includes a trailing CRLF. 958 4. Identifiers in HTTP 960 Uniform Resource Identifiers (URIs) [RFC3986] are used throughout 961 HTTP as the means for identifying resources (Section 3.1). 963 4.1. URI References 965 URI references are used to target requests, indicate redirects, and 966 define relationships. 968 The definitions of "URI-reference", "absolute-URI", "relative-part", 969 "authority", "port", "host", "path-abempty", "segment", and "query" 970 are adopted from the URI generic syntax. An "absolute-path" rule is 971 defined for protocol elements that can contain a non-empty path 972 component. (This rule differs slightly from the path-abempty rule of 973 RFC 3986, which allows for an empty path to be used in references, 974 and path-absolute rule, which does not allow paths that begin with 975 "//".) A "partial-URI" rule is defined for protocol elements that 976 can contain a relative URI but not a fragment component. 978 URI-reference = 979 absolute-URI = 980 relative-part = 981 authority = 982 uri-host = 983 port = 984 path-abempty = 985 segment = 986 query = 988 absolute-path = 1*( "/" segment ) 989 partial-URI = relative-part [ "?" query ] 991 Each protocol element in HTTP that allows a URI reference will 992 indicate in its ABNF production whether the element allows any form 993 of reference (URI-reference), only a URI in absolute form (absolute- 994 URI), only the path and optional query components, or some 995 combination of the above. Unless otherwise indicated, URI references 996 are parsed relative to the target URI (Section 7.1). 998 It is RECOMMENDED that all senders and recipients support, at a 999 minimum, URIs with lengths of 8000 octets in protocol elements. Note 1000 that this implies some structures and on-wire representations (for 1001 example, the request line in HTTP/1.1) will necessarily be larger in 1002 some cases. 1004 4.2. HTTP-Related URI Schemes 1006 IANA maintains the registry of URI Schemes [BCP35] at 1007 . Although requests 1008 might target any URI scheme, the following schemes are inherent to 1009 HTTP servers: 1011 ------------ ------------------------------------ ------- 1012 URI Scheme Description Ref. 1013 ------------ ------------------------------------ ------- 1014 http Hypertext Transfer Protocol 4.2.1 1015 https Hypertext Transfer Protocol Secure 4.2.2 1016 ------------ ------------------------------------ ------- 1018 Table 2 1020 Note that the presence of an "http" or "https" URI does not imply 1021 that there is always an HTTP server at the identified origin 1022 listening for connections. Anyone can mint a URI, whether or not a 1023 server exists and whether or not that server currently maps that 1024 identifier to a resource. The delegated nature of registered names 1025 and IP addresses creates a federated namespace whether or not an HTTP 1026 server is present. 1028 4.2.1. http URI Scheme 1030 The "http" URI scheme is hereby defined for minting identifiers 1031 within the hierarchical namespace governed by a potential HTTP origin 1032 server listening for TCP ([RFC0793]) connections on a given port. 1034 http-URI = "http" "://" authority path-abempty [ "?" query ] 1036 The origin server for an "http" URI is identified by the authority 1037 component, which includes a host identifier and optional port number 1038 ([RFC3986], Section 3.2.2). If the port subcomponent is empty or not 1039 given, TCP port 80 (the reserved port for WWW services) is the 1040 default. The origin determines who has the right to respond 1041 authoritatively to requests that target the identified resource, as 1042 defined in Section 4.3.2. 1044 A sender MUST NOT generate an "http" URI with an empty host 1045 identifier. A recipient that processes such a URI reference MUST 1046 reject it as invalid. 1048 The hierarchical path component and optional query component identify 1049 the target resource within that origin server's name space. 1051 4.2.2. https URI Scheme 1053 The "https" URI scheme is hereby defined for minting identifiers 1054 within the hierarchical namespace governed by a potential origin 1055 server listening for TCP connections on a given port and capable of 1056 establishing a TLS ([RFC8446]) connection that has been secured for 1057 HTTP communication. In this context, "_secured_" specifically means 1058 that the server has been authenticated as acting on behalf of the 1059 identified authority and all HTTP communication with that server has 1060 been protected for confidentiality and integrity through the use of 1061 strong encryption. 1063 https-URI = "https" "://" authority path-abempty [ "?" query ] 1065 The origin server for an "https" URI is identified by the authority 1066 component, which includes a host identifier and optional port number 1067 ([RFC3986], Section 3.2.2). If the port subcomponent is empty or not 1068 given, TCP port 443 (the reserved port for HTTP over TLS) is the 1069 default. The origin determines who has the right to respond 1070 authoritatively to requests that target the identified resource, as 1071 defined in Section 4.3.3. 1073 A sender MUST NOT generate an "https" URI with an empty host 1074 identifier. A recipient that processes such a URI reference MUST 1075 reject it as invalid. 1077 The hierarchical path component and optional query component identify 1078 the target resource within that origin server's name space. 1080 A client MUST ensure that its HTTP requests for an "https" resource 1081 are secured, prior to being communicated, and that it only accepts 1082 secured responses to those requests. 1084 Resources made available via the "https" scheme have no shared 1085 identity with the "http" scheme. They are distinct origins with 1086 separate namespaces. However, an extension to HTTP that is defined 1087 to apply to all origins with the same host, such as the Cookie 1088 protocol [RFC6265], can allow information set by one service to 1089 impact communication with other services within a matching group of 1090 host domains. 1092 4.2.3. http(s) Normalization and Comparison 1094 Since the "http" and "https" schemes conform to the URI generic 1095 syntax, such URIs are normalized and compared according to the 1096 algorithm defined in Section 6 of [RFC3986], using the defaults 1097 described above for each scheme. 1099 If the port is equal to the default port for a scheme, the normal 1100 form is to omit the port subcomponent. When not being used as the 1101 target of an OPTIONS request, an empty path component is equivalent 1102 to an absolute path of "/", so the normal form is to provide a path 1103 of "/" instead. The scheme and host are case-insensitive and 1104 normally provided in lowercase; all other components are compared in 1105 a case-sensitive manner. Characters other than those in the 1106 "reserved" set are equivalent to their percent-encoded octets: the 1107 normal form is to not encode them (see Sections 2.1 and 2.2 of 1108 [RFC3986]). 1110 For example, the following three URIs are equivalent: 1112 http://example.com:80/~smith/home.html 1113 http://EXAMPLE.com/%7Esmith/home.html 1114 http://EXAMPLE.com:/%7esmith/home.html 1116 4.2.4. Deprecation of userinfo in http(s) URIs 1118 The URI generic syntax for authority also includes a userinfo 1119 subcomponent ([RFC3986], Section 3.2.1) for including user 1120 authentication information in the URI. In that subcomponent, the use 1121 of the format "user:password" is deprecated. 1123 Some implementations make use of the userinfo component for internal 1124 configuration of authentication information, such as within command 1125 invocation options, configuration files, or bookmark lists, even 1126 though such usage might expose a user identifier or password. 1128 A sender MUST NOT generate the userinfo subcomponent (and its "@" 1129 delimiter) when an "http" or "https" URI reference is generated 1130 within a message as a target URI or field value. 1132 Before making use of an "http" or "https" URI reference received from 1133 an untrusted source, a recipient SHOULD parse for userinfo and treat 1134 its presence as an error; it is likely being used to obscure the 1135 authority for the sake of phishing attacks. 1137 4.2.5. http(s) References with Fragment Identifiers 1139 Fragment identifiers allow for indirect identification of a secondary 1140 resource, independent of the URI scheme, as defined in Section 3.5 of 1141 [RFC3986]. Some protocol elements that refer to a URI allow 1142 inclusion of a fragment, while others do not. They are distinguished 1143 by use of the ABNF rule for elements where fragment is allowed; 1144 otherwise, a specific rule that excludes fragments is used. 1146 | *Note:* The fragment identifier component is not part of the 1147 | scheme definition for a URI scheme (see Section 4.3 of 1148 | [RFC3986]), thus does not appear in the ABNF definitions for 1149 | the "http" and "https" URI schemes above. 1151 4.3. Authoritative Access 1153 Authoritative access refers to dereferencing a given identifier, for 1154 the sake of access to the identified resource, in a way that the 1155 client believes is authoritative (controlled by the resource owner). 1156 The process for determining that access is defined by the URI scheme 1157 and often uses data within the URI components, such as the authority 1158 component when the generic syntax is used. However, authoritative 1159 access is not limited to the identified mechanism. 1161 Section 4.3.1 defines the concept of an origin as an aid to such 1162 uses, and the subsequent subsections explain how to establish a 1163 peer's association with an authority to represent an origin. 1165 See Section 17.1 for security considerations related to establishing 1166 authority. 1168 4.3.1. URI Origin 1170 The "_origin_" for a given URI is the triple of scheme, host, and 1171 port after normalizing the scheme and host to lowercase and 1172 normalizing the port to remove any leading zeros. If port is elided 1173 from the URI, the default port for that scheme is used. For example, 1174 the URI 1176 https://Example.Com/happy.js 1178 would have the origin 1179 { "https", "example.com", "443" } 1181 which can also be described as the normalized URI prefix with port 1182 always present: 1184 https://example.com:443 1186 Each origin defines its own namespace and controls how identifiers 1187 within that namespace are mapped to resources. In turn, how the 1188 origin responds to valid requests, consistently over time, determines 1189 the semantics that users will associate with a URI, and the 1190 usefulness of those semantics is what ultimately transforms these 1191 mechanisms into a "resource" for users to reference and access in the 1192 future. 1194 Two origins are distinct if they differ in scheme, host, or port. 1195 Even when it can be verified that the same entity controls two 1196 distinct origins, the two namespaces under those origins are distinct 1197 unless explicitly aliased by a server authoritative for that origin. 1199 Origin is also used within HTML and related Web protocols, beyond the 1200 scope of this document, as described in [RFC6454]. 1202 4.3.2. http origins 1204 Although HTTP is independent of the transport protocol, the "http" 1205 scheme (Section 4.2.1) is specific to associating authority with 1206 whomever controls the origin server listening for TCP connections on 1207 the indicated port of whatever host is identified within the 1208 authority component. This is a very weak sense of authority because 1209 it depends on both client-specific name resolution mechanisms and 1210 communication that might not be secured from an on-path attacker. 1211 Nevertheless, it is a sufficient minimum for binding "http" 1212 identifiers to an origin server for consistent resolution within a 1213 trusted environment. 1215 If the host identifier is provided as an IP address, the origin 1216 server is the listener (if any) on the indicated TCP port at that IP 1217 address. If host is a registered name, the registered name is an 1218 indirect identifier for use with a name resolution service, such as 1219 DNS, to find an address for an appropriate origin server. 1221 When an "http" URI is used within a context that calls for access to 1222 the indicated resource, a client MAY attempt access by resolving the 1223 host identifier to an IP address, establishing a TCP connection to 1224 that address on the indicated port, and sending an HTTP request 1225 message to the server containing the URI's identifying data. 1227 If the server responds to such a request with a non-interim HTTP 1228 response message, as described in Section 15, then that response is 1229 considered an authoritative answer to the client's request. 1231 Note, however, that the above is not the only means for obtaining an 1232 authoritative response, nor does it imply that an authoritative 1233 response is always necessary (see [Caching]). For example, the Alt- 1234 Svc header field [RFC7838] allows an origin server to identify other 1235 services that are also authoritative for that origin. Access to 1236 "http" identified resources might also be provided by protocols 1237 outside the scope of this document. 1239 4.3.3. https origins 1241 The "https" scheme (Section 4.2.2) associates authority based on the 1242 ability of a server to use the private key corresponding to a 1243 certificate that the client considers to be trustworthy for the 1244 identified origin server. The client usually relies upon a chain of 1245 trust, conveyed from some prearranged or configured trust anchor, to 1246 deem a certificate trustworthy (Section 4.3.4). 1248 In HTTP/1.1 and earlier, a client will only attribute authority to a 1249 server when they are communicating over a successfully established 1250 and secured connection specifically to that URI origin's host. The 1251 connection establishment and certificate verification are used as 1252 proof of authority. 1254 In HTTP/2 and HTTP/3, a client will attribute authority to a server 1255 when they are communicating over a successfully established and 1256 secured connection if the URI origin's host matches any of the hosts 1257 present in the server's certificate and the client believes that it 1258 could open a connection to that host for that URI. In practice, a 1259 client will make a DNS query to check that the origin's host contains 1260 the same server IP address as the established connection. This 1261 restriction can be removed by the origin server sending an equivalent 1262 ORIGIN frame [RFC8336]. 1264 The request target's host and port value are passed within each HTTP 1265 request, identifying the origin and distinguishing it from other 1266 namespaces that might be controlled by the same server (Section 7.2). 1267 It is the origin's responsibility to ensure that any services 1268 provided with control over its certificate's private key are equally 1269 responsible for managing the corresponding "https" namespaces, or at 1270 least prepared to reject requests that appear to have been 1271 misdirected. A server might be unwilling to serve as the origin for 1272 some hosts even when they have the authority to do so. 1274 For example, if a network attacker causes connections for port N to 1275 be received at port Q, checking the target URI is necessary to ensure 1276 that the attacker can't cause "https://example.com:N/foo" to be 1277 replaced by "https://example.com:Q/foo" without consent. 1279 Note that the "https" scheme does not rely on TCP and the connected 1280 port number for associating authority, since both are outside the 1281 secured communication and thus cannot be trusted as definitive. 1282 Hence, the HTTP communication might take place over any channel that 1283 has been secured, as defined in Section 4.2.2, including protocols 1284 that don't use TCP. 1286 When an "https" URI is used within a context that calls for access to 1287 the indicated resource, a client MAY attempt access by resolving the 1288 host identifier to an IP address, establishing a TCP connection to 1289 that address on the indicated port, securing the connection end-to- 1290 end by successfully initiating TLS over TCP with confidentiality and 1291 integrity protection, and sending an HTTP request message over that 1292 connection containing the URI's identifying data. 1294 If the server responds to such a request with a non-interim HTTP 1295 response message, as described in Section 15, then that response is 1296 considered an authoritative answer to the client's request. 1298 Note, however, that the above is not the only means for obtaining an 1299 authoritative response, nor does it imply that an authoritative 1300 response is always necessary (see [Caching]). 1302 4.3.4. https certificate verification 1304 To establish a secured connection to dereference a URI, a client MUST 1305 verify that the service's identity is an acceptable match for the 1306 URI's origin server. Certificate verification is used to prevent 1307 server impersonation by an on-path attacker or by an attacker that 1308 controls name resolution. This process requires that a client be 1309 configured with a set of trust anchors. 1311 In general, a client MUST verify the service identity using the 1312 verification process defined in Section 6 of [RFC6125] (for a 1313 reference identifier of type URI-ID) unless the client has been 1314 specifically configured to accept some other form of verification. 1315 For example, a client might be connecting to a server whose address 1316 and hostname are dynamic, with an expectation that the service will 1317 present a specific certificate (or a certificate matching some 1318 externally defined reference identity) rather than one matching the 1319 dynamic URI's origin server identifier. 1321 In special cases, it might be appropriate for a client to simply 1322 ignore the server's identity, but it must be understood that this 1323 leaves a connection open to active attack. 1325 If the certificate is not valid for the URI's origin server, a user 1326 agent MUST either notify the user (user agents MAY give the user an 1327 option to continue with the connection in any case) or terminate the 1328 connection with a bad certificate error. Automated clients MUST log 1329 the error to an appropriate audit log (if available) and SHOULD 1330 terminate the connection (with a bad certificate error). Automated 1331 clients MAY provide a configuration setting that disables this check, 1332 but MUST provide a setting which enables it. 1334 5. Fields 1336 HTTP uses "_fields_" to provide data in the form of extensible key/ 1337 value pairs with a registered key namespace. Fields are sent and 1338 received within the header and trailer sections of messages 1339 (Section 6). 1341 5.1. Field Names 1343 A field name labels the corresponding field value as having the 1344 semantics defined by that name. For example, the Date header field 1345 is defined in Section 10.2.2 as containing the origination timestamp 1346 for the message in which it appears. 1348 field-name = token 1350 Field names are case-insensitive and ought to be registered within 1351 the "Hypertext Transfer Protocol (HTTP) Field Name Registry"; see 1352 Section 16.3.1. 1354 The interpretation of a field does not change between minor versions 1355 of the same major HTTP version, though the default behavior of a 1356 recipient in the absence of such a field can change. Unless 1357 specified otherwise, fields are defined for all versions of HTTP. In 1358 particular, the Host and Connection fields ought to be recognized by 1359 all HTTP implementations whether or not they advertise conformance 1360 with HTTP/1.1. 1362 New fields can be introduced without changing the protocol version if 1363 their defined semantics allow them to be safely ignored by recipients 1364 that do not recognize them; see Section 16.3. 1366 A proxy MUST forward unrecognized header fields unless the field name 1367 is listed in the Connection header field (Section 7.6.1) or the proxy 1368 is specifically configured to block, or otherwise transform, such 1369 fields. Other recipients SHOULD ignore unrecognized header and 1370 trailer fields. Adhering to these requirements allows HTTP's 1371 functionality to be extended without updating or removing deployed 1372 intermediaries. 1374 5.2. Field Lines and Combined Field Value 1376 Field sections are composed of any number of "_field lines_", each 1377 with a "_field name_" (see Section 5.1) identifying the field, and a 1378 "_field line value_" that conveys data for that instance of the 1379 field. 1381 When a field name is only present once in a section, the combined 1382 "_field value_" for that field consists of the corresponding field 1383 line value. When a field name is repeated within a section, its 1384 combined field value consists of the list of corresponding field line 1385 values within that section, concatenated in order, with each non- 1386 empty field line value separated by a comma. 1388 For example, this section: 1390 Example-Field: Foo, Bar 1391 Example-Field: Baz 1393 contains two field lines, both with the field name "Example-Field". 1394 The first field line has a field line value of "Foo, Bar", while the 1395 second field line value is "Baz". The field value for "Example- 1396 Field" is a list with three members: "Foo", "Bar", and "Baz". 1398 5.3. Field Order 1400 A recipient MAY combine multiple field lines within a field section 1401 that have the same field name into one field line, without changing 1402 the semantics of the message, by appending each subsequent field line 1403 value to the initial field line value in order, separated by a comma 1404 and OWS (optional whitespace). For consistency, use comma SP. 1406 The order in which field lines with the same name are received is 1407 therefore significant to the interpretation of the field value; a 1408 proxy MUST NOT change the order of these field line values when 1409 forwarding a message. 1411 This means that, aside from the well-known exception noted below, a 1412 sender MUST NOT generate multiple field lines with the same name in a 1413 message (whether in the headers or trailers), or append a field line 1414 when a field line of the same name already exists in the message, 1415 unless that field's definition allows multiple field line values to 1416 be recombined as a comma-separated list [i.e., at least one 1417 alternative of the field's definition allows a comma-separated list, 1418 such as an ABNF rule of #(values) defined in Section 5.6.1]. 1420 | *Note:* In practice, the "Set-Cookie" header field ([RFC6265]) 1421 | often appears in a response message across multiple field lines 1422 | and does not use the list syntax, violating the above 1423 | requirements on multiple field lines with the same field name. 1424 | Since it cannot be combined into a single field value, 1425 | recipients ought to handle "Set-Cookie" as a special case while 1426 | processing fields. (See Appendix A.2.3 of [Kri2001] for 1427 | details.) 1429 The order in which field lines with differing field names are 1430 received in a section is not significant. However, it is good 1431 practice to send header fields that contain additional control data 1432 first, such as Host on requests and Date on responses, so that 1433 implementations can decide when not to handle a message as early as 1434 possible. 1436 A server MUST NOT apply a request to the target resource until the 1437 entire request header section is received, since later header field 1438 lines might include conditionals, authentication credentials, or 1439 deliberately misleading duplicate header fields that would impact 1440 request processing. 1442 5.4. Field Limits 1444 HTTP does not place a predefined limit on the length of each field 1445 line, field value, or on the length of a header or trailer section as 1446 a whole, as described in Section 2. Various ad hoc limitations on 1447 individual lengths are found in practice, often depending on the 1448 specific field's semantics. 1450 A server that receives a request header field line, field value, or 1451 set of fields larger than it wishes to process MUST respond with an 1452 appropriate 4xx (Client Error) status code. Ignoring such header 1453 fields would increase the server's vulnerability to request smuggling 1454 attacks (Section 11.2 of [Messaging]). 1456 A client MAY discard or truncate received field lines that are larger 1457 than the client wishes to process if the field semantics are such 1458 that the dropped value(s) can be safely ignored without changing the 1459 message framing or response semantics. 1461 5.5. Field Values 1463 HTTP field values typically have their syntax defined using ABNF 1464 ([RFC5234]), using the extension defined in Section 5.6.1 as 1465 necessary, and are usually constrained to the range of US-ASCII 1466 characters. Fields needing a greater range of characters can use an 1467 encoding such as the one defined in [RFC8187]. 1469 field-value = *field-content 1470 field-content = field-vchar 1471 [ 1*( SP / HTAB / field-vchar ) field-vchar ] 1472 field-vchar = VCHAR / obs-text 1474 Historically, HTTP allowed field content with text in the ISO-8859-1 1475 charset [ISO-8859-1], supporting other charsets only through use of 1476 [RFC2047] encoding. In practice, most HTTP field values use only a 1477 subset of the US-ASCII charset [USASCII]. Newly defined fields 1478 SHOULD limit their values to US-ASCII octets. A recipient SHOULD 1479 treat other octets in field content (obs-text) as opaque data. 1481 Field values containing control (CTL) characters such as CR or LF are 1482 invalid; recipients MUST either reject a field value containing 1483 control characters, or convert them to SP before processing or 1484 forwarding the message. 1486 Leading and trailing whitespace in raw field values is removed upon 1487 field parsing (e.g., Section 5.1 of [Messaging]). Field definitions 1488 where leading or trailing whitespace in values is significant will 1489 have to use a container syntax such as quoted-string (Section 5.6.4). 1491 Commas (",") often are used to separate members in field values. 1492 Fields that allow multiple members are referred to as _list-based 1493 fields_. Fields that only anticipate a single member are referred to 1494 as _singleton fields_. 1496 Because commas are used as a generic delimiter between members, they 1497 need to be treated with care if they are allowed as data within a 1498 member. This is true for both list-based and singleton fields, since 1499 a singleton field might be sent with multiple members erroneously; 1500 being able to detect this condition improves interoperability. 1501 Fields that expect to contain a comma within a member, such as an 1502 HTTP-date or URI-reference element, ought to be defined with 1503 delimiters around that element to distinguish any comma within that 1504 data from potential list separators. 1506 For example, a textual date and a URI (either of which might contain 1507 a comma) could be safely carried in list-based field values like 1508 these: 1510 Example-URI-Field: "http://example.com/a.html,foo", 1511 "http://without-a-comma.example.com/" 1512 Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005" 1514 Note that double-quote delimiters almost always are used with the 1515 quoted-string production; using a different syntax inside double- 1516 quotes will likely cause unnecessary confusion. 1518 Many fields (such as Content-Type, defined in Section 8.4) use a 1519 common syntax for parameters that allows both unquoted (token) and 1520 quoted (quoted-string) syntax for a parameter value (Section 5.6.6). 1521 Use of common syntax allows recipients to reuse existing parser 1522 components. When allowing both forms, the meaning of a parameter 1523 value ought to be the same whether it was received as a token or a 1524 quoted string. 1526 Historically, HTTP field values could be extended over multiple lines 1527 by preceding each extra line with at least one space or horizontal 1528 tab (obs-fold). This document assumes that any such obsolete line 1529 folding has been replaced with one or more SP octets prior to 1530 interpreting the field value, as described in Section 5.2 of 1531 [Messaging]. 1533 | *Note:* This specification does not use ABNF rules to define 1534 | each "Field Name: Field Value" pair, as was done in earlier 1535 | editions (published before [RFC7230]). Instead, ABNF rules are 1536 | named according to each registered field name, wherein the rule 1537 | defines the valid grammar for that field's corresponding field 1538 | values (i.e., after the field value has been extracted by a 1539 | generic field parser). 1541 5.6. Common Rules for Defining Field Values 1543 5.6.1. Lists (#rule ABNF Extension) 1545 A #rule extension to the ABNF rules of [RFC5234] is used to improve 1546 readability in the definitions of some list-based field values. 1548 A construct "#" is defined, similar to "*", for defining comma- 1549 delimited lists of elements. The full form is "#element" 1550 indicating at least and at most elements, each separated by a 1551 single comma (",") and optional whitespace (OWS). 1553 5.6.1.1. Sender Requirements 1555 In any production that uses the list construct, a sender MUST NOT 1556 generate empty list elements. In other words, a sender MUST generate 1557 lists that satisfy the following syntax: 1559 1#element => element *( OWS "," OWS element ) 1561 and: 1563 #element => [ 1#element ] 1565 and for n >= 1 and m > 1: 1567 #element => element *( OWS "," OWS element ) 1569 Appendix A shows the collected ABNF for senders after the list 1570 constructs have been expanded. 1572 5.6.1.2. Recipient Requirements 1574 Empty elements do not contribute to the count of elements present. A 1575 recipient MUST parse and ignore a reasonable number of empty list 1576 elements: enough to handle common mistakes by senders that merge 1577 values, but not so much that they could be used as a denial-of- 1578 service mechanism. In other words, a recipient MUST accept lists 1579 that satisfy the following syntax: 1581 #element => [ element ] *( OWS "," OWS [ element ] ) 1583 Note that because of the potential presence of empty list elements, 1584 the RFC 5234 ABNF cannot enforce the cardinality of list elements, 1585 and consequently all cases are mapped as if there was no cardinality 1586 specified. 1588 For example, given these ABNF productions: 1590 example-list = 1#example-list-elmt 1591 example-list-elmt = token ; see Section 5.6.2 1593 Then the following are valid values for example-list (not including 1594 the double quotes, which are present for delimitation only): 1596 "foo,bar" 1597 "foo ,bar," 1598 "foo , ,bar,charlie" 1600 In contrast, the following values would be invalid, since at least 1601 one non-empty element is required by the example-list production: 1603 "" 1604 "," 1605 ", ," 1607 5.6.2. Tokens 1609 Many HTTP field values are defined using common syntax components, 1610 separated by whitespace or specific delimiting characters. 1611 Delimiters are chosen from the set of US-ASCII visual characters not 1612 allowed in a token (DQUOTE and "(),/:;<=>?@[\]{}"). 1614 Tokens are short textual identifiers that do not include whitespace 1615 or delimiters. 1617 token = 1*tchar 1619 tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" 1620 / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" 1621 / DIGIT / ALPHA 1622 ; any VCHAR, except delimiters 1624 5.6.3. Whitespace 1626 This specification uses three rules to denote the use of linear 1627 whitespace: OWS (optional whitespace), RWS (required whitespace), and 1628 BWS ("bad" whitespace). 1630 The OWS rule is used where zero or more linear whitespace octets 1631 might appear. For protocol elements where optional whitespace is 1632 preferred to improve readability, a sender SHOULD generate the 1633 optional whitespace as a single SP; otherwise, a sender SHOULD NOT 1634 generate optional whitespace except as needed to white out invalid or 1635 unwanted protocol elements during in-place message filtering. 1637 The RWS rule is used when at least one linear whitespace octet is 1638 required to separate field tokens. A sender SHOULD generate RWS as a 1639 single SP. 1641 OWS and RWS have the same semantics as a single SP. Any content 1642 known to be defined as OWS or RWS MAY be replaced with a single SP 1643 before interpreting it or forwarding the message downstream. 1645 The BWS rule is used where the grammar allows optional whitespace 1646 only for historical reasons. A sender MUST NOT generate BWS in 1647 messages. A recipient MUST parse for such bad whitespace and remove 1648 it before interpreting the protocol element. 1650 BWS has no semantics. Any content known to be defined as BWS MAY be 1651 removed before interpreting it or forwarding the message downstream. 1653 OWS = *( SP / HTAB ) 1654 ; optional whitespace 1655 RWS = 1*( SP / HTAB ) 1656 ; required whitespace 1657 BWS = OWS 1658 ; "bad" whitespace 1660 5.6.4. Quoted Strings 1662 A string of text is parsed as a single value if it is quoted using 1663 double-quote marks. 1665 quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE 1666 qdtext = HTAB / SP / %x21 / %x23-5B / %x5D-7E / obs-text 1667 obs-text = %x80-FF 1669 The backslash octet ("\") can be used as a single-octet quoting 1670 mechanism within quoted-string and comment constructs. Recipients 1671 that process the value of a quoted-string MUST handle a quoted-pair 1672 as if it were replaced by the octet following the backslash. 1674 quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) 1676 A sender SHOULD NOT generate a quoted-pair in a quoted-string except 1677 where necessary to quote DQUOTE and backslash octets occurring within 1678 that string. A sender SHOULD NOT generate a quoted-pair in a comment 1679 except where necessary to quote parentheses ["(" and ")"] and 1680 backslash octets occurring within that comment. 1682 5.6.5. Comments 1684 Comments can be included in some HTTP fields by surrounding the 1685 comment text with parentheses. Comments are only allowed in fields 1686 containing "comment" as part of their field value definition. 1688 comment = "(" *( ctext / quoted-pair / comment ) ")" 1689 ctext = HTAB / SP / %x21-27 / %x2A-5B / %x5D-7E / obs-text 1691 5.6.6. Parameters 1693 Parameters are instances of name=value pairs; they are often used in 1694 field values as a common syntax for appending auxiliary information 1695 to an item. Each parameter is usually delimited by an immediately 1696 preceding semicolon. 1698 parameters = *( OWS ";" OWS [ parameter ] ) 1699 parameter = parameter-name "=" parameter-value 1700 parameter-name = token 1701 parameter-value = ( token / quoted-string ) 1703 Parameter names are case-insensitive. Parameter values might or 1704 might not be case-sensitive, depending on the semantics of the 1705 parameter name. Examples of parameters and some equivalent forms can 1706 be seen in media types (Section 8.4.1) and the Accept header field 1707 (Section 12.5.1). 1709 A parameter value that matches the token production can be 1710 transmitted either as a token or within a quoted-string. The quoted 1711 and unquoted values are equivalent. 1713 | *Note:* Parameters do not allow whitespace (not even "bad" 1714 | whitespace) around the "=" character. 1716 5.6.7. Date/Time Formats 1718 Prior to 1995, there were three different formats commonly used by 1719 servers to communicate timestamps. For compatibility with old 1720 implementations, all three are defined here. The preferred format is 1721 a fixed-length and single-zone subset of the date and time 1722 specification used by the Internet Message Format [RFC5322]. 1724 HTTP-date = IMF-fixdate / obs-date 1726 An example of the preferred format is 1728 Sun, 06 Nov 1994 08:49:37 GMT ; IMF-fixdate 1730 Examples of the two obsolete formats are 1732 Sunday, 06-Nov-94 08:49:37 GMT ; obsolete RFC 850 format 1733 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format 1735 A recipient that parses a timestamp value in an HTTP field MUST 1736 accept all three HTTP-date formats. When a sender generates a field 1737 that contains one or more timestamps defined as HTTP-date, the sender 1738 MUST generate those timestamps in the IMF-fixdate format. 1740 An HTTP-date value represents time as an instance of Coordinated 1741 Universal Time (UTC). The first two formats indicate UTC by the 1742 three-letter abbreviation for Greenwich Mean Time, "GMT", a 1743 predecessor of the UTC name; values in the asctime format are assumed 1744 to be in UTC. A sender that generates HTTP-date values from a local 1745 clock ought to use NTP ([RFC5905]) or some similar protocol to 1746 synchronize its clock to UTC. 1748 Preferred format: 1750 IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT 1751 ; fixed length/zone/capitalization subset of the format 1752 ; see Section 3.3 of [RFC5322] 1754 day-name = %s"Mon" / %s"Tue" / %s"Wed" 1755 / %s"Thu" / %s"Fri" / %s"Sat" / %s"Sun" 1757 date1 = day SP month SP year 1758 ; e.g., 02 Jun 1982 1760 day = 2DIGIT 1761 month = %s"Jan" / %s"Feb" / %s"Mar" / %s"Apr" 1762 / %s"May" / %s"Jun" / %s"Jul" / %s"Aug" 1763 / %s"Sep" / %s"Oct" / %s"Nov" / %s"Dec" 1764 year = 4DIGIT 1766 GMT = %s"GMT" 1768 time-of-day = hour ":" minute ":" second 1769 ; 00:00:00 - 23:59:60 (leap second) 1771 hour = 2DIGIT 1772 minute = 2DIGIT 1773 second = 2DIGIT 1775 Obsolete formats: 1777 obs-date = rfc850-date / asctime-date 1778 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 1779 date2 = day "-" month "-" 2DIGIT 1780 ; e.g., 02-Jun-82 1782 day-name-l = %s"Monday" / %s"Tuesday" / %s"Wednesday" 1783 / %s"Thursday" / %s"Friday" / %s"Saturday" 1784 / %s"Sunday" 1786 asctime-date = day-name SP date3 SP time-of-day SP year 1787 date3 = month SP ( 2DIGIT / ( SP 1DIGIT )) 1788 ; e.g., Jun 2 1790 HTTP-date is case sensitive. Note that Section 4.2 of [Caching] 1791 relaxes this for cache recipients. 1793 A sender MUST NOT generate additional whitespace in an HTTP-date 1794 beyond that specifically included as SP in the grammar. The 1795 semantics of day-name, day, month, year, and time-of-day are the same 1796 as those defined for the Internet Message Format constructs with the 1797 corresponding name ([RFC5322], Section 3.3). 1799 Recipients of a timestamp value in rfc850-date format, which uses a 1800 two-digit year, MUST interpret a timestamp that appears to be more 1801 than 50 years in the future as representing the most recent year in 1802 the past that had the same last two digits. 1804 Recipients of timestamp values are encouraged to be robust in parsing 1805 timestamps unless otherwise restricted by the field definition. For 1806 example, messages are occasionally forwarded over HTTP from a non- 1807 HTTP source that might generate any of the date and time 1808 specifications defined by the Internet Message Format. 1810 | *Note:* HTTP requirements for the date/time stamp format apply 1811 | only to their usage within the protocol stream. 1812 | Implementations are not required to use these formats for user 1813 | presentation, request logging, etc. 1815 6. Message Abstraction 1817 Each major version of HTTP defines its own syntax for communicating 1818 messages. This section defines an abstract data type for HTTP 1819 messages based on a generalization of those message characteristics, 1820 common structure, and capacity for conveying semantics. This 1821 abstraction is used to define requirements on senders and recipients 1822 that are independent of the HTTP version, such that a message in one 1823 version can be relayed through other versions without changing its 1824 meaning. 1826 A _message_ consists of control data to describe and route the 1827 message, a headers lookup table of key/value pairs for extending that 1828 control data and conveying additional information about the sender, 1829 message, payload, or context, a potentially unbounded stream of 1830 payload data, and a trailers lookup table of key/value pairs for 1831 communicating information obtained while sending the payload. 1833 Framing and control data is sent first, followed by a header section 1834 containing fields for the headers table. When a message includes a 1835 payload, the payload data is sent after the header section and 1836 potentially interleaved with zero or more trailer sections containing 1837 fields for the trailers table. 1839 Messages are expected to be processed as a stream, wherein the 1840 purpose of that stream and its continued processing is revealed while 1841 being read. Hence, control data describes what the recipient needs 1842 to know immediately, header fields describe what needs to be known 1843 before receiving a payload, the payload (when present) presumably 1844 contains what the recipient wants or needs to fulfill the message 1845 semantics, and trailer fields provide additional metadata that can be 1846 dropped (safely ignored) when not desired. 1848 Messages are intended to be _self-descriptive_: everything a 1849 recipient needs to know about the message can be determined by 1850 looking at the message itself, after decoding or reconstituting parts 1851 that have been compressed or elided in transit, without requiring an 1852 understanding of the sender's current application state (established 1853 via prior messages). 1855 Note that this message abstraction is a generalization across many 1856 versions of HTTP, including features that might not be found in some 1857 versions. For example, trailers were introduced within the HTTP/1.1 1858 chunked transfer coding as a single trailer section at the end of the 1859 payload data. An equivalent feature is present in HTTP/2 and HTTP/3 1860 within the header block that terminates each stream. However, 1861 multiple trailer sections interleaved with payload data have only 1862 been deployed as frame extensions. 1864 6.1. Framing and Completeness 1866 Message framing indicates how each message begins and ends, such that 1867 each message can be distinguished from other messages or noise on the 1868 same connection. Each major version of HTTP defines its own framing 1869 mechanism. 1871 HTTP/0.9 and early deployments of HTTP/1.0 used closure of the 1872 underlying connection to end a response. For backwards 1873 compatibility, this implicit framing is also allowed in HTTP/1.1. 1875 However, implicit framing can fail to distinguish an incomplete 1876 response if the connection closes early. For that reason, almost all 1877 modern implementations use explicit framing in the form of length- 1878 delimited sequences of message data. 1880 A message is considered _complete_ when all of the octets indicated 1881 by its framing are available. Note that, when no explicit framing is 1882 used, a response message that is ended by the underlying connection's 1883 close is considered complete even though it might be 1884 indistinguishable from an incomplete response, unless a transport- 1885 level error indicates that it is not complete. 1887 6.2. Control Data 1889 Messages start with control data that describe its primary purpose. 1890 Request message control data includes a request method (Section 9), 1891 request target (Section 7.1), and protocol version (Section 2.5). 1892 Response message control data includes a status code (Section 15), 1893 optional reason phrase, and protocol version. 1895 In HTTP/1.1 [Messaging] and earlier, control data is sent as the 1896 first line of a message. In HTTP/2 ([RFC7540]) and HTTP/3 ([HTTP3]), 1897 control data is sent as pseudo-header fields with a reserved name 1898 prefix (e.g., ":authority"). 1900 Every HTTP message has a protocol version. Depending on the version 1901 in use, it might be identified within the message explicitly or 1902 inferred by the connection over which the message is received. 1903 Recipients use that version information to determine limitations or 1904 potential for later communication with that sender. 1906 When a message is forwarded by an intermediary, the protocol version 1907 is updated to reflect the version used by that intermediary. The Via 1908 header field (Section 7.6.3) is used to communicate upstream protocol 1909 information within a forwarded message. 1911 A client SHOULD send a request version equal to the highest version 1912 to which the client is conformant and whose major version is no 1913 higher than the highest version supported by the server, if this is 1914 known. A client MUST NOT send a version to which it is not 1915 conformant. 1917 A client MAY send a lower request version if it is known that the 1918 server incorrectly implements the HTTP specification, but only after 1919 the client has attempted at least one normal request and determined 1920 from the response status code or header fields (e.g., Server) that 1921 the server improperly handles higher request versions. 1923 A server SHOULD send a response version equal to the highest version 1924 to which the server is conformant that has a major version less than 1925 or equal to the one received in the request. A server MUST NOT send 1926 a version to which it is not conformant. A server can send a 505 1927 (HTTP Version Not Supported) response if it wishes, for any reason, 1928 to refuse service of the client's major protocol version. 1930 When an HTTP message is received with a major version number that the 1931 recipient implements, but a higher minor version number than what the 1932 recipient implements, the recipient SHOULD process the message as if 1933 it were in the highest minor version within that major version to 1934 which the recipient is conformant. A recipient can assume that a 1935 message with a higher minor version, when sent to a recipient that 1936 has not yet indicated support for that higher version, is 1937 sufficiently backwards-compatible to be safely processed by any 1938 implementation of the same major version. 1940 6.3. Header Fields 1942 Fields (Section 5) that are sent/received before the payload are 1943 referred to as "header fields" (or just "headers", colloquially). 1945 The "_header section_" of a message consists of a sequence of of 1946 header field lines. Each header field might modify or extend message 1947 semantics, describe the sender, define the payload, or provide 1948 additional context. 1950 | *Note:* We refer to named fields specifically as a "header 1951 | field" when they are only allowed to be sent in the header 1952 | section. 1954 6.4. Payload 1956 HTTP messages often transfer a complete or partial representation as 1957 the message "_payload_", including both representation metadata 1958 transferred as fields and representation data transferred as _payload 1959 data_: a stream of octets sent after the header section, as 1960 delineated by the message framing. 1962 This abstract definition of a payload reflects the data after it has 1963 been extracted from the message framing. For example, an HTTP/1.1 1964 message body (Section 6 of [Messaging]) might consist of a stream of 1965 data encoded with the chunked transfer coding-a sequence of data 1966 chunks, one zero-length chunk, and a trailer section-whereas the 1967 payload data of that same message includes only the data stream after 1968 the transfer coding has been decoded; it does not include the chunk 1969 lengths, chunked framing syntax, nor the trailer fields 1970 (Section 6.5). 1972 6.4.1. Payload Semantics 1974 The purpose of a payload in a request is defined by the method 1975 semantics (Section 9). 1977 For example, a representation in the payload of a PUT request 1978 (Section 9.3.4) represents the desired state of the target resource 1979 after the request is successfully applied, whereas a representation 1980 in the payload of a POST request (Section 9.3.3) represents 1981 information to be processed by the target resource. 1983 In a response, the payload's purpose is defined by both the request 1984 method and the response status code (Section 15). For example, the 1985 payload of a 200 (OK) response to GET (Section 9.3.1) represents the 1986 current state of the target resource, as observed at the time of the 1987 message origination date (Section 10.2.2), whereas the payload of the 1988 same status code in a response to POST might represent either the 1989 processing result or the new state of the target resource after 1990 applying the processing. 1992 The payload of a 206 (Partial Content) response to GET contains 1993 either a single part of the selected representation or a multipart 1994 message body containing multiple parts of that representation, as 1995 described in Section 15.3.7. 1997 Response messages with an error status code usually contain a payload 1998 that represents the error condition, such that the payload data 1999 describes the error state and what steps are suggested for resolving 2000 it. 2002 Responses to the HEAD request method (Section 9.3.2) never include a 2003 payload because the associated response header fields indicate only 2004 what their values would have been if the request method had been GET 2005 (Section 9.3.1). 2007 2xx (Successful) responses to a CONNECT request method 2008 (Section 9.3.6) switch the connection to tunnel mode instead of 2009 having a payload. 2011 All 1xx (Informational), 204 (No Content), and 304 (Not Modified) 2012 responses do not include a payload. 2014 All other responses do include a payload, although that payload data 2015 might be of zero length. 2017 6.4.2. Identifying Payloads 2019 When a complete or partial representation is transferred in a message 2020 payload, it is often desirable for the sender to supply, or the 2021 recipient to determine, an identifier for a resource corresponding to 2022 that representation. 2024 For a request message: 2026 o If the request has a Content-Location header field, then the 2027 sender asserts that the payload is a representation of the 2028 resource identified by the Content-Location field value. However, 2029 such an assertion cannot be trusted unless it can be verified by 2030 other means (not defined by this specification). The information 2031 might still be useful for revision history links. 2033 o Otherwise, the payload is unidentified. 2035 For a response message, the following rules are applied in order 2036 until a match is found: 2038 1. If the request method is GET or HEAD and the response status code 2039 is 200 (OK), 204 (No Content), 206 (Partial Content), or 304 (Not 2040 Modified), the payload is a representation of the resource 2041 identified by the target URI (Section 7.1). 2043 2. If the request method is GET or HEAD and the response status code 2044 is 203 (Non-Authoritative Information), the payload is a 2045 potentially modified or enhanced representation of the target 2046 resource as provided by an intermediary. 2048 3. If the response has a Content-Location header field and its field 2049 value is a reference to the same URI as the target URI, the 2050 payload is a representation of the target resource. 2052 4. If the response has a Content-Location header field and its field 2053 value is a reference to a URI different from the target URI, then 2054 the sender asserts that the payload is a representation of the 2055 resource identified by the Content-Location field value. 2056 However, such an assertion cannot be trusted unless it can be 2057 verified by other means (not defined by this specification). 2059 5. Otherwise, the payload is unidentified. 2061 6.5. Trailer Fields 2063 Fields (Section 5) that are sent/received after the header section 2064 has ended (usually after the payload data begins to stream) are 2065 referred to as "trailer fields" (or just "trailers", colloquially) 2066 and located within a "_trailer section_". Trailer fields can be 2067 useful for supplying message integrity checks, digital signatures, 2068 delivery metrics, or post-processing status information. 2070 Trailer fields ought to be processed and stored separately from the 2071 fields in the header section to avoid contradicting message semantics 2072 known at the time the header section was complete. The presence or 2073 absence of certain header fields might impact choices made for the 2074 routing or processing of the message as a whole before the trailers 2075 are received; those choices cannot be unmade by the later discovery 2076 of trailer fields. 2078 6.5.1. Limitations on use of Trailers 2080 Trailer sections are only possible when supported by the version of 2081 HTTP in use and enabled by an explicit framing mechanism. For 2082 example, the chunked coding in HTTP/1.1 allows a trailer section to 2083 be sent after the payload data (Section 7.1.2 of [Messaging]). 2085 Many fields cannot be processed outside the header section because 2086 their evaluation is necessary prior to receiving the payload data, 2087 such as those that describe message framing, routing, authentication, 2088 request modifiers, response controls, or payload data format. A 2089 sender MUST NOT generate a trailer field unless the sender knows the 2090 corresponding header field name's definition permits the field to be 2091 sent in trailers. 2093 Trailer fields can be difficult to process by intermediaries that 2094 forward messages from one protocol version to another. If the entire 2095 message can be buffered in transit, some intermediaries could merge 2096 trailer fields into the header section (as appropriate) before it is 2097 forwarded. However, in most cases, the trailers are simply 2098 discarded. A recipient MUST NOT merge a trailer field into a header 2099 section unless the recipient understands the corresponding header 2100 field definition and that definition explicitly permits and defines 2101 how trailer field values can be safely merged. 2103 The presence of the keyword "trailers" in the TE header field 2104 (Section 10.1.4) indicates that the client is willing to accept 2105 trailer fields, on behalf of itself and any downstream clients. For 2106 requests from an intermediary, this implies that all downstream 2107 clients are willing to accept trailer fields in the forwarded 2108 response. Note that the presence of "trailers" does not mean that 2109 the client(s) will process any particular trailer field in the 2110 response; only that the trailer section(s) will not be dropped by any 2111 of the clients. 2113 Because of the potential for trailer fields to be discarded in 2114 transit, a server SHOULD NOT generate trailer fields that it believes 2115 are necessary for the user agent to receive. 2117 6.5.2. Processing Trailer Fields 2119 Like header fields, trailer fields with the same name are processed 2120 in the order received; multiple trailer field lines with the same 2121 name have the equivalent semantics as appending the multiple values 2122 as a list of members, even when the field lines are received in 2123 separate trailer sections. Trailer fields that might be generated 2124 more than once during a message MUST be defined as a list-based field 2125 even if each member value is only processed once per field line 2126 received. 2128 Trailer fields are expected (but not required) to be processed one 2129 trailer section at a time. That is, for each trailer section 2130 received, a recipient that is looking for trailer fields will parse 2131 the received section into fields, invoke any associated processing 2132 for those fields at that point in the message processing, and then 2133 append those fields to the set of trailer fields received for the 2134 overall message. 2136 This behavior allows for iterative processing of trailer fields that 2137 contain incremental signatures or mid-stream status information, and 2138 fields that might refer to each other's values within the same 2139 section. However, there is no guarantee that trailer sections won't 2140 shift in relation to the payload data stream, or won't be recombined 2141 (or dropped) in transit. Trailer fields that refer to data outside 2142 the present trailer section need to use self-descriptive references 2143 (i.e., refer to the data by name, ordinal position, or an octet 2144 range) rather than assume it is the data most recently received. 2146 Likewise, at the end of a message, a recipient MAY treat the entire 2147 set of received trailer fields as one data structure to be considered 2148 as the message concludes. Additional processing expectations, if 2149 any, can be defined within the field specification for a field 2150 intended for use in trailers. 2152 7. Routing HTTP Messages 2154 HTTP request message routing is determined by each client based on 2155 the target resource, the client's proxy configuration, and 2156 establishment or reuse of an inbound connection. The corresponding 2157 response routing follows the same connection chain back to the 2158 client. 2160 7.1. Determining the Target Resource 2162 Although HTTP is used in a wide variety of applications, most clients 2163 rely on the same resource identification mechanism and configuration 2164 techniques as general-purpose Web browsers. Even when communication 2165 options are hard-coded in a client's configuration, we can think of 2166 their combined effect as a URI reference (Section 4.1). 2168 A URI reference is resolved to its absolute form in order to obtain 2169 the "_target URI_". The target URI excludes the reference's fragment 2170 component, if any, since fragment identifiers are reserved for 2171 client-side processing ([RFC3986], Section 3.5). 2173 To perform an action on a "_target resource_", the client sends a 2174 request message containing enough components of its parsed target URI 2175 to enable recipients to identify that same resource. For historical 2176 reasons, the parsed target URI components, collectively referred to 2177 as the "_request target_", are sent within the message control data 2178 and the Host header field (Section 7.2). 2180 There are two unusual cases for which the request target components 2181 are in a method-specific form: 2183 o For CONNECT (Section 9.3.6), the request target is the host name 2184 and port number of the tunnel destination, separated by a colon. 2186 o For OPTIONS (Section 9.3.7), the request target can be a single 2187 asterisk ("*"). 2189 See the respective method definitions for details. These forms MUST 2190 NOT be used with other methods. 2192 Upon receipt of a client's request, a server reconstructs the target 2193 URI from the received components in accordance with their local 2194 configuration and incoming connection context. This reconstruction 2195 is specific to each major protocol version. For example, Appendix of 2196 [Messaging] defines how a server determines the target URI of an 2197 HTTP/1.1 request. 2199 | *Note:* Previous specifications defined the recomposed target 2200 | URI as a distinct concept, the _effective request URI_. 2202 7.2. Host and :authority 2204 The "Host" header field in a request provides the host and port 2205 information from the target URI, enabling the origin server to 2206 distinguish among resources while servicing requests for multiple 2207 host names. 2209 In HTTP/2 [RFC7540] and HTTP/3 [HTTP3], the Host header field is, in 2210 some cases, supplanted by the ":authority" pseudo-header field of a 2211 request's control data. 2213 Host = uri-host [ ":" port ] ; Section 4 2215 The target URI's authority information is critical for handling a 2216 request. A user agent SHOULD generate Host as the first field in the 2217 header section of a request unless it has already generated that 2218 information as an ":authority" pseudo-header field. 2220 For example, a GET request to the origin server for 2221 would begin with: 2223 GET /pub/WWW/ HTTP/1.1 2224 Host: www.example.org 2226 Since the host and port information acts as an application-level 2227 routing mechanism, it is a frequent target for malware seeking to 2228 poison a shared cache or redirect a request to an unintended server. 2229 An interception proxy is particularly vulnerable if it relies on the 2230 host and port information for redirecting requests to internal 2231 servers, or for use as a cache key in a shared cache, without first 2232 verifying that the intercepted connection is targeting a valid IP 2233 address for that host. 2235 7.3. Routing Inbound Requests 2237 Once the target URI and its origin are determined, a client decides 2238 whether a network request is necessary to accomplish the desired 2239 semantics and, if so, where that request is to be directed. 2241 7.3.1. To a Cache 2243 If the client has a cache [Caching] and the request can be satisfied 2244 by it, then the request is usually directed there first. 2246 7.3.2. To a Proxy 2248 If the request is not satisfied by a cache, then a typical client 2249 will check its configuration to determine whether a proxy is to be 2250 used to satisfy the request. Proxy configuration is implementation- 2251 dependent, but is often based on URI prefix matching, selective 2252 authority matching, or both, and the proxy itself is usually 2253 identified by an "http" or "https" URI. If a proxy is applicable, 2254 the client connects inbound by establishing (or reusing) a connection 2255 to that proxy. 2257 7.3.3. To the Origin 2259 If no proxy is applicable, a typical client will invoke a handler 2260 routine, usually specific to the target URI's scheme, to connect 2261 directly to an origin for the target resource. How that is 2262 accomplished is dependent on the target URI scheme and defined by its 2263 associated specification. 2265 7.4. Rejecting Misdirected Requests 2267 Before performing a request, a server decides whether or not to 2268 provide service for the target URI via the connection in which the 2269 request is received. For example, a request might have been 2270 misdirected, deliberately or accidentally, such that the information 2271 within a received Host header field differs from the connection's 2272 host or port. 2274 If the connection is from a trusted gateway, such inconsistency might 2275 be expected; otherwise, it might indicate an attempt to bypass 2276 security filters, trick the server into delivering non-public 2277 content, or poison a cache. See Section 17 for security 2278 considerations regarding message routing. 2280 7.5. Response Correlation 2282 A connection might be used for multiple request/response exchanges. 2283 The mechanism used to correlate between request and response messages 2284 is version dependent; some versions of HTTP use implicit ordering of 2285 messages, while others use an explicit identifier. 2287 Responses (both final and interim) can be sent at any time after a 2288 request is received, even if it is not yet complete. However, 2289 clients (including intermediaries) might abandon a request if the 2290 response is not forthcoming within a reasonable period of time. 2292 7.6. Message Forwarding 2294 As described in Section 3.6, intermediaries can serve a variety of 2295 roles in the processing of HTTP requests and responses. Some 2296 intermediaries are used to improve performance or availability. 2297 Others are used for access control or to filter content. Since an 2298 HTTP stream has characteristics similar to a pipe-and-filter 2299 architecture, there are no inherent limits to the extent an 2300 intermediary can enhance (or interfere) with either direction of the 2301 stream. 2303 An intermediary not acting as a tunnel MUST implement the Connection 2304 header field, as specified in Section 7.6.1, and exclude fields from 2305 being forwarded that are only intended for the incoming connection. 2307 An intermediary MUST NOT forward a message to itself unless it is 2308 protected from an infinite request loop. In general, an intermediary 2309 ought to recognize its own server names, including any aliases, local 2310 variations, or literal IP addresses, and respond to such requests 2311 directly. 2313 An HTTP message can be parsed as a stream for incremental processing 2314 or forwarding downstream. However, recipients cannot rely on 2315 incremental delivery of partial messages, since some implementations 2316 will buffer or delay message forwarding for the sake of network 2317 efficiency, security checks, or payload transformations. 2319 7.6.1. Connection 2321 The "Connection" header field allows the sender to list desired 2322 control options for the current connection. 2324 When a field aside from Connection is used to supply control 2325 information for or about the current connection, the sender MUST list 2326 the corresponding field name within the Connection header field. 2327 Note that some versions of HTTP prohibit the use of fields for such 2328 information, and therefore do not allow the Connection field. 2330 Intermediaries MUST parse a received Connection header field before a 2331 message is forwarded and, for each connection-option in this field, 2332 remove any header or trailer field(s) from the message with the same 2333 name as the connection-option, and then remove the Connection header 2334 field itself (or replace it with the intermediary's own connection 2335 options for the forwarded message). 2337 Hence, the Connection header field provides a declarative way of 2338 distinguishing fields that are only intended for the immediate 2339 recipient ("hop-by-hop") from those fields that are intended for all 2340 recipients on the chain ("end-to-end"), enabling the message to be 2341 self-descriptive and allowing future connection-specific extensions 2342 to be deployed without fear that they will be blindly forwarded by 2343 older intermediaries. 2345 Furthermore, intermediaries SHOULD remove or replace field(s) whose 2346 semantics are known to require removal before forwarding, whether or 2347 not they appear as a Connection option, after applying those fields' 2348 semantics. This includes but is not limited to: 2350 o Proxy-Connection (Appendix C.2.2 of [Messaging]) 2352 o Keep-Alive (Section 19.7.1 of [RFC2068]) 2354 o TE (Section 10.1.4) 2356 o Trailer (Section 10.1.5) 2358 o Transfer-Encoding (Section 6.1 of [Messaging]) 2360 o Upgrade (Section 7.8) 2362 The Connection header field's value has the following grammar: 2364 Connection = #connection-option 2365 connection-option = token 2367 Connection options are case-insensitive. 2369 A sender MUST NOT send a connection option corresponding to a field 2370 that is intended for all recipients of the payload. For example, 2371 Cache-Control is never appropriate as a connection option 2372 (Section 5.2 of [Caching]). 2374 The connection options do not always correspond to a field present in 2375 the message, since a connection-specific field might not be needed if 2376 there are no parameters associated with a connection option. In 2377 contrast, a connection-specific field that is received without a 2378 corresponding connection option usually indicates that the field has 2379 been improperly forwarded by an intermediary and ought to be ignored 2380 by the recipient. 2382 When defining new connection options, specification authors ought to 2383 document it as reserved field name and register that definition in 2384 the Hypertext Transfer Protocol (HTTP) Field Name Registry 2385 (Section 16.3.1), to avoid collisions. 2387 7.6.2. Max-Forwards 2389 The "Max-Forwards" header field provides a mechanism with the TRACE 2390 (Section 9.3.8) and OPTIONS (Section 9.3.7) request methods to limit 2391 the number of times that the request is forwarded by proxies. This 2392 can be useful when the client is attempting to trace a request that 2393 appears to be failing or looping mid-chain. 2395 Max-Forwards = 1*DIGIT 2397 The Max-Forwards value is a decimal integer indicating the remaining 2398 number of times this request message can be forwarded. 2400 Each intermediary that receives a TRACE or OPTIONS request containing 2401 a Max-Forwards header field MUST check and update its value prior to 2402 forwarding the request. If the received value is zero (0), the 2403 intermediary MUST NOT forward the request; instead, the intermediary 2404 MUST respond as the final recipient. If the received Max-Forwards 2405 value is greater than zero, the intermediary MUST generate an updated 2406 Max-Forwards field in the forwarded message with a field value that 2407 is the lesser of a) the received value decremented by one (1) or b) 2408 the recipient's maximum supported value for Max-Forwards. 2410 A recipient MAY ignore a Max-Forwards header field received with any 2411 other request methods. 2413 7.6.3. Via 2415 The "Via" header field indicates the presence of intermediate 2416 protocols and recipients between the user agent and the server (on 2417 requests) or between the origin server and the client (on responses), 2418 similar to the "Received" header field in email (Section 3.6.7 of 2419 [RFC5322]). Via can be used for tracking message forwards, avoiding 2420 request loops, and identifying the protocol capabilities of senders 2421 along the request/response chain. 2423 Via = #( received-protocol RWS received-by [ RWS comment ] ) 2425 received-protocol = [ protocol-name "/" ] protocol-version 2426 ; see Section 7.8 2427 received-by = pseudonym [ ":" port ] 2428 pseudonym = token 2430 Each member of the Via field value represents a proxy or gateway that 2431 has forwarded the message. Each intermediary appends its own 2432 information about how the message was received, such that the end 2433 result is ordered according to the sequence of forwarding recipients. 2435 A proxy MUST send an appropriate Via header field, as described 2436 below, in each message that it forwards. An HTTP-to-HTTP gateway 2437 MUST send an appropriate Via header field in each inbound request 2438 message and MAY send a Via header field in forwarded response 2439 messages. 2441 For each intermediary, the received-protocol indicates the protocol 2442 and protocol version used by the upstream sender of the message. 2443 Hence, the Via field value records the advertised protocol 2444 capabilities of the request/response chain such that they remain 2445 visible to downstream recipients; this can be useful for determining 2446 what backwards-incompatible features might be safe to use in 2447 response, or within a later request, as described in Section 2.5. 2448 For brevity, the protocol-name is omitted when the received protocol 2449 is HTTP. 2451 The received-by portion is normally the host and optional port number 2452 of a recipient server or client that subsequently forwarded the 2453 message. However, if the real host is considered to be sensitive 2454 information, a sender MAY replace it with a pseudonym. If a port is 2455 not provided, a recipient MAY interpret that as meaning it was 2456 received on the default TCP port, if any, for the received-protocol. 2458 A sender MAY generate comments to identify the software of each 2459 recipient, analogous to the User-Agent and Server header fields. 2460 However, comments in Via are optional, and a recipient MAY remove 2461 them prior to forwarding the message. 2463 For example, a request message could be sent from an HTTP/1.0 user 2464 agent to an internal proxy code-named "fred", which uses HTTP/1.1 to 2465 forward the request to a public proxy at p.example.net, which 2466 completes the request by forwarding it to the origin server at 2467 www.example.com. The request received by www.example.com would then 2468 have the following Via header field: 2470 Via: 1.0 fred, 1.1 p.example.net 2472 An intermediary used as a portal through a network firewall SHOULD 2473 NOT forward the names and ports of hosts within the firewall region 2474 unless it is explicitly enabled to do so. If not enabled, such an 2475 intermediary SHOULD replace each received-by host of any host behind 2476 the firewall by an appropriate pseudonym for that host. 2478 An intermediary MAY combine an ordered subsequence of Via header 2479 field list members into a single member if the entries have identical 2480 received-protocol values. For example, 2482 Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy 2484 could be collapsed to 2486 Via: 1.0 ricky, 1.1 mertz, 1.0 lucy 2488 A sender SHOULD NOT combine multiple list members unless they are all 2489 under the same organizational control and the hosts have already been 2490 replaced by pseudonyms. A sender MUST NOT combine members that have 2491 different received-protocol values. 2493 7.7. Message Transformations 2495 Some intermediaries include features for transforming messages and 2496 their payloads. A proxy might, for example, convert between image 2497 formats in order to save cache space or to reduce the amount of 2498 traffic on a slow link. However, operational problems might occur 2499 when these transformations are applied to payloads intended for 2500 critical applications, such as medical imaging or scientific data 2501 analysis, particularly when integrity checks or digital signatures 2502 are used to ensure that the payload received is identical to the 2503 original. 2505 An HTTP-to-HTTP proxy is called a "_transforming proxy_" if it is 2506 designed or configured to modify messages in a semantically 2507 meaningful way (i.e., modifications, beyond those required by normal 2508 HTTP processing, that change the message in a way that would be 2509 significant to the original sender or potentially significant to 2510 downstream recipients). For example, a transforming proxy might be 2511 acting as a shared annotation server (modifying responses to include 2512 references to a local annotation database), a malware filter, a 2513 format transcoder, or a privacy filter. Such transformations are 2514 presumed to be desired by whichever client (or client organization) 2515 chose the proxy. 2517 If a proxy receives a target URI with a host name that is not a fully 2518 qualified domain name, it MAY add its own domain to the host name it 2519 received when forwarding the request. A proxy MUST NOT change the 2520 host name if the target URI contains a fully qualified domain name. 2522 A proxy MUST NOT modify the "absolute-path" and "query" parts of the 2523 received target URI when forwarding it to the next inbound server, 2524 except as noted above to replace an empty path with "/" or "*". 2526 A proxy MUST NOT transform the payload (Section 6.4) of a message 2527 that contains a no-transform cache-control response directive 2528 (Section 5.2 of [Caching]). Note that this does not include changes 2529 to the message body that do not affect the payload, such as transfer 2530 codings (Section 7 of [Messaging]). 2532 A proxy MAY transform the payload of a message that does not contain 2533 a no-transform cache-control directive. A proxy that transforms the 2534 payload of a 200 (OK) response can inform downstream recipients that 2535 a transformation has been applied by changing the response status 2536 code to 203 (Non-Authoritative Information) (Section 15.3.4). 2538 A proxy SHOULD NOT modify header fields that provide information 2539 about the endpoints of the communication chain, the resource state, 2540 or the selected representation (other than the payload) unless the 2541 field's definition specifically allows such modification or the 2542 modification is deemed necessary for privacy or security. 2544 7.8. Upgrade 2546 The "Upgrade" header field is intended to provide a simple mechanism 2547 for transitioning from HTTP/1.1 to some other protocol on the same 2548 connection. 2550 A client MAY send a list of protocol names in the Upgrade header 2551 field of a request to invite the server to switch to one or more of 2552 the named protocols, in order of descending preference, before 2553 sending the final response. A server MAY ignore a received Upgrade 2554 header field if it wishes to continue using the current protocol on 2555 that connection. Upgrade cannot be used to insist on a protocol 2556 change. 2558 Upgrade = #protocol 2560 protocol = protocol-name ["/" protocol-version] 2561 protocol-name = token 2562 protocol-version = token 2564 Although protocol names are registered with a preferred case, 2565 recipients SHOULD use case-insensitive comparison when matching each 2566 protocol-name to supported protocols. 2568 A server that sends a 101 (Switching Protocols) response MUST send an 2569 Upgrade header field to indicate the new protocol(s) to which the 2570 connection is being switched; if multiple protocol layers are being 2571 switched, the sender MUST list the protocols in layer-ascending 2572 order. A server MUST NOT switch to a protocol that was not indicated 2573 by the client in the corresponding request's Upgrade header field. A 2574 server MAY choose to ignore the order of preference indicated by the 2575 client and select the new protocol(s) based on other factors, such as 2576 the nature of the request or the current load on the server. 2578 A server that sends a 426 (Upgrade Required) response MUST send an 2579 Upgrade header field to indicate the acceptable protocols, in order 2580 of descending preference. 2582 A server MAY send an Upgrade header field in any other response to 2583 advertise that it implements support for upgrading to the listed 2584 protocols, in order of descending preference, when appropriate for a 2585 future request. 2587 The following is a hypothetical example sent by a client: 2589 GET /hello HTTP/1.1 2590 Host: www.example.com 2591 Connection: upgrade 2592 Upgrade: websocket, IRC/6.9, RTA/x11 2594 The capabilities and nature of the application-level communication 2595 after the protocol change is entirely dependent upon the new 2596 protocol(s) chosen. However, immediately after sending the 101 2597 (Switching Protocols) response, the server is expected to continue 2598 responding to the original request as if it had received its 2599 equivalent within the new protocol (i.e., the server still has an 2600 outstanding request to satisfy after the protocol has been changed, 2601 and is expected to do so without requiring the request to be 2602 repeated). 2604 For example, if the Upgrade header field is received in a GET request 2605 and the server decides to switch protocols, it first responds with a 2606 101 (Switching Protocols) message in HTTP/1.1 and then immediately 2607 follows that with the new protocol's equivalent of a response to a 2608 GET on the target resource. This allows a connection to be upgraded 2609 to protocols with the same semantics as HTTP without the latency cost 2610 of an additional round trip. A server MUST NOT switch protocols 2611 unless the received message semantics can be honored by the new 2612 protocol; an OPTIONS request can be honored by any protocol. 2614 The following is an example response to the above hypothetical 2615 request: 2617 HTTP/1.1 101 Switching Protocols 2618 Connection: upgrade 2619 Upgrade: websocket 2621 [... data stream switches to websocket with an appropriate response 2622 (as defined by new protocol) to the "GET /hello" request ...] 2624 When Upgrade is sent, the sender MUST also send a Connection header 2625 field (Section 7.6.1) that contains an "upgrade" connection option, 2626 in order to prevent Upgrade from being accidentally forwarded by 2627 intermediaries that might not implement the listed protocols. A 2628 server MUST ignore an Upgrade header field that is received in an 2629 HTTP/1.0 request. 2631 A client cannot begin using an upgraded protocol on the connection 2632 until it has completely sent the request message (i.e., the client 2633 can't change the protocol it is sending in the middle of a message). 2634 If a server receives both an Upgrade and an Expect header field with 2635 the "100-continue" expectation (Section 10.1.1), the server MUST send 2636 a 100 (Continue) response before sending a 101 (Switching Protocols) 2637 response. 2639 The Upgrade header field only applies to switching protocols on top 2640 of the existing connection; it cannot be used to switch the 2641 underlying connection (transport) protocol, nor to switch the 2642 existing communication to a different connection. For those 2643 purposes, it is more appropriate to use a 3xx (Redirection) response 2644 (Section 15.4). 2646 This specification only defines the protocol name "HTTP" for use by 2647 the family of Hypertext Transfer Protocols, as defined by the HTTP 2648 version rules of Section 2.5 and future updates to this 2649 specification. Additional protocol names ought to be registered 2650 using the registration procedure defined in Section 16.7. 2652 8. Representations 2654 A "_representation_" is information that is intended to reflect a 2655 past, current, or desired state of a given resource, in a format that 2656 can be readily communicated via the protocol. A representation 2657 consists of a set of representation metadata and a potentially 2658 unbounded stream of representation data. 2660 HTTP allows "information hiding" behind its uniform interface by 2661 phrasing communication with respect to a transferable representation 2662 of the resource state, rather than transferring the resource itself. 2663 This allows the resource identified by a URI to be anything, 2664 including temporal functions like "the current weather in Laguna 2665 Beach", while potentially providing information that represents that 2666 resource at the time a message is generated [REST]. 2668 The uniform interface is similar to a window through which one can 2669 observe and act upon a thing only through the communication of 2670 messages to an independent actor on the other side. A shared 2671 abstraction is needed to represent ("take the place of") the current 2672 or desired state of that thing in our communications. When a 2673 representation is hypertext, it can provide both a representation of 2674 the resource state and processing instructions that help guide the 2675 recipient's future interactions. 2677 8.1. Selected Representations 2679 An origin server might be provided with, or be capable of generating, 2680 multiple representations that are each intended to reflect the 2681 current state of a target resource. In such cases, some algorithm is 2682 used by the origin server to select one of those representations as 2683 most applicable to a given request, usually based on content 2684 negotiation. This "_selected representation_" is used to provide the 2685 data and metadata for evaluating conditional requests (Section 13.1) 2686 and constructing the payload for 200 (OK), 206 (Partial Content), and 2687 304 (Not Modified) responses to GET (Section 9.3.1). 2689 8.2. Representation Data 2691 The representation data associated with an HTTP message is either 2692 provided as the payload data of the message or referred to by the 2693 message semantics and the target URI. The representation data is in 2694 a format and encoding defined by the representation metadata header 2695 fields. 2697 The data type of the representation data is determined via the header 2698 fields Content-Type and Content-Encoding. These define a two-layer, 2699 ordered encoding model: 2701 representation-data := Content-Encoding( Content-Type( bits ) ) 2703 8.3. Representation Metadata 2705 Representation header fields provide metadata about the 2706 representation. When a message includes payload data, the 2707 representation header fields describe how to interpret that data. In 2708 a response to a HEAD request, the representation header fields 2709 describe the representation data that would have been enclosed in the 2710 payload if the same request had been a GET. 2712 8.4. Content-Type 2714 The "Content-Type" header field indicates the media type of the 2715 associated representation: either the representation enclosed in the 2716 message payload or the selected representation, as determined by the 2717 message semantics. The indicated media type defines both the data 2718 format and how that data is intended to be processed by a recipient, 2719 within the scope of the received message semantics, after any content 2720 codings indicated by Content-Encoding are decoded. 2722 Content-Type = media-type 2724 Media types are defined in Section 8.4.1. An example of the field is 2726 Content-Type: text/html; charset=ISO-8859-4 2728 A sender that generates a message containing payload data SHOULD 2729 generate a Content-Type header field in that message unless the 2730 intended media type of the enclosed representation is unknown to the 2731 sender. If a Content-Type header field is not present, the recipient 2732 MAY either assume a media type of "application/octet-stream" 2733 ([RFC2046], Section 4.5.1) or examine the data to determine its type. 2735 In practice, resource owners do not always properly configure their 2736 origin server to provide the correct Content-Type for a given 2737 representation. Some user agents examine a payload's content and, in 2738 certain cases, override the received type (for example, see 2739 [Sniffing]). This "MIME sniffing" risks drawing incorrect 2740 conclusions about the data, which might expose the user to additional 2741 security risks (e.g., "privilege escalation"). Furthermore, it is 2742 impossible to determine the sender's intended processing model by 2743 examining the data format: many data formats match multiple media 2744 types that differ only in processing semantics. Implementers are 2745 encouraged to provide a means to disable such sniffing. 2747 Furthermore, although Content-Type is defined as a singleton field, 2748 it is sometimes incorrectly generated multiple times, resulting in a 2749 combined field value that appears to be a list. Recipients often 2750 attempt to handle this error by using the last syntactically valid 2751 member of the list, but note that some implementations might have 2752 different error handling behaviors, leading to interoperability and/ 2753 or security issues. 2755 8.4.1. Media Type 2757 HTTP uses media types [RFC2046] in the Content-Type (Section 8.4) and 2758 Accept (Section 12.5.1) header fields in order to provide open and 2759 extensible data typing and type negotiation. Media types define both 2760 a data format and various processing models: how to process that data 2761 in accordance with each context in which it is received. 2763 media-type = type "/" subtype parameters 2764 type = token 2765 subtype = token 2767 The type and subtype tokens are case-insensitive. 2769 The type/subtype MAY be followed by semicolon-delimited parameters 2770 (Section 5.6.6) in the form of name=value pairs. The presence or 2771 absence of a parameter might be significant to the processing of a 2772 media type, depending on its definition within the media type 2773 registry. Parameter values might or might not be case-sensitive, 2774 depending on the semantics of the parameter name. 2776 For example, the following media types are equivalent in describing 2777 HTML text data encoded in the UTF-8 character encoding scheme, but 2778 the first is preferred for consistency (the "charset" parameter value 2779 is defined as being case-insensitive in [RFC2046], Section 4.1.2): 2781 text/html;charset=utf-8 2782 Text/HTML;Charset="utf-8" 2783 text/html; charset="utf-8" 2784 text/html;charset=UTF-8 2786 Media types ought to be registered with IANA according to the 2787 procedures defined in [BCP13]. 2789 8.4.2. Charset 2791 HTTP uses _charset_ names to indicate or negotiate the character 2792 encoding scheme of a textual representation [RFC6365]. A charset is 2793 identified by a case-insensitive token. 2795 charset = token 2797 Charset names ought to be registered in the IANA "Character Sets" 2798 registry () 2799 according to the procedures defined in Section 2 of [RFC2978]. 2801 | *Note:* In theory, charset names are defined by the "mime- 2802 | charset" ABNF rule defined in Section 2.3 of [RFC2978] (as 2803 | corrected in [Err1912]). That rule allows two characters that 2804 | are not included in "token" ("{" and "}"), but no charset name 2805 | registered at the time of this writing includes braces (see 2806 | [Err5433]). 2808 8.4.3. Canonicalization and Text Defaults 2810 Media types are registered with a canonical form in order to be 2811 interoperable among systems with varying native encoding formats. 2812 Representations selected or transferred via HTTP ought to be in 2813 canonical form, for many of the same reasons described by the 2814 Multipurpose Internet Mail Extensions (MIME) [RFC2045]. However, the 2815 performance characteristics of email deployments (i.e., store and 2816 forward messages to peers) are significantly different from those 2817 common to HTTP and the Web (server-based information services). 2818 Furthermore, MIME's constraints for the sake of compatibility with 2819 older mail transfer protocols do not apply to HTTP (see Appendix B of 2820 [Messaging]). 2822 MIME's canonical form requires that media subtypes of the "text" type 2823 use CRLF as the text line break. HTTP allows the transfer of text 2824 media with plain CR or LF alone representing a line break, when such 2825 line breaks are consistent for an entire representation. An HTTP 2826 sender MAY generate, and a recipient MUST be able to parse, line 2827 breaks in text media that consist of CRLF, bare CR, or bare LF. In 2828 addition, text media in HTTP is not limited to charsets that use 2829 octets 13 and 10 for CR and LF, respectively. This flexibility 2830 regarding line breaks applies only to text within a representation 2831 that has been assigned a "text" media type; it does not apply to 2832 "multipart" types or HTTP elements outside the payload data (e.g., 2833 header fields). 2835 If a representation is encoded with a content-coding, the underlying 2836 data ought to be in a form defined above prior to being encoded. 2838 8.4.4. Multipart Types 2840 MIME provides for a number of "multipart" types - encapsulations of 2841 one or more representations within a single message body. All 2842 multipart types share a common syntax, as defined in Section 5.1.1 of 2843 [RFC2046], and include a boundary parameter as part of the media type 2844 value. The message body is itself a protocol element; a sender MUST 2845 generate only CRLF to represent line breaks between body parts. 2847 HTTP message framing does not use the multipart boundary as an 2848 indicator of message body length, though it might be used by 2849 implementations that generate or process the payload. For example, 2850 the "multipart/form-data" type is often used for carrying form data 2851 in a request, as described in [RFC7578], and the "multipart/ 2852 byteranges" type is defined by this specification for use in some 206 2853 (Partial Content) responses (see Section 15.3.7). 2855 8.5. Content-Encoding 2857 The "Content-Encoding" header field indicates what content codings 2858 have been applied to the representation, beyond those inherent in the 2859 media type, and thus what decoding mechanisms have to be applied in 2860 order to obtain data in the media type referenced by the Content-Type 2861 header field. Content-Encoding is primarily used to allow a 2862 representation's data to be compressed without losing the identity of 2863 its underlying media type. 2865 Content-Encoding = #content-coding 2867 An example of its use is 2869 Content-Encoding: gzip 2871 If one or more encodings have been applied to a representation, the 2872 sender that applied the encodings MUST generate a Content-Encoding 2873 header field that lists the content codings in the order in which 2874 they were applied. Note that the coding named "identity" is reserved 2875 for its special role in Accept-Encoding, and thus SHOULD NOT be 2876 included. 2878 Additional information about the encoding parameters can be provided 2879 by other header fields not defined by this specification. 2881 Unlike Transfer-Encoding (Section 6.1 of [Messaging]), the codings 2882 listed in Content-Encoding are a characteristic of the 2883 representation; the representation is defined in terms of the coded 2884 form, and all other metadata about the representation is about the 2885 coded form unless otherwise noted in the metadata definition. 2886 Typically, the representation is only decoded just prior to rendering 2887 or analogous usage. 2889 If the media type includes an inherent encoding, such as a data 2890 format that is always compressed, then that encoding would not be 2891 restated in Content-Encoding even if it happens to be the same 2892 algorithm as one of the content codings. Such a content coding would 2893 only be listed if, for some bizarre reason, it is applied a second 2894 time to form the representation. Likewise, an origin server might 2895 choose to publish the same data as multiple representations that 2896 differ only in whether the coding is defined as part of Content-Type 2897 or Content-Encoding, since some user agents will behave differently 2898 in their handling of each response (e.g., open a "Save as ..." dialog 2899 instead of automatic decompression and rendering of content). 2901 An origin server MAY respond with a status code of 415 (Unsupported 2902 Media Type) if a representation in the request message has a content 2903 coding that is not acceptable. 2905 8.5.1. Content Codings 2907 Content coding values indicate an encoding transformation that has 2908 been or can be applied to a representation. Content codings are 2909 primarily used to allow a representation to be compressed or 2910 otherwise usefully transformed without losing the identity of its 2911 underlying media type and without loss of information. Frequently, 2912 the representation is stored in coded form, transmitted directly, and 2913 only decoded by the final recipient. 2915 content-coding = token 2917 All content codings are case-insensitive and ought to be registered 2918 within the "HTTP Content Coding Registry", as described in 2919 Section 16.6 2921 Content-coding values are used in the Accept-Encoding 2922 (Section 12.5.3) and Content-Encoding (Section 8.5) header fields. 2924 8.5.1.1. Compress Coding 2926 The "compress" coding is an adaptive Lempel-Ziv-Welch (LZW) coding 2927 [Welch] that is commonly produced by the UNIX file compression 2928 program "compress". A recipient SHOULD consider "x-compress" to be 2929 equivalent to "compress". 2931 8.5.1.2. Deflate Coding 2933 The "deflate" coding is a "zlib" data format [RFC1950] containing a 2934 "deflate" compressed data stream [RFC1951] that uses a combination of 2935 the Lempel-Ziv (LZ77) compression algorithm and Huffman coding. 2937 | *Note:* Some non-conformant implementations send the "deflate" 2938 | compressed data without the zlib wrapper. 2940 8.5.1.3. Gzip Coding 2942 The "gzip" coding is an LZ77 coding with a 32-bit Cyclic Redundancy 2943 Check (CRC) that is commonly produced by the gzip file compression 2944 program [RFC1952]. A recipient SHOULD consider "x-gzip" to be 2945 equivalent to "gzip". 2947 8.6. Content-Language 2949 The "Content-Language" header field describes the natural language(s) 2950 of the intended audience for the representation. Note that this 2951 might not be equivalent to all the languages used within the 2952 representation. 2954 Content-Language = #language-tag 2956 Language tags are defined in Section 8.6.1. The primary purpose of 2957 Content-Language is to allow a user to identify and differentiate 2958 representations according to the users' own preferred language. 2959 Thus, if the content is intended only for a Danish-literate audience, 2960 the appropriate field is 2962 Content-Language: da 2964 If no Content-Language is specified, the default is that the content 2965 is intended for all language audiences. This might mean that the 2966 sender does not consider it to be specific to any natural language, 2967 or that the sender does not know for which language it is intended. 2969 Multiple languages MAY be listed for content that is intended for 2970 multiple audiences. For example, a rendition of the "Treaty of 2971 Waitangi", presented simultaneously in the original Maori and English 2972 versions, would call for 2974 Content-Language: mi, en 2976 However, just because multiple languages are present within a 2977 representation does not mean that it is intended for multiple 2978 linguistic audiences. An example would be a beginner's language 2979 primer, such as "A First Lesson in Latin", which is clearly intended 2980 to be used by an English-literate audience. In this case, the 2981 Content-Language would properly only include "en". 2983 Content-Language MAY be applied to any media type - it is not limited 2984 to textual documents. 2986 8.6.1. Language Tags 2988 A language tag, as defined in [RFC5646], identifies a natural 2989 language spoken, written, or otherwise conveyed by human beings for 2990 communication of information to other human beings. Computer 2991 languages are explicitly excluded. 2993 HTTP uses language tags within the Accept-Language and 2994 Content-Language header fields. Accept-Language uses the broader 2995 language-range production defined in Section 12.5.4, whereas 2996 Content-Language uses the language-tag production defined below. 2998 language-tag = 3000 A language tag is a sequence of one or more case-insensitive subtags, 3001 each separated by a hyphen character ("-", %x2D). In most cases, a 3002 language tag consists of a primary language subtag that identifies a 3003 broad family of related languages (e.g., "en" = English), which is 3004 optionally followed by a series of subtags that refine or narrow that 3005 language's range (e.g., "en-CA" = the variety of English as 3006 communicated in Canada). Whitespace is not allowed within a language 3007 tag. Example tags include: 3009 fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN 3011 See [RFC5646] for further information. 3013 8.7. Content-Length 3015 The "Content-Length" header field indicates the associated 3016 representation's data length as a decimal non-negative integer number 3017 of octets. When transferring a representation as a payload, Content- 3018 Length refers specifically to the amount of data enclosed so that it 3019 can be used to delimit framing (e.g., Section 6.2 of [Messaging]). 3020 In other cases, Content-Length indicates the selected 3021 representation's current length, which can be used by recipients to 3022 estimate transfer time or compare to previously stored 3023 representations. 3025 Content-Length = 1*DIGIT 3027 An example is 3029 Content-Length: 3495 3031 A sender MUST NOT send a Content-Length header field in any message 3032 that contains a Transfer-Encoding header field. 3034 A user agent SHOULD send a Content-Length in a request message when 3035 no Transfer-Encoding is sent and the request method defines a meaning 3036 for an enclosed payload. For example, a Content-Length header field 3037 is normally sent in a POST request even when the value is 0 3038 (indicating an empty payload data). A user agent SHOULD NOT send a 3039 Content-Length header field when the request message does not contain 3040 a payload data and the method semantics do not anticipate such data. 3042 A server MAY send a Content-Length header field in a response to a 3043 HEAD request (Section 9.3.2); a server MUST NOT send Content-Length 3044 in such a response unless its field value equals the decimal number 3045 of octets that would have been sent in the payload of a response if 3046 the same request had used the GET method. 3048 A server MAY send a Content-Length header field in a 304 (Not 3049 Modified) response to a conditional GET request (Section 15.4.5); a 3050 server MUST NOT send Content-Length in such a response unless its 3051 field value equals the decimal number of octets that would have been 3052 sent in the payload data of a 200 (OK) response to the same request. 3054 A server MUST NOT send a Content-Length header field in any response 3055 with a status code of 1xx (Informational) or 204 (No Content). A 3056 server MUST NOT send a Content-Length header field in any 2xx 3057 (Successful) response to a CONNECT request (Section 9.3.6). 3059 Aside from the cases defined above, in the absence of Transfer- 3060 Encoding, an origin server SHOULD send a Content-Length header field 3061 when the payload data size is known prior to sending the complete 3062 header section. This will allow downstream recipients to measure 3063 transfer progress, know when a received message is complete, and 3064 potentially reuse the connection for additional requests. 3066 Any Content-Length field value greater than or equal to zero is 3067 valid. Since there is no predefined limit to the length of a 3068 payload, a recipient MUST anticipate potentially large decimal 3069 numerals and prevent parsing errors due to integer conversion 3070 overflows (Section 17.5). 3072 If a message is received that has a Content-Length header field value 3073 consisting of the same decimal value as a comma-separated list 3074 (Section 5.6.1) - for example, "Content-Length: 42, 42" - indicating 3075 that duplicate Content-Length header fields have been generated or 3076 combined by an upstream message processor, then the recipient MUST 3077 either reject the message as invalid or replace the duplicated field 3078 values with a single valid Content-Length field containing that 3079 decimal value. 3081 8.8. Content-Location 3083 The "Content-Location" header field references a URI that can be used 3084 as an identifier for a specific resource corresponding to the 3085 representation in this message's payload. In other words, if one 3086 were to perform a GET request on this URI at the time of this 3087 message's generation, then a 200 (OK) response would contain the same 3088 representation that is enclosed as payload in this message. 3090 Content-Location = absolute-URI / partial-URI 3092 The field value is either an absolute-URI or a partial-URI. In the 3093 latter case (Section 4), the referenced URI is relative to the target 3094 URI ([RFC3986], Section 5). 3096 The Content-Location value is not a replacement for the target URI 3097 (Section 7.1). It is representation metadata. It has the same 3098 syntax and semantics as the header field of the same name defined for 3099 MIME body parts in Section 4 of [RFC2557]. However, its appearance 3100 in an HTTP message has some special implications for HTTP recipients. 3102 If Content-Location is included in a 2xx (Successful) response 3103 message and its value refers (after conversion to absolute form) to a 3104 URI that is the same as the target URI, then the recipient MAY 3105 consider the payload to be a current representation of that resource 3106 at the time indicated by the message origination date. For a GET 3107 (Section 9.3.1) or HEAD (Section 9.3.2) request, this is the same as 3108 the default semantics when no Content-Location is provided by the 3109 server. For a state-changing request like PUT (Section 9.3.4) or 3110 POST (Section 9.3.3), it implies that the server's response contains 3111 the new representation of that resource, thereby distinguishing it 3112 from representations that might only report about the action (e.g., 3113 "It worked!"). This allows authoring applications to update their 3114 local copies without the need for a subsequent GET request. 3116 If Content-Location is included in a 2xx (Successful) response 3117 message and its field value refers to a URI that differs from the 3118 target URI, then the origin server claims that the URI is an 3119 identifier for a different resource corresponding to the enclosed 3120 representation. Such a claim can only be trusted if both identifiers 3121 share the same resource owner, which cannot be programmatically 3122 determined via HTTP. 3124 o For a response to a GET or HEAD request, this is an indication 3125 that the target URI refers to a resource that is subject to 3126 content negotiation and the Content-Location field value is a more 3127 specific identifier for the selected representation. 3129 o For a 201 (Created) response to a state-changing method, a 3130 Content-Location field value that is identical to the Location 3131 field value indicates that this payload is a current 3132 representation of the newly created resource. 3134 o Otherwise, such a Content-Location indicates that this payload is 3135 a representation reporting on the requested action's status and 3136 that the same report is available (for future access with GET) at 3137 the given URI. For example, a purchase transaction made via a 3138 POST request might include a receipt document as the payload of 3139 the 200 (OK) response; the Content-Location field value provides 3140 an identifier for retrieving a copy of that same receipt in the 3141 future. 3143 A user agent that sends Content-Location in a request message is 3144 stating that its value refers to where the user agent originally 3145 obtained the content of the enclosed representation (prior to any 3146 modifications made by that user agent). In other words, the user 3147 agent is providing a back link to the source of the original 3148 representation. 3150 An origin server that receives a Content-Location field in a request 3151 message MUST treat the information as transitory request context 3152 rather than as metadata to be saved verbatim as part of the 3153 representation. An origin server MAY use that context to guide in 3154 processing the request or to save it for other uses, such as within 3155 source links or versioning metadata. However, an origin server MUST 3156 NOT use such context information to alter the request semantics. 3158 For example, if a client makes a PUT request on a negotiated resource 3159 and the origin server accepts that PUT (without redirection), then 3160 the new state of that resource is expected to be consistent with the 3161 one representation supplied in that PUT; the Content-Location cannot 3162 be used as a form of reverse content selection identifier to update 3163 only one of the negotiated representations. If the user agent had 3164 wanted the latter semantics, it would have applied the PUT directly 3165 to the Content-Location URI. 3167 8.9. Validator Fields 3169 Validator fields convey metadata about the selected representation 3170 (Section 8). In responses to safe requests, validator fields 3171 describe the selected representation chosen by the origin server 3172 while handling the response. Note that, depending on the status code 3173 semantics, the selected representation for a given response is not 3174 necessarily the same as the representation enclosed as response 3175 payload. 3177 In a successful response to a state-changing request, validator 3178 fields describe the new representation that has replaced the prior 3179 selected representation as a result of processing the request. 3181 For example, an ETag field in a 201 (Created) response communicates 3182 the entity-tag of the newly created resource's representation, so 3183 that it can be used in later conditional requests to prevent the 3184 "lost update" problem Section 13.1. 3186 This specification defines two forms of metadata that are commonly 3187 used to observe resource state and test for preconditions: 3188 modification dates (Section 8.9.2) and opaque entity tags 3189 (Section 8.9.3). Additional metadata that reflects resource state 3190 has been defined by various extensions of HTTP, such as Web 3191 Distributed Authoring and Versioning (WebDAV, [RFC4918]), that are 3192 beyond the scope of this specification. A resource metadata value is 3193 referred to as a "_validator_" when it is used within a precondition. 3195 8.9.1. Weak versus Strong 3197 Validators come in two flavors: strong or weak. Weak validators are 3198 easy to generate but are far less useful for comparisons. Strong 3199 validators are ideal for comparisons but can be very difficult (and 3200 occasionally impossible) to generate efficiently. Rather than impose 3201 that all forms of resource adhere to the same strength of validator, 3202 HTTP exposes the type of validator in use and imposes restrictions on 3203 when weak validators can be used as preconditions. 3205 A "_strong validator_" is representation metadata that changes value 3206 whenever a change occurs to the representation data that would be 3207 observable in the payload data of a 200 (OK) response to GET. 3209 A strong validator might change for reasons other than a change to 3210 the representation data, such as when a semantically significant part 3211 of the representation metadata is changed (e.g., Content-Type), but 3212 it is in the best interests of the origin server to only change the 3213 value when it is necessary to invalidate the stored responses held by 3214 remote caches and authoring tools. 3216 Cache entries might persist for arbitrarily long periods, regardless 3217 of expiration times. Thus, a cache might attempt to validate an 3218 entry using a validator that it obtained in the distant past. A 3219 strong validator is unique across all versions of all representations 3220 associated with a particular resource over time. However, there is 3221 no implication of uniqueness across representations of different 3222 resources (i.e., the same strong validator might be in use for 3223 representations of multiple resources at the same time and does not 3224 imply that those representations are equivalent). 3226 There are a variety of strong validators used in practice. The best 3227 are based on strict revision control, wherein each change to a 3228 representation always results in a unique node name and revision 3229 identifier being assigned before the representation is made 3230 accessible to GET. A collision-resistant hash function applied to 3231 the representation data is also sufficient if the data is available 3232 prior to the response header fields being sent and the digest does 3233 not need to be recalculated every time a validation request is 3234 received. However, if a resource has distinct representations that 3235 differ only in their metadata, such as might occur with content 3236 negotiation over media types that happen to share the same data 3237 format, then the origin server needs to incorporate additional 3238 information in the validator to distinguish those representations. 3240 In contrast, a "_weak validator_" is representation metadata that 3241 might not change for every change to the representation data. This 3242 weakness might be due to limitations in how the value is calculated, 3243 such as clock resolution, an inability to ensure uniqueness for all 3244 possible representations of the resource, or a desire of the resource 3245 owner to group representations by some self-determined set of 3246 equivalency rather than unique sequences of data. An origin server 3247 SHOULD change a weak entity-tag whenever it considers prior 3248 representations to be unacceptable as a substitute for the current 3249 representation. In other words, a weak entity-tag ought to change 3250 whenever the origin server wants caches to invalidate old responses. 3252 For example, the representation of a weather report that changes in 3253 content every second, based on dynamic measurements, might be grouped 3254 into sets of equivalent representations (from the origin server's 3255 perspective) with the same weak validator in order to allow cached 3256 representations to be valid for a reasonable period of time (perhaps 3257 adjusted dynamically based on server load or weather quality). 3258 Likewise, a representation's modification time, if defined with only 3259 one-second resolution, might be a weak validator if it is possible 3260 for the representation to be modified twice during a single second 3261 and retrieved between those modifications. 3263 Likewise, a validator is weak if it is shared by two or more 3264 representations of a given resource at the same time, unless those 3265 representations have identical representation data. For example, if 3266 the origin server sends the same validator for a representation with 3267 a gzip content coding applied as it does for a representation with no 3268 content coding, then that validator is weak. However, two 3269 simultaneous representations might share the same strong validator if 3270 they differ only in the representation metadata, such as when two 3271 different media types are available for the same representation data. 3273 Strong validators are usable for all conditional requests, including 3274 cache validation, partial content ranges, and "lost update" 3275 avoidance. Weak validators are only usable when the client does not 3276 require exact equality with previously obtained representation data, 3277 such as when validating a cache entry or limiting a web traversal to 3278 recent changes. 3280 8.9.2. Last-Modified 3282 The "Last-Modified" header field in a response provides a timestamp 3283 indicating the date and time at which the origin server believes the 3284 selected representation was last modified, as determined at the 3285 conclusion of handling the request. 3287 Last-Modified = HTTP-date 3289 An example of its use is 3291 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 3293 8.9.2.1. Generation 3295 An origin server SHOULD send Last-Modified for any selected 3296 representation for which a last modification date can be reasonably 3297 and consistently determined, since its use in conditional requests 3298 and evaluating cache freshness ([Caching]) results in a substantial 3299 reduction of HTTP traffic on the Internet and can be a significant 3300 factor in improving service scalability and reliability. 3302 A representation is typically the sum of many parts behind the 3303 resource interface. The last-modified time would usually be the most 3304 recent time that any of those parts were changed. How that value is 3305 determined for any given resource is an implementation detail beyond 3306 the scope of this specification. What matters to HTTP is how 3307 recipients of the Last-Modified header field can use its value to 3308 make conditional requests and test the validity of locally cached 3309 responses. 3311 An origin server SHOULD obtain the Last-Modified value of the 3312 representation as close as possible to the time that it generates the 3313 Date field value for its response. This allows a recipient to make 3314 an accurate assessment of the representation's modification time, 3315 especially if the representation changes near the time that the 3316 response is generated. 3318 An origin server with a clock MUST NOT send a Last-Modified date that 3319 is later than the server's time of message origination (Date). If 3320 the last modification time is derived from implementation-specific 3321 metadata that evaluates to some time in the future, according to the 3322 origin server's clock, then the origin server MUST replace that value 3323 with the message origination date. This prevents a future 3324 modification date from having an adverse impact on cache validation. 3326 An origin server without a clock MUST NOT assign Last-Modified values 3327 to a response unless these values were associated with the resource 3328 by some other system or user with a reliable clock. 3330 8.9.2.2. Comparison 3332 A Last-Modified time, when used as a validator in a request, is 3333 implicitly weak unless it is possible to deduce that it is strong, 3334 using the following rules: 3336 o The validator is being compared by an origin server to the actual 3337 current validator for the representation and, 3339 o That origin server reliably knows that the associated 3340 representation did not change twice during the second covered by 3341 the presented validator; 3343 or 3345 o The validator is about to be used by a client in an 3346 If-Modified-Since, If-Unmodified-Since, or If-Range header field, 3347 because the client has a cache entry for the associated 3348 representation, and 3350 o That cache entry includes a Date value which is at least one 3351 second after the Last-Modified value and the client has reason to 3352 believe that they were generated by the same clock or that there 3353 is enough difference between the Last-Modified and Date values to 3354 make clock synchronization issues unlikely; 3356 or 3358 o The validator is being compared by an intermediate cache to the 3359 validator stored in its cache entry for the representation, and 3361 o That cache entry includes a Date value which is at least one 3362 second after the Last-Modified value and the cache has reason to 3363 believe that they were generated by the same clock or that there 3364 is enough difference between the Last-Modified and Date values to 3365 make clock synchronization issues unlikely. 3367 This method relies on the fact that if two different responses were 3368 sent by the origin server during the same second, but both had the 3369 same Last-Modified time, then at least one of those responses would 3370 have a Date value equal to its Last-Modified time. 3372 8.9.3. ETag 3374 The "ETag" field in a response provides the current entity-tag for 3375 the selected representation, as determined at the conclusion of 3376 handling the request. An entity-tag is an opaque validator for 3377 differentiating between multiple representations of the same 3378 resource, regardless of whether those multiple representations are 3379 due to resource state changes over time, content negotiation 3380 resulting in multiple representations being valid at the same time, 3381 or both. An entity-tag consists of an opaque quoted string, possibly 3382 prefixed by a weakness indicator. 3384 ETag = entity-tag 3386 entity-tag = [ weak ] opaque-tag 3387 weak = %s"W/" 3388 opaque-tag = DQUOTE *etagc DQUOTE 3389 etagc = %x21 / %x23-7E / obs-text 3390 ; VCHAR except double quotes, plus obs-text 3392 | *Note:* Previously, opaque-tag was defined to be a quoted- 3393 | string ([RFC2616], Section 3.11); thus, some recipients might 3394 | perform backslash unescaping. Servers therefore ought to avoid 3395 | backslash characters in entity tags. 3397 An entity-tag can be more reliable for validation than a modification 3398 date in situations where it is inconvenient to store modification 3399 dates, where the one-second resolution of HTTP date values is not 3400 sufficient, or where modification dates are not consistently 3401 maintained. 3403 Examples: 3405 ETag: "xyzzy" 3406 ETag: W/"xyzzy" 3407 ETag: "" 3409 An entity-tag can be either a weak or strong validator, with strong 3410 being the default. If an origin server provides an entity-tag for a 3411 representation and the generation of that entity-tag does not satisfy 3412 all of the characteristics of a strong validator (Section 8.9.1), 3413 then the origin server MUST mark the entity-tag as weak by prefixing 3414 its opaque value with "W/" (case-sensitive). 3416 A sender MAY send the Etag field in a trailer section (see 3417 Section 6.5). However, since trailers are often ignored, it is 3418 preferable to send Etag as a header field unless the entity-tag is 3419 generated while sending the payload data. 3421 8.9.3.1. Generation 3423 The principle behind entity-tags is that only the service author 3424 knows the implementation of a resource well enough to select the most 3425 accurate and efficient validation mechanism for that resource, and 3426 that any such mechanism can be mapped to a simple sequence of octets 3427 for easy comparison. Since the value is opaque, there is no need for 3428 the client to be aware of how each entity-tag is constructed. 3430 For example, a resource that has implementation-specific versioning 3431 applied to all changes might use an internal revision number, perhaps 3432 combined with a variance identifier for content negotiation, to 3433 accurately differentiate between representations. Other 3434 implementations might use a collision-resistant hash of 3435 representation content, a combination of various file attributes, or 3436 a modification timestamp that has sub-second resolution. 3438 An origin server SHOULD send an ETag for any selected representation 3439 for which detection of changes can be reasonably and consistently 3440 determined, since the entity-tag's use in conditional requests and 3441 evaluating cache freshness ([Caching]) can result in a substantial 3442 reduction of HTTP network traffic and can be a significant factor in 3443 improving service scalability and reliability. 3445 8.9.3.2. Comparison 3447 There are two entity-tag comparison functions, depending on whether 3448 or not the comparison context allows the use of weak validators: 3450 _Strong comparison_: two entity-tags are equivalent if both are not 3451 weak and their opaque-tags match character-by-character. 3453 _Weak comparison_: two entity-tags are equivalent if their opaque- 3454 tags match character-by-character, regardless of either or both 3455 being tagged as "weak". 3457 The example below shows the results for a set of entity-tag pairs and 3458 both the weak and strong comparison function results: 3460 -------- -------- ------------------- ----------------- 3461 ETag 1 ETag 2 Strong Comparison Weak Comparison 3462 -------- -------- ------------------- ----------------- 3463 W/"1" W/"1" no match match 3464 W/"1" W/"2" no match no match 3465 W/"1" "1" no match match 3466 "1" "1" match match 3467 -------- -------- ------------------- ----------------- 3469 Table 3 3471 8.9.3.3. Example: Entity-Tags Varying on Content-Negotiated Resources 3473 Consider a resource that is subject to content negotiation 3474 (Section 12), and where the representations sent in response to a GET 3475 request vary based on the Accept-Encoding request header field 3476 (Section 12.5.3): 3478 >> Request: 3480 GET /index HTTP/1.1 3481 Host: www.example.com 3482 Accept-Encoding: gzip 3484 In this case, the response might or might not use the gzip content 3485 coding. If it does not, the response might look like: 3487 >> Response: 3489 HTTP/1.1 200 OK 3490 Date: Fri, 26 Mar 2010 00:05:00 GMT 3491 ETag: "123-a" 3492 Content-Length: 70 3493 Vary: Accept-Encoding 3494 Content-Type: text/plain 3496 Hello World! 3497 Hello World! 3498 Hello World! 3499 Hello World! 3500 Hello World! 3502 An alternative representation that does use gzip content coding would 3503 be: 3505 >> Response: 3507 HTTP/1.1 200 OK 3508 Date: Fri, 26 Mar 2010 00:05:00 GMT 3509 ETag: "123-b" 3510 Content-Length: 43 3511 Vary: Accept-Encoding 3512 Content-Type: text/plain 3513 Content-Encoding: gzip 3515 ...binary data... 3517 | *Note:* Content codings are a property of the representation 3518 | data, so a strong entity-tag for a content-encoded 3519 | representation has to be distinct from the entity tag of an 3520 | unencoded representation to prevent potential conflicts during 3521 | cache updates and range requests. In contrast, transfer 3522 | codings (Section 7 of [Messaging]) apply only during message 3523 | transfer and do not result in distinct entity-tags. 3525 8.9.4. When to Use Entity-Tags and Last-Modified Dates 3527 In 200 (OK) responses to GET or HEAD, an origin server: 3529 o SHOULD send an entity-tag validator unless it is not feasible to 3530 generate one. 3532 o MAY send a weak entity-tag instead of a strong entity-tag, if 3533 performance considerations support the use of weak entity-tags, or 3534 if it is unfeasible to send a strong entity-tag. 3536 o SHOULD send a Last-Modified value if it is feasible to send one. 3538 In other words, the preferred behavior for an origin server is to 3539 send both a strong entity-tag and a Last-Modified value in successful 3540 responses to a retrieval request. 3542 A client: 3544 o MUST send that entity-tag in any cache validation request (using 3545 If-Match or If-None-Match) if an entity-tag has been provided by 3546 the origin server. 3548 o SHOULD send the Last-Modified value in non-subrange cache 3549 validation requests (using If-Modified-Since) if only a Last- 3550 Modified value has been provided by the origin server. 3552 o MAY send the Last-Modified value in subrange cache validation 3553 requests (using If-Unmodified-Since) if only a Last-Modified value 3554 has been provided by an HTTP/1.0 origin server. The user agent 3555 SHOULD provide a way to disable this, in case of difficulty. 3557 o SHOULD send both validators in cache validation requests if both 3558 an entity-tag and a Last-Modified value have been provided by the 3559 origin server. This allows both HTTP/1.0 and HTTP/1.1 caches to 3560 respond appropriately. 3562 9. Methods 3564 9.1. Overview 3566 The request method token is the primary source of request semantics; 3567 it indicates the purpose for which the client has made this request 3568 and what is expected by the client as a successful result. 3570 The request method's semantics might be further specialized by the 3571 semantics of some header fields when present in a request if those 3572 additional semantics do not conflict with the method. For example, a 3573 client can send conditional request header fields (Section 13.1) to 3574 make the requested action conditional on the current state of the 3575 target resource. 3577 HTTP was originally designed to be usable as an interface to 3578 distributed object systems. The request method was envisioned as 3579 applying semantics to a target resource in much the same way as 3580 invoking a defined method on an identified object would apply 3581 semantics. 3583 method = token 3585 The method token is case-sensitive because it might be used as a 3586 gateway to object-based systems with case-sensitive method names. By 3587 convention, standardized methods are defined in all-uppercase US- 3588 ASCII letters. 3590 Unlike distributed objects, the standardized request methods in HTTP 3591 are not resource-specific, since uniform interfaces provide for 3592 better visibility and reuse in network-based systems [REST]. Once 3593 defined, a standardized method ought to have the same semantics when 3594 applied to any resource, though each resource determines for itself 3595 whether those semantics are implemented or allowed. 3597 This specification defines a number of standardized methods that are 3598 commonly used in HTTP, as outlined by the following table. 3600 --------- -------------------------------------------- ------- 3601 Method Description Ref. 3602 --------- -------------------------------------------- ------- 3603 GET Transfer a current representation of the 9.3.1 3604 target resource. 3605 HEAD Same as GET, but do not transfer the 9.3.2 3606 response payload. 3607 POST Perform resource-specific processing on 9.3.3 3608 the request payload. 3609 PUT Replace all current representations of the 9.3.4 3610 target resource with the request payload. 3611 DELETE Remove all current representations of the 9.3.5 3612 target resource. 3613 CONNECT Establish a tunnel to the server 9.3.6 3614 identified by the target resource. 3615 OPTIONS Describe the communication options for the 9.3.7 3616 target resource. 3617 TRACE Perform a message loop-back test along the 9.3.8 3618 path to the target resource. 3619 --------- -------------------------------------------- ------- 3621 Table 4 3623 All general-purpose servers MUST support the methods GET and HEAD. 3624 All other methods are OPTIONAL. 3626 The set of methods allowed by a target resource can be listed in an 3627 Allow header field (Section 10.2.1). However, the set of allowed 3628 methods can change dynamically. When a request method is received 3629 that is unrecognized or not implemented by an origin server, the 3630 origin server SHOULD respond with the 501 (Not Implemented) status 3631 code. When a request method is received that is known by an origin 3632 server but not allowed for the target resource, the origin server 3633 SHOULD respond with the 405 (Method Not Allowed) status code. 3635 Additional methods, outside the scope of this specification, have 3636 been specified for use in HTTP. All such methods ought to be 3637 registered within the "Hypertext Transfer Protocol (HTTP) Method 3638 Registry", as described in Section 16.1. 3640 9.2. Common Method Properties 3641 9.2.1. Safe Methods 3643 Request methods are considered "_safe_" if their defined semantics 3644 are essentially read-only; i.e., the client does not request, and 3645 does not expect, any state change on the origin server as a result of 3646 applying a safe method to a target resource. Likewise, reasonable 3647 use of a safe method is not expected to cause any harm, loss of 3648 property, or unusual burden on the origin server. 3650 This definition of safe methods does not prevent an implementation 3651 from including behavior that is potentially harmful, that is not 3652 entirely read-only, or that causes side effects while invoking a safe 3653 method. What is important, however, is that the client did not 3654 request that additional behavior and cannot be held accountable for 3655 it. For example, most servers append request information to access 3656 log files at the completion of every response, regardless of the 3657 method, and that is considered safe even though the log storage might 3658 become full and crash the server. Likewise, a safe request initiated 3659 by selecting an advertisement on the Web will often have the side 3660 effect of charging an advertising account. 3662 Of the request methods defined by this specification, the GET, HEAD, 3663 OPTIONS, and TRACE methods are defined to be safe. 3665 The purpose of distinguishing between safe and unsafe methods is to 3666 allow automated retrieval processes (spiders) and cache performance 3667 optimization (pre-fetching) to work without fear of causing harm. In 3668 addition, it allows a user agent to apply appropriate constraints on 3669 the automated use of unsafe methods when processing potentially 3670 untrusted content. 3672 A user agent SHOULD distinguish between safe and unsafe methods when 3673 presenting potential actions to a user, such that the user can be 3674 made aware of an unsafe action before it is requested. 3676 When a resource is constructed such that parameters within the target 3677 URI have the effect of selecting an action, it is the resource 3678 owner's responsibility to ensure that the action is consistent with 3679 the request method semantics. For example, it is common for Web- 3680 based content editing software to use actions within query 3681 parameters, such as "page?do=delete". If the purpose of such a 3682 resource is to perform an unsafe action, then the resource owner MUST 3683 disable or disallow that action when it is accessed using a safe 3684 request method. Failure to do so will result in unfortunate side 3685 effects when automated processes perform a GET on every URI reference 3686 for the sake of link maintenance, pre-fetching, building a search 3687 index, etc. 3689 9.2.2. Idempotent Methods 3691 A request method is considered "_idempotent_" if the intended effect 3692 on the server of multiple identical requests with that method is the 3693 same as the effect for a single such request. Of the request methods 3694 defined by this specification, PUT, DELETE, and safe request methods 3695 are idempotent. 3697 Like the definition of safe, the idempotent property only applies to 3698 what has been requested by the user; a server is free to log each 3699 request separately, retain a revision control history, or implement 3700 other non-idempotent side effects for each idempotent request. 3702 Idempotent methods are distinguished because the request can be 3703 repeated automatically if a communication failure occurs before the 3704 client is able to read the server's response. For example, if a 3705 client sends a PUT request and the underlying connection is closed 3706 before any response is received, then the client can establish a new 3707 connection and retry the idempotent request. It knows that repeating 3708 the request will have the same intended effect, even if the original 3709 request succeeded, though the response might differ. 3711 A client SHOULD NOT automatically retry a request with a non- 3712 idempotent method unless it has some means to know that the request 3713 semantics are actually idempotent, regardless of the method, or some 3714 means to detect that the original request was never applied. 3716 For example, a user agent that knows (through design or 3717 configuration) that a POST request to a given resource is safe can 3718 repeat that request automatically. Likewise, a user agent designed 3719 specifically to operate on a version control repository might be able 3720 to recover from partial failure conditions by checking the target 3721 resource revision(s) after a failed connection, reverting or fixing 3722 any changes that were partially applied, and then automatically 3723 retrying the requests that failed. 3725 Some clients use weaker signals to initiate automatic retries. For 3726 example, when a POST request is sent, but the underlying transport 3727 connection is closed before any part of the response is received. 3728 Although this is commonly implemented, it is not recommended. 3730 A proxy MUST NOT automatically retry non-idempotent requests. A 3731 client SHOULD NOT automatically retry a failed automatic retry. 3733 9.2.3. Methods and Caching 3735 For a cache to store and use a response, the associated method needs 3736 to explicitly allow caching, and detail under what conditions a 3737 response can be used to satisfy subsequent requests; a method 3738 definition which does not do so cannot be cached. For additional 3739 requirements see [Caching]. 3741 This specification defines caching semantics for GET, HEAD, and POST, 3742 although the overwhelming majority of cache implementations only 3743 support GET and HEAD. 3745 9.3. Method Definitions 3747 9.3.1. GET 3749 The GET method requests transfer of a current selected representation 3750 for the target resource. 3752 GET is the primary mechanism of information retrieval and the focus 3753 of almost all performance optimizations. Hence, when people speak of 3754 retrieving some identifiable information via HTTP, they are generally 3755 referring to making a GET request. A successful response reflects 3756 the quality of "sameness" identified by the target URI. In turn, 3757 constructing applications such that they produce a URI for each 3758 important resource results in more resources being available for 3759 other applications, producing a network effect that promotes further 3760 expansion of the Web. 3762 It is tempting to think of resource identifiers as remote file system 3763 pathnames and of representations as being a copy of the contents of 3764 such files. In fact, that is how many resources are implemented (see 3765 Section 17.3 for related security considerations). However, there 3766 are no such limitations in practice. 3768 The HTTP interface for a resource is just as likely to be implemented 3769 as a tree of content objects, a programmatic view on various database 3770 records, or a gateway to other information systems. Even when the 3771 URI mapping mechanism is tied to a file system, an origin server 3772 might be configured to execute the files with the request as input 3773 and send the output as the representation rather than transfer the 3774 files directly. Regardless, only the origin server needs to know how 3775 each of its resource identifiers corresponds to an implementation and 3776 how each implementation manages to select and send a current 3777 representation of the target resource in a response to GET. 3779 A client can alter the semantics of GET to be a "range request", 3780 requesting transfer of only some part(s) of the selected 3781 representation, by sending a Range header field in the request 3782 (Section 14.2). 3784 A client SHOULD NOT generate payload data in a GET request. A 3785 payload received in a GET request has no defined semantics, cannot 3786 alter the meaning or target of the request, and might lead some 3787 implementations to reject the request and close the connection 3788 because of its potential as a request smuggling attack (Section 11.2 3789 of [Messaging]). 3791 The response to a GET request is cacheable; a cache MAY use it to 3792 satisfy subsequent GET and HEAD requests unless otherwise indicated 3793 by the Cache-Control header field (Section 5.2 of [Caching]). A 3794 cache that receives a payload in a GET request is likely to ignore 3795 that payload and cache regardless of the payload contents. 3797 When information retrieval is performed with a mechanism that 3798 constructs a target URI from user-provided information, such as the 3799 query fields of a form using GET, potentially sensitive data might be 3800 provided that would not be appropriate for disclosure within a URI 3801 (see Section 17.9). In some cases, the data can be filtered or 3802 transformed such that it would not reveal such information. In 3803 others, particularly when there is no benefit from caching a 3804 response, using the POST method (Section 9.3.3) instead of GET can 3805 transmit such information in the request payload rather than within 3806 the target URI. 3808 9.3.2. HEAD 3810 The HEAD method is identical to GET except that the server MUST NOT 3811 send payload data in the response and the response always terminates 3812 at the end of the header section. HEAD is used to obtain metadata 3813 about the selected representation without transferring its 3814 representation data, often for the sake of testing hypertext links or 3815 finding recent modifications. 3817 The server SHOULD send the same header fields in response to a HEAD 3818 request as it would have sent if the request method had been GET. 3819 However, a server MAY omit header fields for which a value is 3820 determined only while generating the payload data. For example, some 3821 servers buffer a dynamic response to GET until a minimum amount of 3822 data is generated so that they can more efficiently delimit small 3823 responses or make late decisions with regard to content selection. 3824 Such a response to GET might contain Content-Length and Vary fields, 3825 for example, that are not generated within a HEAD response. These 3826 minor inconsistencies are considered preferable to generating and 3827 discarding the payload data for a HEAD request, since HEAD is usually 3828 requested for the sake of efficiency. 3830 A payload within a HEAD request message has no defined semantics; 3831 sending payload data in a HEAD request might cause some existing 3832 implementations to reject the request. 3834 The response to a HEAD request is cacheable; a cache MAY use it to 3835 satisfy subsequent HEAD requests unless otherwise indicated by the 3836 Cache-Control header field (Section 5.2 of [Caching]). A HEAD 3837 response might also affect previously cached responses to GET; see 3838 Section 4.3.5 of [Caching]. 3840 9.3.3. POST 3842 The POST method requests that the target resource process the 3843 representation enclosed in the request according to the resource's 3844 own specific semantics. For example, POST is used for the following 3845 functions (among others): 3847 o Providing a block of data, such as the fields entered into an HTML 3848 form, to a data-handling process; 3850 o Posting a message to a bulletin board, newsgroup, mailing list, 3851 blog, or similar group of articles; 3853 o Creating a new resource that has yet to be identified by the 3854 origin server; and 3856 o Appending data to a resource's existing representation(s). 3858 An origin server indicates response semantics by choosing an 3859 appropriate status code depending on the result of processing the 3860 POST request; almost all of the status codes defined by this 3861 specification could be received in a response to POST (the exceptions 3862 being 206 (Partial Content), 304 (Not Modified), and 416 (Range Not 3863 Satisfiable)). 3865 If one or more resources has been created on the origin server as a 3866 result of successfully processing a POST request, the origin server 3867 SHOULD send a 201 (Created) response containing a Location header 3868 field that provides an identifier for the primary resource created 3869 (Section 10.2.3) and a representation that describes the status of 3870 the request while referring to the new resource(s). 3872 Responses to POST requests are only cacheable when they include 3873 explicit freshness information (see Section 4.2.1 of [Caching]) and a 3874 Content-Location header field that has the same value as the POST's 3875 target URI (Section 8.8). A cached POST response can be reused to 3876 satisfy a later GET or HEAD request, but not a POST request, since 3877 POST is required to be written through to the origin server, because 3878 it is unsafe; see Section 4 of [Caching]. 3880 If the result of processing a POST would be equivalent to a 3881 representation of an existing resource, an origin server MAY redirect 3882 the user agent to that resource by sending a 303 (See Other) response 3883 with the existing resource's identifier in the Location field. This 3884 has the benefits of providing the user agent a resource identifier 3885 and transferring the representation via a method more amenable to 3886 shared caching, though at the cost of an extra request if the user 3887 agent does not already have the representation cached. 3889 9.3.4. PUT 3891 The PUT method requests that the state of the target resource be 3892 created or replaced with the state defined by the representation 3893 enclosed in the request message payload. A successful PUT of a given 3894 representation would suggest that a subsequent GET on that same 3895 target resource will result in an equivalent representation being 3896 sent in a 200 (OK) response. However, there is no guarantee that 3897 such a state change will be observable, since the target resource 3898 might be acted upon by other user agents in parallel, or might be 3899 subject to dynamic processing by the origin server, before any 3900 subsequent GET is received. A successful response only implies that 3901 the user agent's intent was achieved at the time of its processing by 3902 the origin server. 3904 If the target resource does not have a current representation and the 3905 PUT successfully creates one, then the origin server MUST inform the 3906 user agent by sending a 201 (Created) response. If the target 3907 resource does have a current representation and that representation 3908 is successfully modified in accordance with the state of the enclosed 3909 representation, then the origin server MUST send either a 200 (OK) or 3910 a 204 (No Content) response to indicate successful completion of the 3911 request. 3913 An origin server SHOULD verify that the PUT representation is 3914 consistent with any constraints the server has for the target 3915 resource that cannot or will not be changed by the PUT. This is 3916 particularly important when the origin server uses internal 3917 configuration information related to the URI in order to set the 3918 values for representation metadata on GET responses. When a PUT 3919 representation is inconsistent with the target resource, the origin 3920 server SHOULD either make them consistent, by transforming the 3921 representation or changing the resource configuration, or respond 3922 with an appropriate error message containing sufficient information 3923 to explain why the representation is unsuitable. The 409 (Conflict) 3924 or 415 (Unsupported Media Type) status codes are suggested, with the 3925 latter being specific to constraints on Content-Type values. 3927 For example, if the target resource is configured to always have a 3928 Content-Type of "text/html" and the representation being PUT has a 3929 Content-Type of "image/jpeg", the origin server ought to do one of: 3931 a. reconfigure the target resource to reflect the new media type; 3933 b. transform the PUT representation to a format consistent with that 3934 of the resource before saving it as the new resource state; or, 3936 c. reject the request with a 415 (Unsupported Media Type) response 3937 indicating that the target resource is limited to "text/html", 3938 perhaps including a link to a different resource that would be a 3939 suitable target for the new representation. 3941 HTTP does not define exactly how a PUT method affects the state of an 3942 origin server beyond what can be expressed by the intent of the user 3943 agent request and the semantics of the origin server response. It 3944 does not define what a resource might be, in any sense of that word, 3945 beyond the interface provided via HTTP. It does not define how 3946 resource state is "stored", nor how such storage might change as a 3947 result of a change in resource state, nor how the origin server 3948 translates resource state into representations. Generally speaking, 3949 all implementation details behind the resource interface are 3950 intentionally hidden by the server. 3952 This extends to how header and trailer fields are stored; while 3953 common header fields like Content-Type will typically be stored and 3954 returned upon subsequent GET requests, header and trailer field 3955 handling is specific to the resource that received the request. As a 3956 result, an origin server SHOULD ignore unrecognized header and 3957 trailer fields received in a PUT request (i.e., do not save them as 3958 part of the resource state). 3960 An origin server MUST NOT send a validator field (Section 8.9), such 3961 as an ETag or Last-Modified field, in a successful response to PUT 3962 unless the request's representation data was saved without any 3963 transformation applied to the payload data (i.e., the resource's new 3964 representation data is identical to the payload data received in the 3965 PUT request) and the validator field value reflects the new 3966 representation. This requirement allows a user agent to know when 3967 the representation it has in memory remains current as a result of 3968 the PUT, thus not in need of being retrieved again from the origin 3969 server, and that the new validator(s) received in the response can be 3970 used for future conditional requests in order to prevent accidental 3971 overwrites (Section 13.1). 3973 The fundamental difference between the POST and PUT methods is 3974 highlighted by the different intent for the enclosed representation. 3975 The target resource in a POST request is intended to handle the 3976 enclosed representation according to the resource's own semantics, 3977 whereas the enclosed representation in a PUT request is defined as 3978 replacing the state of the target resource. Hence, the intent of PUT 3979 is idempotent and visible to intermediaries, even though the exact 3980 effect is only known by the origin server. 3982 Proper interpretation of a PUT request presumes that the user agent 3983 knows which target resource is desired. A service that selects a 3984 proper URI on behalf of the client, after receiving a state-changing 3985 request, SHOULD be implemented using the POST method rather than PUT. 3986 If the origin server will not make the requested PUT state change to 3987 the target resource and instead wishes to have it applied to a 3988 different resource, such as when the resource has been moved to a 3989 different URI, then the origin server MUST send an appropriate 3xx 3990 (Redirection) response; the user agent MAY then make its own decision 3991 regarding whether or not to redirect the request. 3993 A PUT request applied to the target resource can have side effects on 3994 other resources. For example, an article might have a URI for 3995 identifying "the current version" (a resource) that is separate from 3996 the URIs identifying each particular version (different resources 3997 that at one point shared the same state as the current version 3998 resource). A successful PUT request on "the current version" URI 3999 might therefore create a new version resource in addition to changing 4000 the state of the target resource, and might also cause links to be 4001 added between the related resources. 4003 An origin server that allows PUT on a given target resource MUST send 4004 a 400 (Bad Request) response to a PUT request that contains a 4005 Content-Range header field (Section 14.4), since the payload is 4006 likely to be partial content that has been mistakenly PUT as a full 4007 representation. Partial content updates are possible by targeting a 4008 separately identified resource with state that overlaps a portion of 4009 the larger resource, or by using a different method that has been 4010 specifically defined for partial updates (for example, the PATCH 4011 method defined in [RFC5789]). 4013 Responses to the PUT method are not cacheable. If a successful PUT 4014 request passes through a cache that has one or more stored responses 4015 for the target URI, those stored responses will be invalidated (see 4016 Section 4.4 of [Caching]). 4018 9.3.5. DELETE 4020 The DELETE method requests that the origin server remove the 4021 association between the target resource and its current 4022 functionality. In effect, this method is similar to the "rm" command 4023 in UNIX: it expresses a deletion operation on the URI mapping of the 4024 origin server rather than an expectation that the previously 4025 associated information be deleted. 4027 If the target resource has one or more current representations, they 4028 might or might not be destroyed by the origin server, and the 4029 associated storage might or might not be reclaimed, depending 4030 entirely on the nature of the resource and its implementation by the 4031 origin server (which are beyond the scope of this specification). 4032 Likewise, other implementation aspects of a resource might need to be 4033 deactivated or archived as a result of a DELETE, such as database or 4034 gateway connections. In general, it is assumed that the origin 4035 server will only allow DELETE on resources for which it has a 4036 prescribed mechanism for accomplishing the deletion. 4038 Relatively few resources allow the DELETE method - its primary use is 4039 for remote authoring environments, where the user has some direction 4040 regarding its effect. For example, a resource that was previously 4041 created using a PUT request, or identified via the Location header 4042 field after a 201 (Created) response to a POST request, might allow a 4043 corresponding DELETE request to undo those actions. Similarly, 4044 custom user agent implementations that implement an authoring 4045 function, such as revision control clients using HTTP for remote 4046 operations, might use DELETE based on an assumption that the server's 4047 URI space has been crafted to correspond to a version repository. 4049 If a DELETE method is successfully applied, the origin server SHOULD 4050 send 4052 o a 202 (Accepted) status code if the action will likely succeed but 4053 has not yet been enacted, 4055 o a 204 (No Content) status code if the action has been enacted and 4056 no further information is to be supplied, or 4058 o a 200 (OK) status code if the action has been enacted and the 4059 response message includes a representation describing the status. 4061 A client SHOULD NOT generate a payload in a DELETE request. A 4062 payload received in a DELETE request has no defined semantics, cannot 4063 alter the meaning or target of the request, and might lead some 4064 implementations to reject the request. 4066 Responses to the DELETE method are not cacheable. If a successful 4067 DELETE request passes through a cache that has one or more stored 4068 responses for the target URI, those stored responses will be 4069 invalidated (see Section 4.4 of [Caching]). 4071 9.3.6. CONNECT 4073 The CONNECT method requests that the recipient establish a tunnel to 4074 the destination origin server identified by the request target and, 4075 if successful, thereafter restrict its behavior to blind forwarding 4076 of data, in both directions, until the tunnel is closed. Tunnels are 4077 commonly used to create an end-to-end virtual connection, through one 4078 or more proxies, which can then be secured using TLS (Transport Layer 4079 Security, [RFC8446]). 4081 Because CONNECT changes the request/response nature of an HTTP 4082 connection, specific HTTP versions might have different ways of 4083 mapping its semantics into the protocol's wire format. 4085 CONNECT is intended only for use in requests to a proxy. An origin 4086 server that receives a CONNECT request for itself MAY respond with a 4087 2xx (Successful) status code to indicate that a connection is 4088 established. However, most origin servers do not implement CONNECT. 4090 A client sending a CONNECT request MUST send the authority component 4091 (described in Section 3.2 of [RFC3986]) as the request target; i.e., 4092 the request target consists of only the host name and port number of 4093 the tunnel destination, separated by a colon. For example, 4095 CONNECT server.example.com:80 HTTP/1.1 4096 Host: server.example.com:80 4098 The recipient proxy can establish a tunnel either by directly 4099 connecting to the request target or, if configured to use another 4100 proxy, by forwarding the CONNECT request to the next inbound proxy. 4101 Any 2xx (Successful) response indicates that the sender (and all 4102 inbound proxies) will switch to tunnel mode immediately after the 4103 blank line that concludes the successful response's header section; 4104 data received after that blank line is from the server identified by 4105 the request target. Any response other than a successful response 4106 indicates that the tunnel has not yet been formed and that the 4107 connection remains governed by HTTP. 4109 A tunnel is closed when a tunnel intermediary detects that either 4110 side has closed its connection: the intermediary MUST attempt to send 4111 any outstanding data that came from the closed side to the other 4112 side, close both connections, and then discard any remaining data 4113 left undelivered. 4115 Proxy authentication might be used to establish the authority to 4116 create a tunnel. For example, 4118 CONNECT server.example.com:80 HTTP/1.1 4119 Host: server.example.com:80 4120 Proxy-Authorization: basic aGVsbG86d29ybGQ= 4122 There are significant risks in establishing a tunnel to arbitrary 4123 servers, particularly when the destination is a well-known or 4124 reserved TCP port that is not intended for Web traffic. For example, 4125 a CONNECT to "example.com:25" would suggest that the proxy connect to 4126 the reserved port for SMTP traffic; if allowed, that could trick the 4127 proxy into relaying spam email. Proxies that support CONNECT SHOULD 4128 restrict its use to a limited set of known ports or a configurable 4129 whitelist of safe request targets. 4131 A server MUST NOT send any Transfer-Encoding or Content-Length header 4132 fields in a 2xx (Successful) response to CONNECT. A client MUST 4133 ignore any Content-Length or Transfer-Encoding header fields received 4134 in a successful response to CONNECT. 4136 A payload within a CONNECT request message has no defined semantics; 4137 sending payload data in a CONNECT request might cause some existing 4138 implementations to reject the request. 4140 Responses to the CONNECT method are not cacheable. 4142 9.3.7. OPTIONS 4144 The OPTIONS method requests information about the communication 4145 options available for the target resource, at either the origin 4146 server or an intervening intermediary. This method allows a client 4147 to determine the options and/or requirements associated with a 4148 resource, or the capabilities of a server, without implying a 4149 resource action. 4151 An OPTIONS request with an asterisk ("*") as the request target 4152 (Section 7.1) applies to the server in general rather than to a 4153 specific resource. Since a server's communication options typically 4154 depend on the resource, the "*" request is only useful as a "ping" or 4155 "no-op" type of method; it does nothing beyond allowing the client to 4156 test the capabilities of the server. For example, this can be used 4157 to test a proxy for HTTP/1.1 conformance (or lack thereof). 4159 If the request target is not an asterisk, the OPTIONS request applies 4160 to the options that are available when communicating with the target 4161 resource. 4163 A server generating a successful response to OPTIONS SHOULD send any 4164 header that might indicate optional features implemented by the 4165 server and applicable to the target resource (e.g., Allow), including 4166 potential extensions not defined by this specification. The response 4167 payload, if any, might also describe the communication options in a 4168 machine or human-readable representation. A standard format for such 4169 a representation is not defined by this specification, but might be 4170 defined by future extensions to HTTP. 4172 A client MAY send a Max-Forwards header field in an OPTIONS request 4173 to target a specific recipient in the request chain (see 4174 Section 7.6.2). A proxy MUST NOT generate a Max-Forwards header 4175 field while forwarding a request unless that request was received 4176 with a Max-Forwards field. 4178 A client that generates an OPTIONS request containing payload data 4179 MUST send a valid Content-Type header field describing the 4180 representation media type. Note that this specification does not 4181 define any use for such a payload. 4183 Responses to the OPTIONS method are not cacheable. 4185 9.3.8. TRACE 4187 The TRACE method requests a remote, application-level loop-back of 4188 the request message. The final recipient of the request SHOULD 4189 reflect the message received, excluding some fields described below, 4190 back to the client as the payload data of a 200 (OK) response with a 4191 Content-Type of "message/http" (Section 10.1 of [Messaging]). The 4192 final recipient is either the origin server or the first server to 4193 receive a Max-Forwards value of zero (0) in the request 4194 (Section 7.6.2). 4196 A client MUST NOT generate fields in a TRACE request containing 4197 sensitive data that might be disclosed by the response. For example, 4198 it would be foolish for a user agent to send stored user credentials 4199 (Section 11) or cookies [RFC6265] in a TRACE request. The final 4200 recipient of the request SHOULD exclude any request fields that are 4201 likely to contain sensitive data when that recipient generates the 4202 response payload. 4204 TRACE allows the client to see what is being received at the other 4205 end of the request chain and use that data for testing or diagnostic 4206 information. The value of the Via header field (Section 7.6.3) is of 4207 particular interest, since it acts as a trace of the request chain. 4208 Use of the Max-Forwards header field allows the client to limit the 4209 length of the request chain, which is useful for testing a chain of 4210 proxies forwarding messages in an infinite loop. 4212 A client MUST NOT send payload data in a TRACE request. 4214 Responses to the TRACE method are not cacheable. 4216 10. Message Context 4218 10.1. Request Context Fields 4220 The request header fields below provide additional information about 4221 the request context, including information about the user, user 4222 agent, and resource behind the request. 4224 10.1.1. Expect 4226 The "Expect" header field in a request indicates a certain set of 4227 behaviors (expectations) that need to be supported by the server in 4228 order to properly handle this request. 4230 Expect = #expectation 4231 expectation = token [ "=" ( token / quoted-string ) parameters ] 4233 The Expect field value is case-insensitive. 4235 The only expectation defined by this specification is "100-continue" 4236 (with no defined parameters). 4238 A server that receives an Expect field value containing a member 4239 other than 100-continue MAY respond with a 417 (Expectation Failed) 4240 status code to indicate that the unexpected expectation cannot be 4241 met. 4243 A _100-continue_ expectation informs recipients that the client is 4244 about to send a (presumably large) payload in this request and wishes 4245 to receive a 100 (Continue) interim response if the method, target 4246 URI, and header fields are not sufficient to cause an immediate 4247 success, redirect, or error response. This allows the client to wait 4248 for an indication that it is worthwhile to send the payload data 4249 before actually doing so, which can improve efficiency when the data 4250 is huge or when the client anticipates that an error is likely (e.g., 4251 when sending a state-changing method, for the first time, without 4252 previously verified authentication credentials). 4254 For example, a request that begins with 4256 PUT /somewhere/fun HTTP/1.1 4257 Host: origin.example.com 4258 Content-Type: video/h264 4259 Content-Length: 1234567890987 4260 Expect: 100-continue 4262 allows the origin server to immediately respond with an error 4263 message, such as 401 (Unauthorized) or 405 (Method Not Allowed), 4264 before the client starts filling the pipes with an unnecessary data 4265 transfer. 4267 Requirements for clients: 4269 o A client MUST NOT generate a 100-continue expectation in a request 4270 that does not include payload data. 4272 o A client that will wait for a 100 (Continue) response before 4273 sending the request payload data MUST send an Expect header field 4274 containing a 100-continue expectation. 4276 o A client that sends a 100-continue expectation is not required to 4277 wait for any specific length of time; such a client MAY proceed to 4278 send the payload even if it has not yet received a response. 4279 Furthermore, since 100 (Continue) responses cannot be sent through 4280 an HTTP/1.0 intermediary, such a client SHOULD NOT wait for an 4281 indefinite period before sending the payload. 4283 o A client that receives a 417 (Expectation Failed) status code in 4284 response to a request containing a 100-continue expectation SHOULD 4285 repeat that request without a 100-continue expectation, since the 4286 417 response merely indicates that the response chain does not 4287 support expectations (e.g., it passes through an HTTP/1.0 server). 4289 Requirements for servers: 4291 o A server that receives a 100-continue expectation in an HTTP/1.0 4292 request MUST ignore that expectation. 4294 o A server MAY omit sending a 100 (Continue) response if it has 4295 already received some or all of the payload for the corresponding 4296 request, or if the framing indicates that there is no payload. 4298 o A server that sends a 100 (Continue) response MUST ultimately send 4299 a final status code, once the payload is received and processed, 4300 unless the connection is closed prematurely. 4302 o A server that responds with a final status code before reading the 4303 entire request payload SHOULD indicate whether it intends to close 4304 the connection (e.g., see Section 9.6 of [Messaging]) or continue 4305 reading the request payload. 4307 An origin server MUST, upon receiving an HTTP/1.1 (or later) request 4308 that has a method, target URI, and complete header section that 4309 contains a 100-continue expectation and indicates a request payload 4310 will follow, either send an immediate response with a final status 4311 code, if that status can be determined by examining just the method, 4312 target URI, and header fields, or send an immediate 100 (Continue) 4313 response to encourage the client to send the request payload. The 4314 origin server MUST NOT wait for the payload before sending the 100 4315 (Continue) response. 4317 A proxy MUST, upon receiving an HTTP/1.1 (or later) request that has 4318 a method, target URI, and complete header section that contains a 4319 100-continue expectation and indicates a request payload will follow, 4320 either send an immediate response with a final status code, if that 4321 status can be determined by examining just the method, target URI, 4322 and header fields, or begin forwarding the request toward the origin 4323 server by sending a corresponding request-line and header section to 4324 the next inbound server. If the proxy believes (from configuration 4325 or past interaction) that the next inbound server only supports 4326 HTTP/1.0, the proxy MAY generate an immediate 100 (Continue) response 4327 to encourage the client to begin sending the payload. 4329 10.1.2. From 4331 The "From" header field contains an Internet email address for a 4332 human user who controls the requesting user agent. The address ought 4333 to be machine-usable, as defined by "mailbox" in Section 3.4 of 4334 [RFC5322]: 4336 From = mailbox 4338 mailbox = 4340 An example is: 4342 From: webmaster@example.org 4344 The From header field is rarely sent by non-robotic user agents. A 4345 user agent SHOULD NOT send a From header field without explicit 4346 configuration by the user, since that might conflict with the user's 4347 privacy interests or their site's security policy. 4349 A robotic user agent SHOULD send a valid From header field so that 4350 the person responsible for running the robot can be contacted if 4351 problems occur on servers, such as if the robot is sending excessive, 4352 unwanted, or invalid requests. 4354 A server SHOULD NOT use the From header field for access control or 4355 authentication, since most recipients will assume that the field 4356 value is public information. 4358 10.1.3. Referer 4360 The "Referer" [sic] header field allows the user agent to specify a 4361 URI reference for the resource from which the target URI was obtained 4362 (i.e., the "referrer", though the field name is misspelled). A user 4363 agent MUST NOT include the fragment and userinfo components of the 4364 URI reference [RFC3986], if any, when generating the Referer field 4365 value. 4367 Referer = absolute-URI / partial-URI 4369 The field value is either an absolute-URI or a partial-URI. In the 4370 latter case (Section 4), the referenced URI is relative to the target 4371 URI ([RFC3986], Section 5). 4373 The Referer header field allows servers to generate back-links to 4374 other resources for simple analytics, logging, optimized caching, 4375 etc. It also allows obsolete or mistyped links to be found for 4376 maintenance. Some servers use the Referer header field as a means of 4377 denying links from other sites (so-called "deep linking") or 4378 restricting cross-site request forgery (CSRF), but not all requests 4379 contain it. 4381 Example: 4383 Referer: http://www.example.org/hypertext/Overview.html 4385 If the target URI was obtained from a source that does not have its 4386 own URI (e.g., input from the user keyboard, or an entry within the 4387 user's bookmarks/favorites), the user agent MUST either exclude the 4388 Referer header field or send it with a value of "about:blank". 4390 The Referer header field has the potential to reveal information 4391 about the request context or browsing history of the user, which is a 4392 privacy concern if the referring resource's identifier reveals 4393 personal information (such as an account name) or a resource that is 4394 supposed to be confidential (such as behind a firewall or internal to 4395 a secured service). Most general-purpose user agents do not send the 4396 Referer header field when the referring resource is a local "file" or 4397 "data" URI. A user agent MUST NOT send a Referer header field in an 4398 unsecured HTTP request if the referring page was received with a 4399 secure protocol. See Section 17.9 for additional security 4400 considerations. 4402 Some intermediaries have been known to indiscriminately remove 4403 Referer header fields from outgoing requests. This has the 4404 unfortunate side effect of interfering with protection against CSRF 4405 attacks, which can be far more harmful to their users. 4406 Intermediaries and user agent extensions that wish to limit 4407 information disclosure in Referer ought to restrict their changes to 4408 specific edits, such as replacing internal domain names with 4409 pseudonyms or truncating the query and/or path components. An 4410 intermediary SHOULD NOT modify or delete the Referer header field 4411 when the field value shares the same scheme and host as the target 4412 URI. 4414 10.1.4. TE 4416 The "TE" header field in a request can be used to indicate that the 4417 sender will not discard trailer fields when it contains a "trailers" 4418 member, as described in Section 6.5. 4420 Additionally, specific HTTP versions can use it to indicate the 4421 transfer codings the client is willing to accept in the response. 4423 The TE field value consists of a list of tokens, each allowing for 4424 optional parameters (except for the special case "trailers"). 4426 TE = #t-codings 4427 t-codings = "trailers" / ( transfer-coding [ weight ] ) 4428 transfer-coding = token *( OWS ";" OWS transfer-parameter ) 4429 transfer-parameter = token BWS "=" BWS ( token / quoted-string ) 4431 10.1.5. Trailer 4433 The "Trailer" header field provides a list of field names that the 4434 sender anticipates sending as trailer fields within that message. 4435 This allows a recipient to prepare for receipt of the indicated 4436 metadata before it starts processing the payload. 4438 Trailer = #field-name 4440 For example, a sender might indicate that a message integrity check 4441 will be computed as the payload is being streamed and provide the 4442 final signature as a trailer field. This allows a recipient to 4443 perform the same check on the fly as the payload data is received. 4445 A sender that intends to generate one or more trailer fields in a 4446 message SHOULD generate a Trailer header field in the header section 4447 of that message to indicate which fields might be present in the 4448 trailers. 4450 10.1.6. User-Agent 4452 The "User-Agent" header field contains information about the user 4453 agent originating the request, which is often used by servers to help 4454 identify the scope of reported interoperability problems, to work 4455 around or tailor responses to avoid particular user agent 4456 limitations, and for analytics regarding browser or operating system 4457 use. A user agent SHOULD send a User-Agent header field in each 4458 request unless specifically configured not to do so. 4460 User-Agent = product *( RWS ( product / comment ) ) 4462 The User-Agent field value consists of one or more product 4463 identifiers, each followed by zero or more comments (Section 5.6.5), 4464 which together identify the user agent software and its significant 4465 subproducts. By convention, the product identifiers are listed in 4466 decreasing order of their significance for identifying the user agent 4467 software. Each product identifier consists of a name and optional 4468 version. 4470 product = token ["/" product-version] 4471 product-version = token 4473 A sender SHOULD limit generated product identifiers to what is 4474 necessary to identify the product; a sender MUST NOT generate 4475 advertising or other nonessential information within the product 4476 identifier. A sender SHOULD NOT generate information in 4477 product-version that is not a version identifier (i.e., successive 4478 versions of the same product name ought to differ only in the 4479 product-version portion of the product identifier). 4481 Example: 4483 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 4485 A user agent SHOULD NOT generate a User-Agent header field containing 4486 needlessly fine-grained detail and SHOULD limit the addition of 4487 subproducts by third parties. Overly long and detailed User-Agent 4488 field values increase request latency and the risk of a user being 4489 identified against their wishes ("fingerprinting"). 4491 Likewise, implementations are encouraged not to use the product 4492 tokens of other implementations in order to declare compatibility 4493 with them, as this circumvents the purpose of the field. If a user 4494 agent masquerades as a different user agent, recipients can assume 4495 that the user intentionally desires to see responses tailored for 4496 that identified user agent, even if they might not work as well for 4497 the actual user agent being used. 4499 10.2. Response Context Fields 4501 Response header fields can supply control data that supplements the 4502 status code, directs caching, or instructs the client where to go 4503 next. 4505 The response header fields allow the server to pass additional 4506 information about the response beyond the status code. These header 4507 fields give information about the server, about further access to the 4508 target resource, or about related resources. 4510 Although each response header field has a defined meaning, in 4511 general, the precise semantics might be further refined by the 4512 semantics of the request method and/or response status code. 4514 The remaining response header fields provide more information about 4515 the target resource for potential use in later requests. 4517 10.2.1. Allow 4519 The "Allow" header field lists the set of methods advertised as 4520 supported by the target resource. The purpose of this field is 4521 strictly to inform the recipient of valid request methods associated 4522 with the resource. 4524 Allow = #method 4526 Example of use: 4528 Allow: GET, HEAD, PUT 4530 The actual set of allowed methods is defined by the origin server at 4531 the time of each request. An origin server MUST generate an Allow 4532 header field in a 405 (Method Not Allowed) response and MAY do so in 4533 any other response. An empty Allow field value indicates that the 4534 resource allows no methods, which might occur in a 405 response if 4535 the resource has been temporarily disabled by configuration. 4537 A proxy MUST NOT modify the Allow header field - it does not need to 4538 understand all of the indicated methods in order to handle them 4539 according to the generic message handling rules. 4541 10.2.2. Date 4543 The "Date" header field represents the date and time at which the 4544 message was originated, having the same semantics as the Origination 4545 Date Field (orig-date) defined in Section 3.6.1 of [RFC5322]. The 4546 field value is an HTTP-date, as defined in Section 5.6.7. 4548 Date = HTTP-date 4550 An example is 4552 Date: Tue, 15 Nov 1994 08:12:31 GMT 4554 When a Date header field is generated, the sender SHOULD generate its 4555 field value as the best available approximation of the date and time 4556 of message generation. In theory, the date ought to represent the 4557 moment just before the payload is generated. In practice, the date 4558 can be generated at any time during message origination. 4560 An origin server MUST NOT send a Date header field if it does not 4561 have a clock capable of providing a reasonable approximation of the 4562 current instance in Coordinated Universal Time. An origin server MAY 4563 send a Date header field if the response is in the 1xx 4564 (Informational) or 5xx (Server Error) class of status codes. An 4565 origin server MUST send a Date header field in all other cases. 4567 A recipient with a clock that receives a response message without a 4568 Date header field MUST record the time it was received and append a 4569 corresponding Date header field to the message's header section if it 4570 is cached or forwarded downstream. 4572 A user agent MAY send a Date header field in a request, though 4573 generally will not do so unless it is believed to convey useful 4574 information to the server. For example, custom applications of HTTP 4575 might convey a Date if the server is expected to adjust its 4576 interpretation of the user's request based on differences between the 4577 user agent and server clocks. 4579 10.2.3. Location 4581 The "Location" header field is used in some responses to refer to a 4582 specific resource in relation to the response. The type of 4583 relationship is defined by the combination of request method and 4584 status code semantics. 4586 Location = URI-reference 4588 The field value consists of a single URI-reference. When it has the 4589 form of a relative reference ([RFC3986], Section 4.2), the final 4590 value is computed by resolving it against the target URI ([RFC3986], 4591 Section 5). 4593 For 201 (Created) responses, the Location value refers to the primary 4594 resource created by the request. For 3xx (Redirection) responses, 4595 the Location value refers to the preferred target resource for 4596 automatically redirecting the request. 4598 If the Location value provided in a 3xx (Redirection) response does 4599 not have a fragment component, a user agent MUST process the 4600 redirection as if the value inherits the fragment component of the 4601 URI reference used to generate the target URI (i.e., the redirection 4602 inherits the original reference's fragment, if any). 4604 For example, a GET request generated for the URI reference 4605 "http://www.example.org/~tim" might result in a 303 (See Other) 4606 response containing the header field: 4608 Location: /People.html#tim 4610 which suggests that the user agent redirect to 4611 "http://www.example.org/People.html#tim" 4613 Likewise, a GET request generated for the URI reference 4614 "http://www.example.org/index.html#larry" might result in a 301 4615 (Moved Permanently) response containing the header field: 4617 Location: http://www.example.net/index.html 4619 which suggests that the user agent redirect to 4620 "http://www.example.net/index.html#larry", preserving the original 4621 fragment identifier. 4623 There are circumstances in which a fragment identifier in a Location 4624 value would not be appropriate. For example, the Location header 4625 field in a 201 (Created) response is supposed to provide a URI that 4626 is specific to the created resource. 4628 | *Note:* Some recipients attempt to recover from Location header 4629 | fields that are not valid URI references. This specification 4630 | does not mandate or define such processing, but does allow it 4631 | for the sake of robustness. A Location field value cannot 4632 | allow a list of members because the comma list separator is a 4633 | valid data character within a URI-reference. If an invalid 4634 | message is sent with multiple Location field lines, a recipient 4635 | along the path might combine those field lines into one value. 4636 | Recovery of a valid Location field value from that situation is 4637 | difficult and not interoperable across implementations. 4639 | *Note:* The Content-Location header field (Section 8.8) differs 4640 | from Location in that the Content-Location refers to the most 4641 | specific resource corresponding to the enclosed representation. 4642 | It is therefore possible for a response to contain both the 4643 | Location and Content-Location header fields. 4645 10.2.4. Retry-After 4647 Servers send the "Retry-After" header field to indicate how long the 4648 user agent ought to wait before making a follow-up request. When 4649 sent with a 503 (Service Unavailable) response, Retry-After indicates 4650 how long the service is expected to be unavailable to the client. 4651 When sent with any 3xx (Redirection) response, Retry-After indicates 4652 the minimum time that the user agent is asked to wait before issuing 4653 the redirected request. 4655 The Retry-After field value can be either an HTTP-date or a number of 4656 seconds to delay after the response is received. 4658 Retry-After = HTTP-date / delay-seconds 4660 A delay-seconds value is a non-negative decimal integer, representing 4661 time in seconds. 4663 delay-seconds = 1*DIGIT 4665 Two examples of its use are 4667 Retry-After: Fri, 31 Dec 1999 23:59:59 GMT 4668 Retry-After: 120 4670 In the latter example, the delay is 2 minutes. 4672 10.2.5. Server 4674 The "Server" header field contains information about the software 4675 used by the origin server to handle the request, which is often used 4676 by clients to help identify the scope of reported interoperability 4677 problems, to work around or tailor requests to avoid particular 4678 server limitations, and for analytics regarding server or operating 4679 system use. An origin server MAY generate a Server header field in 4680 its responses. 4682 Server = product *( RWS ( product / comment ) ) 4684 The Server header field value consists of one or more product 4685 identifiers, each followed by zero or more comments (Section 5.6.5), 4686 which together identify the origin server software and its 4687 significant subproducts. By convention, the product identifiers are 4688 listed in decreasing order of their significance for identifying the 4689 origin server software. Each product identifier consists of a name 4690 and optional version, as defined in Section 10.1.6. 4692 Example: 4694 Server: CERN/3.0 libwww/2.17 4696 An origin server SHOULD NOT generate a Server header field containing 4697 needlessly fine-grained detail and SHOULD limit the addition of 4698 subproducts by third parties. Overly long and detailed Server field 4699 values increase response latency and potentially reveal internal 4700 implementation details that might make it (slightly) easier for 4701 attackers to find and exploit known security holes. 4703 11. HTTP Authentication 4705 11.1. Authentication Scheme 4707 HTTP provides a general framework for access control and 4708 authentication, via an extensible set of challenge-response 4709 authentication schemes, which can be used by a server to challenge a 4710 client request and by a client to provide authentication information. 4711 It uses a case-insensitive token to identify the authentication 4712 scheme 4714 auth-scheme = token 4716 Aside from the general framework, this document does not specify any 4717 authentication schemes. New and existing authentication schemes are 4718 specified independently and ought to be registered within the 4719 "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry". 4720 For example, the "basic" and "digest" authentication schemes are 4721 defined by RFC 7617 and RFC 7616, respectively. 4723 11.2. Authentication Parameters 4725 The authentication scheme is followed by additional information 4726 necessary for achieving authentication via that scheme as either a 4727 comma-separated list of parameters or a single sequence of characters 4728 capable of holding base64-encoded information. 4730 token68 = 1*( ALPHA / DIGIT / 4731 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 4733 The token68 syntax allows the 66 unreserved URI characters 4734 ([RFC3986]), plus a few others, so that it can hold a base64, 4735 base64url (URL and filename safe alphabet), base32, or base16 (hex) 4736 encoding, with or without padding, but excluding whitespace 4737 ([RFC4648]). 4739 Authentication parameters are name=value pairs, where the name token 4740 is matched case-insensitively and each parameter name MUST only occur 4741 once per challenge. 4743 auth-param = token BWS "=" BWS ( token / quoted-string ) 4745 Parameter values can be expressed either as "token" or as "quoted- 4746 string" (Section 5.6). Authentication scheme definitions need to 4747 accept both notations, both for senders and recipients, to allow 4748 recipients to use generic parsing components regardless of the 4749 authentication scheme. 4751 For backwards compatibility, authentication scheme definitions can 4752 restrict the format for senders to one of the two variants. This can 4753 be important when it is known that deployed implementations will fail 4754 when encountering one of the two formats. 4756 11.3. Challenge and Response 4758 A 401 (Unauthorized) response message is used by an origin server to 4759 challenge the authorization of a user agent, including a 4760 WWW-Authenticate header field containing at least one challenge 4761 applicable to the requested resource. 4763 A 407 (Proxy Authentication Required) response message is used by a 4764 proxy to challenge the authorization of a client, including a 4765 Proxy-Authenticate header field containing at least one challenge 4766 applicable to the proxy for the requested resource. 4768 challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ] 4770 | *Note:* Many clients fail to parse a challenge that contains an 4771 | unknown scheme. A workaround for this problem is to list well- 4772 | supported schemes (such as "basic") first. 4774 A user agent that wishes to authenticate itself with an origin server 4775 - usually, but not necessarily, after receiving a 401 (Unauthorized) 4776 - can do so by including an Authorization header field with the 4777 request. 4779 A client that wishes to authenticate itself with a proxy - usually, 4780 but not necessarily, after receiving a 407 (Proxy Authentication 4781 Required) - can do so by including a Proxy-Authorization header field 4782 with the request. 4784 11.4. Credentials 4786 Both the Authorization field value and the Proxy-Authorization field 4787 value contain the client's credentials for the realm of the resource 4788 being requested, based upon a challenge received in a response 4789 (possibly at some point in the past). When creating their values, 4790 the user agent ought to do so by selecting the challenge with what it 4791 considers to be the most secure auth-scheme that it understands, 4792 obtaining credentials from the user as appropriate. Transmission of 4793 credentials within header field values implies significant security 4794 considerations regarding the confidentiality of the underlying 4795 connection, as described in Section 17.15.1. 4797 credentials = auth-scheme [ 1*SP ( token68 / #auth-param ) ] 4799 Upon receipt of a request for a protected resource that omits 4800 credentials, contains invalid credentials (e.g., a bad password) or 4801 partial credentials (e.g., when the authentication scheme requires 4802 more than one round trip), an origin server SHOULD send a 401 4803 (Unauthorized) response that contains a WWW-Authenticate header field 4804 with at least one (possibly new) challenge applicable to the 4805 requested resource. 4807 Likewise, upon receipt of a request that omits proxy credentials or 4808 contains invalid or partial proxy credentials, a proxy that requires 4809 authentication SHOULD generate a 407 (Proxy Authentication Required) 4810 response that contains a Proxy-Authenticate header field with at 4811 least one (possibly new) challenge applicable to the proxy. 4813 A server that receives valid credentials that are not adequate to 4814 gain access ought to respond with the 403 (Forbidden) status code 4815 (Section 15.5.4). 4817 HTTP does not restrict applications to this simple challenge-response 4818 framework for access authentication. Additional mechanisms can be 4819 used, such as authentication at the transport level or via message 4820 encapsulation, and with additional header fields specifying 4821 authentication information. However, such additional mechanisms are 4822 not defined by this specification. 4824 Note that various custom mechanisms for user authentication use the 4825 Set-Cookie and Cookie header fields, defined in [RFC6265], for 4826 passing tokens related to authentication. 4828 11.5. Establishing a Protection Space (Realm) 4830 The "_realm_" authentication parameter is reserved for use by 4831 authentication schemes that wish to indicate a scope of protection. 4833 A _protection space_ is defined by the origin (see Section 4.3.1) of 4834 the server being accessed, in combination with the realm value if 4835 present. These realms allow the protected resources on a server to 4836 be partitioned into a set of protection spaces, each with its own 4837 authentication scheme and/or authorization database. The realm value 4838 is a string, generally assigned by the origin server, that can have 4839 additional semantics specific to the authentication scheme. Note 4840 that a response can have multiple challenges with the same auth- 4841 scheme but with different realms. 4843 The protection space determines the domain over which credentials can 4844 be automatically applied. If a prior request has been authorized, 4845 the user agent MAY reuse the same credentials for all other requests 4846 within that protection space for a period of time determined by the 4847 authentication scheme, parameters, and/or user preferences (such as a 4848 configurable inactivity timeout). Unless specifically allowed by the 4849 authentication scheme, a single protection space cannot extend 4850 outside the scope of its server. 4852 For historical reasons, a sender MUST only generate the quoted-string 4853 syntax. Recipients might have to support both token and quoted- 4854 string syntax for maximum interoperability with existing clients that 4855 have been accepting both notations for a long time. 4857 11.6. Authenticating Users to Origin Servers 4859 11.6.1. WWW-Authenticate 4861 The "WWW-Authenticate" header field indicates the authentication 4862 scheme(s) and parameters applicable to the target resource. 4864 WWW-Authenticate = #challenge 4866 A server generating a 401 (Unauthorized) response MUST send a WWW- 4867 Authenticate header field containing at least one challenge. A 4868 server MAY generate a WWW-Authenticate header field in other response 4869 messages to indicate that supplying credentials (or different 4870 credentials) might affect the response. 4872 A proxy forwarding a response MUST NOT modify any WWW-Authenticate 4873 header fields in that response. 4875 User agents are advised to take special care in parsing the field 4876 value, as it might contain more than one challenge, and each 4877 challenge can contain a comma-separated list of authentication 4878 parameters. Furthermore, the header field itself can occur multiple 4879 times. 4881 For instance: 4883 WWW-Authenticate: Newauth realm="apps", type=1, 4884 title="Login to \"apps\"", Basic realm="simple" 4886 This header field contains two challenges; one for the "Newauth" 4887 scheme with a realm value of "apps", and two additional parameters 4888 "type" and "title", and another one for the "Basic" scheme with a 4889 realm value of "simple". 4891 Some user agents do not recognise this form, however. As a result, 4892 sending a WWW-Authenticate field value with more than one member on 4893 the same field line might not be interoperable. 4895 | *Note:* The challenge grammar production uses the list syntax 4896 | as well. Therefore, a sequence of comma, whitespace, and comma 4897 | can be considered either as applying to the preceding 4898 | challenge, or to be an empty entry in the list of challenges. 4899 | In practice, this ambiguity does not affect the semantics of 4900 | the header field value and thus is harmless. 4902 11.6.2. Authorization 4904 The "Authorization" header field allows a user agent to authenticate 4905 itself with an origin server - usually, but not necessarily, after 4906 receiving a 401 (Unauthorized) response. Its value consists of 4907 credentials containing the authentication information of the user 4908 agent for the realm of the resource being requested. 4910 Authorization = credentials 4912 If a request is authenticated and a realm specified, the same 4913 credentials are presumed to be valid for all other requests within 4914 this realm (assuming that the authentication scheme itself does not 4915 require otherwise, such as credentials that vary according to a 4916 challenge value or using synchronized clocks). 4918 A proxy forwarding a request MUST NOT modify any Authorization header 4919 fields in that request. See Section 3.4 of [Caching] for details of 4920 and requirements pertaining to handling of the Authorization header 4921 field by HTTP caches. 4923 11.6.3. Authentication-Info 4925 HTTP authentication schemes can use the Authentication-Info response 4926 field to communicate information after the client's authentication 4927 credentials have been accepted. This information can include a 4928 finalization message from the server (e.g., it can contain the server 4929 authentication). 4931 The field value is a list of parameters (name/value pairs), using the 4932 "auth-param" syntax defined in Section 11.3. This specification only 4933 describes the generic format; authentication schemes using 4934 Authentication-Info will define the individual parameters. The 4935 "Digest" Authentication Scheme, for instance, defines multiple 4936 parameters in Section 3.5 of [RFC7616]. 4938 Authentication-Info = #auth-param 4940 The Authentication-Info field can be used in any HTTP response, 4941 independently of request method and status code. Its semantics are 4942 defined by the authentication scheme indicated by the Authorization 4943 header field (Section 11.6.2) of the corresponding request. 4945 A proxy forwarding a response is not allowed to modify the field 4946 value in any way. 4948 Authentication-Info can be sent as a trailer field (Section 6.5) when 4949 the authentication scheme explicitly allows this. 4951 11.7. Authenticating Clients to Proxies 4953 11.7.1. Proxy-Authenticate 4955 The "Proxy-Authenticate" header field consists of at least one 4956 challenge that indicates the authentication scheme(s) and parameters 4957 applicable to the proxy for this request. A proxy MUST send at least 4958 one Proxy-Authenticate header field in each 407 (Proxy Authentication 4959 Required) response that it generates. 4961 Proxy-Authenticate = #challenge 4963 Unlike WWW-Authenticate, the Proxy-Authenticate header field applies 4964 only to the next outbound client on the response chain. This is 4965 because only the client that chose a given proxy is likely to have 4966 the credentials necessary for authentication. However, when multiple 4967 proxies are used within the same administrative domain, such as 4968 office and regional caching proxies within a large corporate network, 4969 it is common for credentials to be generated by the user agent and 4970 passed through the hierarchy until consumed. Hence, in such a 4971 configuration, it will appear as if Proxy-Authenticate is being 4972 forwarded because each proxy will send the same challenge set. 4974 Note that the parsing considerations for WWW-Authenticate apply to 4975 this header field as well; see Section 11.6.1 for details. 4977 11.7.2. Proxy-Authorization 4979 The "Proxy-Authorization" header field allows the client to identify 4980 itself (or its user) to a proxy that requires authentication. Its 4981 value consists of credentials containing the authentication 4982 information of the client for the proxy and/or realm of the resource 4983 being requested. 4985 Proxy-Authorization = credentials 4987 Unlike Authorization, the Proxy-Authorization header field applies 4988 only to the next inbound proxy that demanded authentication using the 4989 Proxy-Authenticate header field. When multiple proxies are used in a 4990 chain, the Proxy-Authorization header field is consumed by the first 4991 inbound proxy that was expecting to receive credentials. A proxy MAY 4992 relay the credentials from the client request to the next proxy if 4993 that is the mechanism by which the proxies cooperatively authenticate 4994 a given request. 4996 11.7.3. Proxy-Authentication-Info 4998 The Proxy-Authentication-Info response header field is equivalent to 4999 Authentication-Info, except that it applies to proxy authentication 5000 (Section 11.3) and its semantics are defined by the authentication 5001 scheme indicated by the Proxy-Authorization header field 5002 (Section 11.7.2) of the corresponding request: 5004 Proxy-Authentication-Info = #auth-param 5006 However, unlike Authentication-Info, the Proxy-Authentication-Info 5007 header field applies only to the next outbound client on the response 5008 chain. This is because only the client that chose a given proxy is 5009 likely to have the credentials necessary for authentication. 5010 However, when multiple proxies are used within the same 5011 administrative domain, such as office and regional caching proxies 5012 within a large corporate network, it is common for credentials to be 5013 generated by the user agent and passed through the hierarchy until 5014 consumed. Hence, in such a configuration, it will appear as if 5015 Proxy-Authentication-Info is being forwarded because each proxy will 5016 send the same field value. 5018 12. Content Negotiation 5020 When responses convey payload information, whether indicating a 5021 success or an error, the origin server often has different ways of 5022 representing that information; for example, in different formats, 5023 languages, or encodings. Likewise, different users or user agents 5024 might have differing capabilities, characteristics, or preferences 5025 that could influence which representation, among those available, 5026 would be best to deliver. For this reason, HTTP provides mechanisms 5027 for content negotiation. 5029 This specification defines three patterns of content negotiation that 5030 can be made visible within the protocol: "proactive" negotiation, 5031 where the server selects the representation based upon the user 5032 agent's stated preferences, "reactive" negotiation, where the server 5033 provides a list of representations for the user agent to choose from, 5034 and "request payload" negotiation, where the user agent selects the 5035 representation for a future request based upon the server's stated 5036 preferences in past responses. 5038 Other patterns of content negotiation include "conditional content", 5039 where the representation consists of multiple parts that are 5040 selectively rendered based on user agent parameters, "active 5041 content", where the representation contains a script that makes 5042 additional (more specific) requests based on the user agent 5043 characteristics, and "Transparent Content Negotiation" ([RFC2295]), 5044 where content selection is performed by an intermediary. These 5045 patterns are not mutually exclusive, and each has trade-offs in 5046 applicability and practicality. 5048 Note that, in all cases, HTTP is not aware of the resource semantics. 5049 The consistency with which an origin server responds to requests, 5050 over time and over the varying dimensions of content negotiation, and 5051 thus the "sameness" of a resource's observed representations over 5052 time, is determined entirely by whatever entity or algorithm selects 5053 or generates those responses. 5055 12.1. Proactive Negotiation 5057 When content negotiation preferences are sent by the user agent in a 5058 request to encourage an algorithm located at the server to select the 5059 preferred representation, it is called _proactive negotiation_ 5060 (a.k.a., _server-driven negotiation_). Selection is based on the 5061 available representations for a response (the dimensions over which 5062 it might vary, such as language, content-coding, etc.) compared to 5063 various information supplied in the request, including both the 5064 explicit negotiation header fields below and implicit 5065 characteristics, such as the client's network address or parts of the 5066 User-Agent field. 5068 Proactive negotiation is advantageous when the algorithm for 5069 selecting from among the available representations is difficult to 5070 describe to a user agent, or when the server desires to send its 5071 "best guess" to the user agent along with the first response (hoping 5072 to avoid the round trip delay of a subsequent request if the "best 5073 guess" is good enough for the user). In order to improve the 5074 server's guess, a user agent MAY send request header fields that 5075 describe its preferences. 5077 Proactive negotiation has serious disadvantages: 5079 o It is impossible for the server to accurately determine what might 5080 be "best" for any given user, since that would require complete 5081 knowledge of both the capabilities of the user agent and the 5082 intended use for the response (e.g., does the user want to view it 5083 on screen or print it on paper?); 5085 o Having the user agent describe its capabilities in every request 5086 can be both very inefficient (given that only a small percentage 5087 of responses have multiple representations) and a potential risk 5088 to the user's privacy; 5090 o It complicates the implementation of an origin server and the 5091 algorithms for generating responses to a request; and, 5093 o It limits the reusability of responses for shared caching. 5095 A user agent cannot rely on proactive negotiation preferences being 5096 consistently honored, since the origin server might not implement 5097 proactive negotiation for the requested resource or might decide that 5098 sending a response that doesn't conform to the user agent's 5099 preferences is better than sending a 406 (Not Acceptable) response. 5101 A Vary header field (Section 12.5.5) is often sent in a response 5102 subject to proactive negotiation to indicate what parts of the 5103 request information were used in the selection algorithm. 5105 The request header fields Accept, Accept-Charset, Accept-Encoding, 5106 and Accept-Language are defined below for a user agent to engage in 5107 proactive negotiation of the response content. The preferences sent 5108 in these fields apply to any content in the response, including 5109 representations of the target resource, representations of error or 5110 processing status, and potentially even the miscellaneous text 5111 strings that might appear within the protocol. 5113 12.2. Reactive Negotiation 5115 With _reactive negotiation_ (a.k.a., _agent-driven negotiation_), 5116 selection of the best response representation (regardless of the 5117 status code) is performed by the user agent after receiving an 5118 initial response from the origin server that contains a list of 5119 resources for alternative representations. 5121 If the user agent is not satisfied by the initial response 5122 representation, it can perform a GET request on one or more of the 5123 alternative resources, selected based on metadata included in the 5124 list, to obtain a different form of representation for that response. 5125 Selection of alternatives might be performed automatically by the 5126 user agent or manually by the user selecting from a generated 5127 (possibly hypertext) menu. 5129 Note that the above refers to representations of the response, in 5130 general, not representations of the resource. The alternative 5131 representations are only considered representations of the target 5132 resource if the response in which those alternatives are provided has 5133 the semantics of being a representation of the target resource (e.g., 5134 a 200 (OK) response to a GET request) or has the semantics of 5135 providing links to alternative representations for the target 5136 resource (e.g., a 300 (Multiple Choices) response to a GET request). 5138 A server might choose not to send an initial representation, other 5139 than the list of alternatives, and thereby indicate that reactive 5140 negotiation by the user agent is preferred. For example, the 5141 alternatives listed in responses with the 300 (Multiple Choices) and 5142 406 (Not Acceptable) status codes include information about the 5143 available representations so that the user or user agent can react by 5144 making a selection. 5146 Reactive negotiation is advantageous when the response would vary 5147 over commonly used dimensions (such as type, language, or encoding), 5148 when the origin server is unable to determine a user agent's 5149 capabilities from examining the request, and generally when public 5150 caches are used to distribute server load and reduce network usage. 5152 Reactive negotiation suffers from the disadvantages of transmitting a 5153 list of alternatives to the user agent, which degrades user-perceived 5154 latency if transmitted in the header section, and needing a second 5155 request to obtain an alternate representation. Furthermore, this 5156 specification does not define a mechanism for supporting automatic 5157 selection, though it does not prevent such a mechanism from being 5158 developed as an extension. 5160 12.3. Request Payload Negotiation 5162 When content negotiation preferences are sent in a server's response, 5163 the listed preferences are called _request payload negotiation_ 5164 because they intend to influence selection of an appropriate payload 5165 for subsequent requests to that resource. For example, the Accept 5166 (Section 12.5.1) and Accept-Encoding (Section 12.5.3) header fields 5167 can be sent in a response to indicate preferred media types and 5168 content codings for subsequent requests to that resource. 5170 Similarly, Section 3.1 of [RFC5789] defines the "Accept-Patch" 5171 response header field which allows discovery of which content types 5172 are accepted in PATCH requests. 5174 12.4. Content Negotiation Field Features 5176 12.4.1. Absence 5178 For each of the content negotiation fields, a request that does not 5179 contain the field implies that the sender has no preference on that 5180 axis of negotiation. 5182 If a content negotiation header field is present in a request and 5183 none of the available representations for the response can be 5184 considered acceptable according to it, the origin server can either 5185 honor the header field by sending a 406 (Not Acceptable) response or 5186 disregard the header field by treating the response as if it is not 5187 subject to content negotiation for that request header field. This 5188 does not imply, however, that the client will be able to use the 5189 representation. 5191 | *Note:* Sending these header fields makes it easier for a 5192 | server to identify an individual by virtue of the user agent's 5193 | request characteristics (Section 17.12). 5195 12.4.2. Quality Values 5197 The content negotiation fields defined by this specification use a 5198 common parameter, named "q" (case-insensitive), to assign a relative 5199 "weight" to the preference for that associated kind of content. This 5200 weight is referred to as a "quality value" (or "qvalue") because the 5201 same parameter name is often used within server configurations to 5202 assign a weight to the relative quality of the various 5203 representations that can be selected for a resource. 5205 The weight is normalized to a real number in the range 0 through 1, 5206 where 0.001 is the least preferred and 1 is the most preferred; a 5207 value of 0 means "not acceptable". If no "q" parameter is present, 5208 the default weight is 1. 5210 weight = OWS ";" OWS "q=" qvalue 5211 qvalue = ( "0" [ "." 0*3DIGIT ] ) 5212 / ( "1" [ "." 0*3("0") ] ) 5214 A sender of qvalue MUST NOT generate more than three digits after the 5215 decimal point. User configuration of these values ought to be 5216 limited in the same fashion. 5218 12.4.3. Wildcard Values 5220 Most of these header fields, where indicated, define a wildcard value 5221 ("*") to select unspecified values. If no wildcard is present, 5222 values that are not explicitly mentioned in the field are considered 5223 unacceptable, except for within Vary where it means the variance is 5224 unlimited. 5226 | *Note:* In practice, using wildcards in content negotiation has 5227 | limited practical value, because it is seldom useful to say, 5228 | for example, "I prefer image/* more or less than (some other 5229 | specific value)". Clients can explicitly request a 406 (Not 5230 | Acceptable) response if a more preferred format is not 5231 | available by sending Accept: */*;q=0, but they still need to be 5232 | able to handle a different response, since the server is 5233 | allowed to ignore their preference. 5235 12.5. Content Negotiation Fields 5236 12.5.1. Accept 5238 The "Accept" header field can be used by user agents to specify their 5239 preferences regarding response media types. For example, Accept 5240 header fields can be used to indicate that the request is 5241 specifically limited to a small set of desired types, as in the case 5242 of a request for an in-line image. 5244 When sent by a server in a response, Accept provides information 5245 about what content types are preferred in the payload of a subsequent 5246 request to the same resource. 5248 Accept = #( media-range [ accept-params ] ) 5250 media-range = ( "*/*" 5251 / ( type "/" "*" ) 5252 / ( type "/" subtype ) 5253 ) parameters 5254 accept-params = weight *( accept-ext ) 5255 accept-ext = OWS ";" OWS token [ "=" ( token / quoted-string ) ] 5257 The asterisk "*" character is used to group media types into ranges, 5258 with "*/*" indicating all media types and "type/*" indicating all 5259 subtypes of that type. The media-range can include media type 5260 parameters that are applicable to that range. 5262 Each media-range might be followed by zero or more applicable media 5263 type parameters (e.g., charset), an optional "q" parameter for 5264 indicating a relative weight (Section 12.4.2), and then zero or more 5265 extension parameters. The "q" parameter is necessary if any 5266 extensions (accept-ext) are present, since it acts as a separator 5267 between the two parameter sets. 5269 | *Note:* Use of the "q" parameter name to separate media type 5270 | parameters from Accept extension parameters is due to 5271 | historical practice. Although this prevents any media type 5272 | parameter named "q" from being used with a media range, such an 5273 | event is believed to be unlikely given the lack of any "q" 5274 | parameters in the IANA media type registry and the rare usage 5275 | of any media type parameters in Accept. Future media types are 5276 | discouraged from registering any parameter named "q". 5278 The example 5280 Accept: audio/*; q=0.2, audio/basic 5282 is interpreted as "I prefer audio/basic, but send me any audio type 5283 if it is the best available after an 80% markdown in quality". 5285 A more elaborate example is 5287 Accept: text/plain; q=0.5, text/html, 5288 text/x-dvi; q=0.8, text/x-c 5290 Verbally, this would be interpreted as "text/html and text/x-c are 5291 the equally preferred media types, but if they do not exist, then 5292 send the text/x-dvi representation, and if that does not exist, send 5293 the text/plain representation". 5295 Media ranges can be overridden by more specific media ranges or 5296 specific media types. If more than one media range applies to a 5297 given type, the most specific reference has precedence. For example, 5299 Accept: text/*, text/plain, text/plain;format=flowed, */* 5301 have the following precedence: 5303 1. text/plain;format=flowed 5305 2. text/plain 5307 3. text/* 5309 4. */* 5311 The media type quality factor associated with a given type is 5312 determined by finding the media range with the highest precedence 5313 that matches the type. For example, 5315 Accept: text/*;q=0.3, text/plain;q=0.7, text/plain;format=flowed, 5316 text/plain;format=fixed;q=0.4, */*;q=0.5 5318 would cause the following values to be associated: 5320 -------------------------- --------------- 5321 Media Type Quality Value 5322 -------------------------- --------------- 5323 text/plain;format=flowed 1 5324 text/plain 0.7 5325 text/html 0.3 5326 image/jpeg 0.5 5327 text/plain;format=fixed 0.4 5328 text/html;level=3 0.7 5329 -------------------------- --------------- 5331 Table 5 5333 | *Note:* A user agent might be provided with a default set of 5334 | quality values for certain media ranges. However, unless the 5335 | user agent is a closed system that cannot interact with other 5336 | rendering agents, this default set ought to be configurable by 5337 | the user. 5339 12.5.2. Accept-Charset 5341 The "Accept-Charset" header field can be sent by a user agent to 5342 indicate its preferences for charsets in textual response content. 5343 For example, this field allows user agents capable of understanding 5344 more comprehensive or special-purpose charsets to signal that 5345 capability to an origin server that is capable of representing 5346 information in those charsets. 5348 Accept-Charset = #( ( charset / "*" ) [ weight ] ) 5350 Charset names are defined in Section 8.4.2. A user agent MAY 5351 associate a quality value with each charset to indicate the user's 5352 relative preference for that charset, as defined in Section 12.4.2. 5353 An example is 5355 Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 5357 The special value "*", if present in the Accept-Charset header field, 5358 matches every charset that is not mentioned elsewhere in the field. 5360 | *Note:* Accept-Charset is deprecated because UTF-8 has become 5361 | nearly ubiquitous and sending a detailed list of user-preferred 5362 | charsets wastes bandwidth, increases latency, and makes passive 5363 | fingerprinting far too easy (Section 17.12). Most general- 5364 | purpose user agents do not send Accept-Charset, unless 5365 | specifically configured to do so. 5367 12.5.3. Accept-Encoding 5369 The "Accept-Encoding" header field can be used to indicate 5370 preferences regarding the use of content codings (Section 8.5.1). 5372 When sent by a user agent in a request, Accept-Encoding indicates the 5373 content codings acceptable in a response. 5375 When sent by a server in a response, Accept-Encoding provides 5376 information about what content codings are preferred in the payload 5377 of a subsequent request to the same resource. 5379 An "identity" token is used as a synonym for "no encoding" in order 5380 to communicate when no encoding is preferred. 5382 Accept-Encoding = #( codings [ weight ] ) 5383 codings = content-coding / "identity" / "*" 5385 Each codings value MAY be given an associated quality value 5386 representing the preference for that encoding, as defined in 5387 Section 12.4.2. The asterisk "*" symbol in an Accept-Encoding field 5388 matches any available content-coding not explicitly listed in the 5389 field. 5391 For example, 5393 Accept-Encoding: compress, gzip 5394 Accept-Encoding: 5395 Accept-Encoding: * 5396 Accept-Encoding: compress;q=0.5, gzip;q=1.0 5397 Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 5399 A server tests whether a content-coding for a given representation is 5400 acceptable using these rules: 5402 1. If no Accept-Encoding header field is in the request, any 5403 content-coding is considered acceptable by the user agent. 5405 2. If the representation has no content-coding, then it is 5406 acceptable by default unless specifically excluded by the Accept- 5407 Encoding header field stating either "identity;q=0" or "*;q=0" 5408 without a more specific entry for "identity". 5410 3. If the representation's content-coding is one of the content- 5411 codings listed in the Accept-Encoding field value, then it is 5412 acceptable unless it is accompanied by a qvalue of 0. (As 5413 defined in Section 12.4.2, a qvalue of 0 means "not acceptable".) 5415 4. If multiple content-codings are acceptable, then the acceptable 5416 content-coding with the highest non-zero qvalue is preferred. 5418 An Accept-Encoding header field with a field value that is empty 5419 implies that the user agent does not want any content-coding in 5420 response. If an Accept-Encoding header field is present in a request 5421 and none of the available representations for the response have a 5422 content-coding that is listed as acceptable, the origin server SHOULD 5423 send a response without any content-coding. 5425 When the Accept-Encoding header field is present in a response, it 5426 indicates what content codings the resource was willing to accept in 5427 the associated request. The field value is evaluated the same way as 5428 in a request. 5430 Note that this information is specific to the associated request; the 5431 set of supported encodings might be different for other resources on 5432 the same server and could change over time or depend on other aspects 5433 of the request (such as the request method). 5435 Servers that fail a request due to an unsupported content coding 5436 ought to respond with a 415 (Unsupported Media Type) status and 5437 include an Accept-Encoding header field in that response, allowing 5438 clients to distinguish between issues related to content codings and 5439 media types. In order to avoid confusion with issues related to 5440 media types, servers that fail a request with a 415 status for 5441 reasons unrelated to content codings MUST NOT include the Accept- 5442 Encoding header field. 5444 The most common use of Accept-Encoding is in responses with a 415 5445 (Unsupported Media Type) status code, in response to optimistic use 5446 of a content coding by clients. However, the header field can also 5447 be used to indicate to clients that content codings are supported, to 5448 optimize future interactions. For example, a resource might include 5449 it in a 2xx (Successful) response when the request payload was big 5450 enough to justify use of a compression coding but the client failed 5451 do so. 5453 | *Note:* Most HTTP/1.0 applications do not recognize or obey 5454 | qvalues associated with content-codings. This means that 5455 | qvalues might not work and are not permitted with x-gzip or 5456 | x-compress. 5458 12.5.4. Accept-Language 5460 The "Accept-Language" header field can be used by user agents to 5461 indicate the set of natural languages that are preferred in the 5462 response. Language tags are defined in Section 8.6.1. 5464 Accept-Language = #( language-range [ weight ] ) 5465 language-range = 5466 5468 Each language-range can be given an associated quality value 5469 representing an estimate of the user's preference for the languages 5470 specified by that range, as defined in Section 12.4.2. For example, 5472 Accept-Language: da, en-gb;q=0.8, en;q=0.7 5474 would mean: "I prefer Danish, but will accept British English and 5475 other types of English". 5477 Note that some recipients treat the order in which language tags are 5478 listed as an indication of descending priority, particularly for tags 5479 that are assigned equal quality values (no value is the same as q=1). 5480 However, this behavior cannot be relied upon. For consistency and to 5481 maximize interoperability, many user agents assign each language tag 5482 a unique quality value while also listing them in order of decreasing 5483 quality. Additional discussion of language priority lists can be 5484 found in Section 2.3 of [RFC4647]. 5486 For matching, Section 3 of [RFC4647] defines several matching 5487 schemes. Implementations can offer the most appropriate matching 5488 scheme for their requirements. The "Basic Filtering" scheme 5489 ([RFC4647], Section 3.3.1) is identical to the matching scheme that 5490 was previously defined for HTTP in Section 14.4 of [RFC2616]. 5492 It might be contrary to the privacy expectations of the user to send 5493 an Accept-Language header field with the complete linguistic 5494 preferences of the user in every request (Section 17.12). 5496 Since intelligibility is highly dependent on the individual user, 5497 user agents need to allow user control over the linguistic preference 5498 (either through configuration of the user agent itself or by 5499 defaulting to a user controllable system setting). A user agent that 5500 does not provide such control to the user MUST NOT send an Accept- 5501 Language header field. 5503 | *Note:* User agents ought to provide guidance to users when 5504 | setting a preference, since users are rarely familiar with the 5505 | details of language matching as described above. For example, 5506 | users might assume that on selecting "en-gb", they will be 5507 | served any kind of English document if British English is not 5508 | available. A user agent might suggest, in such a case, to add 5509 | "en" to the list for better matching behavior. 5511 12.5.5. Vary 5513 The "Vary" header field in a response describes what parts of a 5514 request message, aside from the method and target URI, might 5515 influence the origin server's process for selecting and representing 5516 this response. 5518 Vary = #( "*" / field-name ) 5520 A Vary field value is a list of request field names, known as the 5521 selecting header fields, that might have a role in selecting the 5522 representation for this response. Potential selecting header fields 5523 are not limited to those defined by this specification. 5525 If the list contains "*", it signals that other aspects of the 5526 request might play a role in selecting the response representation, 5527 possibly including elements outside the message syntax (e.g., the 5528 client's network address). A recipient will not be able to determine 5529 whether this response is appropriate for a later request without 5530 forwarding the request to the origin server. A proxy MUST NOT 5531 generate "*" in a Vary field value. 5533 For example, a response that contains 5535 Vary: accept-encoding, accept-language 5537 indicates that the origin server might have used the request's 5538 Accept-Encoding and Accept-Language header fields (or lack thereof) 5539 as determining factors while choosing the content for this response. 5541 An origin server might send Vary with a list of header fields for two 5542 purposes: 5544 1. To inform cache recipients that they MUST NOT use this response 5545 to satisfy a later request unless the later request has the same 5546 values for the listed header fields as the original request 5547 (Section 4.1 of [Caching]). In other words, Vary expands the 5548 cache key required to match a new request to the stored cache 5549 entry. 5551 2. To inform user agent recipients that this response is subject to 5552 content negotiation (Section 12) and that a different 5553 representation might be sent in a subsequent request if 5554 additional parameters are provided in the listed header fields 5555 (proactive negotiation). 5557 An origin server SHOULD send a Vary header field when its algorithm 5558 for selecting a representation varies based on aspects of the request 5559 message other than the method and target URI, unless the variance 5560 cannot be crossed or the origin server has been deliberately 5561 configured to prevent cache transparency. For example, there is no 5562 need to send the Authorization field name in Vary because reuse 5563 across users is constrained by the field definition (Section 11.6.2). 5564 Likewise, an origin server might use Cache-Control response 5565 directives (Section 5.2 of [Caching]) to supplant Vary if it 5566 considers the variance less significant than the performance cost of 5567 Vary's impact on caching. 5569 13. Conditional Requests 5571 A conditional request is an HTTP request with one or more request 5572 header fields that indicate a precondition to be tested before 5573 applying the request method to the target resource. Section 13.2 5574 defines when preconditions are applied. Section 13.3 defines the 5575 order of evaluation when more than one precondition is present. 5577 Conditional GET requests are the most efficient mechanism for HTTP 5578 cache updates [Caching]. Conditionals can also be applied to state- 5579 changing methods, such as PUT and DELETE, to prevent the "lost 5580 update" problem: one client accidentally overwriting the work of 5581 another client that has been acting in parallel. 5583 Conditional request preconditions are based on the state of the 5584 target resource as a whole (its current value set) or the state as 5585 observed in a previously obtained representation (one value in that 5586 set). A resource might have multiple current representations, each 5587 with its own observable state. The conditional request mechanisms 5588 assume that the mapping of requests to a selected representation 5589 (Section 8) will be consistent over time if the server intends to 5590 take advantage of conditionals. Regardless, if the mapping is 5591 inconsistent and the server is unable to select the appropriate 5592 representation, then no harm will result when the precondition 5593 evaluates to false. 5595 13.1. Preconditions 5597 The request header fields below allow a client to place a 5598 precondition on the state of the target resource, so that the action 5599 corresponding to the method semantics will not be applied if the 5600 precondition evaluates to false. Each precondition defined by this 5601 specification consists of a comparison between a set of validators 5602 obtained from prior representations of the target resource to the 5603 current state of validators for the selected representation 5604 (Section 8.9). Hence, these preconditions evaluate whether the state 5605 of the target resource has changed since a given state known by the 5606 client. The effect of such an evaluation depends on the method 5607 semantics and choice of conditional, as defined in Section 13.2. 5609 13.1.1. If-Match 5611 The "If-Match" header field makes the request method conditional on 5612 the recipient origin server either having at least one current 5613 representation of the target resource, when the field value is "*", 5614 or having a current representation of the target resource that has an 5615 entity-tag matching a member of the list of entity-tags provided in 5616 the field value. 5618 An origin server MUST use the strong comparison function when 5619 comparing entity-tags for If-Match (Section 8.9.3.2), since the 5620 client intends this precondition to prevent the method from being 5621 applied if there have been any changes to the representation data. 5623 If-Match = "*" / #entity-tag 5625 Examples: 5627 If-Match: "xyzzy" 5628 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 5629 If-Match: * 5631 If-Match is most often used with state-changing methods (e.g., POST, 5632 PUT, DELETE) to prevent accidental overwrites when multiple user 5633 agents might be acting in parallel on the same resource (i.e., to 5634 prevent the "lost update" problem). It can also be used with any 5635 method to abort a request if the selected representation does not 5636 match one that the client has already stored (or partially stored) 5637 from a prior request. 5639 An origin server that receives an If-Match header field MUST evaluate 5640 the condition as per Section 13.2 prior to performing the method. 5642 To evaluate a received If-Match header field: 5644 1. If the field value is "*", the condition is true if the origin 5645 server has a current representation for the target resource. 5647 2. If the field value is a list of entity-tags, the condition is 5648 true if any of the listed tags match the entity-tag of the 5649 selected representation. 5651 3. Otherwise, the condition is false. 5653 An origin server MUST NOT perform the requested method if a received 5654 If-Match condition evaluates to false. Instead, the origin server 5655 MAY indicate that the conditional request failed by responding with a 5656 412 (Precondition Failed) status code. Alternatively, if the request 5657 is a state-changing operation that appears to have already been 5658 applied to the selected representation, the origin server MAY respond 5659 with a 2xx (Successful) status code (i.e., the change requested by 5660 the user agent has already succeeded, but the user agent might not be 5661 aware of it, perhaps because the prior response was lost or an 5662 equivalent change was made by some other user agent). 5664 Allowing an origin server to send a success response when a change 5665 request appears to have already been applied is more efficient for 5666 many authoring use cases, but comes with some risk if multiple user 5667 agents are making change requests that are very similar but not 5668 cooperative. For example, multiple user agents writing to a common 5669 resource as a semaphore (e.g., a non-atomic increment) are likely to 5670 collide and potentially lose important state transitions. For those 5671 kinds of resources, an origin server is better off being stringent in 5672 sending 412 for every failed precondition on an unsafe method. In 5673 other cases, excluding the ETag field from a success response might 5674 encourage the user agent to perform a GET as its next request to 5675 eliminate confusion about the resource's current state. 5677 The If-Match header field can be ignored by caches and intermediaries 5678 because it is not applicable to a stored response. 5680 Note that an If-Match header field with a list value containing "*" 5681 and other values (including other instances of "*") is unlikely to be 5682 interoperable. 5684 13.1.2. If-None-Match 5686 The "If-None-Match" header field makes the request method conditional 5687 on a recipient cache or origin server either not having any current 5688 representation of the target resource, when the field value is "*", 5689 or having a selected representation with an entity-tag that does not 5690 match any of those listed in the field value. 5692 A recipient MUST use the weak comparison function when comparing 5693 entity-tags for If-None-Match (Section 8.9.3.2), since weak entity- 5694 tags can be used for cache validation even if there have been changes 5695 to the representation data. 5697 If-None-Match = "*" / #entity-tag 5699 Examples: 5701 If-None-Match: "xyzzy" 5702 If-None-Match: W/"xyzzy" 5703 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 5704 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 5705 If-None-Match: * 5707 If-None-Match is primarily used in conditional GET requests to enable 5708 efficient updates of cached information with a minimum amount of 5709 transaction overhead. When a client desires to update one or more 5710 stored responses that have entity-tags, the client SHOULD generate an 5711 If-None-Match header field containing a list of those entity-tags 5712 when making a GET request; this allows recipient servers to send a 5713 304 (Not Modified) response to indicate when one of those stored 5714 responses matches the selected representation. 5716 If-None-Match can also be used with a value of "*" to prevent an 5717 unsafe request method (e.g., PUT) from inadvertently modifying an 5718 existing representation of the target resource when the client 5719 believes that the resource does not have a current representation 5720 (Section 9.2.1). This is a variation on the "lost update" problem 5721 that might arise if more than one client attempts to create an 5722 initial representation for the target resource. 5724 An origin server that receives an If-None-Match header field MUST 5725 evaluate the condition as per Section 13.2 prior to performing the 5726 method. 5728 To evaluate a received If-None-Match header field: 5730 1. If the field value is "*", the condition is false if the origin 5731 server has a current representation for the target resource. 5733 2. If the field value is a list of entity-tags, the condition is 5734 false if one of the listed tags matches the entity-tag of the 5735 selected representation. 5737 3. Otherwise, the condition is true. 5739 An origin server MUST NOT perform the requested method if the 5740 condition evaluates to false; instead, the origin server MUST respond 5741 with either a) the 304 (Not Modified) status code if the request 5742 method is GET or HEAD or b) the 412 (Precondition Failed) status code 5743 for all other request methods. 5745 Requirements on cache handling of a received If-None-Match header 5746 field are defined in Section 4.3.2 of [Caching]. 5748 Note that an If-None-Match header field with a list value containing 5749 "*" and other values (including other instances of "*") is unlikely 5750 to be interoperable. 5752 13.1.3. If-Modified-Since 5754 The "If-Modified-Since" header field makes a GET or HEAD request 5755 method conditional on the selected representation's modification date 5756 being more recent than the date provided in the field value. 5757 Transfer of the selected representation's data is avoided if that 5758 data has not changed. 5760 If-Modified-Since = HTTP-date 5762 An example of the field is: 5764 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 5766 A recipient MUST ignore If-Modified-Since if the request contains an 5767 If-None-Match header field; the condition in If-None-Match is 5768 considered to be a more accurate replacement for the condition in If- 5769 Modified-Since, and the two are only combined for the sake of 5770 interoperating with older intermediaries that might not implement 5771 If-None-Match. 5773 A recipient MUST ignore the If-Modified-Since header field if the 5774 received field value is not a valid HTTP-date, the field value has 5775 more than one member, or if the request method is neither GET nor 5776 HEAD. 5778 A recipient MUST interpret an If-Modified-Since field value's 5779 timestamp in terms of the origin server's clock. 5781 If-Modified-Since is typically used for two distinct purposes: 1) to 5782 allow efficient updates of a cached representation that does not have 5783 an entity-tag and 2) to limit the scope of a web traversal to 5784 resources that have recently changed. 5786 When used for cache updates, a cache will typically use the value of 5787 the cached message's Last-Modified header field to generate the field 5788 value of If-Modified-Since. This behavior is most interoperable for 5789 cases where clocks are poorly synchronized or when the server has 5790 chosen to only honor exact timestamp matches (due to a problem with 5791 Last-Modified dates that appear to go "back in time" when the origin 5792 server's clock is corrected or a representation is restored from an 5793 archived backup). However, caches occasionally generate the field 5794 value based on other data, such as the Date header field of the 5795 cached message or the local clock time that the message was received, 5796 particularly when the cached message does not contain a Last-Modified 5797 header field. 5799 When used for limiting the scope of retrieval to a recent time 5800 window, a user agent will generate an If-Modified-Since field value 5801 based on either its own local clock or a Date header field received 5802 from the server in a prior response. Origin servers that choose an 5803 exact timestamp match based on the selected representation's 5804 Last-Modified header field will not be able to help the user agent 5805 limit its data transfers to only those changed during the specified 5806 window. 5808 An origin server that receives an If-Modified-Since header field 5809 SHOULD evaluate the condition as per Section 13.2 prior to performing 5810 the method. The origin server SHOULD NOT perform the requested 5811 method if the selected representation's last modification date is 5812 earlier than or equal to the date provided in the field value; 5813 instead, the origin server SHOULD generate a 304 (Not Modified) 5814 response, including only those metadata that are useful for 5815 identifying or updating a previously cached response. 5817 Requirements on cache handling of a received If-Modified-Since header 5818 field are defined in Section 4.3.2 of [Caching]. 5820 13.1.4. If-Unmodified-Since 5822 The "If-Unmodified-Since" header field makes the request method 5823 conditional on the selected representation's last modification date 5824 being earlier than or equal to the date provided in the field value. 5825 This field accomplishes the same purpose as If-Match for cases where 5826 the user agent does not have an entity-tag for the representation. 5828 If-Unmodified-Since = HTTP-date 5830 An example of the field is: 5832 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 5834 A recipient MUST ignore If-Unmodified-Since if the request contains 5835 an If-Match header field; the condition in If-Match is considered to 5836 be a more accurate replacement for the condition in If-Unmodified- 5837 Since, and the two are only combined for the sake of interoperating 5838 with older intermediaries that might not implement If-Match. 5840 A recipient MUST ignore the If-Unmodified-Since header field if the 5841 received field value is not a valid HTTP-date (including when the 5842 field value appears to be a list of dates). 5844 A recipient MUST interpret an If-Unmodified-Since field value's 5845 timestamp in terms of the origin server's clock. 5847 If-Unmodified-Since is most often used with state-changing methods 5848 (e.g., POST, PUT, DELETE) to prevent accidental overwrites when 5849 multiple user agents might be acting in parallel on a resource that 5850 does not supply entity-tags with its representations (i.e., to 5851 prevent the "lost update" problem). It can also be used with any 5852 method to abort a request if the selected representation does not 5853 match one that the client already stored (or partially stored) from a 5854 prior request. 5856 An origin server that receives an If-Unmodified-Since header field 5857 MUST evaluate the condition as per Section 13.2 prior to performing 5858 the method. 5860 If the selected representation has a last modification date, the 5861 origin server MUST NOT perform the requested method if that date is 5862 more recent than the date provided in the field value. Instead, the 5863 origin server MAY indicate that the conditional request failed by 5864 responding with a 412 (Precondition Failed) status code. 5865 Alternatively, if the request is a state-changing operation that 5866 appears to have already been applied to the selected representation, 5867 the origin server MAY respond with a 2xx (Successful) status code 5868 (i.e., the change requested by the user agent has already succeeded, 5869 but the user agent might not be aware of it, perhaps because the 5870 prior response was lost or an equivalent change was made by some 5871 other user agent). 5873 Allowing an origin server to send a success response when a change 5874 request appears to have already been applied is more efficient for 5875 many authoring use cases, but comes with some risk if multiple user 5876 agents are making change requests that are very similar but not 5877 cooperative. In those cases, an origin server is better off being 5878 stringent in sending 412 for every failed precondition on an unsafe 5879 method. 5881 The If-Unmodified-Since header field can be ignored by caches and 5882 intermediaries because it is not applicable to a stored response. 5884 13.1.5. If-Range 5886 The "If-Range" header field provides a special conditional request 5887 mechanism that is similar to the If-Match and If-Unmodified-Since 5888 header fields but that instructs the recipient to ignore the Range 5889 header field if the validator doesn't match, resulting in transfer of 5890 the new selected representation instead of a 412 (Precondition 5891 Failed) response. 5893 If a client has a partial copy of a representation and wishes to have 5894 an up-to-date copy of the entire representation, it could use the 5895 Range header field with a conditional GET (using either or both of 5896 If-Unmodified-Since and If-Match.) However, if the precondition 5897 fails because the representation has been modified, the client would 5898 then have to make a second request to obtain the entire current 5899 representation. 5901 The "If-Range" header field allows a client to "short-circuit" the 5902 second request. Informally, its meaning is as follows: if the 5903 representation is unchanged, send me the part(s) that I am requesting 5904 in Range; otherwise, send me the entire representation. 5906 If-Range = entity-tag / HTTP-date 5908 A client MUST NOT generate an If-Range header field in a request that 5909 does not contain a Range header field. A server MUST ignore an If- 5910 Range header field received in a request that does not contain a 5911 Range header field. An origin server MUST ignore an If-Range header 5912 field received in a request for a target resource that does not 5913 support Range requests. 5915 A client MUST NOT generate an If-Range header field containing an 5916 entity-tag that is marked as weak. A client MUST NOT generate an If- 5917 Range header field containing an HTTP-date unless the client has no 5918 entity-tag for the corresponding representation and the date is a 5919 strong validator in the sense defined by Section 8.9.2.2. 5921 A server that evaluates an If-Range precondition MUST use the strong 5922 comparison function when comparing entity-tags (Section 8.9.3.2) and 5923 MUST evaluate the condition as false if an HTTP-date validator is 5924 provided that is not a strong validator in the sense defined by 5925 Section 8.9.2.2. A valid entity-tag can be distinguished from a 5926 valid HTTP-date by examining the first three characters for a DQUOTE. 5928 If the validator given in the If-Range header field matches the 5929 current validator for the selected representation of the target 5930 resource, then the server SHOULD process the Range header field as 5931 requested. If the validator does not match, the server MUST ignore 5932 the Range header field. Note that this comparison by exact match, 5933 including when the validator is an HTTP-date, differs from the 5934 "earlier than or equal to" comparison used when evaluating an 5935 If-Unmodified-Since conditional. 5937 13.2. Evaluation of Preconditions 5939 Except when excluded below, a recipient cache or origin server MUST 5940 evaluate received request preconditions after it has successfully 5941 performed its normal request checks and just before it would process 5942 the request payload (if any) or perform the action associated with 5943 the request method. A server MUST ignore all received preconditions 5944 if its response to the same request without those conditions, prior 5945 to processing the request payload, would have been a status code 5946 other than a 2xx (Successful) or 412 (Precondition Failed). In other 5947 words, redirects and failures that can be detected before significant 5948 processing occurs take precedence over the evaluation of 5949 preconditions. 5951 A server that is not the origin server for the target resource and 5952 cannot act as a cache for requests on the target resource MUST NOT 5953 evaluate the conditional request header fields defined by this 5954 specification, and it MUST forward them if the request is forwarded, 5955 since the generating client intends that they be evaluated by a 5956 server that can provide a current representation. Likewise, a server 5957 MUST ignore the conditional request header fields defined by this 5958 specification when received with a request method that does not 5959 involve the selection or modification of a selected representation, 5960 such as CONNECT, OPTIONS, or TRACE. 5962 Note that protocol extensions can modify the conditions under which 5963 revalidation is triggered. For example, the "immutable" cache 5964 directive (defined by [RFC8246]) instructs caches to forgo 5965 revalidation of fresh responses even when requested by the client. 5967 Conditional request header fields that are defined by extensions to 5968 HTTP might place conditions on all recipients, on the state of the 5969 target resource in general, or on a group of resources. For 5970 instance, the "If" header field in WebDAV can make a request 5971 conditional on various aspects of multiple resources, such as locks, 5972 if the recipient understands and implements that field ([RFC4918], 5973 Section 10.4). 5975 Although conditional request header fields are defined as being 5976 usable with the HEAD method (to keep HEAD's semantics consistent with 5977 those of GET), there is no point in sending a conditional HEAD 5978 because a successful response is around the same size as a 304 (Not 5979 Modified) response and more useful than a 412 (Precondition Failed) 5980 response. 5982 13.3. Precedence of Preconditions 5984 When more than one conditional request header field is present in a 5985 request, the order in which the fields are evaluated becomes 5986 important. In practice, the fields defined in this document are 5987 consistently implemented in a single, logical order, since "lost 5988 update" preconditions have more strict requirements than cache 5989 validation, a validated cache is more efficient than a partial 5990 response, and entity tags are presumed to be more accurate than date 5991 validators. 5993 A recipient cache or origin server MUST evaluate the request 5994 preconditions defined by this specification in the following order: 5996 1. When recipient is the origin server and If-Match is present, 5997 evaluate the If-Match precondition: 5999 o if true, continue to step 3 6001 o if false, respond 412 (Precondition Failed) unless it can be 6002 determined that the state-changing request has already 6003 succeeded (see Section 13.1.1) 6005 2. When recipient is the origin server, If-Match is not present, and 6006 If-Unmodified-Since is present, evaluate the If-Unmodified-Since 6007 precondition: 6009 o if true, continue to step 3 6011 o if false, respond 412 (Precondition Failed) unless it can be 6012 determined that the state-changing request has already 6013 succeeded (see Section 13.1.4) 6015 3. When If-None-Match is present, evaluate the If-None-Match 6016 precondition: 6018 o if true, continue to step 5 6020 o if false for GET/HEAD, respond 304 (Not Modified) 6022 o if false for other methods, respond 412 (Precondition Failed) 6024 4. When the method is GET or HEAD, If-None-Match is not present, and 6025 If-Modified-Since is present, evaluate the If-Modified-Since 6026 precondition: 6028 o if true, continue to step 5 6029 o if false, respond 304 (Not Modified) 6031 5. When the method is GET and both Range and If-Range are present, 6032 evaluate the If-Range precondition: 6034 o if the validator matches and the Range specification is 6035 applicable to the selected representation, respond 206 6036 (Partial Content) 6038 6. Otherwise, 6040 o all conditions are met, so perform the requested action and 6041 respond according to its success or failure. 6043 Any extension to HTTP that defines additional conditional request 6044 header fields ought to define its own expectations regarding the 6045 order for evaluating such fields in relation to those defined in this 6046 document and other conditionals that might be found in practice. 6048 14. Range Requests 6050 Clients often encounter interrupted data transfers as a result of 6051 canceled requests or dropped connections. When a client has stored a 6052 partial representation, it is desirable to request the remainder of 6053 that representation in a subsequent request rather than transfer the 6054 entire representation. Likewise, devices with limited local storage 6055 might benefit from being able to request only a subset of a larger 6056 representation, such as a single page of a very large document, or 6057 the dimensions of an embedded image. 6059 Range requests are an OPTIONAL feature of HTTP, designed so that 6060 recipients not implementing this feature (or not supporting it for 6061 the target resource) can respond as if it is a normal GET request 6062 without impacting interoperability. Partial responses are indicated 6063 by a distinct status code to not be mistaken for full responses by 6064 caches that might not implement the feature. 6066 14.1. Range Units 6068 Representation data can be partitioned into subranges when there are 6069 addressable structural units inherent to that data's content coding 6070 or media type. For example, octet (a.k.a., byte) boundaries are a 6071 structural unit common to all representation data, allowing 6072 partitions of the data to be identified as a range of bytes at some 6073 offset from the start or end of that data. 6075 This general notion of a "_range unit_" is used in the Accept-Ranges 6076 (Section 14.3) response header field to advertise support for range 6077 requests, the Range (Section 14.2) request header field to delineate 6078 the parts of a representation that are requested, and the 6079 Content-Range (Section 14.4) payload header field to describe which 6080 part of a representation is being transferred. 6082 range-unit = token 6084 All range unit names are case-insensitive and ought to be registered 6085 within the "HTTP Range Unit Registry", as defined in Section 16.5.1 6087 Range units are intended to be extensible, as described in 6088 Section 16.5. 6090 14.1.1. Range Specifiers 6092 Ranges are expressed in terms of a range unit paired with a set of 6093 range specifiers. The range unit name determines what kinds of 6094 range-spec are applicable to its own specifiers. Hence, the 6095 following gramar is generic: each range unit is expected to specify 6096 requirements on when int-range, suffix-range, and other-range are 6097 allowed. 6099 A range request can specify a single range or a set of ranges within 6100 a single representation. 6102 ranges-specifier = range-unit "=" range-set 6103 range-set = 1#range-spec 6104 range-spec = int-range 6105 / suffix-range 6106 / other-range 6108 An int-range is a range expressed as two non-negative integers or as 6109 one non-negative integer through to the end of the representation 6110 data. The range unit specifies what the integers mean (e.g., they 6111 might indicate unit offsets from the beginning, inclusive numbered 6112 parts, etc.). 6114 int-range = first-pos "-" [ last-pos ] 6115 first-pos = 1*DIGIT 6116 last-pos = 1*DIGIT 6118 An int-range is invalid if the last-pos value is present and less 6119 than the first-pos. 6121 A suffix-range is a range expressed as a suffix of the representation 6122 data with the provided non-negative integer maximum length (in range 6123 units). In other words, the last N units of the representation data. 6125 suffix-range = "-" suffix-length 6126 suffix-length = 1*DIGIT 6128 To provide for extensibility, the other-range rule is a mostly 6129 unconstrained grammar that allows application-specific or future 6130 range units to define additional range specifiers. 6132 other-range = 1*( %x21-2B / %x2D-7E ) 6133 ; 1*(VCHAR excluding comma) 6135 14.1.2. Byte Ranges 6137 The "bytes" range unit is used to express subranges of a 6138 representation data's octet sequence. Each byte range is expressed 6139 as an integer range at some offset, relative to either the beginning 6140 (int-range) or end (suffix-range) of the representation data. Byte 6141 ranges do not use the other-range specifier. 6143 The first-pos value in a bytes int-range gives the offset of the 6144 first byte in a range. The last-pos value gives the offset of the 6145 last byte in the range; that is, the byte positions specified are 6146 inclusive. Byte offsets start at zero. 6148 If the representation data has a content coding applied, each byte 6149 range is calculated with respect to the encoded sequence of bytes, 6150 not the sequence of underlying bytes that would be obtained after 6151 decoding. 6153 Examples of bytes range specifiers: 6155 o The first 500 bytes (byte offsets 0-499, inclusive): 6157 bytes=0-499 6159 o The second 500 bytes (byte offsets 500-999, inclusive): 6161 bytes=500-999 6163 A client can limit the number of bytes requested without knowing the 6164 size of the selected representation. If the last-pos value is 6165 absent, or if the value is greater than or equal to the current 6166 length of the representation data, the byte range is interpreted as 6167 the remainder of the representation (i.e., the server replaces the 6168 value of last-pos with a value that is one less than the current 6169 length of the selected representation). 6171 A client can request the last N bytes (N > 0) of the selected 6172 representation using a suffix-range. If the selected representation 6173 is shorter than the specified suffix-length, the entire 6174 representation is used. 6176 Additional examples, assuming a representation of length 10000: 6178 o The final 500 bytes (byte offsets 9500-9999, inclusive): 6180 bytes=-500 6182 Or: 6184 bytes=9500- 6186 o The first and last bytes only (bytes 0 and 9999): 6188 bytes=0-0,-1 6190 o The first, middle, and last 1000 bytes: 6192 bytes= 0-999, 4500-5499, -1000 6194 o Other valid (but not canonical) specifications of the second 500 6195 bytes (byte offsets 500-999, inclusive): 6197 bytes=500-600,601-999 6198 bytes=500-700,601-999 6200 If a valid bytes range-set includes at least one range-spec with a 6201 first-pos that is less than the current length of the representation, 6202 or at least one suffix-range with a non-zero suffix-length, then the 6203 bytes range-set is satisfiable. Otherwise, the bytes range-set is 6204 unsatisfiable. 6206 If the selected representation has zero length, the only satisfiable 6207 form of range-spec is a suffix-range with a non-zero suffix-length. 6209 In the byte-range syntax, first-pos, last-pos, and suffix-length are 6210 expressed as decimal number of octets. Since there is no predefined 6211 limit to the length of a payload, recipients MUST anticipate 6212 potentially large decimal numerals and prevent parsing errors due to 6213 integer conversion overflows. 6215 14.2. Range 6217 The "Range" header field on a GET request modifies the method 6218 semantics to request transfer of only one or more subranges of the 6219 selected representation data (Section 8.2), rather than the entire 6220 selected representation. 6222 Range = ranges-specifier 6224 A server MAY ignore the Range header field. However, origin servers 6225 and intermediate caches ought to support byte ranges when possible, 6226 since they support efficient recovery from partially failed transfers 6227 and partial retrieval of large representations. 6229 A server MUST ignore a Range header field received with a request 6230 method which is unrecognized or for which range handling is not 6231 defined. For this specification, GET is the only method for which 6232 range handling is defined. 6234 An origin server MUST ignore a Range header field that contains a 6235 range unit it does not understand. A proxy MAY discard a Range 6236 header field that contains a range unit it does not understand. 6238 A server that supports range requests MAY ignore or reject a Range 6239 header field that consists of more than two overlapping ranges, or a 6240 set of many small ranges that are not listed in ascending order, 6241 since both are indications of either a broken client or a deliberate 6242 denial-of-service attack (Section 17.14). A client SHOULD NOT 6243 request multiple ranges that are inherently less efficient to process 6244 and transfer than a single range that encompasses the same data. 6246 A server that supports range requests MAY ignore a Range header field 6247 when the selected representation has no payload data (i.e., the 6248 selected representation's data is of zero length). 6250 A client that is requesting multiple ranges SHOULD list those ranges 6251 in ascending order (the order in which they would typically be 6252 received in a complete representation) unless there is a specific 6253 need to request a later part earlier. For example, a user agent 6254 processing a large representation with an internal catalog of parts 6255 might need to request later parts first, particularly if the 6256 representation consists of pages stored in reverse order and the user 6257 agent wishes to transfer one page at a time. 6259 The Range header field is evaluated after evaluating the precondition 6260 header fields defined in Section 13.1, and only if the result in 6261 absence of the Range header field would be a 200 (OK) response. In 6262 other words, Range is ignored when a conditional GET would result in 6263 a 304 (Not Modified) response. 6265 The If-Range header field (Section 13.1.5) can be used as a 6266 precondition to applying the Range header field. 6268 If all of the preconditions are true, the server supports the Range 6269 header field for the target resource, and the specified range(s) are 6270 valid and satisfiable (as defined in Section 14.1.2), the server 6271 SHOULD send a 206 (Partial Content) response with a payload 6272 containing one or more partial representations that correspond to the 6273 satisfiable ranges requested. 6275 The above does not imply that a server will send all requested 6276 ranges. In some cases, it may only be possible (or efficient) to 6277 send a portion of the requested ranges first, while expecting the 6278 client to re-request the remaining portions later if they are still 6279 desired (see Section 15.3.7). 6281 If all of the preconditions are true, the server supports the Range 6282 header field for the target resource, and the specified range(s) are 6283 invalid or unsatisfiable, the server SHOULD send a 416 (Range Not 6284 Satisfiable) response. 6286 14.3. Accept-Ranges 6288 The "Accept-Ranges" header field allows a server to indicate that it 6289 supports range requests for the target resource. 6291 Accept-Ranges = acceptable-ranges 6292 acceptable-ranges = 1#range-unit / "none" 6294 An origin server that supports byte-range requests for a given target 6295 resource MAY send 6297 Accept-Ranges: bytes 6299 to indicate what range units are supported. A client MAY generate 6300 range requests without having received this header field for the 6301 resource involved. Range units are defined in Section 14.1. 6303 A server that does not support any kind of range request for the 6304 target resource MAY send 6306 Accept-Ranges: none 6308 to advise the client not to attempt a range request. 6310 14.4. Content-Range 6312 The "Content-Range" header field is sent in a single part 206 6313 (Partial Content) response to indicate the partial range of the 6314 selected representation enclosed as the message payload, sent in each 6315 part of a multipart 206 response to indicate the range enclosed 6316 within each body part, and sent in 416 (Range Not Satisfiable) 6317 responses to provide information about the selected representation. 6319 Content-Range = range-unit SP 6320 ( range-resp / unsatisfied-range ) 6322 range-resp = incl-range "/" ( complete-length / "*" ) 6323 incl-range = first-pos "-" last-pos 6324 unsatisfied-range = "*/" complete-length 6326 complete-length = 1*DIGIT 6328 If a 206 (Partial Content) response contains a Content-Range header 6329 field with a range unit (Section 14.1) that the recipient does not 6330 understand, the recipient MUST NOT attempt to recombine it with a 6331 stored representation. A proxy that receives such a message SHOULD 6332 forward it downstream. 6334 For byte ranges, a sender SHOULD indicate the complete length of the 6335 representation from which the range has been extracted, unless the 6336 complete length is unknown or difficult to determine. An asterisk 6337 character ("*") in place of the complete-length indicates that the 6338 representation length was unknown when the header field was 6339 generated. 6341 The following example illustrates when the complete length of the 6342 selected representation is known by the sender to be 1234 bytes: 6344 Content-Range: bytes 42-1233/1234 6346 and this second example illustrates when the complete length is 6347 unknown: 6349 Content-Range: bytes 42-1233/* 6351 A Content-Range field value is invalid if it contains a range-resp 6352 that has a last-pos value less than its first-pos value, or a 6353 complete-length value less than or equal to its last-pos value. The 6354 recipient of an invalid Content-Range MUST NOT attempt to recombine 6355 the received content with a stored representation. 6357 A server generating a 416 (Range Not Satisfiable) response to a byte- 6358 range request SHOULD send a Content-Range header field with an 6359 unsatisfied-range value, as in the following example: 6361 Content-Range: bytes */1234 6363 The complete-length in a 416 response indicates the current length of 6364 the selected representation. 6366 The Content-Range header field has no meaning for status codes that 6367 do not explicitly describe its semantic. For this specification, 6368 only the 206 (Partial Content) and 416 (Range Not Satisfiable) status 6369 codes describe a meaning for Content-Range. 6371 The following are examples of Content-Range values in which the 6372 selected representation contains a total of 1234 bytes: 6374 o The first 500 bytes: 6376 Content-Range: bytes 0-499/1234 6378 o The second 500 bytes: 6380 Content-Range: bytes 500-999/1234 6382 o All except for the first 500 bytes: 6384 Content-Range: bytes 500-1233/1234 6386 o The last 500 bytes: 6388 Content-Range: bytes 734-1233/1234 6390 14.5. Media Type multipart/byteranges 6392 When a 206 (Partial Content) response message includes the content of 6393 multiple ranges, they are transmitted as body parts in a multipart 6394 message body ([RFC2046], Section 5.1) with the media type of 6395 "multipart/byteranges". 6397 The multipart/byteranges media type includes one or more body parts, 6398 each with its own Content-Type and Content-Range fields. The 6399 required boundary parameter specifies the boundary string used to 6400 separate each body part. 6402 Implementation Notes: 6404 1. Additional CRLFs might precede the first boundary string in the 6405 body. 6407 2. Although [RFC2046] permits the boundary string to be quoted, some 6408 existing implementations handle a quoted boundary string 6409 incorrectly. 6411 3. A number of clients and servers were coded to an early draft of 6412 the byteranges specification that used a media type of multipart/ 6413 x-byteranges , which is almost (but not quite) compatible with 6414 this type. 6416 Despite the name, the "multipart/byteranges" media type is not 6417 limited to byte ranges. The following example uses an "exampleunit" 6418 range unit: 6420 HTTP/1.1 206 Partial Content 6421 Date: Tue, 14 Nov 1995 06:25:24 GMT 6422 Last-Modified: Tue, 14 July 04:58:08 GMT 6423 Content-Length: 2331785 6424 Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 6426 --THIS_STRING_SEPARATES 6427 Content-Type: video/example 6428 Content-Range: exampleunit 1.2-4.3/25 6430 ...the first range... 6431 --THIS_STRING_SEPARATES 6432 Content-Type: video/example 6433 Content-Range: exampleunit 11.2-14.3/25 6435 ...the second range 6436 --THIS_STRING_SEPARATES-- 6438 The following information serves as the registration form for the 6439 multipart/byteranges media type. 6441 Type name: multipart 6443 Subtype name: byteranges 6445 Required parameters: boundary 6447 Optional parameters: N/A 6449 Encoding considerations: only "7bit", "8bit", or "binary" are 6450 permitted 6452 Security considerations: see Section 17 6454 Interoperability considerations: N/A 6456 Published specification: This specification (see Section 14.5). 6458 Applications that use this media type: HTTP components supporting 6459 multiple ranges in a single request. 6461 Fragment identifier considerations: N/A 6463 Additional information: Deprecated alias names for this type: N/A 6465 Magic number(s): N/A 6467 File extension(s): N/A 6469 Macintosh file type code(s): N/A 6471 Person and email address to contact for further information: See Aut 6472 hors' Addresses section. 6474 Intended usage: COMMON 6476 Restrictions on usage: N/A 6478 Author: See Authors' Addresses section. 6480 Change controller: IESG 6482 15. Status Codes 6484 The (response) status code is a three-digit integer code giving the 6485 result of the attempt to understand and satisfy the request. 6487 HTTP status codes are extensible. HTTP clients are not required to 6488 understand the meaning of all registered status codes, though such 6489 understanding is obviously desirable. However, a client MUST 6490 understand the class of any status code, as indicated by the first 6491 digit, and treat an unrecognized status code as being equivalent to 6492 the x00 status code of that class. 6494 For example, if an unrecognized status code of 471 is received by a 6495 client, the client can assume that there was something wrong with its 6496 request and treat the response as if it had received a 400 (Bad 6497 Request) status code. The response message will usually contain a 6498 representation that explains the status. 6500 The first digit of the status code defines the class of response. 6501 The last two digits do not have any categorization role. There are 6502 five values for the first digit: 6504 o 1xx (Informational): The request was received, continuing process 6506 o 2xx (Successful): The request was successfully received, 6507 understood, and accepted 6509 o 3xx (Redirection): Further action needs to be taken in order to 6510 complete the request 6512 o 4xx (Client Error): The request contains bad syntax or cannot be 6513 fulfilled 6515 o 5xx (Server Error): The server failed to fulfill an apparently 6516 valid request 6518 A single request can have multiple associated responses: zero or more 6519 _interim_ (non-final) responses with status codes in the 6520 "informational" (1xx) range, followed by exactly one _final_ response 6521 with a status code in one of the other ranges. 6523 15.1. Overview of Status Codes 6525 The status codes listed below are defined in this specification. The 6526 reason phrases listed here are only recommendations - they can be 6527 replaced by local equivalents or left out altogether without 6528 affecting the protocol. 6530 Responses with status codes that are defined as heuristically 6531 cacheable (e.g., 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 6532 414, and 501 in this specification) can be reused by a cache with 6533 heuristic expiration unless otherwise indicated by the method 6534 definition or explicit cache controls [Caching]; all other status 6535 codes are not heuristically cacheable. 6537 Additional status codes, outside the scope of this specification, 6538 have been specified for use in HTTP. All such status codes ought to 6539 be registered within the "Hypertext Transfer Protocol (HTTP) Status 6540 Code Registry", as described in Section 16.2. 6542 15.2. Informational 1xx 6544 The _1xx (Informational)_ class of status code indicates an interim 6545 response for communicating connection status or request progress 6546 prior to completing the requested action and sending a final 6547 response. Since HTTP/1.0 did not define any 1xx status codes, a 6548 server MUST NOT send a 1xx response to an HTTP/1.0 client. 6550 A 1xx response is terminated by the end of the header section; it 6551 cannot contain payload data or trailers. 6553 A client MUST be able to parse one or more 1xx responses received 6554 prior to a final response, even if the client does not expect one. A 6555 user agent MAY ignore unexpected 1xx responses. 6557 A proxy MUST forward 1xx responses unless the proxy itself requested 6558 the generation of the 1xx response. For example, if a proxy adds an 6559 "Expect: 100-continue" header field when it forwards a request, then 6560 it need not forward the corresponding 100 (Continue) response(s). 6562 15.2.1. 100 Continue 6564 The _100 (Continue)_ status code indicates that the initial part of a 6565 request has been received and has not yet been rejected by the 6566 server. The server intends to send a final response after the 6567 request has been fully received and acted upon. 6569 When the request contains an Expect header field that includes a 6570 100-continue expectation, the 100 response indicates that the server 6571 wishes to receive the request payload, as described in 6572 Section 10.1.1. The client ought to continue sending the request and 6573 discard the 100 response. 6575 If the request did not contain an Expect header field containing the 6576 100-continue expectation, the client can simply discard this interim 6577 response. 6579 15.2.2. 101 Switching Protocols 6581 The _101 (Switching Protocols)_ status code indicates that the server 6582 understands and is willing to comply with the client's request, via 6583 the Upgrade header field (Section 7.8), for a change in the 6584 application protocol being used on this connection. The server MUST 6585 generate an Upgrade header field in the response that indicates which 6586 protocol(s) will be switched to immediately after the empty line that 6587 terminates the 101 response. 6589 It is assumed that the server will only agree to switch protocols 6590 when it is advantageous to do so. For example, switching to a newer 6591 version of HTTP might be advantageous over older versions, and 6592 switching to a real-time, synchronous protocol might be advantageous 6593 when delivering resources that use such features. 6595 15.3. Successful 2xx 6597 The _2xx (Successful)_ class of status code indicates that the 6598 client's request was successfully received, understood, and accepted. 6600 15.3.1. 200 OK 6602 The _200 (OK)_ status code indicates that the request has succeeded. 6603 The payload sent in a 200 response depends on the request method. 6604 For the methods defined by this specification, the intended meaning 6605 of the payload can be summarized as: 6607 ---------------- -------------------------------------------- 6608 request method response payload is a representation of 6609 ---------------- -------------------------------------------- 6610 GET the target resource 6611 HEAD the target resource, like GET, but without 6612 transferring the representation data 6613 POST the status of, or results obtained from, 6614 the action 6615 PUT, DELETE the status of the action 6616 OPTIONS communication options for the target 6617 resource 6618 TRACE the request message as received by the 6619 server returning the trace 6620 ---------------- -------------------------------------------- 6622 Table 6 6624 Aside from responses to CONNECT, a 200 response always has a payload, 6625 though an origin server MAY generate payload data of zero length. If 6626 no payload is desired, an origin server ought to send _204 (No 6627 Content)_ instead. For CONNECT, no payload is allowed because the 6628 successful result is a tunnel, which begins immediately after the 200 6629 response header section. 6631 A 200 response is heuristically cacheable; i.e., unless otherwise 6632 indicated by the method definition or explicit cache controls (see 6633 Section 4.2.2 of [Caching]). 6635 15.3.2. 201 Created 6637 The _201 (Created)_ status code indicates that the request has been 6638 fulfilled and has resulted in one or more new resources being 6639 created. The primary resource created by the request is identified 6640 by either a Location header field in the response or, if no Location 6641 header field is received, by the target URI. 6643 The 201 response payload typically describes and links to the 6644 resource(s) created. See Section 8.9 for a discussion of the meaning 6645 and purpose of validator fields, such as ETag and Last-Modified, in a 6646 201 response. 6648 15.3.3. 202 Accepted 6650 The _202 (Accepted)_ status code indicates that the request has been 6651 accepted for processing, but the processing has not been completed. 6652 The request might or might not eventually be acted upon, as it might 6653 be disallowed when processing actually takes place. There is no 6654 facility in HTTP for re-sending a status code from an asynchronous 6655 operation. 6657 The 202 response is intentionally noncommittal. Its purpose is to 6658 allow a server to accept a request for some other process (perhaps a 6659 batch-oriented process that is only run once per day) without 6660 requiring that the user agent's connection to the server persist 6661 until the process is completed. The representation sent with this 6662 response ought to describe the request's current status and point to 6663 (or embed) a status monitor that can provide the user with an 6664 estimate of when the request will be fulfilled. 6666 15.3.4. 203 Non-Authoritative Information 6668 The _203 (Non-Authoritative Information)_ status code indicates that 6669 the request was successful but the enclosed payload has been modified 6670 from that of the origin server's 200 (OK) response by a transforming 6671 proxy (Section 7.7). This status code allows the proxy to notify 6672 recipients when a transformation has been applied, since that 6673 knowledge might impact later decisions regarding the content. For 6674 example, future cache validation requests for the content might only 6675 be applicable along the same request path (through the same proxies). 6677 A 203 response is heuristically cacheable; i.e., unless otherwise 6678 indicated by the method definition or explicit cache controls (see 6679 Section 4.2.2 of [Caching]). 6681 15.3.5. 204 No Content 6683 The _204 (No Content)_ status code indicates that the server has 6684 successfully fulfilled the request and that there is no additional 6685 content to send in the response payload data. Metadata in the 6686 response header fields refer to the target resource and its selected 6687 representation after the requested action was applied. 6689 For example, if a 204 status code is received in response to a PUT 6690 request and the response contains an ETag field, then the PUT was 6691 successful and the ETag field value contains the entity-tag for the 6692 new representation of that target resource. 6694 The 204 response allows a server to indicate that the action has been 6695 successfully applied to the target resource, while implying that the 6696 user agent does not need to traverse away from its current "document 6697 view" (if any). The server assumes that the user agent will provide 6698 some indication of the success to its user, in accord with its own 6699 interface, and apply any new or updated metadata in the response to 6700 its active representation. 6702 For example, a 204 status code is commonly used with document editing 6703 interfaces corresponding to a "save" action, such that the document 6704 being saved remains available to the user for editing. It is also 6705 frequently used with interfaces that expect automated data transfers 6706 to be prevalent, such as within distributed version control systems. 6708 A 204 response is terminated by the end of the header section; it 6709 cannot contain payload data or trailers. 6711 A 204 response is heuristically cacheable; i.e., unless otherwise 6712 indicated by the method definition or explicit cache controls (see 6713 Section 4.2.2 of [Caching]). 6715 15.3.6. 205 Reset Content 6717 The _205 (Reset Content)_ status code indicates that the server has 6718 fulfilled the request and desires that the user agent reset the 6719 "document view", which caused the request to be sent, to its original 6720 state as received from the origin server. 6722 This response is intended to support a common data entry use case 6723 where the user receives content that supports data entry (a form, 6724 notepad, canvas, etc.), enters or manipulates data in that space, 6725 causes the entered data to be submitted in a request, and then the 6726 data entry mechanism is reset for the next entry so that the user can 6727 easily initiate another input action. 6729 Since the 205 status code implies that no additional content will be 6730 provided, a server MUST NOT generate a payload in a 205 response. 6732 15.3.7. 206 Partial Content 6734 The _206 (Partial Content)_ status code indicates that the server is 6735 successfully fulfilling a range request for the target resource by 6736 transferring one or more parts of the selected representation. 6738 A server that supports range requests (Section 14) will usually 6739 attempt to satisfy all of the requested ranges, since sending less 6740 data will likely result in another client request for the remainder. 6741 However, a server might want to send only a subset of the data 6742 requested for reasons of its own, such as temporary unavailability, 6743 cache efficiency, load balancing, etc. Since a 206 response is self- 6744 descriptive, the client can still understand a response that only 6745 partially satisfies its range request. 6747 A client MUST inspect a 206 response's Content-Type and Content-Range 6748 field(s) to determine what parts are enclosed and whether additional 6749 requests are needed. 6751 When a 206 response is generated, the server MUST generate the 6752 following header fields, in addition to those required in the 6753 subsections below, if the field would have been sent in a 200 (OK) 6754 response to the same request: Date, Cache-Control, ETag, Expires, 6755 Content-Location, and Vary. 6757 A Content-Length header field present in a 206 response indicates the 6758 number of octets in the payload data of this message, which is 6759 usually not the complete length of the selected representation. Each 6760 Content-Range header field includes information about the selected 6761 representation's complete length. 6763 If a 206 is generated in response to a request with an If-Range 6764 header field, the sender SHOULD NOT generate other representation 6765 header fields beyond those required, because the client is understood 6766 to already have a prior response containing those header fields. 6767 Otherwise, the sender MUST generate all of the representation header 6768 fields that would have been sent in a 200 (OK) response to the same 6769 request. 6771 A 206 response is heuristically cacheable; i.e., unless otherwise 6772 indicated by explicit cache controls (see Section 4.2.2 of 6773 [Caching]). 6775 15.3.7.1. Single Part 6777 If a single part is being transferred, the server generating the 206 6778 response MUST generate a Content-Range header field, describing what 6779 range of the selected representation is enclosed, and a payload 6780 consisting of the range. For example: 6782 HTTP/1.1 206 Partial Content 6783 Date: Wed, 15 Nov 1995 06:25:24 GMT 6784 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 6785 Content-Range: bytes 21010-47021/47022 6786 Content-Length: 26012 6787 Content-Type: image/gif 6789 ... 26012 bytes of partial image data ... 6791 15.3.7.2. Multiple Parts 6793 If multiple parts are being transferred, the server generating the 6794 206 response MUST generate a "multipart/byteranges" payload, as 6795 defined in Section 14.5, and a Content-Type header field containing 6796 the multipart/byteranges media type and its required boundary 6797 parameter. To avoid confusion with single-part responses, a server 6798 MUST NOT generate a Content-Range header field in the HTTP header 6799 section of a multiple part response (this field will be sent in each 6800 part instead). 6802 Within the header area of each body part in the multipart payload, 6803 the server MUST generate a Content-Range header field corresponding 6804 to the range being enclosed in that body part. If the selected 6805 representation would have had a Content-Type header field in a 200 6806 (OK) response, the server SHOULD generate that same Content-Type 6807 header field in the header area of each body part. For example: 6809 HTTP/1.1 206 Partial Content 6810 Date: Wed, 15 Nov 1995 06:25:24 GMT 6811 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 6812 Content-Length: 1741 6813 Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 6815 --THIS_STRING_SEPARATES 6816 Content-Type: application/pdf 6817 Content-Range: bytes 500-999/8000 6819 ...the first range... 6820 --THIS_STRING_SEPARATES 6821 Content-Type: application/pdf 6822 Content-Range: bytes 7000-7999/8000 6824 ...the second range 6825 --THIS_STRING_SEPARATES-- 6827 When multiple ranges are requested, a server MAY coalesce any of the 6828 ranges that overlap, or that are separated by a gap that is smaller 6829 than the overhead of sending multiple parts, regardless of the order 6830 in which the corresponding range-spec appeared in the received Range 6831 header field. Since the typical overhead between parts of a 6832 multipart/byteranges payload is around 80 bytes, depending on the 6833 selected representation's media type and the chosen boundary 6834 parameter length, it can be less efficient to transfer many small 6835 disjoint parts than it is to transfer the entire selected 6836 representation. 6838 A server MUST NOT generate a multipart response to a request for a 6839 single range, since a client that does not request multiple parts 6840 might not support multipart responses. However, a server MAY 6841 generate a multipart/byteranges payload with only a single body part 6842 if multiple ranges were requested and only one range was found to be 6843 satisfiable or only one range remained after coalescing. A client 6844 that cannot process a multipart/byteranges response MUST NOT generate 6845 a request that asks for multiple ranges. 6847 When a multipart response payload is generated, the server SHOULD 6848 send the parts in the same order that the corresponding range-spec 6849 appeared in the received Range header field, excluding those ranges 6850 that were deemed unsatisfiable or that were coalesced into other 6851 ranges. A client that receives a multipart response MUST inspect the 6852 Content-Range header field present in each body part in order to 6853 determine which range is contained in that body part; a client cannot 6854 rely on receiving the same ranges that it requested, nor the same 6855 order that it requested. 6857 15.3.7.3. Combining Parts 6859 A response might transfer only a subrange of a representation if the 6860 connection closed prematurely or if the request used one or more 6861 Range specifications. After several such transfers, a client might 6862 have received several ranges of the same representation. These 6863 ranges can only be safely combined if they all have in common the 6864 same strong validator (Section 8.9.1). 6866 A client that has received multiple partial responses to GET requests 6867 on a target resource MAY combine those responses into a larger 6868 continuous range if they share the same strong validator. 6870 If the most recent response is an incomplete 200 (OK) response, then 6871 the header fields of that response are used for any combined response 6872 and replace those of the matching stored responses. 6874 If the most recent response is a 206 (Partial Content) response and 6875 at least one of the matching stored responses is a 200 (OK), then the 6876 combined response header fields consist of the most recent 200 6877 response's header fields. If all of the matching stored responses 6878 are 206 responses, then the stored response with the most recent 6879 header fields is used as the source of header fields for the combined 6880 response, except that the client MUST use other header fields 6881 provided in the new response, aside from Content-Range, to replace 6882 all instances of the corresponding header fields in the stored 6883 response. 6885 The combined response payload data consists of the union of partial 6886 content ranges in the new response and each of the selected 6887 responses. If the union consists of the entire range of the 6888 representation, then the client MUST process the combined response as 6889 if it were a complete 200 (OK) response, including a Content-Length 6890 header field that reflects the complete length. Otherwise, the 6891 client MUST process the set of continuous ranges as one of the 6892 following: an incomplete 200 (OK) response if the combined response 6893 is a prefix of the representation, a single 206 (Partial Content) 6894 response containing a multipart/byteranges payload, or multiple 206 6895 (Partial Content) responses, each with one continuous range that is 6896 indicated by a Content-Range header field. 6898 15.4. Redirection 3xx 6900 The _3xx (Redirection)_ class of status code indicates that further 6901 action needs to be taken by the user agent in order to fulfill the 6902 request. There are several types of redirects: 6904 1. Redirects that indicate this resource might be available at a 6905 different URI, as provided by the Location header field, as in 6906 the status codes 301 (Moved Permanently), 302 (Found), 307 6907 (Temporary Redirect), and 308 (Permanent Redirect). 6909 2. Redirection that offers a choice among matching resources capable 6910 of representing this resource, as in the 300 (Multiple Choices) 6911 status code. 6913 3. Redirection to a different resource, identified by the Location 6914 header field, that can represent an indirect response to the 6915 request, as in the 303 (See Other) status code. 6917 4. Redirection to a previously stored result, as in the 304 (Not 6918 Modified) status code. 6920 If a Location header field (Section 10.2.3) is provided, the user 6921 agent MAY automatically redirect its request to the URI referenced by 6922 the Location field value, even if the specific status code is not 6923 understood. Automatic redirection needs to be done with care for 6924 methods not known to be safe, as defined in Section 9.2.1, since the 6925 user might not wish to redirect an unsafe request. 6927 When automatically following a redirected request, the user agent 6928 SHOULD resend the original request message with the following 6929 modifications: 6931 1. Replace the target URI with the URI referenced by the redirection 6932 response's Location header field value after resolving it 6933 relative to the original request's target URI. 6935 2. Remove header fields that were automatically generated by the 6936 implementation, replacing them with updated values as appropriate 6937 to the new request. This includes: 6939 1. Connection-specific header fields (see Section 7.6.1), 6941 2. Header fields specific to the client's proxy configuration, 6942 including (but not limited to) Proxy-Authorization, 6944 3. Origin-specific header fields (if any), including (but not 6945 limited to) Host, 6947 4. Validating header fields that were added by the 6948 implementation's cache (e.g., If-None-Match, 6949 If-Modified-Since), 6951 5. Resource-specific header fields, including (but not limited 6952 to) Referer, Origin, Authorization, and Cookie. 6954 3. Consider removing header fields that were not automatically 6955 generated by the implementation (i.e., those present in the 6956 request because they were added by the calling context) where 6957 there are security implications; this includes but is not limited 6958 to Authorization and Cookie. 6960 4. Change the request method according to the redirecting status 6961 code's semantics, if applicable. 6963 5. If the request method has been changed to GET or HEAD, remove 6964 content-specific header fields, including (but not limited to) 6965 Content-Encoding, Content-Language, Content-Location, 6966 Content-Type, Content-Length, Digest, ETag, Last-Modified. 6968 | *Note:* In HTTP/1.0, the status codes 301 (Moved Permanently) 6969 | and 302 (Found) were defined for the first type of redirect 6970 | ([RFC1945], Section 9.3). Early user agents split on whether 6971 | the method applied to the redirect target would be the same as 6972 | the original request or would be rewritten as GET. Although 6973 | HTTP originally defined the former semantics for 301 and 302 6974 | (to match its original implementation at CERN), and defined 303 6975 | (See Other) to match the latter semantics, prevailing practice 6976 | gradually converged on the latter semantics for 301 and 302 as 6977 | well. The first revision of HTTP/1.1 added 307 (Temporary 6978 | Redirect) to indicate the former semantics of 302 without being 6979 | impacted by divergent practice. For the same reason, 308 6980 | (Permanent Redirect) was later on added in [RFC7538] to match 6981 | 301. Over 10 years later, most user agents still do method 6982 | rewriting for 301 and 302; therefore, [RFC7231] made that 6983 | behavior conformant when the original request is POST. 6985 A client SHOULD detect and intervene in cyclical redirections (i.e., 6986 "infinite" redirection loops). 6988 | *Note:* An earlier version of this specification recommended a 6989 | maximum of five redirections ([RFC2068], Section 10.3). 6990 | Content developers need to be aware that some clients might 6991 | implement such a fixed limitation. 6993 15.4.1. 300 Multiple Choices 6995 The _300 (Multiple Choices)_ status code indicates that the target 6996 resource has more than one representation, each with its own more 6997 specific identifier, and information about the alternatives is being 6998 provided so that the user (or user agent) can select a preferred 6999 representation by redirecting its request to one or more of those 7000 identifiers. In other words, the server desires that the user agent 7001 engage in reactive negotiation to select the most appropriate 7002 representation(s) for its needs (Section 12). 7004 If the server has a preferred choice, the server SHOULD generate a 7005 Location header field containing a preferred choice's URI reference. 7006 The user agent MAY use the Location field value for automatic 7007 redirection. 7009 For request methods other than HEAD, the server SHOULD generate a 7010 payload in the 300 response containing a list of representation 7011 metadata and URI reference(s) from which the user or user agent can 7012 choose the one most preferred. The user agent MAY make a selection 7013 from that list automatically if it understands the provided media 7014 type. A specific format for automatic selection is not defined by 7015 this specification because HTTP tries to remain orthogonal to the 7016 definition of its payloads. In practice, the representation is 7017 provided in some easily parsed format believed to be acceptable to 7018 the user agent, as determined by shared design or content 7019 negotiation, or in some commonly accepted hypertext format. 7021 A 300 response is heuristically cacheable; i.e., unless otherwise 7022 indicated by the method definition or explicit cache controls (see 7023 Section 4.2.2 of [Caching]). 7025 | *Note:* The original proposal for the 300 status code defined 7026 | the URI header field as providing a list of alternative 7027 | representations, such that it would be usable for 200, 300, and 7028 | 406 responses and be transferred in responses to the HEAD 7029 | method. However, lack of deployment and disagreement over 7030 | syntax led to both URI and Alternates (a subsequent proposal) 7031 | being dropped from this specification. It is possible to 7032 | communicate the list as a Link header field value [RFC8288] 7033 | whose members have a relationship of "alternate", though 7034 | deployment is a chicken-and-egg problem. 7036 15.4.2. 301 Moved Permanently 7038 The _301 (Moved Permanently)_ status code indicates that the target 7039 resource has been assigned a new permanent URI and any future 7040 references to this resource ought to use one of the enclosed URIs. 7041 Clients with link-editing capabilities ought to automatically re-link 7042 references to the target URI to one or more of the new references 7043 sent by the server, where possible. 7045 The server SHOULD generate a Location header field in the response 7046 containing a preferred URI reference for the new permanent URI. The 7047 user agent MAY use the Location field value for automatic 7048 redirection. The server's response payload usually contains a short 7049 hypertext note with a hyperlink to the new URI(s). 7051 | *Note:* For historical reasons, a user agent MAY change the 7052 | request method from POST to GET for the subsequent request. If 7053 | this behavior is undesired, the 308 (Permanent Redirect) status 7054 | code can be used instead. 7056 A 301 response is heuristically cacheable; i.e., unless otherwise 7057 indicated by the method definition or explicit cache controls (see 7058 Section 4.2.2 of [Caching]). 7060 15.4.3. 302 Found 7062 The _302 (Found)_ status code indicates that the target resource 7063 resides temporarily under a different URI. Since the redirection 7064 might be altered on occasion, the client ought to continue to use the 7065 target URI for future requests. 7067 The server SHOULD generate a Location header field in the response 7068 containing a URI reference for the different URI. The user agent MAY 7069 use the Location field value for automatic redirection. The server's 7070 response payload usually contains a short hypertext note with a 7071 hyperlink to the different URI(s). 7073 | *Note:* For historical reasons, a user agent MAY change the 7074 | request method from POST to GET for the subsequent request. If 7075 | this behavior is undesired, the 307 (Temporary Redirect) status 7076 | code can be used instead. 7078 15.4.4. 303 See Other 7080 The _303 (See Other)_ status code indicates that the server is 7081 redirecting the user agent to a different resource, as indicated by a 7082 URI in the Location header field, which is intended to provide an 7083 indirect response to the original request. A user agent can perform 7084 a retrieval request targeting that URI (a GET or HEAD request if 7085 using HTTP), which might also be redirected, and present the eventual 7086 result as an answer to the original request. Note that the new URI 7087 in the Location header field is not considered equivalent to the 7088 target URI. 7090 This status code is applicable to any HTTP method. It is primarily 7091 used to allow the output of a POST action to redirect the user agent 7092 to a selected resource, since doing so provides the information 7093 corresponding to the POST response in a form that can be separately 7094 identified, bookmarked, and cached, independent of the original 7095 request. 7097 A 303 response to a GET request indicates that the origin server does 7098 not have a representation of the target resource that can be 7099 transferred by the server over HTTP. However, the Location field 7100 value refers to a resource that is descriptive of the target 7101 resource, such that making a retrieval request on that other resource 7102 might result in a representation that is useful to recipients without 7103 implying that it represents the original target resource. Note that 7104 answers to the questions of what can be represented, what 7105 representations are adequate, and what might be a useful description 7106 are outside the scope of HTTP. 7108 Except for responses to a HEAD request, the representation of a 303 7109 response ought to contain a short hypertext note with a hyperlink to 7110 the same URI reference provided in the Location header field. 7112 15.4.5. 304 Not Modified 7114 The _304 (Not Modified)_ status code indicates that a conditional GET 7115 or HEAD request has been received and would have resulted in a 200 7116 (OK) response if it were not for the fact that the condition 7117 evaluated to false. In other words, there is no need for the server 7118 to transfer a representation of the target resource because the 7119 request indicates that the client, which made the request 7120 conditional, already has a valid representation; the server is 7121 therefore redirecting the client to make use of that stored 7122 representation as if it were the payload of a 200 (OK) response. 7124 The server generating a 304 response MUST generate any of the 7125 following header fields that would have been sent in a 200 (OK) 7126 response to the same request: Cache-Control, Content-Location, Date, 7127 ETag, Expires, and Vary. 7129 Since the goal of a 304 response is to minimize information transfer 7130 when the recipient already has one or more cached representations, a 7131 sender SHOULD NOT generate representation metadata other than the 7132 above listed fields unless said metadata exists for the purpose of 7133 guiding cache updates (e.g., Last-Modified might be useful if the 7134 response does not have an ETag field). 7136 Requirements on a cache that receives a 304 response are defined in 7137 Section 4.3.4 of [Caching]. If the conditional request originated 7138 with an outbound client, such as a user agent with its own cache 7139 sending a conditional GET to a shared proxy, then the proxy SHOULD 7140 forward the 304 response to that client. 7142 A 304 response is terminated by the end of the header section; it 7143 cannot contain payload data or trailers. 7145 15.4.6. 305 Use Proxy 7147 The _305 (Use Proxy)_ status code was defined in a previous version 7148 of this specification and is now deprecated (Appendix B of 7149 [RFC7231]). 7151 15.4.7. 306 (Unused) 7153 The 306 status code was defined in a previous version of this 7154 specification, is no longer used, and the code is reserved. 7156 15.4.8. 307 Temporary Redirect 7158 The _307 (Temporary Redirect)_ status code indicates that the target 7159 resource resides temporarily under a different URI and the user agent 7160 MUST NOT change the request method if it performs an automatic 7161 redirection to that URI. Since the redirection can change over time, 7162 the client ought to continue using the original target URI for future 7163 requests. 7165 The server SHOULD generate a Location header field in the response 7166 containing a URI reference for the different URI. The user agent MAY 7167 use the Location field value for automatic redirection. The server's 7168 response payload usually contains a short hypertext note with a 7169 hyperlink to the different URI(s). 7171 15.4.9. 308 Permanent Redirect 7173 The _308 (Permanent Redirect)_ status code indicates that the target 7174 resource has been assigned a new permanent URI and any future 7175 references to this resource ought to use one of the enclosed URIs. 7176 Clients with link editing capabilities ought to automatically re-link 7177 references to the target URI to one or more of the new references 7178 sent by the server, where possible. 7180 The server SHOULD generate a Location header field in the response 7181 containing a preferred URI reference for the new permanent URI. The 7182 user agent MAY use the Location field value for automatic 7183 redirection. The server's response payload usually contains a short 7184 hypertext note with a hyperlink to the new URI(s). 7186 A 308 response is heuristically cacheable; i.e., unless otherwise 7187 indicated by the method definition or explicit cache controls (see 7188 Section 4.2.2 of [Caching]). 7190 | *Note:* This status code is much younger (June 2014) than its 7191 | sibling codes, and thus might not be recognized everywhere. 7192 | See Section 4 of [RFC7538] for deployment considerations. 7194 15.5. Client Error 4xx 7196 The _4xx (Client Error)_ class of status code indicates that the 7197 client seems to have erred. Except when responding to a HEAD 7198 request, the server SHOULD send a representation containing an 7199 explanation of the error situation, and whether it is a temporary or 7200 permanent condition. These status codes are applicable to any 7201 request method. User agents SHOULD display any included 7202 representation to the user. 7204 15.5.1. 400 Bad Request 7206 The _400 (Bad Request)_ status code indicates that the server cannot 7207 or will not process the request due to something that is perceived to 7208 be a client error (e.g., malformed request syntax, invalid request 7209 message framing, or deceptive request routing). 7211 15.5.2. 401 Unauthorized 7213 The _401 (Unauthorized)_ status code indicates that the request has 7214 not been applied because it lacks valid authentication credentials 7215 for the target resource. The server generating a 401 response MUST 7216 send a WWW-Authenticate header field (Section 11.6.1) containing at 7217 least one challenge applicable to the target resource. 7219 If the request included authentication credentials, then the 401 7220 response indicates that authorization has been refused for those 7221 credentials. The user agent MAY repeat the request with a new or 7222 replaced Authorization header field (Section 11.6.2). If the 401 7223 response contains the same challenge as the prior response, and the 7224 user agent has already attempted authentication at least once, then 7225 the user agent SHOULD present the enclosed representation to the 7226 user, since it usually contains relevant diagnostic information. 7228 15.5.3. 402 Payment Required 7230 The _402 (Payment Required)_ status code is reserved for future use. 7232 15.5.4. 403 Forbidden 7234 The _403 (Forbidden)_ status code indicates that the server 7235 understood the request but refuses to fulfill it. A server that 7236 wishes to make public why the request has been forbidden can describe 7237 that reason in the response payload (if any). 7239 If authentication credentials were provided in the request, the 7240 server considers them insufficient to grant access. The client 7241 SHOULD NOT automatically repeat the request with the same 7242 credentials. The client MAY repeat the request with new or different 7243 credentials. However, a request might be forbidden for reasons 7244 unrelated to the credentials. 7246 An origin server that wishes to "hide" the current existence of a 7247 forbidden target resource MAY instead respond with a status code of 7248 404 (Not Found). 7250 15.5.5. 404 Not Found 7252 The _404 (Not Found)_ status code indicates that the origin server 7253 did not find a current representation for the target resource or is 7254 not willing to disclose that one exists. A 404 status code does not 7255 indicate whether this lack of representation is temporary or 7256 permanent; the 410 (Gone) status code is preferred over 404 if the 7257 origin server knows, presumably through some configurable means, that 7258 the condition is likely to be permanent. 7260 A 404 response is heuristically cacheable; i.e., unless otherwise 7261 indicated by the method definition or explicit cache controls (see 7262 Section 4.2.2 of [Caching]). 7264 15.5.6. 405 Method Not Allowed 7266 The _405 (Method Not Allowed)_ status code indicates that the method 7267 received in the request-line is known by the origin server but not 7268 supported by the target resource. The origin server MUST generate an 7269 Allow header field in a 405 response containing a list of the target 7270 resource's currently supported methods. 7272 A 405 response is heuristically cacheable; i.e., unless otherwise 7273 indicated by the method definition or explicit cache controls (see 7274 Section 4.2.2 of [Caching]). 7276 15.5.7. 406 Not Acceptable 7278 The _406 (Not Acceptable)_ status code indicates that the target 7279 resource does not have a current representation that would be 7280 acceptable to the user agent, according to the proactive negotiation 7281 header fields received in the request (Section 12.1), and the server 7282 is unwilling to supply a default representation. 7284 The server SHOULD generate a payload containing a list of available 7285 representation characteristics and corresponding resource identifiers 7286 from which the user or user agent can choose the one most 7287 appropriate. A user agent MAY automatically select the most 7288 appropriate choice from that list. However, this specification does 7289 not define any standard for such automatic selection, as described in 7290 Section 15.4.1. 7292 15.5.8. 407 Proxy Authentication Required 7294 The _407 (Proxy Authentication Required)_ status code is similar to 7295 401 (Unauthorized), but it indicates that the client needs to 7296 authenticate itself in order to use a proxy for this request. The 7297 proxy MUST send a Proxy-Authenticate header field (Section 11.7.1) 7298 containing a challenge applicable to that proxy for the request. The 7299 client MAY repeat the request with a new or replaced 7300 Proxy-Authorization header field (Section 11.7.2). 7302 15.5.9. 408 Request Timeout 7304 The _408 (Request Timeout)_ status code indicates that the server did 7305 not receive a complete request message within the time that it was 7306 prepared to wait. 7308 If the client has an outstanding request in transit, it MAY repeat 7309 that request. If the current connection is not usable (e.g., as it 7310 would be in HTTP/1.1, because request delimitation is lost), a new 7311 connection will be used. 7313 15.5.10. 409 Conflict 7315 The _409 (Conflict)_ status code indicates that the request could not 7316 be completed due to a conflict with the current state of the target 7317 resource. This code is used in situations where the user might be 7318 able to resolve the conflict and resubmit the request. The server 7319 SHOULD generate a payload that includes enough information for a user 7320 to recognize the source of the conflict. 7322 Conflicts are most likely to occur in response to a PUT request. For 7323 example, if versioning were being used and the representation being 7324 PUT included changes to a resource that conflict with those made by 7325 an earlier (third-party) request, the origin server might use a 409 7326 response to indicate that it can't complete the request. In this 7327 case, the response representation would likely contain information 7328 useful for merging the differences based on the revision history. 7330 15.5.11. 410 Gone 7332 The _410 (Gone)_ status code indicates that access to the target 7333 resource is no longer available at the origin server and that this 7334 condition is likely to be permanent. If the origin server does not 7335 know, or has no facility to determine, whether or not the condition 7336 is permanent, the status code 404 (Not Found) ought to be used 7337 instead. 7339 The 410 response is primarily intended to assist the task of web 7340 maintenance by notifying the recipient that the resource is 7341 intentionally unavailable and that the server owners desire that 7342 remote links to that resource be removed. Such an event is common 7343 for limited-time, promotional services and for resources belonging to 7344 individuals no longer associated with the origin server's site. It 7345 is not necessary to mark all permanently unavailable resources as 7346 "gone" or to keep the mark for any length of time - that is left to 7347 the discretion of the server owner. 7349 A 410 response is heuristically cacheable; i.e., unless otherwise 7350 indicated by the method definition or explicit cache controls (see 7351 Section 4.2.2 of [Caching]). 7353 15.5.12. 411 Length Required 7355 The _411 (Length Required)_ status code indicates that the server 7356 refuses to accept the request without a defined Content-Length 7357 (Section 8.7). The client MAY repeat the request if it adds a valid 7358 Content-Length header field containing the length of the request 7359 payload data. 7361 15.5.13. 412 Precondition Failed 7363 The _412 (Precondition Failed)_ status code indicates that one or 7364 more conditions given in the request header fields evaluated to false 7365 when tested on the server. This response status code allows the 7366 client to place preconditions on the current resource state (its 7367 current representations and metadata) and, thus, prevent the request 7368 method from being applied if the target resource is in an unexpected 7369 state. 7371 15.5.14. 413 Payload Too Large 7373 The _413 (Payload Too Large)_ status code indicates that the server 7374 is refusing to process a request because the request payload is 7375 larger than the server is willing or able to process. The server MAY 7376 terminate the request, if the protocol version in use allows it; 7377 otherwise, the server MAY close the connection. 7379 If the condition is temporary, the server SHOULD generate a 7380 Retry-After header field to indicate that it is temporary and after 7381 what time the client MAY try again. 7383 15.5.15. 414 URI Too Long 7385 The _414 (URI Too Long)_ status code indicates that the server is 7386 refusing to service the request because the target URI is longer than 7387 the server is willing to interpret. This rare condition is only 7388 likely to occur when a client has improperly converted a POST request 7389 to a GET request with long query information, when the client has 7390 descended into a "black hole" of redirection (e.g., a redirected URI 7391 prefix that points to a suffix of itself) or when the server is under 7392 attack by a client attempting to exploit potential security holes. 7394 A 414 response is heuristically cacheable; i.e., unless otherwise 7395 indicated by the method definition or explicit cache controls (see 7396 Section 4.2.2 of [Caching]). 7398 15.5.16. 415 Unsupported Media Type 7400 The _415 (Unsupported Media Type)_ status code indicates that the 7401 origin server is refusing to service the request because the payload 7402 is in a format not supported by this method on the target resource. 7404 The format problem might be due to the request's indicated 7405 Content-Type or Content-Encoding, or as a result of inspecting the 7406 data directly. 7408 If the problem was caused by an unsupported content coding, the 7409 Accept-Encoding response header field (Section 12.5.3) ought to be 7410 used to indicate what (if any) content codings would have been 7411 accepted in the request. 7413 On the other hand, if the cause was an unsupported media type, the 7414 Accept response header field (Section 12.5.1) can be used to indicate 7415 what media types would have been accepted in the request. 7417 15.5.17. 416 Range Not Satisfiable 7419 The _416 (Range Not Satisfiable)_ status code indicates that the set 7420 of ranges in the request's Range header field (Section 14.2) has been 7421 rejected either because none of the requested ranges are satisfiable 7422 or because the client has requested an excessive number of small or 7423 overlapping ranges (a potential denial of service attack). 7425 Each range unit defines what is required for its own range sets to be 7426 satisfiable. For example, Section 14.1.2 defines what makes a bytes 7427 range set satisfiable. 7429 When this status code is generated in response to a byte-range 7430 request, the sender SHOULD generate a Content-Range header field 7431 specifying the current length of the selected representation 7432 (Section 14.4). 7434 For example: 7436 HTTP/1.1 416 Range Not Satisfiable 7437 Date: Fri, 20 Jan 2012 15:41:54 GMT 7438 Content-Range: bytes */47022 7440 | *Note:* Because servers are free to ignore Range, many 7441 | implementations will respond with the entire selected 7442 | representation in a 200 (OK) response. That is partly because 7443 | most clients are prepared to receive a 200 (OK) to complete the 7444 | task (albeit less efficiently) and partly because clients might 7445 | not stop making an invalid partial request until they have 7446 | received a complete representation. Thus, clients cannot 7447 | depend on receiving a 416 (Range Not Satisfiable) response even 7448 | when it is most appropriate. 7450 15.5.18. 417 Expectation Failed 7452 The _417 (Expectation Failed)_ status code indicates that the 7453 expectation given in the request's Expect header field 7454 (Section 10.1.1) could not be met by at least one of the inbound 7455 servers. 7457 15.5.19. 418 (Unused) 7459 [RFC2324] was an April 1 RFC that lampooned the various ways HTTP was 7460 abused; one such abuse was the definition of an application-specific 7461 418 status code. In the intervening years, this status code has been 7462 widely implemented as an "Easter Egg", and therefore is effectively 7463 consumed by this use. 7465 Therefore, the 418 status code is reserved in the IANA HTTP Status 7466 Code Registry. This indicates that the status code cannot be 7467 assigned to other applications currently. If future circumstances 7468 require its use (e.g., exhaustion of 4NN status codes), it can be re- 7469 assigned to another use. 7471 15.5.20. 422 Unprocessable Payload 7473 The 422 (Unprocessable Payload) status code indicates that the server 7474 understands the content type of the request payload (hence a 415 7475 (Unsupported Media Type) status code is inappropriate), and the 7476 syntax of the request payload is correct, but was unable to process 7477 the contained instructions. For example, this status code can be 7478 sent if an XML request payload contains well-formed (i.e., 7479 syntactically correct), but semantically erroneous XML instructions. 7481 15.5.21. 426 Upgrade Required 7483 The _426 (Upgrade Required)_ status code indicates that the server 7484 refuses to perform the request using the current protocol but might 7485 be willing to do so after the client upgrades to a different 7486 protocol. The server MUST send an Upgrade header field in a 426 7487 response to indicate the required protocol(s) (Section 7.8). 7489 Example: 7491 HTTP/1.1 426 Upgrade Required 7492 Upgrade: HTTP/3.0 7493 Connection: Upgrade 7494 Content-Length: 53 7495 Content-Type: text/plain 7497 This service requires use of the HTTP/3.0 protocol. 7499 15.6. Server Error 5xx 7501 The _5xx (Server Error)_ class of status code indicates that the 7502 server is aware that it has erred or is incapable of performing the 7503 requested method. Except when responding to a HEAD request, the 7504 server SHOULD send a representation containing an explanation of the 7505 error situation, and whether it is a temporary or permanent 7506 condition. A user agent SHOULD display any included representation 7507 to the user. These response codes are applicable to any request 7508 method. 7510 15.6.1. 500 Internal Server Error 7512 The _500 (Internal Server Error)_ status code indicates that the 7513 server encountered an unexpected condition that prevented it from 7514 fulfilling the request. 7516 15.6.2. 501 Not Implemented 7518 The _501 (Not Implemented)_ status code indicates that the server 7519 does not support the functionality required to fulfill the request. 7520 This is the appropriate response when the server does not recognize 7521 the request method and is not capable of supporting it for any 7522 resource. 7524 A 501 response is heuristically cacheable; i.e., unless otherwise 7525 indicated by the method definition or explicit cache controls (see 7526 Section 4.2.2 of [Caching]). 7528 15.6.3. 502 Bad Gateway 7530 The _502 (Bad Gateway)_ status code indicates that the server, while 7531 acting as a gateway or proxy, received an invalid response from an 7532 inbound server it accessed while attempting to fulfill the request. 7534 15.6.4. 503 Service Unavailable 7536 The _503 (Service Unavailable)_ status code indicates that the server 7537 is currently unable to handle the request due to a temporary overload 7538 or scheduled maintenance, which will likely be alleviated after some 7539 delay. The server MAY send a Retry-After header field 7540 (Section 10.2.4) to suggest an appropriate amount of time for the 7541 client to wait before retrying the request. 7543 | *Note:* The existence of the 503 status code does not imply 7544 | that a server has to use it when becoming overloaded. Some 7545 | servers might simply refuse the connection. 7547 15.6.5. 504 Gateway Timeout 7549 The _504 (Gateway Timeout)_ status code indicates that the server, 7550 while acting as a gateway or proxy, did not receive a timely response 7551 from an upstream server it needed to access in order to complete the 7552 request. 7554 15.6.6. 505 HTTP Version Not Supported 7556 The _505 (HTTP Version Not Supported)_ status code indicates that the 7557 server does not support, or refuses to support, the major version of 7558 HTTP that was used in the request message. The server is indicating 7559 that it is unable or unwilling to complete the request using the same 7560 major version as the client, as described in Section 2.5, other than 7561 with this error message. The server SHOULD generate a representation 7562 for the 505 response that describes why that version is not supported 7563 and what other protocols are supported by that server. 7565 16. Extending HTTP 7567 HTTP defines a number of generic extension points that can be used to 7568 introduce capabilities to the protocol without introducing a new 7569 version, including methods, status codes, field names, and further 7570 extensibility points within defined fields, such as authentication 7571 schemes and cache-directives (see Cache-Control extensions in 7572 Section 5.2.3 of [Caching]). Because the semantics of HTTP are not 7573 versioned, these extension points are persistent; the version of the 7574 protocol in use does not affect their semantics. 7576 Version-independent extensions are discouraged from depending on or 7577 interacting with the specific version of the protocol in use. When 7578 this is unavoidable, careful consideration needs to be given to how 7579 the extension can interoperate across versions. 7581 Additionally, specific versions of HTTP might have their own 7582 extensibility points, such as transfer-codings in HTTP/1.1 7583 (Section 6.1 of [Messaging]) and HTTP/2 ([RFC7540]) SETTINGS or frame 7584 types. These extension points are specific to the version of the 7585 protocol they occur within. 7587 Version-specific extensions cannot override or modify the semantics 7588 of a version-independent mechanism or extension point (like a method 7589 or header field) without explicitly being allowed by that protocol 7590 element. For example, the CONNECT method (Section 9.3.6) allows 7591 this. 7593 These guidelines assure that the protocol operates correctly and 7594 predictably, even when parts of the path implement different versions 7595 of HTTP. 7597 16.1. Method Extensibility 7599 16.1.1. Method Registry 7601 The "Hypertext Transfer Protocol (HTTP) Method Registry", maintained 7602 by IANA at , registers 7603 method names. 7605 HTTP method registrations MUST include the following fields: 7607 o Method Name (see Section 9) 7609 o Safe ("yes" or "no", see Section 9.2.1) 7611 o Idempotent ("yes" or "no", see Section 9.2.2) 7613 o Pointer to specification text 7615 Values to be added to this namespace require IETF Review (see 7616 [RFC8126], Section 4.8). 7618 16.1.2. Considerations for New Methods 7620 Standardized methods are generic; that is, they are potentially 7621 applicable to any resource, not just one particular media type, kind 7622 of resource, or application. As such, it is preferred that new 7623 methods be registered in a document that isn't specific to a single 7624 application or data format, since orthogonal technologies deserve 7625 orthogonal specification. 7627 Since message parsing (Section 6 of [Messaging]) needs to be 7628 independent of method semantics (aside from responses to HEAD), 7629 definitions of new methods cannot change the parsing algorithm or 7630 prohibit the presence of payload data on either the request or the 7631 response message. Definitions of new methods can specify that only a 7632 zero-length payload data is allowed by requiring a Content-Length 7633 header field with a value of "0". 7635 A new method definition needs to indicate whether it is safe 7636 (Section 9.2.1), idempotent (Section 9.2.2), cacheable 7637 (Section 9.2.3), what semantics are to be associated with the request 7638 payload (if any), and what refinements the method makes to header 7639 field or status code semantics. If the new method is cacheable, its 7640 definition ought to describe how, and under what conditions, a cache 7641 can store a response and use it to satisfy a subsequent request. The 7642 new method ought to describe whether it can be made conditional 7643 (Section 13.1) and, if so, how a server responds when the condition 7644 is false. Likewise, if the new method might have some use for 7645 partial response semantics (Section 14.2), it ought to document this, 7646 too. 7648 | *Note:* Avoid defining a method name that starts with "M-", 7649 | since that prefix might be misinterpreted as having the 7650 | semantics assigned to it by [RFC2774]. 7652 16.2. Status Code Extensibility 7654 16.2.1. Status Code Registry 7656 The "Hypertext Transfer Protocol (HTTP) Status Code Registry", 7657 maintained by IANA at , registers status code numbers. 7660 A registration MUST include the following fields: 7662 o Status Code (3 digits) 7664 o Short Description 7666 o Pointer to specification text 7668 Values to be added to the HTTP status code namespace require IETF 7669 Review (see [RFC8126], Section 4.8). 7671 16.2.2. Considerations for New Status Codes 7673 When it is necessary to express semantics for a response that are not 7674 defined by current status codes, a new status code can be registered. 7675 Status codes are generic; they are potentially applicable to any 7676 resource, not just one particular media type, kind of resource, or 7677 application of HTTP. As such, it is preferred that new status codes 7678 be registered in a document that isn't specific to a single 7679 application. 7681 New status codes are required to fall under one of the categories 7682 defined in Section 15. To allow existing parsers to process the 7683 response message, new status codes cannot disallow a payload, 7684 although they can mandate a zero-length payload data. 7686 Proposals for new status codes that are not yet widely deployed ought 7687 to avoid allocating a specific number for the code until there is 7688 clear consensus that it will be registered; instead, early drafts can 7689 use a notation such as "4NN", or "3N0" .. "3N9", to indicate the 7690 class of the proposed status code(s) without consuming a number 7691 prematurely. 7693 The definition of a new status code ought to explain the request 7694 conditions that would cause a response containing that status code 7695 (e.g., combinations of request header fields and/or method(s)) along 7696 with any dependencies on response header fields (e.g., what fields 7697 are required, what fields can modify the semantics, and what field 7698 semantics are further refined when used with the new status code). 7700 By default, a status code applies only to the request corresponding 7701 to the response it occurs within. If a status code applies to a 7702 larger scope of applicability - for example, all requests to the 7703 resource in question, or all requests to a server - this must be 7704 explicitly specified. When doing so, it should be noted that not all 7705 clients can be expected to consistently apply a larger scope, because 7706 they might not understand the new status code. 7708 The definition of a new status code ought to specify whether or not 7709 it is cacheable. Note that all status codes can be cached if the 7710 response they occur in has explicit freshness information; however, 7711 status codes that are defined as being cacheable are allowed to be 7712 cached without explicit freshness information. Likewise, the 7713 definition of a status code can place constraints upon cache 7714 behavior. See [Caching] for more information. 7716 Finally, the definition of a new status code ought to indicate 7717 whether the payload has any implied association with an identified 7718 resource (Section 6.4.2). 7720 16.3. Field Extensibility 7722 HTTP's most widely used extensibility point is the definition of new 7723 header and trailer fields. 7725 New fields can be defined such that, when they are understood by a 7726 recipient, they override or enhance the interpretation of previously 7727 defined fields, define preconditions on request evaluation, or refine 7728 the meaning of responses. 7730 However, defining a field doesn't guarantee its deployment or 7731 recognition by recipients. Most fields are designed with the 7732 expectation that a recipient can safely ignore (but forward 7733 downstream) any field not recognized. In other cases, the sender's 7734 ability to understand a given field might be indicated by its prior 7735 communication, perhaps in the protocol version or fields that it sent 7736 in prior messages, or its use of a specific media type. Likewise, 7737 direct inspection of support might be possible through an OPTIONS 7738 request or by interacting with a defined well-known URI [RFC8615] if 7739 such inspection is defined along with the field being introduced. 7741 16.3.1. Field Name Registry 7743 The "Hypertext Transfer Protocol (HTTP) Field Name Registry" defines 7744 the namespace for HTTP field names. 7746 Any party can request registration of a HTTP field. See 7747 Section 16.3.3 for considerations to take into account when creating 7748 a new HTTP field. 7750 The "Hypertext Transfer Protocol (HTTP) Field Name Registry" is 7751 located at . 7752 Registration requests can be made by following the instructions 7753 located there or by sending an email to the "ietf-http-wg@ietf.org" 7754 mailing list. 7756 Field names are registered on the advice of a Designated Expert 7757 (appointed by the IESG or their delegate). Fields with the status 7758 'permanent' are Specification Required ([RFC8126], Section 4.6). 7760 Registration requests consist of at least the following information: 7762 Field name: 7763 The requested field name. It MUST conform to the field-name 7764 syntax defined in Section 5.1, and SHOULD be restricted to just 7765 letters, digits, hyphen ('-') and underscore ('_') characters, 7766 with the first character being a letter. 7768 Status: 7769 "permanent" or "provisional". 7771 Specification document(s): 7772 Reference to the document that specifies the field, preferably 7773 including a URI that can be used to retrieve a copy of the 7774 document. An indication of the relevant section(s) can also be 7775 included, but is not required. 7777 And, optionally: 7779 Comments: Additional information, such as about reserved entries. 7781 The Expert(s) can define additional fields to be collected in the 7782 registry, in consultation with the community. 7784 Standards-defined names have a status of "permanent". Other names 7785 can also be registered as permanent, if the Expert(s) find that they 7786 are in use, in consultation with the community. Other names should 7787 be registered as "provisional". 7789 Provisional entries can be removed by the Expert(s) if - in 7790 consultation with the community - the Expert(s) find that they are 7791 not in use. The Experts can change a provisional entry's status to 7792 permanent at any time. 7794 Note that names can be registered by third parties (including the 7795 Expert(s)), if the Expert(s) determines that an unregistered name is 7796 widely deployed and not likely to be registered in a timely manner 7797 otherwise. 7799 16.3.2. Considerations for New Field Names 7801 Authors of specifications defining new fields are advised to choose a 7802 short but descriptive field name. Short names avoid needless data 7803 transmission; descriptive names avoid confusion and "squatting" on 7804 names that might have broader uses. 7806 To that end, limited-use fields (such as a header confined to a 7807 single application or use case) are encouraged to use a name that 7808 includes its name (or an abbreviation) as a prefix; for example, if 7809 the Foo Application needs a Description field, it might use "Foo- 7810 Desc"; "Description" is too generic, and "Foo-Description" is 7811 needlessly long. 7813 While the field-name syntax is defined to allow any token character, 7814 in practice some implementations place limits on the characters they 7815 accept in field-names. To be interoperable, new field names SHOULD 7816 constrain themselves to alphanumeric characters, "-", and ".", and 7817 SHOULD begin with an alphanumeric character. 7819 Field names ought not be prefixed with "X-"; see [BCP178] for further 7820 information. 7822 Other prefixes are sometimes used in HTTP field names; for example, 7823 "Accept-" is used in many content negotiation headers. These 7824 prefixes are only an aid to recognizing the purpose of a field, and 7825 do not trigger automatic processing. 7827 16.3.3. Considerations for New Field Values 7829 Authors of specifications defining new fields are advised to consider 7830 documenting: 7832 o Whether the field has a singleton or list-based value (see 7833 Section 5.5). 7835 If it is a singleton field, document how to treat messages where 7836 the multiple members are present (a sensible default would be to 7837 ignore the field, but this might not always be the right choice). 7839 Note that intermediaries and software libraries might combine 7840 multiple field lines into a single one, despite the field being 7841 defined as a singleton. A robust format enables recipients to 7842 discover these situations (good example: "Content-Type", as the 7843 comma can only appear inside quoted strings; bad example: 7844 "Location", as a comma can occur inside a URI). 7846 o Under what conditions the field can be used; e.g., only in 7847 responses or requests, in all messages, only on responses to a 7848 particular request method, etc. 7850 o What the scope of applicability for the information conveyed in 7851 the field is. By default, fields apply only to the message they 7852 are associated with, but some response fields are designed to 7853 apply to all representations of a resource, the resource itself, 7854 or an even broader scope. Specifications that expand the scope of 7855 a response field will need to carefully consider issues such as 7856 content negotiation, the time period of applicability, and (in 7857 some cases) multi-tenant server deployments. 7859 o Whether the field should be stored by origin servers that 7860 understand it upon a PUT request. 7862 o Whether the field semantics are further refined by the context, 7863 such as by existing request methods or status codes. 7865 o Whether it is appropriate to list the field name in the Connection 7866 header field (i.e., if the field is to be hop-by-hop; see 7867 Section 7.6.1). 7869 o Under what conditions intermediaries are allowed to insert, 7870 delete, or modify the field's value. 7872 o Whether it is appropriate to list the field name in a Vary 7873 response header field (e.g., when the request header field is used 7874 by an origin server's content selection algorithm; see 7875 Section 12.5.5). 7877 o Whether the field is allowable in trailers (see Section 6.5). 7879 o Whether the field ought to be preserved across redirects. 7881 o Whether it introduces any additional security considerations, such 7882 as disclosure of privacy-related data. 7884 16.4. Authentication Scheme Extensibility 7886 16.4.1. Authentication Scheme Registry 7888 The "Hypertext Transfer Protocol (HTTP) Authentication Scheme 7889 Registry" defines the namespace for the authentication schemes in 7890 challenges and credentials. It is maintained at 7891 . 7893 Registrations MUST include the following fields: 7895 o Authentication Scheme Name 7897 o Pointer to specification text 7899 o Notes (optional) 7901 Values to be added to this namespace require IETF Review (see 7902 [RFC8126], Section 4.8). 7904 16.4.2. Considerations for New Authentication Schemes 7906 There are certain aspects of the HTTP Authentication framework that 7907 put constraints on how new authentication schemes can work: 7909 o HTTP authentication is presumed to be stateless: all of the 7910 information necessary to authenticate a request MUST be provided 7911 in the request, rather than be dependent on the server remembering 7912 prior requests. Authentication based on, or bound to, the 7913 underlying connection is outside the scope of this specification 7914 and inherently flawed unless steps are taken to ensure that the 7915 connection cannot be used by any party other than the 7916 authenticated user (see Section 3.6). 7918 o The authentication parameter "realm" is reserved for defining 7919 protection spaces as described in Section 11.5. New schemes MUST 7920 NOT use it in a way incompatible with that definition. 7922 o The "token68" notation was introduced for compatibility with 7923 existing authentication schemes and can only be used once per 7924 challenge or credential. Thus, new schemes ought to use the auth- 7925 param syntax instead, because otherwise future extensions will be 7926 impossible. 7928 o The parsing of challenges and credentials is defined by this 7929 specification and cannot be modified by new authentication 7930 schemes. When the auth-param syntax is used, all parameters ought 7931 to support both token and quoted-string syntax, and syntactical 7932 constraints ought to be defined on the field value after parsing 7933 (i.e., quoted-string processing). This is necessary so that 7934 recipients can use a generic parser that applies to all 7935 authentication schemes. 7937 *Note:* The fact that the value syntax for the "realm" parameter 7938 is restricted to quoted-string was a bad design choice not to be 7939 repeated for new parameters. 7941 o Definitions of new schemes ought to define the treatment of 7942 unknown extension parameters. In general, a "must-ignore" rule is 7943 preferable to a "must-understand" rule, because otherwise it will 7944 be hard to introduce new parameters in the presence of legacy 7945 recipients. Furthermore, it's good to describe the policy for 7946 defining new parameters (such as "update the specification" or 7947 "use this registry"). 7949 o Authentication schemes need to document whether they are usable in 7950 origin-server authentication (i.e., using WWW-Authenticate), and/ 7951 or proxy authentication (i.e., using Proxy-Authenticate). 7953 o The credentials carried in an Authorization header field are 7954 specific to the user agent and, therefore, have the same effect on 7955 HTTP caches as the "private" Cache-Control response directive 7956 (Section 5.2.2.7 of [Caching]), within the scope of the request in 7957 which they appear. 7959 Therefore, new authentication schemes that choose not to carry 7960 credentials in the Authorization header field (e.g., using a newly 7961 defined header field) will need to explicitly disallow caching, by 7962 mandating the use of Cache-Control response directives (e.g., 7963 "private"). 7965 o Schemes using Authentication-Info, Proxy-Authentication-Info, or 7966 any other authentication related response header field need to 7967 consider and document the related security considerations (see 7968 Section 17.15.4). 7970 16.5. Range Unit Extensibility 7971 16.5.1. Range Unit Registry 7973 The "HTTP Range Unit Registry" defines the namespace for the range 7974 unit names and refers to their corresponding specifications. It is 7975 maintained at . 7977 Registration of an HTTP Range Unit MUST include the following fields: 7979 o Name 7981 o Description 7983 o Pointer to specification text 7985 Values to be added to this namespace require IETF Review (see 7986 [RFC8126], Section 4.8). 7988 16.5.2. Considerations for New Range Units 7990 Other range units, such as format-specific boundaries like pages, 7991 sections, records, rows, or time, are potentially usable in HTTP for 7992 application-specific purposes, but are not commonly used in practice. 7993 Implementors of alternative range units ought to consider how they 7994 would work with content codings and general-purpose intermediaries. 7996 16.6. Content Coding Extensibility 7998 16.6.1. Content Coding Registry 8000 The "HTTP Content Coding Registry", maintained by IANA at 8001 , registers 8002 content-coding names. 8004 Content coding registrations MUST include the following fields: 8006 o Name 8008 o Description 8010 o Pointer to specification text 8012 Names of content codings MUST NOT overlap with names of transfer 8013 codings (Section 7 of [Messaging]), unless the encoding 8014 transformation is identical (as is the case for the compression 8015 codings defined in Section 8.5.1). 8017 Values to be added to this namespace require IETF Review (see 8018 Section 4.8 of [RFC8126]) and MUST conform to the purpose of content 8019 coding defined in Section 8.5.1. 8021 16.6.2. Considerations for New Content Codings 8023 New content codings ought to be self-descriptive whenever possible, 8024 with optional parameters discoverable within the coding format 8025 itself, rather than rely on external metadata that might be lost 8026 during transit. 8028 16.7. Upgrade Token Registry 8030 The "Hypertext Transfer Protocol (HTTP) Upgrade Token Registry" 8031 defines the namespace for protocol-name tokens used to identify 8032 protocols in the Upgrade header field. The registry is maintained at 8033 . 8035 Each registered protocol name is associated with contact information 8036 and an optional set of specifications that details how the connection 8037 will be processed after it has been upgraded. 8039 Registrations happen on a "First Come First Served" basis (see 8040 Section 4.4 of [RFC8126]) and are subject to the following rules: 8042 1. A protocol-name token, once registered, stays registered forever. 8044 2. A protocol-name token is case-insensitive and registered with the 8045 preferred case to be generated by senders. 8047 3. The registration MUST name a responsible party for the 8048 registration. 8050 4. The registration MUST name a point of contact. 8052 5. The registration MAY name a set of specifications associated with 8053 that token. Such specifications need not be publicly available. 8055 6. The registration SHOULD name a set of expected "protocol-version" 8056 tokens associated with that token at the time of registration. 8058 7. The responsible party MAY change the registration at any time. 8059 The IANA will keep a record of all such changes, and make them 8060 available upon request. 8062 8. The IESG MAY reassign responsibility for a protocol token. This 8063 will normally only be used in the case when a responsible party 8064 cannot be contacted. 8066 17. Security Considerations 8068 This section is meant to inform developers, information providers, 8069 and users of known security concerns relevant to HTTP semantics and 8070 its use for transferring information over the Internet. 8071 Considerations related to caching are discussed in Section 7 of 8072 [Caching] and considerations related to HTTP/1.1 message syntax and 8073 parsing are discussed in Section 11 of [Messaging]. 8075 The list of considerations below is not exhaustive. Most security 8076 concerns related to HTTP semantics are about securing server-side 8077 applications (code behind the HTTP interface), securing user agent 8078 processing of payloads received via HTTP, or secure use of the 8079 Internet in general, rather than security of the protocol. Various 8080 organizations maintain topical information and links to current 8081 research on Web application security (e.g., [OWASP]). 8083 17.1. Establishing Authority 8085 HTTP relies on the notion of an _authoritative response_: a response 8086 that has been determined by (or at the direction of) the origin 8087 server identified within the target URI to be the most appropriate 8088 response for that request given the state of the target resource at 8089 the time of response message origination. 8091 When a registered name is used in the authority component, the "http" 8092 URI scheme (Section 4.2.1) relies on the user's local name resolution 8093 service to determine where it can find authoritative responses. This 8094 means that any attack on a user's network host table, cached names, 8095 or name resolution libraries becomes an avenue for attack on 8096 establishing authority for "http" URIs. Likewise, the user's choice 8097 of server for Domain Name Service (DNS), and the hierarchy of servers 8098 from which it obtains resolution results, could impact the 8099 authenticity of address mappings; DNS Security Extensions (DNSSEC, 8100 [RFC4033]) are one way to improve authenticity. 8102 Furthermore, after an IP address is obtained, establishing authority 8103 for an "http" URI is vulnerable to attacks on Internet Protocol 8104 routing. 8106 The "https" scheme (Section 4.2.2) is intended to prevent (or at 8107 least reveal) many of these potential attacks on establishing 8108 authority, provided that the negotiated connection is secured and the 8109 client properly verifies that the communicating server's identity 8110 matches the target URI's authority component (Section 4.3.4). 8111 Correctly implementing such verification can be difficult (see 8112 [Georgiev]). 8114 Authority for a given origin server can be delegated through protocol 8115 extensions; for example, [RFC7838]. Likewise, the set of servers for 8116 which a connection is considered authoritative can be changed with a 8117 protocol extension like [RFC8336]. 8119 Providing a response from a non-authoritative source, such as a 8120 shared proxy cache, is often useful to improve performance and 8121 availability, but only to the extent that the source can be trusted 8122 or the distrusted response can be safely used. 8124 Unfortunately, communicating authority to users can be difficult. 8125 For example, _phishing_ is an attack on the user's perception of 8126 authority, where that perception can be misled by presenting similar 8127 branding in hypertext, possibly aided by userinfo obfuscating the 8128 authority component (see Section 4.2.1). User agents can reduce the 8129 impact of phishing attacks by enabling users to easily inspect a 8130 target URI prior to making an action, by prominently distinguishing 8131 (or rejecting) userinfo when present, and by not sending stored 8132 credentials and cookies when the referring document is from an 8133 unknown or untrusted source. 8135 17.2. Risks of Intermediaries 8137 HTTP intermediaries are inherently situated for on-path attacks. 8138 Compromise of the systems on which the intermediaries run can result 8139 in serious security and privacy problems. Intermediaries might have 8140 access to security-related information, personal information about 8141 individual users and organizations, and proprietary information 8142 belonging to users and content providers. A compromised 8143 intermediary, or an intermediary implemented or configured without 8144 regard to security and privacy considerations, might be used in the 8145 commission of a wide range of potential attacks. 8147 Intermediaries that contain a shared cache are especially vulnerable 8148 to cache poisoning attacks, as described in Section 7 of [Caching]. 8150 Implementers need to consider the privacy and security implications 8151 of their design and coding decisions, and of the configuration 8152 options they provide to operators (especially the default 8153 configuration). 8155 Users need to be aware that intermediaries are no more trustworthy 8156 than the people who run them; HTTP itself cannot solve this problem. 8158 17.3. Attacks Based on File and Path Names 8160 Origin servers frequently make use of their local file system to 8161 manage the mapping from target URI to resource representations. Most 8162 file systems are not designed to protect against malicious file or 8163 path names. Therefore, an origin server needs to avoid accessing 8164 names that have a special significance to the system when mapping the 8165 target resource to files, folders, or directories. 8167 For example, UNIX, Microsoft Windows, and other operating systems use 8168 ".." as a path component to indicate a directory level above the 8169 current one, and they use specially named paths or file names to send 8170 data to system devices. Similar naming conventions might exist 8171 within other types of storage systems. Likewise, local storage 8172 systems have an annoying tendency to prefer user-friendliness over 8173 security when handling invalid or unexpected characters, 8174 recomposition of decomposed characters, and case-normalization of 8175 case-insensitive names. 8177 Attacks based on such special names tend to focus on either denial- 8178 of-service (e.g., telling the server to read from a COM port) or 8179 disclosure of configuration and source files that are not meant to be 8180 served. 8182 17.4. Attacks Based on Command, Code, or Query Injection 8184 Origin servers often use parameters within the URI as a means of 8185 identifying system services, selecting database entries, or choosing 8186 a data source. However, data received in a request cannot be 8187 trusted. An attacker could construct any of the request data 8188 elements (method, target URI, header fields, or payload data) to 8189 contain data that might be misinterpreted as a command, code, or 8190 query when passed through a command invocation, language interpreter, 8191 or database interface. 8193 For example, SQL injection is a common attack wherein additional 8194 query language is inserted within some part of the target URI or 8195 header fields (e.g., Host, Referer, etc.). If the received data is 8196 used directly within a SELECT statement, the query language might be 8197 interpreted as a database command instead of a simple string value. 8198 This type of implementation vulnerability is extremely common, in 8199 spite of being easy to prevent. 8201 In general, resource implementations ought to avoid use of request 8202 data in contexts that are processed or interpreted as instructions. 8203 Parameters ought to be compared to fixed strings and acted upon as a 8204 result of that comparison, rather than passed through an interface 8205 that is not prepared for untrusted data. Received data that isn't 8206 based on fixed parameters ought to be carefully filtered or encoded 8207 to avoid being misinterpreted. 8209 Similar considerations apply to request data when it is stored and 8210 later processed, such as within log files, monitoring tools, or when 8211 included within a data format that allows embedded scripts. 8213 17.5. Attacks via Protocol Element Length 8215 Because HTTP uses mostly textual, character-delimited fields, parsers 8216 are often vulnerable to attacks based on sending very long (or very 8217 slow) streams of data, particularly where an implementation is 8218 expecting a protocol element with no predefined length (Section 2.3). 8220 To promote interoperability, specific recommendations are made for 8221 minimum size limits on fields (Section 5.4). These are minimum 8222 recommendations, chosen to be supportable even by implementations 8223 with limited resources; it is expected that most implementations will 8224 choose substantially higher limits. 8226 A server can reject a message that has a target URI that is too long 8227 (Section 15.5.15) or a request payload that is too large 8228 (Section 15.5.14). Additional status codes related to capacity 8229 limits have been defined by extensions to HTTP [RFC6585]. 8231 Recipients ought to carefully limit the extent to which they process 8232 other protocol elements, including (but not limited to) request 8233 methods, response status phrases, field names, numeric values, and 8234 chunk lengths. Failure to limit such processing can result in buffer 8235 overflows, arithmetic overflows, or increased vulnerability to 8236 denial-of-service attacks. 8238 17.6. Attacks using Shared-dictionary Compression 8240 Some attacks on encrypted protocols use the differences in size 8241 created by dynamic compression to reveal confidential information; 8242 for example, [BREACH]. These attacks rely on creating a redundancy 8243 between attacker-controlled content and the confidential information, 8244 such that a dynamic compression algorithm using the same dictionary 8245 for both content will compress more efficiently when the attacker- 8246 controlled content matches parts of the confidential content. 8248 HTTP messages can be compressed in a number of ways, including using 8249 TLS compression, content-codings, transfer-codings, and other 8250 extension or version-specific mechanisms. 8252 The most effective mitigation for this risk is to disable compression 8253 on sensitive data, or to strictly separate sensitive data from 8254 attacker-controlled data so that they cannot share the same 8255 compression dictionary. With careful design, a compression scheme 8256 can be designed in a way that is not considered exploitable in 8257 limited use cases, such as HPACK ([RFC7541]). 8259 17.7. Disclosure of Personal Information 8261 Clients are often privy to large amounts of personal information, 8262 including both information provided by the user to interact with 8263 resources (e.g., the user's name, location, mail address, passwords, 8264 encryption keys, etc.) and information about the user's browsing 8265 activity over time (e.g., history, bookmarks, etc.). Implementations 8266 need to prevent unintentional disclosure of personal information. 8268 17.8. Privacy of Server Log Information 8270 A server is in the position to save personal data about a user's 8271 requests over time, which might identify their reading patterns or 8272 subjects of interest. In particular, log information gathered at an 8273 intermediary often contains a history of user agent interaction, 8274 across a multitude of sites, that can be traced to individual users. 8276 HTTP log information is confidential in nature; its handling is often 8277 constrained by laws and regulations. Log information needs to be 8278 securely stored and appropriate guidelines followed for its analysis. 8279 Anonymization of personal information within individual entries 8280 helps, but it is generally not sufficient to prevent real log traces 8281 from being re-identified based on correlation with other access 8282 characteristics. As such, access traces that are keyed to a specific 8283 client are unsafe to publish even if the key is pseudonymous. 8285 To minimize the risk of theft or accidental publication, log 8286 information ought to be purged of personally identifiable 8287 information, including user identifiers, IP addresses, and user- 8288 provided query parameters, as soon as that information is no longer 8289 necessary to support operational needs for security, auditing, or 8290 fraud control. 8292 17.9. Disclosure of Sensitive Information in URIs 8294 URIs are intended to be shared, not secured, even when they identify 8295 secure resources. URIs are often shown on displays, added to 8296 templates when a page is printed, and stored in a variety of 8297 unprotected bookmark lists. Many servers, proxies, and user agents 8298 log or display the target URI in places where it might be visible to 8299 third parties. It is therefore unwise to include information within 8300 a URI that is sensitive, personally identifiable, or a risk to 8301 disclose. 8303 When an application uses client-side mechanisms to construct a target 8304 URI out of user-provided information, such as the query fields of a 8305 form using GET, potentially sensitive data might be provided that 8306 would not be appropriate for disclosure within a URI. POST is often 8307 preferred in such cases because it usually doesn't construct a URI; 8308 instead, POST of a form transmits the potentially sensitive data in 8309 the request payload data. However, this hinders caching and uses an 8310 unsafe method for what would otherwise be a safe request. 8311 Alternative workarounds include transforming the user-provided data 8312 prior to constructing the URI, or filtering the data to only include 8313 common values that are not sensitive. Likewise, redirecting the 8314 result of a query to a different (server-generated) URI can remove 8315 potentially sensitive data from later links and provide a cacheable 8316 response for later reuse. 8318 Since the Referer header field tells a target site about the context 8319 that resulted in a request, it has the potential to reveal 8320 information about the user's immediate browsing history and any 8321 personal information that might be found in the referring resource's 8322 URI. Limitations on the Referer header field are described in 8323 Section 10.1.3 to address some of its security considerations. 8325 17.10. Disclosure of Fragment after Redirects 8327 Although fragment identifiers used within URI references are not sent 8328 in requests, implementers ought to be aware that they will be visible 8329 to the user agent and any extensions or scripts running as a result 8330 of the response. In particular, when a redirect occurs and the 8331 original request's fragment identifier is inherited by the new 8332 reference in Location (Section 10.2.3), this might have the effect of 8333 disclosing one site's fragment to another site. If the first site 8334 uses personal information in fragments, it ought to ensure that 8335 redirects to other sites include a (possibly empty) fragment 8336 component in order to block that inheritance. 8338 17.11. Disclosure of Product Information 8340 The User-Agent (Section 10.1.6), Via (Section 7.6.3), and Server 8341 (Section 10.2.5) header fields often reveal information about the 8342 respective sender's software systems. In theory, this can make it 8343 easier for an attacker to exploit known security holes; in practice, 8344 attackers tend to try all potential holes regardless of the apparent 8345 software versions being used. 8347 Proxies that serve as a portal through a network firewall ought to 8348 take special precautions regarding the transfer of header information 8349 that might identify hosts behind the firewall. The Via header field 8350 allows intermediaries to replace sensitive machine names with 8351 pseudonyms. 8353 17.12. Browser Fingerprinting 8355 Browser fingerprinting is a set of techniques for identifying a 8356 specific user agent over time through its unique set of 8357 characteristics. These characteristics might include information 8358 related to its TCP behavior, feature capabilities, and scripting 8359 environment, though of particular interest here is the set of unique 8360 characteristics that might be communicated via HTTP. Fingerprinting 8361 is considered a privacy concern because it enables tracking of a user 8362 agent's behavior over time ([Bujlow]) without the corresponding 8363 controls that the user might have over other forms of data collection 8364 (e.g., cookies). Many general-purpose user agents (i.e., Web 8365 browsers) have taken steps to reduce their fingerprints. 8367 There are a number of request header fields that might reveal 8368 information to servers that is sufficiently unique to enable 8369 fingerprinting. The From header field is the most obvious, though it 8370 is expected that From will only be sent when self-identification is 8371 desired by the user. Likewise, Cookie header fields are deliberately 8372 designed to enable re-identification, so fingerprinting concerns only 8373 apply to situations where cookies are disabled or restricted by the 8374 user agent's configuration. 8376 The User-Agent header field might contain enough information to 8377 uniquely identify a specific device, usually when combined with other 8378 characteristics, particularly if the user agent sends excessive 8379 details about the user's system or extensions. However, the source 8380 of unique information that is least expected by users is proactive 8381 negotiation (Section 12.1), including the Accept, Accept-Charset, 8382 Accept-Encoding, and Accept-Language header fields. 8384 In addition to the fingerprinting concern, detailed use of the 8385 Accept-Language header field can reveal information the user might 8386 consider to be of a private nature. For example, understanding a 8387 given language set might be strongly correlated to membership in a 8388 particular ethnic group. An approach that limits such loss of 8389 privacy would be for a user agent to omit the sending of Accept- 8390 Language except for sites that have been whitelisted, perhaps via 8391 interaction after detecting a Vary header field that indicates 8392 language negotiation might be useful. 8394 In environments where proxies are used to enhance privacy, user 8395 agents ought to be conservative in sending proactive negotiation 8396 header fields. General-purpose user agents that provide a high 8397 degree of header field configurability ought to inform users about 8398 the loss of privacy that might result if too much detail is provided. 8399 As an extreme privacy measure, proxies could filter the proactive 8400 negotiation header fields in relayed requests. 8402 17.13. Validator Retention 8404 The validators defined by this specification are not intended to 8405 ensure the validity of a representation, guard against malicious 8406 changes, or detect on-path attacks. At best, they enable more 8407 efficient cache updates and optimistic concurrent writes when all 8408 participants are behaving nicely. At worst, the conditions will fail 8409 and the client will receive a response that is no more harmful than 8410 an HTTP exchange without conditional requests. 8412 An entity-tag can be abused in ways that create privacy risks. For 8413 example, a site might deliberately construct a semantically invalid 8414 entity-tag that is unique to the user or user agent, send it in a 8415 cacheable response with a long freshness time, and then read that 8416 entity-tag in later conditional requests as a means of re-identifying 8417 that user or user agent. Such an identifying tag would become a 8418 persistent identifier for as long as the user agent retained the 8419 original cache entry. User agents that cache representations ought 8420 to ensure that the cache is cleared or replaced whenever the user 8421 performs privacy-maintaining actions, such as clearing stored cookies 8422 or changing to a private browsing mode. 8424 17.14. Denial-of-Service Attacks Using Range 8426 Unconstrained multiple range requests are susceptible to denial-of- 8427 service attacks because the effort required to request many 8428 overlapping ranges of the same data is tiny compared to the time, 8429 memory, and bandwidth consumed by attempting to serve the requested 8430 data in many parts. Servers ought to ignore, coalesce, or reject 8431 egregious range requests, such as requests for more than two 8432 overlapping ranges or for many small ranges in a single set, 8433 particularly when the ranges are requested out of order for no 8434 apparent reason. Multipart range requests are not designed to 8435 support random access. 8437 17.15. Authentication Considerations 8439 Everything about the topic of HTTP authentication is a security 8440 consideration, so the list of considerations below is not exhaustive. 8441 Furthermore, it is limited to security considerations regarding the 8442 authentication framework, in general, rather than discussing all of 8443 the potential considerations for specific authentication schemes 8444 (which ought to be documented in the specifications that define those 8445 schemes). Various organizations maintain topical information and 8446 links to current research on Web application security (e.g., 8447 [OWASP]), including common pitfalls for implementing and using the 8448 authentication schemes found in practice. 8450 17.15.1. Confidentiality of Credentials 8452 The HTTP authentication framework does not define a single mechanism 8453 for maintaining the confidentiality of credentials; instead, each 8454 authentication scheme defines how the credentials are encoded prior 8455 to transmission. While this provides flexibility for the development 8456 of future authentication schemes, it is inadequate for the protection 8457 of existing schemes that provide no confidentiality on their own, or 8458 that do not sufficiently protect against replay attacks. 8459 Furthermore, if the server expects credentials that are specific to 8460 each individual user, the exchange of those credentials will have the 8461 effect of identifying that user even if the content within 8462 credentials remains confidential. 8464 HTTP depends on the security properties of the underlying transport- 8465 or session-level connection to provide confidential transmission of 8466 fields. Services that depend on individual user authentication 8467 require a secured connection prior to exchanging credentials 8468 (Section 4.2.2). 8470 17.15.2. Credentials and Idle Clients 8472 Existing HTTP clients and user agents typically retain authentication 8473 information indefinitely. HTTP does not provide a mechanism for the 8474 origin server to direct clients to discard these cached credentials, 8475 since the protocol has no awareness of how credentials are obtained 8476 or managed by the user agent. The mechanisms for expiring or 8477 revoking credentials can be specified as part of an authentication 8478 scheme definition. 8480 Circumstances under which credential caching can interfere with the 8481 application's security model include but are not limited to: 8483 o Clients that have been idle for an extended period, following 8484 which the server might wish to cause the client to re-prompt the 8485 user for credentials. 8487 o Applications that include a session termination indication (such 8488 as a "logout" or "commit" button on a page) after which the server 8489 side of the application "knows" that there is no further reason 8490 for the client to retain the credentials. 8492 User agents that cache credentials are encouraged to provide a 8493 readily accessible mechanism for discarding cached credentials under 8494 user control. 8496 17.15.3. Protection Spaces 8498 Authentication schemes that solely rely on the "realm" mechanism for 8499 establishing a protection space will expose credentials to all 8500 resources on an origin server. Clients that have successfully made 8501 authenticated requests with a resource can use the same 8502 authentication credentials for other resources on the same origin 8503 server. This makes it possible for a different resource to harvest 8504 authentication credentials for other resources. 8506 This is of particular concern when an origin server hosts resources 8507 for multiple parties under the same origin (Section 11.5). Possible 8508 mitigation strategies include restricting direct access to 8509 authentication credentials (i.e., not making the content of the 8510 Authorization request header field available), and separating 8511 protection spaces by using a different host name (or port number) for 8512 each party. 8514 17.15.4. Additional Response Fields 8516 Adding information to responses that are sent over an unencrypted 8517 channel can affect security and privacy. The presence of the 8518 Authentication-Info and Proxy-Authentication-Info header fields alone 8519 indicates that HTTP authentication is in use. Additional information 8520 could be exposed by the contents of the authentication-scheme 8521 specific parameters; this will have to be considered in the 8522 definitions of these schemes. 8524 18. IANA Considerations 8526 The change controller for the following registrations is: "IETF 8527 (iesg@ietf.org) - Internet Engineering Task Force". 8529 18.1. URI Scheme Registration 8531 Please update the registry of URI Schemes [BCP35] at 8532 with the permanent 8533 schemes listed in the table in Section 4.2. 8535 18.2. Method Registration 8537 Please update the "Hypertext Transfer Protocol (HTTP) Method 8538 Registry" at with the 8539 registration procedure of Section 16.1.1 and the method names 8540 summarized in the following table. 8542 --------- ------ ------------ ------- 8543 Method Safe Idempotent Ref. 8544 --------- ------ ------------ ------- 8545 CONNECT no no 9.3.6 8546 DELETE no yes 9.3.5 8547 GET yes yes 9.3.1 8548 HEAD yes yes 9.3.2 8549 OPTIONS yes yes 9.3.7 8550 POST no no 9.3.3 8551 PUT no yes 9.3.4 8552 TRACE yes yes 9.3.8 8553 * no no 18.2 8554 --------- ------ ------------ ------- 8556 Table 7 8558 The method name "*" is reserved, since using that name as HTTP method 8559 name might conflict with special semantics in fields such as "Access- 8560 Control-Request-Method". 8562 18.3. Status Code Registration 8564 Please update the "Hypertext Transfer Protocol (HTTP) Status Code 8565 Registry" at 8566 with the registration procedure of Section 16.2.1 and the status code 8567 values summarized in the following table. 8569 ------- ------------------------------- --------- 8570 Value Description Ref. 8571 ------- ------------------------------- --------- 8572 100 Continue 15.2.1 8573 101 Switching Protocols 15.2.2 8574 200 OK 15.3.1 8575 201 Created 15.3.2 8576 202 Accepted 15.3.3 8577 203 Non-Authoritative Information 15.3.4 8578 204 No Content 15.3.5 8579 205 Reset Content 15.3.6 8580 206 Partial Content 15.3.7 8581 300 Multiple Choices 15.4.1 8582 301 Moved Permanently 15.4.2 8583 302 Found 15.4.3 8584 303 See Other 15.4.4 8585 304 Not Modified 15.4.5 8586 305 Use Proxy 15.4.6 8587 306 (Unused) 15.4.7 8588 307 Temporary Redirect 15.4.8 8589 308 Permanent Redirect 15.4.9 8590 400 Bad Request 15.5.1 8591 401 Unauthorized 15.5.2 8592 402 Payment Required 15.5.3 8593 403 Forbidden 15.5.4 8594 404 Not Found 15.5.5 8595 405 Method Not Allowed 15.5.6 8596 406 Not Acceptable 15.5.7 8597 407 Proxy Authentication Required 15.5.8 8598 408 Request Timeout 15.5.9 8599 409 Conflict 15.5.10 8600 410 Gone 15.5.11 8601 411 Length Required 15.5.12 8602 412 Precondition Failed 15.5.13 8603 413 Payload Too Large 15.5.14 8604 414 URI Too Long 15.5.15 8605 415 Unsupported Media Type 15.5.16 8606 416 Range Not Satisfiable 15.5.17 8607 417 Expectation Failed 15.5.18 8608 418 (Unused) 15.5.19 8609 422 Unprocessable Payload 15.5.20 8610 426 Upgrade Required 15.5.21 8611 500 Internal Server Error 15.6.1 8612 501 Not Implemented 15.6.2 8613 502 Bad Gateway 15.6.3 8614 503 Service Unavailable 15.6.4 8615 504 Gateway Timeout 15.6.5 8616 505 HTTP Version Not Supported 15.6.6 8617 ------- ------------------------------- --------- 8619 Table 8 8621 18.4. Field Name Registration 8623 This specification updates the HTTP related aspects of the existing 8624 registration procedures for message header fields defined in 8625 [RFC3864]. It defines both a new registration procedure and moves 8626 HTTP field definitions into a separate registry. 8628 Please create a new registry as outlined in Section 16.3.1. 8630 After creating the registry, all entries in the Permanent and 8631 Provisional Message Header Registries with the protocol 'http' are to 8632 be moved to it, with the following changes applied: 8634 1. The 'Applicable Protocol' field is to be omitted. 8636 2. Entries with a status of 'standard', 'experimental', 'reserved', 8637 or 'informational' are to have a status of 'permanent'. 8639 3. Provisional entries without a status are to have a status of 8640 'provisional'. 8642 4. Permanent entries without a status (after confirmation that the 8643 registration document did not define one) will have a status of 8644 'provisional'. The Expert(s) can choose to update their status 8645 if there is evidence that another is more appropriate. 8647 Please annotate the Permanent and Provisional Message Header 8648 registries to indicate that HTTP field name registrations have moved, 8649 with an appropriate link. 8651 After that is complete, please update the new registry with the field 8652 names listed in the following table. 8654 --------------------------- ------------ -------- ------------ 8655 Field Name Status Ref. Comments 8656 --------------------------- ------------ -------- ------------ 8657 Accept standard 12.5.1 8658 Accept-Charset deprecated 12.5.2 8659 Accept-Encoding standard 12.5.3 8660 Accept-Language standard 12.5.4 8661 Accept-Ranges standard 14.3 8662 Allow standard 10.2.1 8663 Authentication-Info standard 11.6.3 8664 Authorization standard 11.6.2 8665 Connection standard 7.6.1 8666 Content-Encoding standard 8.5 8667 Content-Language standard 8.6 8668 Content-Length standard 8.7 8669 Content-Location standard 8.8 8670 Content-Range standard 14.4 8671 Content-Type standard 8.4 8672 Date standard 10.2.2 8673 ETag standard 8.9.3 8674 Expect standard 10.1.1 8675 From standard 10.1.2 8676 Host standard 7.2 8677 If-Match standard 13.1.1 8678 If-Modified-Since standard 13.1.3 8679 If-None-Match standard 13.1.2 8680 If-Range standard 13.1.5 8681 If-Unmodified-Since standard 13.1.4 8682 Last-Modified standard 8.9.2 8683 Location standard 10.2.3 8684 Max-Forwards standard 7.6.2 8685 Proxy-Authenticate standard 11.7.1 8686 Proxy-Authentication-Info standard 11.7.3 8687 Proxy-Authorization standard 11.7.2 8688 Range standard 14.2 8689 Referer standard 10.1.3 8690 Retry-After standard 10.2.4 8691 Server standard 10.2.5 8692 TE standard 10.1.4 8693 Trailer standard 10.1.5 8694 Upgrade standard 7.8 8695 User-Agent standard 10.1.6 8696 Vary standard 12.5.5 8697 Via standard 7.6.3 8698 WWW-Authenticate standard 11.6.1 8699 * standard 12.5.5 (reserved) 8700 --------------------------- ------------ -------- ------------ 8702 Table 9 8704 The field name "*" is reserved, since using that name as an HTTP 8705 header field might conflict with its special semantics in the Vary 8706 header field (Section 12.5.5). 8708 Finally, please update the "Content-MD5" entry in the new registry to 8709 have a status of 'obsoleted' with references to Section 14.15 of 8710 [RFC2616] (for the definition of the header field) and Appendix B of 8711 [RFC7231] (which removed the field definition from the updated 8712 specification). 8714 18.5. Authentication Scheme Registration 8716 Please update the "Hypertext Transfer Protocol (HTTP) Authentication 8717 Scheme Registry" at with the registration procedure of Section 16.4.1. No 8719 authentication schemes are defined in this document. 8721 18.6. Content Coding Registration 8723 Please update the "HTTP Content Coding Registry" at 8724 with the 8725 registration procedure of Section 16.6.1 and the content coding names 8726 summarized in the table below. 8728 ------------ ------------------------------------------- --------- 8729 Name Description Ref. 8730 ------------ ------------------------------------------- --------- 8731 compress UNIX "compress" data format [Welch] 8.5.1.1 8732 deflate "deflate" compressed data ([RFC1951]) 8.5.1.2 8733 inside the "zlib" data format ([RFC1950]) 8734 gzip GZIP file format [RFC1952] 8.5.1.3 8735 identity Reserved 12.5.3 8736 x-compress Deprecated (alias for compress) 8.5.1.1 8737 x-gzip Deprecated (alias for gzip) 8.5.1.3 8738 ------------ ------------------------------------------- --------- 8740 Table 10 8742 18.7. Range Unit Registration 8744 Please update the "HTTP Range Unit Registry" at 8745 with the 8746 registration procedure of Section 16.5.1 and the range unit names 8747 summarized in the table below. 8749 ----------------- ---------------------------------- -------- 8750 Range Unit Name Description Ref. 8751 ----------------- ---------------------------------- -------- 8752 bytes a range of octets 14.1.2 8753 none reserved as keyword to indicate 14.3 8754 range requests are not supported 8755 ----------------- ---------------------------------- -------- 8757 Table 11 8759 18.8. Media Type Registration 8761 Please update the "Media Types" registry at 8762 with the registration 8763 information in Section 14.5 for the media type "multipart/ 8764 byteranges". 8766 18.9. Port Registration 8768 Please update the "Service Name and Transport Protocol Port Number" 8769 registry at for the services on ports 80 and 443 that use UDP or TCP 8771 to: 8773 1. use this document as "Reference", and 8775 2. when currently unspecified, set "Assignee" to "IESG" and 8776 "Contact" to "IETF_Chair". 8778 18.10. Upgrade Token Registration 8780 Please update the "Hypertext Transfer Protocol (HTTP) Upgrade Token 8781 Registry" at 8782 with the registration procedure of Section 16.7 and the upgrade token 8783 names summarized in the following table. 8785 ------ ------------------- ------------------------- ------ 8786 Name Description Expected Version Tokens Ref. 8787 ------ ------------------- ------------------------- ------ 8788 HTTP Hypertext any DIGIT.DIGIT (e.g, 2.5 8789 Transfer Protocol "2.0") 8790 ------ ------------------- ------------------------- ------ 8792 Table 12 8794 19. References 8796 19.1. Normative References 8798 [Caching] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 8799 Ed., "HTTP Caching", Work in Progress, Internet-Draft, 8800 draft-ietf-httpbis-cache-13, December 14, 2020, 8801 . 8803 [Messaging] 8804 Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 8805 Ed., "HTTP/1.1", Work in Progress, Internet-Draft, draft- 8806 ietf-httpbis-messaging-13, December 14, 2020, 8807 . 8810 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 8811 RFC 793, DOI 10.17487/RFC0793, September 1981, 8812 . 8814 [RFC1950] Deutsch, L.P. and J-L. Gailly, "ZLIB Compressed Data 8815 Format Specification version 3.3", RFC 1950, 8816 DOI 10.17487/RFC1950, May 1996, 8817 . 8819 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 8820 version 1.3", RFC 1951, DOI 10.17487/RFC1951, May 1996, 8821 . 8823 [RFC1952] Deutsch, P., Gailly, J-L., Adler, M., Deutsch, L.P., and 8824 G. Randers-Pehrson, "GZIP file format specification 8825 version 4.3", RFC 1952, DOI 10.17487/RFC1952, May 1996, 8826 . 8828 [RFC2045] Freed, N. and N.S. Borenstein, "Multipurpose Internet Mail 8829 Extensions (MIME) Part One: Format of Internet Message 8830 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 8831 . 8833 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 8834 Extensions (MIME) Part Two: Media Types", RFC 2046, 8835 DOI 10.17487/RFC2046, November 1996, 8836 . 8838 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 8839 Requirement Levels", BCP 14, RFC 2119, 8840 DOI 10.17487/RFC2119, March 1997, 8841 . 8843 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 8844 Resource Identifier (URI): Generic Syntax", STD 66, 8845 RFC 3986, DOI 10.17487/RFC3986, January 2005, 8846 . 8848 [RFC4647] Phillips, A., Ed. and M. Davis, Ed., "Matching of Language 8849 Tags", BCP 47, RFC 4647, DOI 10.17487/RFC4647, September 8850 2006, . 8852 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 8853 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 8854 . 8856 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 8857 Specifications: ABNF", STD 68, RFC 5234, 8858 DOI 10.17487/RFC5234, January 2008, 8859 . 8861 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 8862 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 8863 September 2009, . 8865 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 8866 Verification of Domain-Based Application Service Identity 8867 within Internet Public Key Infrastructure Using X.509 8868 (PKIX) Certificates in the Context of Transport Layer 8869 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 8870 2011, . 8872 [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in 8873 Internationalization in the IETF", BCP 166, RFC 6365, 8874 DOI 10.17487/RFC6365, September 2011, 8875 . 8877 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 8878 RFC 7405, DOI 10.17487/RFC7405, December 2014, 8879 . 8881 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 8882 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 8883 May 2017, . 8885 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 8886 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 8887 . 8889 [USASCII] American National Standards Institute, "Coded Character 8890 Set -- 7-bit American Standard Code for Information 8891 Interchange", ANSI X3.4, 1986. 8893 [Welch] Welch, T. A., "A Technique for High-Performance Data 8894 Compression", IEEE Computer 17(6), 8895 DOI 10.1109/MC.1984.1659158, June 1984, 8896 . 8898 19.2. Informative References 8900 [BCP13] Freed, N., Klensin, J., and T. Hansen, "Media Type 8901 Specifications and Registration Procedures", BCP 13, 8902 RFC 6838, January 2013, 8903 . 8905 [BCP178] Saint-Andre, P., Crocker, D., and M. Nottingham, 8906 "Deprecating the "X-" Prefix and Similar Constructs in 8907 Application Protocols", BCP 178, RFC 6648, June 2012, 8908 . 8910 [BCP35] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 8911 and Registration Procedures for URI Schemes", BCP 35, 8912 RFC 7595, June 2015, 8913 . 8915 [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving the 8916 CRIME Attack", July 2013, 8917 . 8920 [Bujlow] Bujlow, T., Carela-Espanol, V., Sole-Pareta, J., and P. 8921 Barlet-Ros, "A Survey on Web Tracking: Mechanisms, 8922 Implications, and Defenses", 8923 DOI 10.1109/JPROC.2016.2637878, Proceedings of the 8924 IEEE 105(8), August 2017, 8925 . 8927 [Err1912] RFC Errata, Erratum ID 1912, RFC 2978, 8928 . 8930 [Err5433] RFC Errata, Erratum ID 5433, RFC 2978, 8931 . 8933 [Georgiev] Georgiev, M., Iyengar, S., Jana, S., Anubhai, R., Boneh, 8934 D., and V. Shmatikov, "The Most Dangerous Code in the 8935 World: Validating SSL Certificates in Non-browser 8936 Software", DOI 10.1145/2382196.2382204, In Proceedings of 8937 the 2012 ACM Conference on Computer and Communications 8938 Security (CCS '12), pp. 38-49, October 2012, 8939 . 8941 [HTTP/0.9] Berners-Lee, T., "The Original HTTP as defined in 1991", 8942 October 1996, 8943 . 8945 [HTTP3] Bishop, M., "Hypertext Transfer Protocol Version 3 8946 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 8947 quic-http-32, October 20, 2020, 8948 . 8950 [ISO-8859-1] 8951 International Organization for Standardization, 8952 "Information technology -- 8-bit single-byte coded graphic 8953 character sets -- Part 1: Latin alphabet No. 1", ISO/ 8954 IEC 8859-1:1998, 1998. 8956 [Kri2001] Kristol, D., "HTTP Cookies: Standards, Privacy, and 8957 Politics", ACM Transactions on Internet Technology 1(2), 8958 November 2001, . 8960 [OWASP] van der Stock, A., Ed., "A Guide to Building Secure Web 8961 Applications and Web Services", The Open Web Application 8962 Security Project (OWASP) 2.0.1, July 27, 2005, 8963 . 8965 [REST] Fielding, R.T., "Architectural Styles and the Design of 8966 Network-based Software Architectures", 8967 Doctoral Dissertation, University of California, Irvine, 8968 September 2000, 8969 . 8971 [RFC1919] Chatel, M., "Classical versus Transparent IP Proxies", 8972 RFC 1919, DOI 10.17487/RFC1919, March 1996, 8973 . 8975 [RFC1945] Berners-Lee, T., Fielding, R.T., and H.F. Nielsen, 8976 "Hypertext Transfer Protocol -- HTTP/1.0", RFC 1945, 8977 DOI 10.17487/RFC1945, May 1996, 8978 . 8980 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 8981 Part Three: Message Header Extensions for Non-ASCII Text", 8982 RFC 2047, DOI 10.17487/RFC2047, November 1996, 8983 . 8985 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T. 8986 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", 8987 RFC 2068, DOI 10.17487/RFC2068, January 1997, 8988 . 8990 [RFC2145] Mogul, J.C., Fielding, R.T., Gettys, J., and H.F. Nielsen, 8991 "Use and Interpretation of HTTP Version Numbers", 8992 RFC 2145, DOI 10.17487/RFC2145, May 1997, 8993 . 8995 [RFC2295] Holtman, K. and A.H. Mutz, "Transparent Content 8996 Negotiation in HTTP", RFC 2295, DOI 10.17487/RFC2295, 8997 March 1998, . 8999 [RFC2324] Masinter, L., "Hyper Text Coffee Pot Control Protocol 9000 (HTCPCP/1.0)", RFC 2324, DOI 10.17487/RFC2324, April 1, 9001 1998, . 9003 [RFC2557] Palme, F., Hopmann, A., Shelness, N., and E. Stefferud, 9004 "MIME Encapsulation of Aggregate Documents, such as HTML 9005 (MHTML)", RFC 2557, DOI 10.17487/RFC2557, March 1999, 9006 . 9008 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 9009 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 9010 Transfer Protocol -- HTTP/1.1", RFC 2616, 9011 DOI 10.17487/RFC2616, June 1999, 9012 . 9014 [RFC2617] Franks, J., Hallam-Baker, P.M., Hostetler, J.L., Lawrence, 9015 S.D., Leach, P.J., Luotonen, A., and L. Stewart, "HTTP 9016 Authentication: Basic and Digest Access Authentication", 9017 RFC 2617, DOI 10.17487/RFC2617, June 1999, 9018 . 9020 [RFC2774] Frystyk, H., Leach, P., and S. Lawrence, "An HTTP 9021 Extension Framework", RFC 2774, DOI 10.17487/RFC2774, 9022 February 2000, . 9024 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 9025 DOI 10.17487/RFC2818, May 2000, 9026 . 9028 [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration 9029 Procedures", BCP 19, RFC 2978, DOI 10.17487/RFC2978, 9030 October 2000, . 9032 [RFC3040] Cooper, I., Melve, I., and G. Tomlinson, "Internet Web 9033 Replication and Caching Taxonomy", RFC 3040, 9034 DOI 10.17487/RFC3040, January 2001, 9035 . 9037 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 9038 Procedures for Message Header Fields", BCP 90, RFC 3864, 9039 DOI 10.17487/RFC3864, September 2004, 9040 . 9042 [RFC4033] Arends, R., Austein, R., Larson, M., Massey, D., and S. 9043 Rose, "DNS Security Introduction and Requirements", 9044 RFC 4033, DOI 10.17487/RFC4033, March 2005, 9045 . 9047 [RFC4559] Jaganathan, K., Zhu, L., and J. Brezak, "SPNEGO-based 9048 Kerberos and NTLM HTTP Authentication in Microsoft 9049 Windows", RFC 4559, DOI 10.17487/RFC4559, June 2006, 9050 . 9052 [RFC4918] Dusseault, L.M., Ed., "HTTP Extensions for Web Distributed 9053 Authoring and Versioning (WebDAV)", RFC 4918, 9054 DOI 10.17487/RFC4918, June 2007, 9055 . 9057 [RFC5322] Resnick, P., "Internet Message Format", RFC 5322, 9058 DOI 10.17487/RFC5322, October 2008, 9059 . 9061 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 9062 RFC 5789, DOI 10.17487/RFC5789, March 2010, 9063 . 9065 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 9066 "Network Time Protocol Version 4: Protocol and Algorithms 9067 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 9068 . 9070 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 9071 DOI 10.17487/RFC6265, April 2011, 9072 . 9074 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 9075 DOI 10.17487/RFC6454, December 2011, 9076 . 9078 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 9079 Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, 9080 . 9082 [RFC7230] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9083 Transfer Protocol (HTTP/1.1): Message Syntax and Routing", 9084 RFC 7230, DOI 10.17487/RFC7230, June 2014, 9085 . 9087 [RFC7231] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9088 Transfer Protocol (HTTP/1.1): Semantics and Content", 9089 RFC 7231, DOI 10.17487/RFC7231, June 2014, 9090 . 9092 [RFC7232] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9093 Transfer Protocol (HTTP/1.1): Conditional Requests", 9094 RFC 7232, DOI 10.17487/RFC7232, June 2014, 9095 . 9097 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. F. Reschke, Ed., 9098 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 9099 RFC 7233, DOI 10.17487/RFC7233, June 2014, 9100 . 9102 [RFC7235] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9103 Transfer Protocol (HTTP/1.1): Authentication", RFC 7235, 9104 DOI 10.17487/RFC7235, June 2014, 9105 . 9107 [RFC7538] Reschke, J. F., "The Hypertext Transfer Protocol Status 9108 Code 308 (Permanent Redirect)", RFC 7538, 9109 DOI 10.17487/RFC7538, April 2015, 9110 . 9112 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 9113 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 9114 DOI 10.17487/RFC7540, May 2015, 9115 . 9117 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 9118 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 9119 . 9121 [RFC7578] Masinter, L., "Returning Values from Forms: multipart/ 9122 form-data", RFC 7578, DOI 10.17487/RFC7578, July 2015, 9123 . 9125 [RFC7615] Reschke, J. F., "HTTP Authentication-Info and Proxy- 9126 Authentication-Info Response Header Fields", RFC 7615, 9127 DOI 10.17487/RFC7615, September 2015, 9128 . 9130 [RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP 9131 Digest Access Authentication", RFC 7616, 9132 DOI 10.17487/RFC7616, September 2015, 9133 . 9135 [RFC7617] Reschke, J. F., "The 'Basic' HTTP Authentication Scheme", 9136 RFC 7617, DOI 10.17487/RFC7617, September 2015, 9137 . 9139 [RFC7694] Reschke, J. F., "Hypertext Transfer Protocol (HTTP) 9140 Client-Initiated Content-Encoding", RFC 7694, 9141 DOI 10.17487/RFC7694, November 2015, 9142 . 9144 [RFC7838] Nottingham, M., McManus, P., and J. Reschke, "HTTP 9145 Alternative Services", RFC 7838, DOI 10.17487/RFC7838, 9146 April 2016, . 9148 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 9149 Writing an IANA Considerations Section in RFCs", BCP 26, 9150 RFC 8126, DOI 10.17487/RFC8126, June 2017, 9151 . 9153 [RFC8187] Reschke, J. F., "Indicating Character Encoding and 9154 Language for HTTP Header Field Parameters", RFC 8187, 9155 DOI 10.17487/RFC8187, September 2017, 9156 . 9158 [RFC8246] McManus, P., "HTTP Immutable Responses", RFC 8246, 9159 DOI 10.17487/RFC8246, September 2017, 9160 . 9162 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 9163 DOI 10.17487/RFC8288, October 2017, 9164 . 9166 [RFC8336] Nottingham, M. and E. Nygren, "The ORIGIN HTTP/2 Frame", 9167 RFC 8336, DOI 10.17487/RFC8336, March 2018, 9168 . 9170 [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers 9171 (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, 9172 . 9174 [Sniffing] WHATWG, "MIME Sniffing", 9175 . 9177 Appendix A. Collected ABNF 9179 In the collected ABNF below, list rules are expanded as per 9180 Section 5.6.1.1. 9182 Accept = [ ( media-range [ accept-params ] ) *( OWS "," OWS ( 9183 media-range [ accept-params ] ) ) ] 9184 Accept-Charset = [ ( ( charset / "*" ) [ weight ] ) *( OWS "," OWS ( 9185 ( charset / "*" ) [ weight ] ) ) ] 9186 Accept-Encoding = [ ( codings [ weight ] ) *( OWS "," OWS ( codings [ 9187 weight ] ) ) ] 9188 Accept-Language = [ ( language-range [ weight ] ) *( OWS "," OWS ( 9189 language-range [ weight ] ) ) ] 9190 Accept-Ranges = acceptable-ranges 9191 Allow = [ method *( OWS "," OWS method ) ] 9192 Authentication-Info = [ auth-param *( OWS "," OWS auth-param ) ] 9193 Authorization = credentials 9195 BWS = OWS 9197 Connection = [ connection-option *( OWS "," OWS connection-option ) 9198 ] 9199 Content-Encoding = [ content-coding *( OWS "," OWS content-coding ) 9200 ] 9201 Content-Language = [ language-tag *( OWS "," OWS language-tag ) ] 9202 Content-Length = 1*DIGIT 9203 Content-Location = absolute-URI / partial-URI 9204 Content-Range = range-unit SP ( range-resp / unsatisfied-range ) 9205 Content-Type = media-type 9207 Date = HTTP-date 9209 ETag = entity-tag 9210 Expect = [ expectation *( OWS "," OWS expectation ) ] 9212 From = mailbox 9214 GMT = %x47.4D.54 ; GMT 9216 HTTP-date = IMF-fixdate / obs-date 9217 Host = uri-host [ ":" port ] 9219 IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT 9220 If-Match = "*" / [ entity-tag *( OWS "," OWS entity-tag ) ] 9221 If-Modified-Since = HTTP-date 9222 If-None-Match = "*" / [ entity-tag *( OWS "," OWS entity-tag ) ] 9223 If-Range = entity-tag / HTTP-date 9224 If-Unmodified-Since = HTTP-date 9225 Last-Modified = HTTP-date 9226 Location = URI-reference 9228 Max-Forwards = 1*DIGIT 9230 OWS = *( SP / HTAB ) 9232 Proxy-Authenticate = [ challenge *( OWS "," OWS challenge ) ] 9233 Proxy-Authentication-Info = [ auth-param *( OWS "," OWS auth-param ) 9234 ] 9235 Proxy-Authorization = credentials 9237 RWS = 1*( SP / HTAB ) 9238 Range = ranges-specifier 9239 Referer = absolute-URI / partial-URI 9240 Retry-After = HTTP-date / delay-seconds 9242 Server = product *( RWS ( product / comment ) ) 9244 TE = [ t-codings *( OWS "," OWS t-codings ) ] 9245 Trailer = [ field-name *( OWS "," OWS field-name ) ] 9247 URI-reference = 9248 Upgrade = [ protocol *( OWS "," OWS protocol ) ] 9249 User-Agent = product *( RWS ( product / comment ) ) 9251 Vary = [ ( "*" / field-name ) *( OWS "," OWS ( "*" / field-name ) ) 9252 ] 9253 Via = [ ( received-protocol RWS received-by [ RWS comment ] ) *( OWS 9254 "," OWS ( received-protocol RWS received-by [ RWS comment ] ) ) ] 9256 WWW-Authenticate = [ challenge *( OWS "," OWS challenge ) ] 9258 absolute-URI = 9259 absolute-path = 1*( "/" segment ) 9260 accept-ext = OWS ";" OWS token [ "=" ( token / quoted-string ) ] 9261 accept-params = weight *accept-ext 9262 acceptable-ranges = ( range-unit *( OWS "," OWS range-unit ) ) / 9263 "none" 9264 asctime-date = day-name SP date3 SP time-of-day SP year 9265 auth-param = token BWS "=" BWS ( token / quoted-string ) 9266 auth-scheme = token 9267 authority = 9269 challenge = auth-scheme [ 1*SP ( token68 / [ auth-param *( OWS "," 9270 OWS auth-param ) ] ) ] 9271 charset = token 9272 codings = content-coding / "identity" / "*" 9273 comment = "(" *( ctext / quoted-pair / comment ) ")" 9274 complete-length = 1*DIGIT 9275 connection-option = token 9276 content-coding = token 9277 credentials = auth-scheme [ 1*SP ( token68 / [ auth-param *( OWS "," 9278 OWS auth-param ) ] ) ] 9279 ctext = HTAB / SP / %x21-27 ; '!'-''' 9280 / %x2A-5B ; '*'-'[' 9281 / %x5D-7E ; ']'-'~' 9282 / obs-text 9284 date1 = day SP month SP year 9285 date2 = day "-" month "-" 2DIGIT 9286 date3 = month SP ( 2DIGIT / ( SP DIGIT ) ) 9287 day = 2DIGIT 9288 day-name = %x4D.6F.6E ; Mon 9289 / %x54.75.65 ; Tue 9290 / %x57.65.64 ; Wed 9291 / %x54.68.75 ; Thu 9292 / %x46.72.69 ; Fri 9293 / %x53.61.74 ; Sat 9294 / %x53.75.6E ; Sun 9295 day-name-l = %x4D.6F.6E.64.61.79 ; Monday 9296 / %x54.75.65.73.64.61.79 ; Tuesday 9297 / %x57.65.64.6E.65.73.64.61.79 ; Wednesday 9298 / %x54.68.75.72.73.64.61.79 ; Thursday 9299 / %x46.72.69.64.61.79 ; Friday 9300 / %x53.61.74.75.72.64.61.79 ; Saturday 9301 / %x53.75.6E.64.61.79 ; Sunday 9302 delay-seconds = 1*DIGIT 9304 entity-tag = [ weak ] opaque-tag 9305 etagc = "!" / %x23-7E ; '#'-'~' 9306 / obs-text 9307 expectation = token [ "=" ( token / quoted-string ) parameters ] 9309 field-content = field-vchar [ 1*( SP / HTAB / field-vchar ) 9310 field-vchar ] 9311 field-name = token 9312 field-value = *field-content 9313 field-vchar = VCHAR / obs-text 9314 first-pos = 1*DIGIT 9316 hour = 2DIGIT 9317 http-URI = "http://" authority path-abempty [ "?" query ] 9318 https-URI = "https://" authority path-abempty [ "?" query ] 9320 incl-range = first-pos "-" last-pos 9321 int-range = first-pos "-" [ last-pos ] 9323 language-range = 9324 language-tag = 9325 last-pos = 1*DIGIT 9327 mailbox = 9328 media-range = ( "*/*" / ( type "/*" ) / ( type "/" subtype ) ) 9329 parameters 9330 media-type = type "/" subtype parameters 9331 method = token 9332 minute = 2DIGIT 9333 month = %x4A.61.6E ; Jan 9334 / %x46.65.62 ; Feb 9335 / %x4D.61.72 ; Mar 9336 / %x41.70.72 ; Apr 9337 / %x4D.61.79 ; May 9338 / %x4A.75.6E ; Jun 9339 / %x4A.75.6C ; Jul 9340 / %x41.75.67 ; Aug 9341 / %x53.65.70 ; Sep 9342 / %x4F.63.74 ; Oct 9343 / %x4E.6F.76 ; Nov 9344 / %x44.65.63 ; Dec 9346 obs-date = rfc850-date / asctime-date 9347 obs-text = %x80-FF 9348 opaque-tag = DQUOTE *etagc DQUOTE 9349 other-range = 1*( %x21-2B ; '!'-'+' 9350 / %x2D-7E ; '-'-'~' 9351 ) 9353 parameter = parameter-name "=" parameter-value 9354 parameter-name = token 9355 parameter-value = ( token / quoted-string ) 9356 parameters = *( OWS ";" OWS [ parameter ] ) 9357 partial-URI = relative-part [ "?" query ] 9358 path-abempty = 9359 port = 9360 product = token [ "/" product-version ] 9361 product-version = token 9362 protocol = protocol-name [ "/" protocol-version ] 9363 protocol-name = token 9364 protocol-version = token 9365 pseudonym = token 9367 qdtext = HTAB / SP / "!" / %x23-5B ; '#'-'[' 9368 / %x5D-7E ; ']'-'~' 9369 / obs-text 9370 query = 9371 quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) 9372 quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE 9373 qvalue = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] ) 9375 range-resp = incl-range "/" ( complete-length / "*" ) 9376 range-set = range-spec *( OWS "," OWS range-spec ) 9377 range-spec = int-range / suffix-range / other-range 9378 range-unit = token 9379 ranges-specifier = range-unit "=" range-set 9380 received-by = pseudonym [ ":" port ] 9381 received-protocol = [ protocol-name "/" ] protocol-version 9382 relative-part = 9383 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 9385 second = 2DIGIT 9386 segment = 9387 subtype = token 9388 suffix-length = 1*DIGIT 9389 suffix-range = "-" suffix-length 9391 t-codings = "trailers" / ( transfer-coding [ weight ] ) 9392 tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / 9393 "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA 9394 time-of-day = hour ":" minute ":" second 9395 token = 1*tchar 9396 token68 = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" ) 9397 *"=" 9398 transfer-coding = token *( OWS ";" OWS transfer-parameter ) 9399 transfer-parameter = token BWS "=" BWS ( token / quoted-string ) 9400 type = token 9402 unsatisfied-range = "*/" complete-length 9403 uri-host = 9405 weak = %x57.2F ; W/ 9406 weight = OWS ";" OWS "q=" qvalue 9408 year = 4DIGIT 9410 Appendix B. Changes from previous RFCs 9412 B.1. Changes from RFC 2818 9414 None yet. 9416 B.2. Changes from RFC 7230 9418 The sections introducing HTTP's design goals, history, architecture, 9419 conformance criteria, protocol versioning, URIs, message routing, and 9420 header fields have been moved here (without substantive change). 9422 The description of an origin and authoritative access to origin 9423 servers has been extended for both "http" and "https" URIs to account 9424 for alternative services and secured connections that are not 9425 necessarily based on TCP. (Section 4.2.1, Section 4.2.2, 9426 Section 4.3.1, Section 7.3.3) 9428 "Field value" now refers to the value after multiple field lines are 9429 combined with commas - by far the most common use. To refer to a 9430 single header line's value, use "field line value". (Section 6.3) 9432 Parameters in media type, media range, and expectation can be empty 9433 via one or more trailing semicolons. (Section 5.6.6) 9435 Trailer field semantics now transcend the specifics of chunked 9436 encoding. Use of trailer fields has been further limited to only 9437 allow generation as a trailer field when the sender knows the field 9438 defines that usage and to only allow merging into the header section 9439 if the recipient knows the corresponding field definition permits and 9440 defines how to merge. In all other cases, implementations are 9441 encouraged to either store the trailer fields separately or discard 9442 them instead of merging. (Section 6.5.1) 9444 Trailer fields can now potentially appear as multiple trailer 9445 sections, if allowed by the HTTP version and framing in use, with 9446 processing described as being iterative as each section is received. 9447 (Section 6.5.2) 9449 Made the priority of the absolute form of the request URI over the 9450 Host header by origin servers explicit, to align with proxy handling. 9451 (Section 7.2) 9453 The grammar definition for the Via field's "received-by" was expanded 9454 in 7230 due to changes in the URI grammar for host [RFC3986] that are 9455 not desirable for Via. For simplicity, we have removed uri-host from 9456 the received-by production because it can be encompassed by the 9457 existing grammar for pseudonym. In particular, this change removed 9458 comma from the allowed set of charaters for a host name in received- 9459 by. (Section 7.6.3) 9461 B.3. Changes from RFC 7231 9463 Minimum URI lengths to be supported by implementations are now 9464 recommended. (Section 3.1) 9466 Clarify that control characters in field values are to be rejected or 9467 mapped to SP. (Section 5.5) 9469 Parameters in media type, media range, and expectation can be empty 9470 via one or more trailing semicolons. (Section 5.6.6) 9472 An abstract data type for HTTP messages has been introduced to define 9473 the components of a message and their semantics as an abstraction 9474 across multiple HTTP versions, rather than in terms of the specific 9475 syntax form of HTTP/1.1 in [Messaging], and reflect the contents 9476 after the message is parsed. This makes it easier to distinguish 9477 between requirements on the payload data (what is conveyed) versus 9478 requirements on the messaging syntax (how it is conveyed) and avoids 9479 baking limitations of early protocol versions into the future of 9480 HTTP. (Section 6) 9482 The term "effective request URI" has been replaced with "target URI". 9483 (Section 7.1) 9485 Restrictions on client retries have been loosened, to reflect 9486 implementation behavior. (Section 9.2.2) 9488 Clarified that request bodies on GET and DELETE are not 9489 interoperable. (Section 9.3.1, Section 9.3.5) 9491 Removed a superfluous requirement about setting Content-Length from 9492 the description of the OPTIONS method. (Section 9.3.7) 9494 Restore list-based grammar for Expect for compatibility with RFC 9495 2616. (Section 10.1.1) 9497 The semantics of "*" in the Vary header field when other values are 9498 present was clarified. (Section 12.5.5) 9500 Allow Accept and Accept-Encoding in response messages; the latter was 9501 introduced by [RFC7694]. (Section 12.3) 9503 Range units are compared in a case insensitive fashion. 9504 (Section 14.1) 9506 The process of creating a redirected request has been clarified. 9507 (Section 15.4) 9508 Added status code 308 (previously defined in [RFC7538]) so that it's 9509 defined closer to status codes 301, 302, and 307. (Section 15.4.9) 9511 Added status code 422 (previously defined in Section 11.2 of 9512 [RFC4918]) because of its general applicability. (Section 15.5.20) 9514 B.4. Changes from RFC 7232 9516 Previous revisions of HTTP imposed an arbitrary 60-second limit on 9517 the determination of whether Last-Modified was a strong validator to 9518 guard against the possibility that the Date and Last-Modified values 9519 are generated from different clocks or at somewhat different times 9520 during the preparation of the response. This specification has 9521 relaxed that to allow reasonable discretion. (Section 8.9.2.2) 9523 Removed edge case requirement on If-Match and If-Unmodified-Since 9524 that a validator not be sent in a 2xx response when validation fails 9525 and the server decides that the same change request has already been 9526 applied. (Section 13.1.1 and Section 13.1.4) 9528 Clarified that If-Unmodified-Since doesn't apply to a resource 9529 without a concept of modification time. (Section 13.1.4) 9531 Preconditions can now be evaluated before the request payload is 9532 processed rather than waiting until the response would otherwise be 9533 successful. (Section 13.2) 9535 B.5. Changes from RFC 7233 9537 Refactored the range-unit and ranges-specifier grammars to simplify 9538 and reduce artificial distinctions between bytes and other 9539 (extension) range units, removing the overlapping grammar of other- 9540 range-unit by defining range units generically as a token and placing 9541 extensions within the scope of a range-spec (other-range). This 9542 disambiguates the role of list syntax (commas) in all range sets, 9543 including extension range units, for indicating a range-set of more 9544 than one range. Moving the extension grammar into range specifiers 9545 also allows protocol specific to byte ranges to be specified 9546 separately. 9548 It is now possible to define Range handling on extension methods. 9549 (Section 14.2) 9551 B.6. Changes from RFC 7235 9553 None yet. 9555 B.7. Changes from RFC 7538 9557 None yet. 9559 B.8. Changes from RFC 7615 9561 None yet. 9563 B.9. Changes from RFC 7694 9565 This specification includes the extension defined in [RFC7694], but 9566 leaves out examples and deployment considerations. 9568 Appendix C. Change Log 9570 This section is to be removed before publishing as an RFC. 9572 C.1. Between RFC723x and draft 00 9574 The changes were purely editorial: 9576 o Change boilerplate and abstract to indicate the "draft" status, 9577 and update references to ancestor specifications. 9579 o Remove version "1.1" from document title, indicating that this 9580 specification applies to all HTTP versions. 9582 o Adjust historical notes. 9584 o Update links to sibling specifications. 9586 o Replace sections listing changes from RFC 2616 by new empty 9587 sections referring to RFC 723x. 9589 o Remove acknowledgements specific to RFC 723x. 9591 o Move "Acknowledgements" to the very end and make them unnumbered. 9593 C.2. Since draft-ietf-httpbis-semantics-00 9595 The changes in this draft are editorial, with respect to HTTP as a 9596 whole, to merge core HTTP semantics into this document: 9598 o Merged introduction, architecture, conformance, and ABNF 9599 extensions from RFC 7230 (Messaging). 9601 o Rearranged architecture to extract conformance, http(s) schemes, 9602 and protocol versioning into a separate major section. 9604 o Moved discussion of MIME differences to [Messaging] since that is 9605 primarily concerned with transforming 1.1 messages. 9607 o Merged entire content of RFC 7232 (Conditional Requests). 9609 o Merged entire content of RFC 7233 (Range Requests). 9611 o Merged entire content of RFC 7235 (Auth Framework). 9613 o Moved all extensibility tips, registration procedures, and 9614 registry tables from the IANA considerations to normative 9615 sections, reducing the IANA considerations to just instructions 9616 that will be removed prior to publication as an RFC. 9618 C.3. Since draft-ietf-httpbis-semantics-01 9620 o Improve [Welch] citation () 9623 o Remove HTTP/1.1-ism about Range Requests 9624 () 9626 o Cite RFC 8126 instead of RFC 5226 () 9629 o Cite RFC 7538 instead of RFC 7238 () 9632 o Cite RFC 8288 instead of RFC 5988 () 9635 o Cite RFC 8187 instead of RFC 5987 () 9638 o Cite RFC 7578 instead of RFC 2388 () 9641 o Cite RFC 7595 instead of RFC 4395 () 9644 o improve ABNF readability for qdtext (, ) 9647 o Clarify "resource" vs "representation" in definition of status 9648 code 416 (, 9649 ) 9651 o Resolved erratum 4072, no change needed here 9652 (, 9653 ) 9655 o Clarify DELETE status code suggestions 9656 (, 9657 ) 9659 o In Section 14.4, fix ABNF for "other-range-resp" to use VCHAR 9660 instead of CHAR (, 9661 ) 9663 o Resolved erratum 5162, no change needed here 9664 (, 9665 ) 9667 o Replace "response code" with "response status code" and "status- 9668 code" (the ABNF production name from the HTTP/1.1 message format) 9669 by "status code" (, 9670 ) 9672 o Added a missing word in Section 15.4 (, ) 9675 o In Section 5.6.1, fixed an example that had trailing whitespace 9676 where it shouldn't (, ) 9679 o In Section 15.3.7, remove words that were potentially misleading 9680 with respect to the relation to the requested ranges 9681 (, 9682 ) 9684 C.4. Since draft-ietf-httpbis-semantics-02 9686 o Included (Proxy-)Auth-Info header field definition from RFC 7615 9687 () 9689 o In Section 9.3.3, clarify POST caching 9690 () 9692 o Add Section 15.5.19 to reserve the 418 status code 9693 () 9695 o In Section 3.3 and Section 10.1.1, clarified when a response can 9696 be sent () 9698 o In Section 8.4.2, explain the difference between the "token" 9699 production, the RFC 2978 ABNF for charset names, and the actual 9700 registration practice (, ) 9703 o In Section 3.1, removed the fragment component in the URI scheme 9704 definitions as per Section 4.3 of [RFC3986], furthermore moved 9705 fragment discussion into a separate section 9706 (, 9707 , ) 9710 o In Section 2.5, add language about minor HTTP version number 9711 defaulting () 9713 o Added Section 15.5.20 for status code 422, previously defined in 9714 Section 11.2 of [RFC4918] () 9717 o In Section 15.5.17, fixed prose about byte range comparison 9718 (, 9719 ) 9721 o In Section 3.3, explain that request/response correlation is 9722 version specific () 9725 C.5. Since draft-ietf-httpbis-semantics-03 9727 o In Section 15.4.9, include status code 308 from RFC 7538 9728 () 9730 o In Section 8.4.1, clarify that the charset parameter value is 9731 case-insensitive due to the definition in RFC 2046 9732 () 9734 o Define a separate registry for HTTP header field names 9735 () 9737 o In Section 12.1, refactor and clarify description of wildcard 9738 ("*") handling () 9740 o Deprecate Accept-Charset () 9743 o In Section 13.2, mention Cache-Control: immutable 9744 () 9746 o In Section 5.3, clarify when header field combination is allowed 9747 () 9749 o In Section 18.4, instruct IANA to mark Content-MD5 as obsolete 9750 () 9752 o Use RFC 7405 ABNF notation for case-sensitive string constants 9753 () 9755 o Rework Section 3.3 to be more version-independent 9756 () 9758 o In Section 9.3.5, clarify that DELETE needs to be successful to 9759 invalidate cache (, ) 9762 C.6. Since draft-ietf-httpbis-semantics-04 9764 o In Section 5.5, fix field-content ABNF 9765 (, 9766 ) 9768 o Move Section 5.6.6 into its own section 9769 () 9771 o In Section 8.4, reference MIME Sniffing 9772 () 9774 o In Section 5.6.1, simplify the #rule mapping for recipients 9775 (, 9776 ) 9778 o In Section 9.3.7, remove misleading text about "extension" of HTTP 9779 is needed to define method payloads () 9782 o Fix editorial issue in Section 8 () 9785 o In Section 15.5.20, rephrase language not to use "entity" anymore, 9786 and also avoid lowercase "may" () 9789 o Move discussion of retries from [Messaging] into Section 9.2.2 9790 () 9792 C.7. Since draft-ietf-httpbis-semantics-05 9793 o Moved transport-independent part of the description of trailers 9794 into Section 6.5 () 9796 o Loosen requirements on retries based upon implementation behavior 9797 () 9799 o In Section 18.9, update IANA port registry for TCP/UDP on ports 80 9800 and 443 () 9802 o In Section 16.3.3, revise guidelines for new header field names 9803 () 9805 o In Section 9.2.3, remove concept of "cacheable methods" in favor 9806 of prose (, 9807 ) 9809 o In Section 17.1, mention that the concept of authority can be 9810 modified by protocol extensions () 9813 o Create new subsection on payload in Section 6.4, taken from 9814 portions of message body () 9817 o Moved definition of "Whitespace" into new container "Generic 9818 Syntax" () 9820 o In Section 3.1, recommend minimum URI size support for 9821 implementations () 9823 o In Section 14.1, refactored the range-unit and ranges-specifier 9824 grammars (, 9825 ) 9827 o In Section 9.3.1, caution against a request payload more strongly 9828 () 9830 o Reorganized text in Section 16.3.3 () 9833 o In Section 15.5.4, replace "authorize" with "fulfill" 9834 () 9836 o In Section 9.3.7, removed a misleading statement about Content- 9837 Length (, 9838 ) 9840 o In Section 17.1, add text from RFC 2818 9841 () 9843 o Changed "cacheable by default" to "heuristically cacheable" 9844 throughout () 9846 C.8. Since draft-ietf-httpbis-semantics-06 9848 o In Section 7.6.3, simplify received-by grammar (and disallow comma 9849 character) () 9851 o In Section 5.1, give guidance on interoperable field names 9852 () 9854 o In Section 5.6.3, define the semantics and possible replacement of 9855 whitespace when it is known to occur (, ) 9858 o In Section 6.3, introduce field terminology and distinguish 9859 between field line values and field values; use terminology 9860 consistently throughout () 9863 o Moved #rule definition into Section 5.5 and whitespace into 9864 Section 2.1 () 9866 o In Section 14.1, explicitly call out range unit names as case- 9867 insensitive, and encourage registration 9868 () 9870 o In Section 8.5.1, explicitly call out content codings as case- 9871 insensitive, and encourage registration 9872 () 9874 o In Section 5.1, explicitly call out field names as case- 9875 insensitive () 9877 o In Section 17.12, cite [Bujlow] () 9880 o In Section 15, formally define "final" and "interim" status codes 9881 () 9883 o In Section 9.3.5, caution against a request payload more strongly 9884 () 9886 o In Section 8.9.3, note that Etag can be used in trailers 9887 () 9889 o In Section 18.4, consider reserved fields as well 9890 () 9892 o In Section 4.2.4, be more correct about what was deprecated by RFC 9893 3986 (, 9894 ) 9896 o In Section 5.3, recommend comma SP when combining field lines 9897 () 9899 o In Section 7.2, make explicit requirements on origin server to use 9900 authority from absolute-form when available 9901 () 9903 o In Section 4.2.1, Section 4.2.2, Section 4.3.1, and Section 7.3.3, 9904 refactored schemes to define origin and authoritative access to an 9905 origin server for both "http" and "https" URIs to account for 9906 alternative services and secured connections that are not 9907 necessarily based on TCP () 9910 o In Section 2.2, reference RFC 8174 as well 9911 () 9913 C.9. Since draft-ietf-httpbis-semantics-07 9915 o In Section 14.2, explicitly reference the definition of 9916 representation data as including any content codings 9917 () 9919 o Move TE: trailers from [Messaging] into Section 6.5.1 9920 () 9922 o In Section 8.7, adjust requirements for handling multiple content- 9923 length values () 9925 o In Section 13.1.1 and Section 13.1.2, clarified condition 9926 evaluation () 9928 o In Section 5.5, remove concept of obs-fold, as that is 9929 HTTP/1-specific () 9931 o In Section 12, introduce the concept of request payload 9932 negotiation (Section 12.3) and define for Accept-Encoding 9933 () 9935 o In Section 15.3.6, Section 15.5.9, and Section 15.5.14, remove 9936 HTTP/1-specific, connection-related requirements 9937 () 9939 o In Section 9.3.6, correct language about what is forwarded 9940 () 9942 o Throughout, replace "effective request URI", "request-target" and 9943 similar with "target URI" () 9946 o In Section 16.3.3 and Section 16.2.2, describe how extensions 9947 should consider scope of applicability 9948 () 9950 o In Section 3.3, don't rely on the HTTP/1.1 Messaging specification 9951 to define "message" () 9954 o In Section 8.8 and Section 10.1.3, note that URL resolution is 9955 necessary () 9957 o In Section 8, explicitly reference 206 as one of the status codes 9958 that provide representation data () 9961 o In Section 13.1.4, refine requirements so that they don't apply to 9962 resources without a concept of modification time 9963 () 9965 o In Section 11.7.1, specify the scope as a request, not a target 9966 resource () 9968 o In Section 3.3, introduce concept of "complete" messages 9969 () 9971 o In Section 7.1, Section 9.3.6, and Section 9.3.7, refine use of 9972 "request target" () 9975 o Throughout, remove "status-line" and "request-line", as these are 9976 HTTP/1.1-specific () 9979 C.10. Since draft-ietf-httpbis-semantics-08 9980 o In Section 15.5.17, remove duplicate definition of what makes a 9981 range satisfiable and refer instead to each range unit's 9982 definition () 9984 o In Section 14.1.2 and Section 14.2, clarify that a selected 9985 representation of zero length can only be satisfiable as a suffix 9986 range and that a server can still ignore Range for that case 9987 () 9989 o In Section 12.5.1 and Section 15.5.16, allow "Accept" as response 9990 field () 9992 o Appendix A now uses the sender variant of the "#" list expansion 9993 () 9995 o In Section 12.5.5, make the field list-based even when "*" is 9996 present () 9998 o In Section 16.3.1, add optional "Comments" entry 9999 () 10001 o In Section 18.4, reserve "*" as field name 10002 () 10004 o In Section 18.2, reserve "*" as method name 10005 () 10007 o In Section 13.1.1 and Section 13.1.2, state that multiple "*" is 10008 unlikely to be interoperable () 10011 o In Section 12.5.1, avoid use of obsolete media type parameter on 10012 text/html (, 10013 ) 10015 o Rephrase prose in Section 3.3 to become version-agnostic 10016 () 10018 o In Section 5.5, instruct recipients how to deal with control 10019 characters in field values () 10022 o In Section 5.5, update note about field ABNF 10023 () 10025 o Add Section 16 about Extending and Versioning HTTP 10026 () 10028 o In Section 15.1, include status 308 in list of heuristically 10029 cacheable status codes () 10032 o In Section 8.5, make it clearer that "identity" is not to be 10033 included () 10035 C.11. Since draft-ietf-httpbis-semantics-09 10037 o Switch to xml2rfc v3 mode for draft generation 10038 () 10040 C.12. Since draft-ietf-httpbis-semantics-10 10042 o In Section 17.6, mention compression attacks 10043 () 10045 o In Section 16.6.1, advise to make new content codings self- 10046 descriptive () 10048 o In Section 5.6.6, introduced the "parameters" ABNF rule, allowing 10049 empty parameters and trailing semicolons within media type, media 10050 range, and expectation () 10053 o In Section 15.4, explain how to create a redirected request 10054 () 10056 o In Section 8.4, defined error handling for multiple members 10057 () 10059 o In Section 1, revise the introduction and introduce HTTP/2 and 10060 HTTP/3 () 10062 o In Section 8.7, added a definition for Content-Length that 10063 encompasses its various roles in describing message payload or 10064 selected representation length; in Section 15.3.7, noted that 10065 Content-Length counts only the message payload (not the selected 10066 representation) and that the representation length is in each 10067 Content-Range () 10069 o Noted that "WWW-Authenticate" with more than one value on a line 10070 is sometimes not interoperable [Messaging] 10071 () 10073 o In Section 13.1.1 and Section 13.1.4, removed requirement that a 10074 validator not be sent in a 2xx response when validation fails and 10075 the server decides that the same change request has already been 10076 applied () 10078 o Moved requirements specific to HTTP/1.1 from Section 7.2 to 10079 [Messaging] () 10081 o In Section 5.5, introduce the terms "singleton field" and "list- 10082 based field" (also - in various places - discuss what to do when a 10083 singleton field is received as a list) 10084 () 10086 o In Section 10.1.1, change the ABNF back to be a list of 10087 expectations, as defined in RFC 2616 () 10090 o In Section 10.1.5 (Trailer), Section 7.6.3 (Via), Section 7.8 10091 (Upgrade), Section 7.6.1 (Connection), Section 8.5 10092 (Content-Encoding), Section 8.6 (Content-Language), Section 10.1.1 10093 (Expect), Section 13.1.1 (If-Match), Section 13.1.2 10094 (If-None-Match), Section 12.5.2 (Accept-Charset), Section 12.5.4 10095 (Accept-Language), Section 12.5.5 (Vary), Section 11.6.1 10096 (WWW-Authenticate), and Section 11.7.1 (Proxy-Authenticate), 10097 adjust ABNF to allow empty lists () 10100 o In Section 9.3.1 and Section 17.9, provide a more nuanced 10101 explanation of sensitive data in GET-based forms and describe 10102 workarounds () 10104 o In Section 13.2, allow preconditions to be evaluated before the 10105 request payload (if any) is processed () 10108 o In Section 6.3 and Section 6.5.2, allow for trailer fields in 10109 multiple trailer sections, depending on the HTTP version and 10110 framing in use, with processing being iterative as each section is 10111 received () 10113 o Moved definitions of "TE" and "Upgrade" from [Messaging] 10114 () 10116 o Moved 1.1-specific discussion of TLS to Messaging and rewrote 10117 Section 4.3.4 to refer to RFC6125 () 10120 o Moved definition of "Connection" from [Messaging] 10121 () 10123 C.13. Since draft-ietf-httpbis-semantics-11 10125 o The entire document has been reorganized, with no changes to 10126 content except editorial for the reorganization 10127 () 10129 o Move IANA Upgrade Token Registry instructions from [Messaging] 10130 () 10132 C.14. Since draft-ietf-httpbis-semantics-12 10134 o In Appendix "Acknowledgments" (Appendix D), added acks for the 10135 work since 2014 () 10137 o In Section 15.3.7, specifically require that a client check the 10138 206 response header fields to determine what ranges are enclosed, 10139 since it cannot assume they exactly match those requested 10140 () 10142 o In Section 16.3, explain why new fields need to be backwards- 10143 compatible () 10145 o In Section 5.3, constrain field combination to be within a section 10146 () 10148 o In Section 5.6.7, mention that caching relaxes date sensitivity 10149 () 10151 o In Section 18.4, moved "*" field registration into main table 10152 () 10154 o In Section 1.2, reference [HTTP/0.9] () 10157 o In Section 9.3.4, clarify handling of unrecognized fields 10158 () 10160 o In Section 15.2, align language about bodies and trailers with 204 10161 and 304 () 10163 o Moved table of content codings into Section 18.6, moved table of 10164 range units into Section 18.7 () 10167 o In Section 6, add an abstract data type for message to help define 10168 semantics without being dependent on the specific structure of 10169 HTTP/1.1 () 10171 o In Section 8.9.2.2, relax arbitrary 60-second comparison limit 10172 () 10174 o In Section 7.2, add ":authority" pseudo-header to Host discussion 10175 and make section applicable to both () 10178 o In Section 18.4, note that this document updates [RFC3864] 10179 () 10181 o Moved transfer-coding ABNF from [Messaging] to Section 10.1.4 and 10182 replaced "t-ranking" ABNF by equivalent "weight" 10183 () 10185 o In Section 11.5, replace "canonical root URI" by "origin" 10186 () 10188 o In Section 10.1.1, remove obsolete note about a change in RFC 723x 10189 () 10191 o Changed to using "payload data" when defining requirements about 10192 the data being conveyed within a message, instead of the terms 10193 "payload body" or "response body" or "representation body", since 10194 they often get confused with the HTTP/1.1 message body (which 10195 includes transfer coding) () 10198 o Rewrite definition of HEAD method () 10201 o In Section 13.1.5, fix an off-by-one bug about how many chars to 10202 consider when checking for etags () 10205 o In Section 15.1, clarify that "no reason phrase" is fine as well 10206 () 10208 o In Section 15.3.4, remove an obsolete reference to the Warning 10209 response header field () 10212 o In Section 15.5.9, rephrase prose about connection re-use 10213 () 10215 o In Section 14.2, potentially allow Range handling on methods other 10216 than GET () 10218 o In Section 18.3, remove redundant text about status code 418 10219 () 10221 o In Section 17.15.1, rewrite requirement to refer to "secured 10222 connection" () 10224 o Make reference to [RFC8446] normative () 10227 Acknowledgments 10229 This edition of the HTTP specification builds on the many 10230 contributions that went into RFC 1945, RFC 2068, RFC 2145, RFC 2616, 10231 and RFC 2818, including substantial contributions made by the 10232 previous authors, editors, and Working Group Chairs: Tim Berners-Lee, 10233 Jean-François Groff, Ari Luotonen, Roy T. Fielding, Henrik Frystyk 10234 Nielsen, Jim Gettys, Jeffrey C. Mogul, Larry Masinter, Paul J. 10235 Leach, Eric Rescorla, and Yves Lafon. 10237 In addition, this document has reincorporated the HTTP Authentication 10238 Framework, previously defined in RFC 7235 and RFC 2617. We thank 10239 John Franks, Phillip M. Hallam-Baker, Jeffery L. Hostetler, Scott 10240 D. Lawrence, Paul J. Leach, Ari Luotonen, and Lawrence C. Stewart 10241 for their work on that specification. See Section 6 of [RFC2617] for 10242 further acknowledgements. 10244 Since 2014, the following contributors have helped improve the HTTP 10245 specification by reporting bugs, asking smart questions, drafting or 10246 reviewing text, and evaluating open issues: 10248 Alan Egerton, Alex Rousskov, Amichai Rothman, Amos Jeffries, Anders 10249 Kaseorg, Andreas Gebhardt, Anne van Kesteren, Armin Abfalterer, Aron 10250 Duby, Asanka Herath, Asbjørn Ulsberg, Attila Gulyas, Austin Wright, 10251 Barry Pollard, Ben Burkert, Björn Höhrmann, Brad Fitzpatrick, Chris 10252 Pacejo, Colin Bendell, Cory Benfield, Cory Nelson, Daisuke Miyakawa, 10253 Daniel Stenberg, Danil Suits, David Benjamin, David Matson, David 10254 Schinazi, Дилян Палаузов (Dilyan Palauzov), Eric Anderson, Eric 10255 Rescorla, Erwin Pe, Etan Kissling, Evert Pot, Evgeny Vrublevsky, 10256 Florian Best, Igor Lubashev, James Callahan, Jeffrey Yasskin, Kalin 10257 Gyokov, Kannan Goundan, Kazuho Oku, Ken Murchison, Lucas Pardue, 10258 Martin Dürst, Martin Thomson, Martynas Jusevičius, Matt Menke, 10259 Matthias Pigulla, Michael Osipov, Mike Bishop, Mike Pennisi, Mike 10260 West, Nicholas Hurley, Nikita Piskunov, Patrick McManus, Piotr 10261 Sikora, Poul-Henning Kamp, Rick van Rein, Roberto Polli, Semyon 10262 Kholodnov, Simon Pieters, Simon Schüppel, Todd Greer, Tommy Pauly, 10263 Vasiliy Faronov, Vladimir Lashchev, Wenbo Zhu, William A. Rowe Jr., 10264 Willy Tarreau, Xingwei Liu, and Yishuai Li. 10266 See Section 10 of [RFC7230] for further acknowledgements from prior 10267 revisions. 10269 Authors' Addresses 10271 Roy T. Fielding (editor) 10272 Adobe 10273 345 Park Ave 10274 San Jose, CA 95110 10275 United States of America 10277 Email: fielding@gbiv.com 10278 URI: https://roy.gbiv.com/ 10280 Mark Nottingham (editor) 10281 Fastly 10282 Prahran VIC 10283 Australia 10285 Email: mnot@mnot.net 10286 URI: https://www.mnot.net/ 10288 Julian Reschke (editor) 10289 greenbytes GmbH 10290 Hafenweg 16 10291 48155 Münster 10292 Germany 10293 Email: julian.reschke@greenbytes.de 10294 URI: https://greenbytes.de/tech/webdav/