idnits 2.17.1 draft-ietf-httpbis-semantics-16.txt: -(10857): 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 10 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 abstract seems to indicate that this document updates RFC7615, but the header doesn't have an 'Updates:' line to match this. -- The abstract seems to indicate that this document updates RFC7538, but the header doesn't have an 'Updates:' line to match this. -- The abstract seems to indicate that this document updates RFC7231, but the header doesn't have an 'Updates:' line to match this. -- The abstract seems to indicate that this document updates RFC7232, but the header doesn't have an 'Updates:' line to match this. -- The abstract seems to indicate that this document updates RFC7233, but the header doesn't have an 'Updates:' line to match this. -- The abstract seems to indicate that this document updates RFC7694, but the header doesn't have an 'Updates:' line to match this. -- The abstract seems to indicate that this document updates RFC7235, but the header doesn't have an 'Updates:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (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 (27 May 2021) is 1057 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 9398, but no explicit reference was found in the text == Unused Reference: 'RFC2617' is defined on line 9422, but no explicit reference was found in the text == Unused Reference: 'RFC7234' is defined on line 9514, but no explicit reference was found in the text == Unused Reference: 'RFC7617' is defined on line 9552, but no explicit reference was found in the text == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-cache-16 -- Possible downref: Normative reference to a draft: ref. 'Caching' ** 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 (-19) exists of draft-ietf-httpbis-messaging-16 -- 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 7234 (Obsoleted by RFC 9111) -- 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 (~~), 9 warnings (==), 34 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: 28 November 2021 27 May 2021 10 HTTP Semantics 11 draft-ietf-httpbis-semantics-16 13 Abstract 15 The Hypertext Transfer Protocol (HTTP) is a stateless application- 16 level protocol for distributed, collaborative, hypertext information 17 systems. This document describes the overall architecture of HTTP, 18 establishes common terminology, and defines aspects of the protocol 19 that are shared by all versions. In this definition are core 20 protocol elements, extensibility mechanisms, and the "http" and 21 "https" Uniform Resource Identifier (URI) schemes. 23 This document updates RFC 3864 and obsoletes RFC 2818, RFC 7231, RFC 24 7232, RFC 7233, RFC 7235, RFC 7538, RFC 7615, RFC 7694, and portions 25 of RFC 7230. 27 Editorial Note 29 This note is to be removed before publishing as an RFC. 31 Discussion of this draft takes place on the HTTP working group 32 mailing list (ietf-http-wg@w3.org), which is archived at 33 . 35 Working Group information can be found at ; 36 source code and issues list for this draft can be found at 37 . 39 The changes in this draft are summarized in Appendix C.17. 41 Status of This Memo 43 This Internet-Draft is submitted in full conformance with the 44 provisions of BCP 78 and BCP 79. 46 Internet-Drafts are working documents of the Internet Engineering 47 Task Force (IETF). Note that other groups may also distribute 48 working documents as Internet-Drafts. The list of current Internet- 49 Drafts is at https://datatracker.ietf.org/drafts/current/. 51 Internet-Drafts are draft documents valid for a maximum of six months 52 and may be updated, replaced, or obsoleted by other documents at any 53 time. It is inappropriate to use Internet-Drafts as reference 54 material or to cite them other than as "work in progress." 56 This Internet-Draft will expire on 28 November 2021. 58 Copyright Notice 60 Copyright (c) 2021 IETF Trust and the persons identified as the 61 document authors. All rights reserved. 63 This document is subject to BCP 78 and the IETF Trust's Legal 64 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 65 license-info) in effect on the date of publication of this document. 66 Please review these documents carefully, as they describe your rights 67 and restrictions with respect to this document. Code Components 68 extracted from this document must include Simplified BSD License text 69 as described in Section 4.e of the Trust Legal Provisions and are 70 provided without warranty as described in the Simplified BSD License. 72 This document may contain material from IETF Documents or IETF 73 Contributions published or made publicly available before November 74 10, 2008. The person(s) controlling the copyright in some of this 75 material may not have granted the IETF Trust the right to allow 76 modifications of such material outside the IETF Standards Process. 77 Without obtaining an adequate license from the person(s) controlling 78 the copyright in such materials, this document may not be modified 79 outside the IETF Standards Process, and derivative works of it may 80 not be created outside the IETF Standards Process, except to format 81 it for publication as an RFC or to translate it into languages other 82 than English. 84 Table of Contents 86 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 9 87 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 9 88 1.2. History and Evolution . . . . . . . . . . . . . . . . . . 10 89 1.3. Core Semantics . . . . . . . . . . . . . . . . . . . . . 11 90 1.4. Specifications Obsoleted by this Document . . . . . . . . 11 91 2. Conformance . . . . . . . . . . . . . . . . . . . . . . . . . 12 92 2.1. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 12 93 2.2. Requirements Notation . . . . . . . . . . . . . . . . . . 13 94 2.3. Length Requirements . . . . . . . . . . . . . . . . . . . 14 95 2.4. Error Handling . . . . . . . . . . . . . . . . . . . . . 15 96 2.5. Protocol Version . . . . . . . . . . . . . . . . . . . . 15 97 3. Terminology and Core Concepts . . . . . . . . . . . . . . . . 16 98 3.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . 16 99 3.2. Representations . . . . . . . . . . . . . . . . . . . . . 17 100 3.3. Connections, Clients and Servers . . . . . . . . . . . . 17 101 3.4. Messages . . . . . . . . . . . . . . . . . . . . . . . . 18 102 3.5. User Agents . . . . . . . . . . . . . . . . . . . . . . . 18 103 3.6. Origin Server . . . . . . . . . . . . . . . . . . . . . . 19 104 3.7. Intermediaries . . . . . . . . . . . . . . . . . . . . . 20 105 3.8. Caches . . . . . . . . . . . . . . . . . . . . . . . . . 22 106 3.9. Example Message Exchange . . . . . . . . . . . . . . . . 22 107 4. Identifiers in HTTP . . . . . . . . . . . . . . . . . . . . . 23 108 4.1. URI References . . . . . . . . . . . . . . . . . . . . . 23 109 4.2. HTTP-Related URI Schemes . . . . . . . . . . . . . . . . 24 110 4.2.1. http URI Scheme . . . . . . . . . . . . . . . . . . . 25 111 4.2.2. https URI Scheme . . . . . . . . . . . . . . . . . . 25 112 4.2.3. http(s) Normalization and Comparison . . . . . . . . 26 113 4.2.4. Deprecation of userinfo in http(s) URIs . . . . . . . 27 114 4.2.5. http(s) References with Fragment Identifiers . . . . 27 115 4.3. Authoritative Access . . . . . . . . . . . . . . . . . . 28 116 4.3.1. URI Origin . . . . . . . . . . . . . . . . . . . . . 28 117 4.3.2. http origins . . . . . . . . . . . . . . . . . . . . 29 118 4.3.3. https origins . . . . . . . . . . . . . . . . . . . . 30 119 4.3.4. https certificate verification . . . . . . . . . . . 31 120 4.3.5. IP-ID reference identity . . . . . . . . . . . . . . 32 121 5. Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 122 5.1. Field Names . . . . . . . . . . . . . . . . . . . . . . . 32 123 5.2. Field Lines and Combined Field Value . . . . . . . . . . 33 124 5.3. Field Order . . . . . . . . . . . . . . . . . . . . . . . 34 125 5.4. Field Limits . . . . . . . . . . . . . . . . . . . . . . 35 126 5.5. Field Values . . . . . . . . . . . . . . . . . . . . . . 35 127 5.6. Common Rules for Defining Field Values . . . . . . . . . 37 128 5.6.1. Lists (#rule ABNF Extension) . . . . . . . . . . . . 37 129 5.6.1.1. Sender Requirements . . . . . . . . . . . . . . . 37 130 5.6.1.2. Recipient Requirements . . . . . . . . . . . . . 38 131 5.6.2. Tokens . . . . . . . . . . . . . . . . . . . . . . . 38 132 5.6.3. Whitespace . . . . . . . . . . . . . . . . . . . . . 39 133 5.6.4. Quoted Strings . . . . . . . . . . . . . . . . . . . 39 134 5.6.5. Comments . . . . . . . . . . . . . . . . . . . . . . 40 135 5.6.6. Parameters . . . . . . . . . . . . . . . . . . . . . 40 136 5.6.7. Date/Time Formats . . . . . . . . . . . . . . . . . . 41 137 6. Message Abstraction . . . . . . . . . . . . . . . . . . . . . 43 138 6.1. Framing and Completeness . . . . . . . . . . . . . . . . 44 139 6.2. Control Data . . . . . . . . . . . . . . . . . . . . . . 45 140 6.3. Header Fields . . . . . . . . . . . . . . . . . . . . . . 46 141 6.4. Content . . . . . . . . . . . . . . . . . . . . . . . . . 46 142 6.4.1. Content Semantics . . . . . . . . . . . . . . . . . . 46 143 6.4.2. Identifying Content . . . . . . . . . . . . . . . . . 47 144 6.5. Trailer Fields . . . . . . . . . . . . . . . . . . . . . 48 145 6.5.1. Limitations on use of Trailers . . . . . . . . . . . 49 146 6.5.2. Processing Trailer Fields . . . . . . . . . . . . . . 50 147 7. Routing HTTP Messages . . . . . . . . . . . . . . . . . . . . 50 148 7.1. Determining the Target Resource . . . . . . . . . . . . . 50 149 7.2. Host and :authority . . . . . . . . . . . . . . . . . . . 51 150 7.3. Routing Inbound Requests . . . . . . . . . . . . . . . . 52 151 7.3.1. To a Cache . . . . . . . . . . . . . . . . . . . . . 52 152 7.3.2. To a Proxy . . . . . . . . . . . . . . . . . . . . . 52 153 7.3.3. To the Origin . . . . . . . . . . . . . . . . . . . . 52 154 7.4. Rejecting Misdirected Requests . . . . . . . . . . . . . 53 155 7.5. Response Correlation . . . . . . . . . . . . . . . . . . 53 156 7.6. Message Forwarding . . . . . . . . . . . . . . . . . . . 54 157 7.6.1. Connection . . . . . . . . . . . . . . . . . . . . . 54 158 7.6.2. Max-Forwards . . . . . . . . . . . . . . . . . . . . 56 159 7.6.3. Via . . . . . . . . . . . . . . . . . . . . . . . . . 57 160 7.7. Message Transformations . . . . . . . . . . . . . . . . . 58 161 7.8. Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . 59 162 8. Representation Data and Metadata . . . . . . . . . . . . . . 62 163 8.1. Representation Data . . . . . . . . . . . . . . . . . . . 62 164 8.2. Representation Metadata . . . . . . . . . . . . . . . . . 62 165 8.3. Content-Type . . . . . . . . . . . . . . . . . . . . . . 62 166 8.3.1. Media Type . . . . . . . . . . . . . . . . . . . . . 63 167 8.3.2. Charset . . . . . . . . . . . . . . . . . . . . . . . 64 168 8.3.3. Multipart Types . . . . . . . . . . . . . . . . . . . 64 169 8.4. Content-Encoding . . . . . . . . . . . . . . . . . . . . 65 170 8.4.1. Content Codings . . . . . . . . . . . . . . . . . . . 66 171 8.4.1.1. Compress Coding . . . . . . . . . . . . . . . . . 66 172 8.4.1.2. Deflate Coding . . . . . . . . . . . . . . . . . 66 173 8.4.1.3. Gzip Coding . . . . . . . . . . . . . . . . . . . 67 174 8.5. Content-Language . . . . . . . . . . . . . . . . . . . . 67 175 8.5.1. Language Tags . . . . . . . . . . . . . . . . . . . . 68 176 8.6. Content-Length . . . . . . . . . . . . . . . . . . . . . 68 177 8.7. Content-Location . . . . . . . . . . . . . . . . . . . . 70 178 8.8. Validator Fields . . . . . . . . . . . . . . . . . . . . 72 179 8.8.1. Weak versus Strong . . . . . . . . . . . . . . . . . 72 180 8.8.2. Last-Modified . . . . . . . . . . . . . . . . . . . . 74 181 8.8.2.1. Generation . . . . . . . . . . . . . . . . . . . 74 182 8.8.2.2. Comparison . . . . . . . . . . . . . . . . . . . 75 183 8.8.3. ETag . . . . . . . . . . . . . . . . . . . . . . . . 76 184 8.8.3.1. Generation . . . . . . . . . . . . . . . . . . . 77 185 8.8.3.2. Comparison . . . . . . . . . . . . . . . . . . . 77 186 8.8.3.3. Example: Entity-Tags Varying on Content-Negotiated 187 Resources . . . . . . . . . . . . . . . . . . . . . 78 188 8.8.4. When to Use Entity-Tags and Last-Modified Dates . . . 79 189 9. Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 190 9.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 80 191 9.2. Common Method Properties . . . . . . . . . . . . . . . . 82 192 9.2.1. Safe Methods . . . . . . . . . . . . . . . . . . . . 82 193 9.2.2. Idempotent Methods . . . . . . . . . . . . . . . . . 83 194 9.2.3. Methods and Caching . . . . . . . . . . . . . . . . . 84 195 9.3. Method Definitions . . . . . . . . . . . . . . . . . . . 84 196 9.3.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 84 197 9.3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 85 198 9.3.3. POST . . . . . . . . . . . . . . . . . . . . . . . . 86 199 9.3.4. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 87 200 9.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 90 201 9.3.6. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 91 202 9.3.7. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 92 203 9.3.8. TRACE . . . . . . . . . . . . . . . . . . . . . . . . 93 204 10. Message Context . . . . . . . . . . . . . . . . . . . . . . . 94 205 10.1. Request Context Fields . . . . . . . . . . . . . . . . . 94 206 10.1.1. Expect . . . . . . . . . . . . . . . . . . . . . . . 94 207 10.1.2. From . . . . . . . . . . . . . . . . . . . . . . . . 96 208 10.1.3. Referer . . . . . . . . . . . . . . . . . . . . . . 97 209 10.1.4. TE . . . . . . . . . . . . . . . . . . . . . . . . . 98 210 10.1.5. Trailer . . . . . . . . . . . . . . . . . . . . . . 99 211 10.1.6. User-Agent . . . . . . . . . . . . . . . . . . . . . 99 212 10.2. Response Context Fields . . . . . . . . . . . . . . . . 100 213 10.2.1. Allow . . . . . . . . . . . . . . . . . . . . . . . 101 214 10.2.2. Date . . . . . . . . . . . . . . . . . . . . . . . . 101 215 10.2.3. Location . . . . . . . . . . . . . . . . . . . . . . 102 216 10.2.4. Retry-After . . . . . . . . . . . . . . . . . . . . 104 217 10.2.5. Server . . . . . . . . . . . . . . . . . . . . . . . 104 218 11. HTTP Authentication . . . . . . . . . . . . . . . . . . . . . 105 219 11.1. Authentication Scheme . . . . . . . . . . . . . . . . . 105 220 11.2. Authentication Parameters . . . . . . . . . . . . . . . 105 221 11.3. Challenge and Response . . . . . . . . . . . . . . . . . 106 222 11.4. Credentials . . . . . . . . . . . . . . . . . . . . . . 107 223 11.5. Establishing a Protection Space (Realm) . . . . . . . . 107 224 11.6. Authenticating Users to Origin Servers . . . . . . . . . 108 225 11.6.1. WWW-Authenticate . . . . . . . . . . . . . . . . . . 108 226 11.6.2. Authorization . . . . . . . . . . . . . . . . . . . 109 227 11.6.3. Authentication-Info . . . . . . . . . . . . . . . . 110 228 11.7. Authenticating Clients to Proxies . . . . . . . . . . . 110 229 11.7.1. Proxy-Authenticate . . . . . . . . . . . . . . . . . 110 230 11.7.2. Proxy-Authorization . . . . . . . . . . . . . . . . 111 231 11.7.3. Proxy-Authentication-Info . . . . . . . . . . . . . 111 232 12. Content Negotiation . . . . . . . . . . . . . . . . . . . . . 112 233 12.1. Proactive Negotiation . . . . . . . . . . . . . . . . . 113 234 12.2. Reactive Negotiation . . . . . . . . . . . . . . . . . . 114 235 12.3. Request Content Negotiation . . . . . . . . . . . . . . 115 236 12.4. Content Negotiation Field Features . . . . . . . . . . . 115 237 12.4.1. Absence . . . . . . . . . . . . . . . . . . . . . . 115 238 12.4.2. Quality Values . . . . . . . . . . . . . . . . . . . 115 239 12.4.3. Wildcard Values . . . . . . . . . . . . . . . . . . 116 240 12.5. Content Negotiation Fields . . . . . . . . . . . . . . . 116 241 12.5.1. Accept . . . . . . . . . . . . . . . . . . . . . . . 116 242 12.5.2. Accept-Charset . . . . . . . . . . . . . . . . . . . 119 243 12.5.3. Accept-Encoding . . . . . . . . . . . . . . . . . . 119 244 12.5.4. Accept-Language . . . . . . . . . . . . . . . . . . 121 245 12.5.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . 122 246 13. Conditional Requests . . . . . . . . . . . . . . . . . . . . 124 247 13.1. Preconditions . . . . . . . . . . . . . . . . . . . . . 124 248 13.1.1. If-Match . . . . . . . . . . . . . . . . . . . . . . 125 249 13.1.2. If-None-Match . . . . . . . . . . . . . . . . . . . 126 250 13.1.3. If-Modified-Since . . . . . . . . . . . . . . . . . 128 251 13.1.4. If-Unmodified-Since . . . . . . . . . . . . . . . . 130 252 13.1.5. If-Range . . . . . . . . . . . . . . . . . . . . . . 131 253 13.2. Evaluation of Preconditions . . . . . . . . . . . . . . 132 254 13.2.1. When to Evaluate . . . . . . . . . . . . . . . . . . 133 255 13.2.2. Precedence of Preconditions . . . . . . . . . . . . 133 256 14. Range Requests . . . . . . . . . . . . . . . . . . . . . . . 135 257 14.1. Range Units . . . . . . . . . . . . . . . . . . . . . . 135 258 14.1.1. Range Specifiers . . . . . . . . . . . . . . . . . . 136 259 14.1.2. Byte Ranges . . . . . . . . . . . . . . . . . . . . 137 260 14.2. Range . . . . . . . . . . . . . . . . . . . . . . . . . 138 261 14.3. Accept-Ranges . . . . . . . . . . . . . . . . . . . . . 140 262 14.4. Content-Range . . . . . . . . . . . . . . . . . . . . . 140 263 14.5. Partial PUT . . . . . . . . . . . . . . . . . . . . . . 142 264 14.6. Media Type multipart/byteranges . . . . . . . . . . . . 143 265 15. Status Codes . . . . . . . . . . . . . . . . . . . . . . . . 145 266 15.1. Overview of Status Codes . . . . . . . . . . . . . . . . 146 267 15.2. Informational 1xx . . . . . . . . . . . . . . . . . . . 146 268 15.2.1. 100 Continue . . . . . . . . . . . . . . . . . . . . 147 269 15.2.2. 101 Switching Protocols . . . . . . . . . . . . . . 147 270 15.3. Successful 2xx . . . . . . . . . . . . . . . . . . . . . 147 271 15.3.1. 200 OK . . . . . . . . . . . . . . . . . . . . . . . 148 272 15.3.2. 201 Created . . . . . . . . . . . . . . . . . . . . 148 273 15.3.3. 202 Accepted . . . . . . . . . . . . . . . . . . . . 149 274 15.3.4. 203 Non-Authoritative Information . . . . . . . . . 149 275 15.3.5. 204 No Content . . . . . . . . . . . . . . . . . . . 149 276 15.3.6. 205 Reset Content . . . . . . . . . . . . . . . . . 150 277 15.3.7. 206 Partial Content . . . . . . . . . . . . . . . . 150 278 15.3.7.1. Single Part . . . . . . . . . . . . . . . . . . 151 279 15.3.7.2. Multiple Parts . . . . . . . . . . . . . . . . . 152 280 15.3.7.3. Combining Parts . . . . . . . . . . . . . . . . 153 281 15.4. Redirection 3xx . . . . . . . . . . . . . . . . . . . . 154 282 15.4.1. 300 Multiple Choices . . . . . . . . . . . . . . . . 156 283 15.4.2. 301 Moved Permanently . . . . . . . . . . . . . . . 157 284 15.4.3. 302 Found . . . . . . . . . . . . . . . . . . . . . 157 285 15.4.4. 303 See Other . . . . . . . . . . . . . . . . . . . 158 286 15.4.5. 304 Not Modified . . . . . . . . . . . . . . . . . . 159 287 15.4.6. 305 Use Proxy . . . . . . . . . . . . . . . . . . . 159 288 15.4.7. 306 (Unused) . . . . . . . . . . . . . . . . . . . . 159 289 15.4.8. 307 Temporary Redirect . . . . . . . . . . . . . . . 160 290 15.4.9. 308 Permanent Redirect . . . . . . . . . . . . . . . 160 291 15.5. Client Error 4xx . . . . . . . . . . . . . . . . . . . . 160 292 15.5.1. 400 Bad Request . . . . . . . . . . . . . . . . . . 161 293 15.5.2. 401 Unauthorized . . . . . . . . . . . . . . . . . . 161 294 15.5.3. 402 Payment Required . . . . . . . . . . . . . . . . 161 295 15.5.4. 403 Forbidden . . . . . . . . . . . . . . . . . . . 161 296 15.5.5. 404 Not Found . . . . . . . . . . . . . . . . . . . 162 297 15.5.6. 405 Method Not Allowed . . . . . . . . . . . . . . . 162 298 15.5.7. 406 Not Acceptable . . . . . . . . . . . . . . . . . 162 299 15.5.8. 407 Proxy Authentication Required . . . . . . . . . 163 300 15.5.9. 408 Request Timeout . . . . . . . . . . . . . . . . 163 301 15.5.10. 409 Conflict . . . . . . . . . . . . . . . . . . . . 163 302 15.5.11. 410 Gone . . . . . . . . . . . . . . . . . . . . . . 163 303 15.5.12. 411 Length Required . . . . . . . . . . . . . . . . 164 304 15.5.13. 412 Precondition Failed . . . . . . . . . . . . . . 164 305 15.5.14. 413 Content Too Large . . . . . . . . . . . . . . . 164 306 15.5.15. 414 URI Too Long . . . . . . . . . . . . . . . . . . 165 307 15.5.16. 415 Unsupported Media Type . . . . . . . . . . . . . 165 308 15.5.17. 416 Range Not Satisfiable . . . . . . . . . . . . . 165 309 15.5.18. 417 Expectation Failed . . . . . . . . . . . . . . . 166 310 15.5.19. 418 (Unused) . . . . . . . . . . . . . . . . . . . . 166 311 15.5.20. 421 Misdirected Request . . . . . . . . . . . . . . 167 312 15.5.21. 422 Unprocessable Content . . . . . . . . . . . . . 167 313 15.5.22. 426 Upgrade Required . . . . . . . . . . . . . . . . 167 314 15.6. Server Error 5xx . . . . . . . . . . . . . . . . . . . . 168 315 15.6.1. 500 Internal Server Error . . . . . . . . . . . . . 168 316 15.6.2. 501 Not Implemented . . . . . . . . . . . . . . . . 168 317 15.6.3. 502 Bad Gateway . . . . . . . . . . . . . . . . . . 168 318 15.6.4. 503 Service Unavailable . . . . . . . . . . . . . . 168 319 15.6.5. 504 Gateway Timeout . . . . . . . . . . . . . . . . 169 320 15.6.6. 505 HTTP Version Not Supported . . . . . . . . . . . 169 321 16. Extending HTTP . . . . . . . . . . . . . . . . . . . . . . . 169 322 16.1. Method Extensibility . . . . . . . . . . . . . . . . . . 170 323 16.1.1. Method Registry . . . . . . . . . . . . . . . . . . 170 324 16.1.2. Considerations for New Methods . . . . . . . . . . . 170 325 16.2. Status Code Extensibility . . . . . . . . . . . . . . . 171 326 16.2.1. Status Code Registry . . . . . . . . . . . . . . . . 171 327 16.2.2. Considerations for New Status Codes . . . . . . . . 171 328 16.3. Field Extensibility . . . . . . . . . . . . . . . . . . 172 329 16.3.1. Field Name Registry . . . . . . . . . . . . . . . . 173 330 16.3.2. Considerations for New Fields . . . . . . . . . . . 174 331 16.3.2.1. Considerations for New Field Names . . . . . . . 175 332 16.3.2.2. Considerations for New Field Values . . . . . . 176 333 16.4. Authentication Scheme Extensibility . . . . . . . . . . 176 334 16.4.1. Authentication Scheme Registry . . . . . . . . . . . 177 335 16.4.2. Considerations for New Authentication Schemes . . . 177 336 16.5. Range Unit Extensibility . . . . . . . . . . . . . . . . 178 337 16.5.1. Range Unit Registry . . . . . . . . . . . . . . . . 179 338 16.5.2. Considerations for New Range Units . . . . . . . . . 179 339 16.6. Content Coding Extensibility . . . . . . . . . . . . . . 179 340 16.6.1. Content Coding Registry . . . . . . . . . . . . . . 179 341 16.6.2. Considerations for New Content Codings . . . . . . . 180 342 16.7. Upgrade Token Registry . . . . . . . . . . . . . . . . . 180 343 17. Security Considerations . . . . . . . . . . . . . . . . . . . 181 344 17.1. Establishing Authority . . . . . . . . . . . . . . . . . 181 345 17.2. Risks of Intermediaries . . . . . . . . . . . . . . . . 182 346 17.3. Attacks Based on File and Path Names . . . . . . . . . . 183 347 17.4. Attacks Based on Command, Code, or Query Injection . . . 183 348 17.5. Attacks via Protocol Element Length . . . . . . . . . . 184 349 17.6. Attacks using Shared-dictionary Compression . . . . . . 184 350 17.7. Disclosure of Personal Information . . . . . . . . . . . 185 351 17.8. Privacy of Server Log Information . . . . . . . . . . . 185 352 17.9. Disclosure of Sensitive Information in URIs . . . . . . 186 353 17.10. Application Handling of Field Names . . . . . . . . . . 186 354 17.11. Disclosure of Fragment after Redirects . . . . . . . . . 187 355 17.12. Disclosure of Product Information . . . . . . . . . . . 188 356 17.13. Browser Fingerprinting . . . . . . . . . . . . . . . . . 188 357 17.14. Validator Retention . . . . . . . . . . . . . . . . . . 189 358 17.15. Denial-of-Service Attacks Using Range . . . . . . . . . 189 359 17.16. Authentication Considerations . . . . . . . . . . . . . 190 360 17.16.1. Confidentiality of Credentials . . . . . . . . . . 190 361 17.16.2. Credentials and Idle Clients . . . . . . . . . . . 190 362 17.16.3. Protection Spaces . . . . . . . . . . . . . . . . . 191 363 17.16.4. Additional Response Fields . . . . . . . . . . . . 191 364 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 191 365 18.1. URI Scheme Registration . . . . . . . . . . . . . . . . 192 366 18.2. Method Registration . . . . . . . . . . . . . . . . . . 192 367 18.3. Status Code Registration . . . . . . . . . . . . . . . . 192 368 18.4. Field Name Registration . . . . . . . . . . . . . . . . 195 369 18.5. Authentication Scheme Registration . . . . . . . . . . . 197 370 18.6. Content Coding Registration . . . . . . . . . . . . . . 198 371 18.7. Range Unit Registration . . . . . . . . . . . . . . . . 198 372 18.8. Media Type Registration . . . . . . . . . . . . . . . . 199 373 18.9. Port Registration . . . . . . . . . . . . . . . . . . . 199 374 18.10. Upgrade Token Registration . . . . . . . . . . . . . . . 199 375 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 199 376 19.1. Normative References . . . . . . . . . . . . . . . . . . 199 377 19.2. Informative References . . . . . . . . . . . . . . . . . 201 378 Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 208 379 Appendix B. Changes from previous RFCs . . . . . . . . . . . . . 212 380 B.1. Changes from RFC 2818 . . . . . . . . . . . . . . . . . . 212 381 B.2. Changes from RFC 7230 . . . . . . . . . . . . . . . . . . 213 382 B.3. Changes from RFC 7231 . . . . . . . . . . . . . . . . . . 213 383 B.4. Changes from RFC 7232 . . . . . . . . . . . . . . . . . . 215 384 B.5. Changes from RFC 7233 . . . . . . . . . . . . . . . . . . 216 385 B.6. Changes from RFC 7235 . . . . . . . . . . . . . . . . . . 216 386 B.7. Changes from RFC 7538 . . . . . . . . . . . . . . . . . . 216 387 B.8. Changes from RFC 7615 . . . . . . . . . . . . . . . . . . 216 388 B.9. Changes from RFC 7694 . . . . . . . . . . . . . . . . . . 216 389 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 216 390 C.1. Between RFC723x and draft 00 . . . . . . . . . . . . . . 216 391 C.2. Since draft-ietf-httpbis-semantics-00 . . . . . . . . . . 217 392 C.3. Since draft-ietf-httpbis-semantics-01 . . . . . . . . . . 217 393 C.4. Since draft-ietf-httpbis-semantics-02 . . . . . . . . . . 219 394 C.5. Since draft-ietf-httpbis-semantics-03 . . . . . . . . . . 220 395 C.6. Since draft-ietf-httpbis-semantics-04 . . . . . . . . . . 220 396 C.7. Since draft-ietf-httpbis-semantics-05 . . . . . . . . . . 221 397 C.8. Since draft-ietf-httpbis-semantics-06 . . . . . . . . . . 222 398 C.9. Since draft-ietf-httpbis-semantics-07 . . . . . . . . . . 224 399 C.10. Since draft-ietf-httpbis-semantics-08 . . . . . . . . . . 225 400 C.11. Since draft-ietf-httpbis-semantics-09 . . . . . . . . . . 226 401 C.12. Since draft-ietf-httpbis-semantics-10 . . . . . . . . . . 226 402 C.13. Since draft-ietf-httpbis-semantics-11 . . . . . . . . . . 228 403 C.14. Since draft-ietf-httpbis-semantics-12 . . . . . . . . . . 228 404 C.15. Since draft-ietf-httpbis-semantics-13 . . . . . . . . . . 230 405 C.16. Since draft-ietf-httpbis-semantics-14 . . . . . . . . . . 231 406 C.17. Since draft-ietf-httpbis-semantics-15 . . . . . . . . . . 233 407 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 234 408 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 409 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 246 411 1. Introduction 413 1.1. Purpose 415 The Hypertext Transfer Protocol (HTTP) is a family of stateless, 416 application-level, request/response protocols that share a generic 417 interface, extensible semantics, and self-descriptive messages to 418 enable flexible interaction with network-based hypertext information 419 systems. 421 HTTP hides the details of how a service is implemented by presenting 422 a uniform interface to clients that is independent of the types of 423 resources provided. Likewise, servers do not need to be aware of 424 each client's purpose: a request can be considered in isolation 425 rather than being associated with a specific type of client or a 426 predetermined sequence of application steps. This allows general- 427 purpose implementations to be used effectively in many different 428 contexts, reduces interaction complexity, and enables independent 429 evolution over time. 431 HTTP is also designed for use as an intermediation protocol, wherein 432 proxies and gateways can translate non-HTTP information systems into 433 a more generic interface. 435 One consequence of this flexibility is that the protocol cannot be 436 defined in terms of what occurs behind the interface. Instead, we 437 are limited to defining the syntax of communication, the intent of 438 received communication, and the expected behavior of recipients. If 439 the communication is considered in isolation, then successful actions 440 ought to be reflected in corresponding changes to the observable 441 interface provided by servers. However, since multiple clients might 442 act in parallel and perhaps at cross-purposes, we cannot require that 443 such changes be observable beyond the scope of a single response. 445 1.2. History and Evolution 447 HTTP has been the primary information transfer protocol for the World 448 Wide Web since its introduction in 1990. It began as a trivial 449 mechanism for low-latency requests, with a single method (GET) to 450 request transfer of a presumed hypertext document identified by a 451 given pathname. As the Web grew, HTTP was extended to enclose 452 requests and responses within messages, transfer arbitrary data 453 formats using MIME-like media types, and route requests through 454 intermediaries. These protocols were eventually defined as HTTP/0.9 455 and HTTP/1.0 (see [RFC1945]). 457 HTTP/1.1 was designed to refine the protocol's features while 458 retaining compatibility with the existing text-based messaging 459 syntax, improving its interoperability, scalability, and robustness 460 across the Internet. This included length-based data delimiters for 461 both fixed and dynamic (chunked) content, a consistent framework for 462 content negotiation, opaque validators for conditional requests, 463 cache controls for better cache consistency, range requests for 464 partial updates, and default persistent connections. HTTP/1.1 was 465 introduced in 1995 and published on the standards track in 1997 466 [RFC2068], revised in 1999 [RFC2616], and revised again in 2014 467 ([RFC7230] - [RFC7235]). 469 HTTP/2 ([RFC7540]) introduced a multiplexed session layer on top of 470 the existing TLS and TCP protocols for exchanging concurrent HTTP 471 messages with efficient field compression and server push. HTTP/3 472 ([HTTP3]) provides greater independence for concurrent messages by 473 using QUIC as a secure multiplexed transport over UDP instead of TCP. 475 All three major versions of HTTP rely on the semantics defined by 476 this document. They have not obsoleted each other because each one 477 has specific benefits and limitations depending on the context of 478 use. Implementations are expected to choose the most appropriate 479 transport and messaging syntax for their particular context. 481 This revision of HTTP separates the definition of semantics (this 482 document) and caching ([Caching]) from the current HTTP/1.1 messaging 483 syntax ([Messaging]) to allow each major protocol version to progress 484 independently while referring to the same core semantics. 486 1.3. Core Semantics 488 HTTP provides a uniform interface for interacting with a resource 489 (Section 3.1) - regardless of its type, nature, or implementation - 490 by sending messages that manipulate or transfer representations 491 (Section 3.2). 493 Each message is either a request or a response. A client constructs 494 request messages that communicate its intentions and routes those 495 messages toward an identified origin server. A server listens for 496 requests, parses each message received, interprets the message 497 semantics in relation to the identified target resource, and responds 498 to that request with one or more response messages. The client 499 examines received responses to see if its intentions were carried 500 out, determining what to do next based on the status codes and 501 content received. 503 HTTP semantics include the intentions defined by each request method 504 (Section 9), extensions to those semantics that might be described in 505 request header fields, status codes that describe the response 506 (Section 15), and other control data and resource metadata that might 507 be given in response fields. 509 Semantics also include representation metadata that describe how 510 content is intended to be interpreted by a recipient, request header 511 fields that might influence content selection, and the various 512 selection algorithms that are collectively referred to as _content 513 negotiation_ (Section 12). 515 1.4. Specifications Obsoleted by this Document 517 This document obsoletes the following specifications: 519 +============================================+===========+=========+ 520 | Title | Reference | Changes | 521 +============================================+===========+=========+ 522 | HTTP Over TLS | [RFC2818] | B.1 | 523 +--------------------------------------------+-----------+---------+ 524 | HTTP/1.1 Message Syntax and Routing [*] | [RFC7230] | B.2 | 525 +--------------------------------------------+-----------+---------+ 526 | HTTP/1.1 Semantics and Content | [RFC7231] | B.3 | 527 +--------------------------------------------+-----------+---------+ 528 | HTTP/1.1 Conditional Requests | [RFC7232] | B.4 | 529 +--------------------------------------------+-----------+---------+ 530 | HTTP/1.1 Range Requests | [RFC7233] | B.5 | 531 +--------------------------------------------+-----------+---------+ 532 | HTTP/1.1 Authentication | [RFC7235] | B.6 | 533 +--------------------------------------------+-----------+---------+ 534 | HTTP Status Code 308 (Permanent Redirect) | [RFC7538] | B.7 | 535 +--------------------------------------------+-----------+---------+ 536 | HTTP Authentication-Info and Proxy- | [RFC7615] | B.8 | 537 | Authentication-Info Response Header Fields | | | 538 +--------------------------------------------+-----------+---------+ 539 | HTTP Client-Initiated Content-Encoding | [RFC7694] | B.9 | 540 +--------------------------------------------+-----------+---------+ 542 Table 1 544 [*] This document only obsoletes the portions of RFC 7230 that are 545 independent of the HTTP/1.1 messaging syntax and connection 546 management; the remaining bits of RFC 7230 are obsoleted by 547 "HTTP/1.1" [Messaging]. 549 2. Conformance 551 2.1. Syntax Notation 553 This specification uses the Augmented Backus-Naur Form (ABNF) 554 notation of [RFC5234], extended with the notation for case- 555 sensitivity in strings defined in [RFC7405]. 557 It also uses a list extension, defined in Section 5.6.1, that allows 558 for compact definition of comma-separated lists using a "#" operator 559 (similar to how the "*" operator indicates repetition). Appendix A 560 shows the collected grammar with all list operators expanded to 561 standard ABNF notation. 563 As a convention, ABNF rule names prefixed with "obs-" denote 564 "obsolete" grammar rules that appear for historical reasons. 566 The following core rules are included by reference, as defined in 567 Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), 568 CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double 569 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF 570 (line feed), OCTET (any 8-bit sequence of data), SP (space), and 571 VCHAR (any visible US-ASCII character). 573 Section 5.6 defines some generic syntactic components for field 574 values. 576 This specification uses the terms "character", "character encoding 577 scheme", "charset", and "protocol element" as they are defined in 578 [RFC6365]. 580 2.2. Requirements Notation 582 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 583 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 584 "OPTIONAL" in this document are to be interpreted as described in BCP 585 14 [RFC2119] [RFC8174] when, and only when, they appear in all 586 capitals, as shown here. 588 This specification targets conformance criteria according to the role 589 of a participant in HTTP communication. Hence, requirements are 590 placed on senders, recipients, clients, servers, user agents, 591 intermediaries, origin servers, proxies, gateways, or caches, 592 depending on what behavior is being constrained by the requirement. 593 Additional (social) requirements are placed on implementations, 594 resource owners, and protocol element registrations when they apply 595 beyond the scope of a single communication. 597 The verb "generate" is used instead of "send" where a requirement 598 applies only to implementations that create the protocol element, 599 rather than an implementation that forwards a received element 600 downstream. 602 An implementation is considered conformant if it complies with all of 603 the requirements associated with the roles it partakes in HTTP. 605 A sender MUST NOT generate protocol elements that do not match the 606 grammar defined by the corresponding ABNF rules. Within a given 607 message, a sender MUST NOT generate protocol elements or syntax 608 alternatives that are only allowed to be generated by participants in 609 other roles (i.e., a role that the sender does not have for that 610 message). 612 Conformance to HTTP includes both conformance to the particular 613 messaging syntax of the protocol version in use and conformance to 614 the semantics of protocol elements sent. For example, a client that 615 claims conformance to HTTP/1.1 but fails to recognize the features 616 required of HTTP/1.1 recipients will fail to interoperate with 617 servers that adjust their responses in accordance with those claims. 618 Features that reflect user choices, such as content negotiation and 619 user-selected extensions, can impact application behavior beyond the 620 protocol stream; sending protocol elements that inaccurately reflect 621 a user's choices will confuse the user and inhibit choice. 623 When an implementation fails semantic conformance, recipients of that 624 implementation's messages will eventually develop workarounds to 625 adjust their behavior accordingly. A recipient MAY employ such 626 workarounds while remaining conformant to this protocol if the 627 workarounds are limited to the implementations at fault. For 628 example, servers often scan portions of the User-Agent field value, 629 and user agents often scan the Server field value, to adjust their 630 own behavior with respect to known bugs or poorly chosen defaults. 632 2.3. Length Requirements 634 A recipient SHOULD parse a received protocol element defensively, 635 with only marginal expectations that the element will conform to its 636 ABNF grammar and fit within a reasonable buffer size. 638 HTTP does not have specific length limitations for many of its 639 protocol elements because the lengths that might be appropriate will 640 vary widely, depending on the deployment context and purpose of the 641 implementation. Hence, interoperability between senders and 642 recipients depends on shared expectations regarding what is a 643 reasonable length for each protocol element. Furthermore, what is 644 commonly understood to be a reasonable length for some protocol 645 elements has changed over the course of the past two decades of HTTP 646 use and is expected to continue changing in the future. 648 At a minimum, a recipient MUST be able to parse and process protocol 649 element lengths that are at least as long as the values that it 650 generates for those same protocol elements in other messages. For 651 example, an origin server that publishes very long URI references to 652 its own resources needs to be able to parse and process those same 653 references when received as a target URI. 655 Many received protocol elements are only parsed to the extent 656 necessary to identify and forward that element downstream. For 657 example, an intermediary might parse a received field into its field 658 name and field value components, but then forward the field without 659 further parsing inside the field value. 661 2.4. Error Handling 663 A recipient MUST interpret a received protocol element according to 664 the semantics defined for it by this specification, including 665 extensions to this specification, unless the recipient has determined 666 (through experience or configuration) that the sender incorrectly 667 implements what is implied by those semantics. For example, an 668 origin server might disregard the contents of a received 669 Accept-Encoding header field if inspection of the User-Agent header 670 field indicates a specific implementation version that is known to 671 fail on receipt of certain content codings. 673 Unless noted otherwise, a recipient MAY attempt to recover a usable 674 protocol element from an invalid construct. HTTP does not define 675 specific error handling mechanisms except when they have a direct 676 impact on security, since different applications of the protocol 677 require different error handling strategies. For example, a Web 678 browser might wish to transparently recover from a response where the 679 Location header field doesn't parse according to the ABNF, whereas a 680 systems control client might consider any form of error recovery to 681 be dangerous. 683 Some requests can be automatically retried by a client in the event 684 of an underlying connection failure, as described in Section 9.2.2. 686 2.5. Protocol Version 688 HTTP's version number consists of two decimal digits separated by a 689 "." (period or decimal point). The first digit ("major version") 690 indicates the messaging syntax, whereas the second digit ("minor 691 version") indicates the highest minor version within that major 692 version to which the sender is conformant (able to understand for 693 future communication). 695 While HTTP's core semantics don't change between protocol versions, 696 the expression of them "on the wire" can change, and so the HTTP 697 version number changes when incompatible changes are made to the wire 698 format. Additionally, HTTP allows incremental, backwards-compatible 699 changes to be made to the protocol without changing its version 700 through the use of defined extension points (Section 16). 702 The protocol version as a whole indicates the sender's conformance 703 with the set of requirements laid out in that version's corresponding 704 specification of HTTP. For example, the version "HTTP/1.1" is 705 defined by the combined specifications of this document, "HTTP 706 Caching" [Caching], and "HTTP/1.1" [Messaging]. 708 HTTP's major version number is incremented when an incompatible 709 message syntax is introduced. The minor number is incremented when 710 changes made to the protocol have the effect of adding to the message 711 semantics or implying additional capabilities of the sender. 713 The minor version advertises the sender's communication capabilities 714 even when the sender is only using a backwards-compatible subset of 715 the protocol, thereby letting the recipient know that more advanced 716 features can be used in response (by servers) or in future requests 717 (by clients). 719 When a major version of HTTP does not define any minor versions, the 720 minor version "0" is implied and is used when referring to that 721 protocol within a protocol element that requires sending a minor 722 version. 724 3. Terminology and Core Concepts 726 HTTP was created for the World Wide Web (WWW) architecture and has 727 evolved over time to support the scalability needs of a worldwide 728 hypertext system. Much of that architecture is reflected in the 729 terminology and syntax productions used to define HTTP. 731 3.1. Resources 733 The target of an HTTP request is called a _resource_. HTTP does not 734 limit the nature of a resource; it merely defines an interface that 735 might be used to interact with resources. Most resources are 736 identified by a Uniform Resource Identifier (URI), as described in 737 Section 4. 739 One design goal of HTTP is to separate resource identification from 740 request semantics, which is made possible by vesting the request 741 semantics in the request method (Section 9) and a few request- 742 modifying header fields. A resource cannot treat a request in a 743 manner inconsistent with the semantics of the method of the request. 744 For example, though the URI of a resource might imply semantics that 745 are not safe, a client can expect the resource to avoid actions that 746 are unsafe when processing a request with a safe method (see 747 Section 9.2.1). 749 HTTP relies upon the Uniform Resource Identifier (URI) standard 750 [RFC3986] to indicate the target resource (Section 7.1) and 751 relationships between resources. 753 3.2. Representations 755 A _representation_ is information that is intended to reflect a past, 756 current, or desired state of a given resource, in a format that can 757 be readily communicated via the protocol. A representation consists 758 of a set of representation metadata and a potentially unbounded 759 stream of representation data (Section 8). 761 HTTP allows "information hiding" behind its uniform interface by 762 defining communication with respect to a transferable representation 763 of the resource state, rather than transferring the resource itself. 764 This allows the resource identified by a URI to be anything, 765 including temporal functions like "the current weather in Laguna 766 Beach", while potentially providing information that represents that 767 resource at the time a message is generated [REST]. 769 The uniform interface is similar to a window through which one can 770 observe and act upon a thing only through the communication of 771 messages to an independent actor on the other side. A shared 772 abstraction is needed to represent ("take the place of") the current 773 or desired state of that thing in our communications. When a 774 representation is hypertext, it can provide both a representation of 775 the resource state and processing instructions that help guide the 776 recipient's future interactions. 778 A target resource might be provided with, or be capable of 779 generating, multiple representations that are each intended to 780 reflect the resource's current state. An algorithm, usually based on 781 content negotiation (Section 12), would be used to select one of 782 those representations as being most applicable to a given request. 783 This _selected representation_ provides the data and metadata for 784 evaluating conditional requests (Section 13) and constructing the 785 content for 200 (OK), 206 (Partial Content), and 304 (Not Modified) 786 responses to GET (Section 9.3.1). 788 3.3. Connections, Clients and Servers 790 HTTP is a client/server protocol that operates over a reliable 791 transport- or session-layer _connection_. 793 An HTTP _client_ is a program that establishes a connection to a 794 server for the purpose of sending one or more HTTP requests. An HTTP 795 _server_ is a program that accepts connections in order to service 796 HTTP requests by sending HTTP responses. 798 The terms "client" and "server" refer only to the roles that these 799 programs perform for a particular connection. The same program might 800 act as a client on some connections and a server on others. 802 HTTP is defined as a stateless protocol, meaning that each request 803 message's semantics can be understood in isolation, and that the 804 relationship between connections and messages on them has no impact 805 on the interpretation of those messages. For example, a CONNECT 806 request (Section 9.3.6) or a request with the Upgrade header field 807 (Section 7.8) can occur at any time, not just in the first message on 808 a connection. Many implementations depend on HTTP's stateless design 809 in order to reuse proxied connections or dynamically load balance 810 requests across multiple servers. 812 As a result, a server MUST NOT assume that two requests on the same 813 connection are from the same user agent unless the connection is 814 secured and specific to that agent. Some non-standard HTTP 815 extensions (e.g., [RFC4559]) have been known to violate this 816 requirement, resulting in security and interoperability problems. 818 3.4. Messages 820 HTTP is a stateless request/response protocol for exchanging 821 _messages_ across a connection. The terms _sender_ and _recipient_ 822 refer to any implementation that sends or receives a given message, 823 respectively. 825 A client sends requests to a server in the form of a _request_ 826 message with a method (Section 9) and request target (Section 7.1). 827 The request might also contain header fields (Section 6.3) for 828 request modifiers, client information, and representation metadata, 829 content (Section 6.4) intended for processing in accordance with the 830 method, and trailer fields (Section 6.5) to communicate information 831 collected while sending the content. 833 A server responds to a client's request by sending one or more 834 _response_ messages, each including a status code (Section 15). The 835 response might also contain header fields for server information, 836 resource metadata, and representation metadata, content to be 837 interpreted in accordance with the status code, and trailer fields to 838 communicate information collected while sending the content. 840 3.5. User Agents 842 The term _user agent_ refers to any of the various client programs 843 that initiate a request. 845 The most familiar form of user agent is the general-purpose Web 846 browser, but that's only a small percentage of implementations. 847 Other common user agents include spiders (web-traversing robots), 848 command-line tools, billboard screens, household appliances, scales, 849 light bulbs, firmware update scripts, mobile apps, and communication 850 devices in a multitude of shapes and sizes. 852 Being a user agent does not imply that there is a human user directly 853 interacting with the software agent at the time of a request. In 854 many cases, a user agent is installed or configured to run in the 855 background and save its results for later inspection (or save only a 856 subset of those results that might be interesting or erroneous). 857 Spiders, for example, are typically given a start URI and configured 858 to follow certain behavior while crawling the Web as a hypertext 859 graph. 861 Many user agents cannot, or choose not to, make interactive 862 suggestions to their user or provide adequate warning for security or 863 privacy concerns. In the few cases where this specification requires 864 reporting of errors to the user, it is acceptable for such reporting 865 to only be observable in an error console or log file. Likewise, 866 requirements that an automated action be confirmed by the user before 867 proceeding might be met via advance configuration choices, run-time 868 options, or simple avoidance of the unsafe action; confirmation does 869 not imply any specific user interface or interruption of normal 870 processing if the user has already made that choice. 872 3.6. Origin Server 874 The term _origin server_ refers to a program that can originate 875 authoritative responses for a given target resource. 877 The most familiar form of origin server are large public websites. 878 However, like user agents being equated with browsers, it is easy to 879 be misled into thinking that all origin servers are alike. Common 880 origin servers also include home automation units, configurable 881 networking components, office machines, autonomous robots, news 882 feeds, traffic cameras, real-time ad selectors, and video-on-demand 883 platforms. 885 Most HTTP communication consists of a retrieval request (GET) for a 886 representation of some resource identified by a URI. In the simplest 887 case, this might be accomplished via a single bidirectional 888 connection (===) between the user agent (UA) and the origin server 889 (O). 891 request > 892 UA ======================================= O 893 < response 895 Figure 1 897 3.7. Intermediaries 899 HTTP enables the use of intermediaries to satisfy requests through a 900 chain of connections. There are three common forms of HTTP 901 _intermediary_: proxy, gateway, and tunnel. In some cases, a single 902 intermediary might act as an origin server, proxy, gateway, or 903 tunnel, switching behavior based on the nature of each request. 905 > > > > 906 UA =========== A =========== B =========== C =========== O 907 < < < < 909 Figure 2 911 The figure above shows three intermediaries (A, B, and C) between the 912 user agent and origin server. A request or response message that 913 travels the whole chain will pass through four separate connections. 914 Some HTTP communication options might apply only to the connection 915 with the nearest, non-tunnel neighbor, only to the endpoints of the 916 chain, or to all connections along the chain. Although the diagram 917 is linear, each participant might be engaged in multiple, 918 simultaneous communications. For example, B might be receiving 919 requests from many clients other than A, and/or forwarding requests 920 to servers other than C, at the same time that it is handling A's 921 request. Likewise, later requests might be sent through a different 922 path of connections, often based on dynamic configuration for load 923 balancing. 925 The terms _upstream_ and _downstream_ are used to describe 926 directional requirements in relation to the message flow: all 927 messages flow from upstream to downstream. The terms "inbound" and 928 "outbound" are used to describe directional requirements in relation 929 to the request route: _inbound_ means toward the origin server and 930 _outbound_ means toward the user agent. 932 A _proxy_ is a message-forwarding agent that is chosen by the client, 933 usually via local configuration rules, to receive requests for some 934 type(s) of absolute URI and attempt to satisfy those requests via 935 translation through the HTTP interface. Some translations are 936 minimal, such as for proxy requests for "http" URIs, whereas other 937 requests might require translation to and from entirely different 938 application-level protocols. Proxies are often used to group an 939 organization's HTTP requests through a common intermediary for the 940 sake of security, annotation services, or shared caching. Some 941 proxies are designed to apply transformations to selected messages or 942 content while they are being forwarded, as described in Section 7.7. 944 A _gateway_ (a.k.a. _reverse proxy_) is an intermediary that acts as 945 an origin server for the outbound connection but translates received 946 requests and forwards them inbound to another server or servers. 947 Gateways are often used to encapsulate legacy or untrusted 948 information services, to improve server performance through 949 _accelerator_ caching, and to enable partitioning or load balancing 950 of HTTP services across multiple machines. 952 All HTTP requirements applicable to an origin server also apply to 953 the outbound communication of a gateway. A gateway communicates with 954 inbound servers using any protocol that it desires, including private 955 extensions to HTTP that are outside the scope of this specification. 956 However, an HTTP-to-HTTP gateway that wishes to interoperate with 957 third-party HTTP servers needs to conform to user agent requirements 958 on the gateway's inbound connection. 960 A _tunnel_ acts as a blind relay between two connections without 961 changing the messages. Once active, a tunnel is not considered a 962 party to the HTTP communication, though the tunnel might have been 963 initiated by an HTTP request. A tunnel ceases to exist when both 964 ends of the relayed connection are closed. Tunnels are used to 965 extend a virtual connection through an intermediary, such as when 966 Transport Layer Security (TLS, [RFC8446]) is used to establish 967 confidential communication through a shared firewall proxy. 969 The above categories for intermediary only consider those acting as 970 participants in the HTTP communication. There are also 971 intermediaries that can act on lower layers of the network protocol 972 stack, filtering or redirecting HTTP traffic without the knowledge or 973 permission of message senders. Network intermediaries are 974 indistinguishable (at a protocol level) from an on-path attacker, 975 often introducing security flaws or interoperability problems due to 976 mistakenly violating HTTP semantics. 978 For example, an _interception proxy_ [RFC3040] (also commonly known 979 as a _transparent proxy_ [RFC1919]) differs from an HTTP proxy 980 because it is not chosen by the client. Instead, an interception 981 proxy filters or redirects outgoing TCP port 80 packets (and 982 occasionally other common port traffic). Interception proxies are 983 commonly found on public network access points, as a means of 984 enforcing account subscription prior to allowing use of non-local 985 Internet services, and within corporate firewalls to enforce network 986 usage policies. 988 3.8. Caches 990 A _cache_ is a local store of previous response messages and the 991 subsystem that controls its message storage, retrieval, and deletion. 992 A cache stores cacheable responses in order to reduce the response 993 time and network bandwidth consumption on future, equivalent 994 requests. Any client or server MAY employ a cache, though a cache 995 cannot be used while acting as a tunnel. 997 The effect of a cache is that the request/response chain is shortened 998 if one of the participants along the chain has a cached response 999 applicable to that request. The following illustrates the resulting 1000 chain if B has a cached copy of an earlier response from O (via C) 1001 for a request that has not been cached by UA or A. 1003 > > 1004 UA =========== A =========== B - - - - - - C - - - - - - O 1005 < < 1007 Figure 3 1009 A response is _cacheable_ if a cache is allowed to store a copy of 1010 the response message for use in answering subsequent requests. Even 1011 when a response is cacheable, there might be additional constraints 1012 placed by the client or by the origin server on when that cached 1013 response can be used for a particular request. HTTP requirements for 1014 cache behavior and cacheable responses are defined in [Caching]. 1016 There is a wide variety of architectures and configurations of caches 1017 deployed across the World Wide Web and inside large organizations. 1018 These include national hierarchies of proxy caches to save bandwidth 1019 and reduce latency, Content Delivery Networks that use gateway 1020 caching to optimise regional and global distribution of popular 1021 sites, collaborative systems that broadcast or multicast cache 1022 entries, archives of pre-fetched cache entries for use in off-line or 1023 high-latency environments, and so on. 1025 3.9. Example Message Exchange 1027 The following example illustrates a typical HTTP/1.1 message exchange 1028 for a GET request (Section 9.3.1) on the URI "http://www.example.com/ 1029 hello.txt": 1031 Client request: 1033 GET /hello.txt HTTP/1.1 1034 User-Agent: curl/7.16.3 libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3 1035 Host: www.example.com 1036 Accept-Language: en, mi 1038 Server response: 1040 HTTP/1.1 200 OK 1041 Date: Mon, 27 Jul 2009 12:28:53 GMT 1042 Server: Apache 1043 Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT 1044 ETag: "34aa387-d-1568eb00" 1045 Accept-Ranges: bytes 1046 Content-Length: 51 1047 Vary: Accept-Encoding 1048 Content-Type: text/plain 1050 Hello World! My content includes a trailing CRLF. 1052 4. Identifiers in HTTP 1054 Uniform Resource Identifiers (URIs) [RFC3986] are used throughout 1055 HTTP as the means for identifying resources (Section 3.1). 1057 4.1. URI References 1059 URI references are used to target requests, indicate redirects, and 1060 define relationships. 1062 The definitions of "URI-reference", "absolute-URI", "relative-part", 1063 "authority", "port", "host", "path-abempty", "segment", and "query" 1064 are adopted from the URI generic syntax. An "absolute-path" rule is 1065 defined for protocol elements that can contain a non-empty path 1066 component. (This rule differs slightly from the path-abempty rule of 1067 RFC 3986, which allows for an empty path to be used in references, 1068 and path-absolute rule, which does not allow paths that begin with 1069 "//".) A "partial-URI" rule is defined for protocol elements that 1070 can contain a relative URI but not a fragment component. 1072 URI-reference = 1073 absolute-URI = 1074 relative-part = 1075 authority = 1076 uri-host = 1077 port = 1078 path-abempty = 1079 segment = 1080 query = 1082 absolute-path = 1*( "/" segment ) 1083 partial-URI = relative-part [ "?" query ] 1085 Each protocol element in HTTP that allows a URI reference will 1086 indicate in its ABNF production whether the element allows any form 1087 of reference (URI-reference), only a URI in absolute form (absolute- 1088 URI), only the path and optional query components, or some 1089 combination of the above. Unless otherwise indicated, URI references 1090 are parsed relative to the target URI (Section 7.1). 1092 It is RECOMMENDED that all senders and recipients support, at a 1093 minimum, URIs with lengths of 8000 octets in protocol elements. Note 1094 that this implies some structures and on-wire representations (for 1095 example, the request line in HTTP/1.1) will necessarily be larger in 1096 some cases. 1098 4.2. HTTP-Related URI Schemes 1100 IANA maintains the registry of URI Schemes [BCP35] at 1101 . Although requests 1102 might target any URI scheme, the following schemes are inherent to 1103 HTTP servers: 1105 +============+====================================+=======+ 1106 | URI Scheme | Description | Ref. | 1107 +============+====================================+=======+ 1108 | http | Hypertext Transfer Protocol | 4.2.1 | 1109 +------------+------------------------------------+-------+ 1110 | https | Hypertext Transfer Protocol Secure | 4.2.2 | 1111 +------------+------------------------------------+-------+ 1113 Table 2 1115 Note that the presence of an "http" or "https" URI does not imply 1116 that there is always an HTTP server at the identified origin 1117 listening for connections. Anyone can mint a URI, whether or not a 1118 server exists and whether or not that server currently maps that 1119 identifier to a resource. The delegated nature of registered names 1120 and IP addresses creates a federated namespace whether or not an HTTP 1121 server is present. 1123 4.2.1. http URI Scheme 1125 The "http" URI scheme is hereby defined for minting identifiers 1126 within the hierarchical namespace governed by a potential HTTP origin 1127 server listening for TCP ([RFC0793]) connections on a given port. 1129 http-URI = "http" "://" authority path-abempty [ "?" query ] 1131 The origin server for an "http" URI is identified by the authority 1132 component, which includes a host identifier and optional port number 1133 ([RFC3986], Section 3.2.2). If the port subcomponent is empty or not 1134 given, TCP port 80 (the reserved port for WWW services) is the 1135 default. The origin determines who has the right to respond 1136 authoritatively to requests that target the identified resource, as 1137 defined in Section 4.3.2. 1139 A sender MUST NOT generate an "http" URI with an empty host 1140 identifier. A recipient that processes such a URI reference MUST 1141 reject it as invalid. 1143 The hierarchical path component and optional query component identify 1144 the target resource within that origin server's name space. 1146 4.2.2. https URI Scheme 1148 The "https" URI scheme is hereby defined for minting identifiers 1149 within the hierarchical namespace governed by a potential origin 1150 server listening for TCP connections on a given port and capable of 1151 establishing a TLS ([RFC8446]) connection that has been secured for 1152 HTTP communication. In this context, _secured_ specifically means 1153 that the server has been authenticated as acting on behalf of the 1154 identified authority and all HTTP communication with that server has 1155 confidentiality and integrity protection that is acceptable to both 1156 client and server. 1158 https-URI = "https" "://" authority path-abempty [ "?" query ] 1160 The origin server for an "https" URI is identified by the authority 1161 component, which includes a host identifier and optional port number 1162 ([RFC3986], Section 3.2.2). If the port subcomponent is empty or not 1163 given, TCP port 443 (the reserved port for HTTP over TLS) is the 1164 default. The origin determines who has the right to respond 1165 authoritatively to requests that target the identified resource, as 1166 defined in Section 4.3.3. 1168 A sender MUST NOT generate an "https" URI with an empty host 1169 identifier. A recipient that processes such a URI reference MUST 1170 reject it as invalid. 1172 The hierarchical path component and optional query component identify 1173 the target resource within that origin server's name space. 1175 A client MUST ensure that its HTTP requests for an "https" resource 1176 are secured, prior to being communicated, and that it only accepts 1177 secured responses to those requests. Note that the definition of 1178 what cryptographic mechanisms are acceptable to client and server are 1179 usually negotiated and can change over time. 1181 Resources made available via the "https" scheme have no shared 1182 identity with the "http" scheme. They are distinct origins with 1183 separate namespaces. However, an extension to HTTP that is defined 1184 to apply to all origins with the same host, such as the Cookie 1185 protocol [RFC6265], can allow information set by one service to 1186 impact communication with other services within a matching group of 1187 host domains. 1189 4.2.3. http(s) Normalization and Comparison 1191 The "http" and "https" URI are normalized and compared according to 1192 the methods defined in Section 6 of [RFC3986], using the defaults 1193 described above for each scheme. 1195 HTTP does not require use of a specific method for determining 1196 equivalence. For example, a cache key might be compared as a simple 1197 string, after syntax-based normalization, or after scheme-based 1198 normalization. 1200 Two HTTP URIs that are equivalent after normalization (using any 1201 method) can be assumed to identify the same resource, and any HTTP 1202 component MAY perform normalization. As a result, distinct resources 1203 SHOULD NOT be identified by HTTP URIs that are equivalent after 1204 normalization (using any method defined in Section 6.2 of [RFC3986]). 1206 Scheme-based normalization (Section 6.2.3 of [RFC3986]) of "http" and 1207 "https" URIs involves the following additional rules: 1209 * If the port is equal to the default port for a scheme, the normal 1210 form is to omit the port subcomponent. 1212 * When not being used as the target of an OPTIONS request, an empty 1213 path component is equivalent to an absolute path of "/", so the 1214 normal form is to provide a path of "/" instead. 1216 * The scheme and host are case-insensitive and normally provided in 1217 lowercase; all other components are compared in a case-sensitive 1218 manner. 1220 * Characters other than those in the "reserved" set are equivalent 1221 to their percent-encoded octets: the normal form is to not encode 1222 them (see Sections 2.1 and 2.2 of [RFC3986]). 1224 For example, the following three URIs are equivalent: 1226 http://example.com:80/~smith/home.html 1227 http://EXAMPLE.com/%7Esmith/home.html 1228 http://EXAMPLE.com:/%7esmith/home.html 1230 4.2.4. Deprecation of userinfo in http(s) URIs 1232 The URI generic syntax for authority also includes a userinfo 1233 subcomponent ([RFC3986], Section 3.2.1) for including user 1234 authentication information in the URI. In that subcomponent, the use 1235 of the format "user:password" is deprecated. 1237 Some implementations make use of the userinfo component for internal 1238 configuration of authentication information, such as within command 1239 invocation options, configuration files, or bookmark lists, even 1240 though such usage might expose a user identifier or password. 1242 A sender MUST NOT generate the userinfo subcomponent (and its "@" 1243 delimiter) when an "http" or "https" URI reference is generated 1244 within a message as a target URI or field value. 1246 Before making use of an "http" or "https" URI reference received from 1247 an untrusted source, a recipient SHOULD parse for userinfo and treat 1248 its presence as an error; it is likely being used to obscure the 1249 authority for the sake of phishing attacks. 1251 4.2.5. http(s) References with Fragment Identifiers 1253 Fragment identifiers allow for indirect identification of a secondary 1254 resource, independent of the URI scheme, as defined in Section 3.5 of 1255 [RFC3986]. Some protocol elements that refer to a URI allow 1256 inclusion of a fragment, while others do not. They are distinguished 1257 by use of the ABNF rule for elements where fragment is allowed; 1258 otherwise, a specific rule that excludes fragments is used. 1260 | *Note:* The fragment identifier component is not part of the 1261 | scheme definition for a URI scheme (see Section 4.3 of 1262 | [RFC3986]), thus does not appear in the ABNF definitions for 1263 | the "http" and "https" URI schemes above. 1265 4.3. Authoritative Access 1267 Authoritative access refers to dereferencing a given identifier, for 1268 the sake of access to the identified resource, in a way that the 1269 client believes is authoritative (controlled by the resource owner). 1270 The process for determining that access is defined by the URI scheme 1271 and often uses data within the URI components, such as the authority 1272 component when the generic syntax is used. However, authoritative 1273 access is not limited to the identified mechanism. 1275 Section 4.3.1 defines the concept of an origin as an aid to such 1276 uses, and the subsequent subsections explain how to establish a 1277 peer's association with an authority to represent an origin. 1279 See Section 17.1 for security considerations related to establishing 1280 authority. 1282 4.3.1. URI Origin 1284 The _origin_ for a given URI is the triple of scheme, host, and port 1285 after normalizing the scheme and host to lowercase and normalizing 1286 the port to remove any leading zeros. If port is elided from the 1287 URI, the default port for that scheme is used. For example, the URI 1289 https://Example.Com/happy.js 1291 would have the origin 1293 { "https", "example.com", "443" } 1295 which can also be described as the normalized URI prefix with port 1296 always present: 1298 https://example.com:443 1300 Each origin defines its own namespace and controls how identifiers 1301 within that namespace are mapped to resources. In turn, how the 1302 origin responds to valid requests, consistently over time, determines 1303 the semantics that users will associate with a URI, and the 1304 usefulness of those semantics is what ultimately transforms these 1305 mechanisms into a "resource" for users to reference and access in the 1306 future. 1308 Two origins are distinct if they differ in scheme, host, or port. 1309 Even when it can be verified that the same entity controls two 1310 distinct origins, the two namespaces under those origins are distinct 1311 unless explicitly aliased by a server authoritative for that origin. 1313 Origin is also used within HTML and related Web protocols, beyond the 1314 scope of this document, as described in [RFC6454]. 1316 4.3.2. http origins 1318 Although HTTP is independent of the transport protocol, the "http" 1319 scheme (Section 4.2.1) is specific to associating authority with 1320 whomever controls the origin server listening for TCP connections on 1321 the indicated port of whatever host is identified within the 1322 authority component. This is a very weak sense of authority because 1323 it depends on both client-specific name resolution mechanisms and 1324 communication that might not be secured from an on-path attacker. 1325 Nevertheless, it is a sufficient minimum for binding "http" 1326 identifiers to an origin server for consistent resolution within a 1327 trusted environment. 1329 If the host identifier is provided as an IP address, the origin 1330 server is the listener (if any) on the indicated TCP port at that IP 1331 address. If host is a registered name, the registered name is an 1332 indirect identifier for use with a name resolution service, such as 1333 DNS, to find an address for an appropriate origin server. 1335 When an "http" URI is used within a context that calls for access to 1336 the indicated resource, a client MAY attempt access by resolving the 1337 host identifier to an IP address, establishing a TCP connection to 1338 that address on the indicated port, and sending an HTTP request 1339 message to the server containing the URI's identifying data. 1341 If the server responds to such a request with a non-interim HTTP 1342 response message, as described in Section 15, then that response is 1343 considered an authoritative answer to the client's request. 1345 Note, however, that the above is not the only means for obtaining an 1346 authoritative response, nor does it imply that an authoritative 1347 response is always necessary (see [Caching]). For example, the Alt- 1348 Svc header field [RFC7838] allows an origin server to identify other 1349 services that are also authoritative for that origin. Access to 1350 "http" identified resources might also be provided by protocols 1351 outside the scope of this document. 1353 4.3.3. https origins 1355 The "https" scheme (Section 4.2.2) associates authority based on the 1356 ability of a server to use the private key corresponding to a 1357 certificate that the client considers to be trustworthy for the 1358 identified origin server. The client usually relies upon a chain of 1359 trust, conveyed from some prearranged or configured trust anchor, to 1360 deem a certificate trustworthy (Section 4.3.4). 1362 In HTTP/1.1 and earlier, a client will only attribute authority to a 1363 server when they are communicating over a successfully established 1364 and secured connection specifically to that URI origin's host. The 1365 connection establishment and certificate verification are used as 1366 proof of authority. 1368 In HTTP/2 and HTTP/3, a client will attribute authority to a server 1369 when they are communicating over a successfully established and 1370 secured connection if the URI origin's host matches any of the hosts 1371 present in the server's certificate and the client believes that it 1372 could open a connection to that host for that URI. In practice, a 1373 client will make a DNS query to check that the origin's host contains 1374 the same server IP address as the established connection. This 1375 restriction can be removed by the origin server sending an equivalent 1376 ORIGIN frame [RFC8336]. 1378 The request target's host and port value are passed within each HTTP 1379 request, identifying the origin and distinguishing it from other 1380 namespaces that might be controlled by the same server (Section 7.2). 1381 It is the origin's responsibility to ensure that any services 1382 provided with control over its certificate's private key are equally 1383 responsible for managing the corresponding "https" namespaces, or at 1384 least prepared to reject requests that appear to have been 1385 misdirected. A server might be unwilling to serve as the origin for 1386 some hosts even when they have the authority to do so. 1388 For example, if a network attacker causes connections for port N to 1389 be received at port Q, checking the target URI is necessary to ensure 1390 that the attacker can't cause "https://example.com:N/foo" to be 1391 replaced by "https://example.com:Q/foo" without consent. 1393 Note that the "https" scheme does not rely on TCP and the connected 1394 port number for associating authority, since both are outside the 1395 secured communication and thus cannot be trusted as definitive. 1396 Hence, the HTTP communication might take place over any channel that 1397 has been secured, as defined in Section 4.2.2, including protocols 1398 that don't use TCP. 1400 When an "https" URI is used within a context that calls for access to 1401 the indicated resource, a client MAY attempt access by resolving the 1402 host identifier to an IP address, establishing a TCP connection to 1403 that address on the indicated port, securing the connection end-to- 1404 end by successfully initiating TLS over TCP with confidentiality and 1405 integrity protection, and sending an HTTP request message over that 1406 connection containing the URI's identifying data. 1408 If the server responds to such a request with a non-interim HTTP 1409 response message, as described in Section 15, then that response is 1410 considered an authoritative answer to the client's request. 1412 Note, however, that the above is not the only means for obtaining an 1413 authoritative response, nor does it imply that an authoritative 1414 response is always necessary (see [Caching]). 1416 4.3.4. https certificate verification 1418 To establish a secured connection to dereference a URI, a client MUST 1419 verify that the service's identity is an acceptable match for the 1420 URI's origin server. Certificate verification is used to prevent 1421 server impersonation by an on-path attacker or by an attacker that 1422 controls name resolution. This process requires that a client be 1423 configured with a set of trust anchors. 1425 In general, a client MUST verify the service identity using the 1426 verification process defined in Section 6 of [RFC6125]. The client 1427 MUST construct a reference identity from the service's host: if the 1428 host is a literal IP address (Section 4.3.5), the reference identity 1429 is an IP-ID, otherwise the host is a name and the reference identity 1430 is a DNS-ID. 1432 A reference identity of type CN-ID MUST NOT be used by clients. As 1433 noted in Section 6.2.1 of [RFC6125] a reference identity of type CN- 1434 ID might be used by older clients. 1436 A client might be specially configured to accept an alternative form 1437 of server identity verification. For example, a client might be 1438 connecting to a server whose address and hostname are dynamic, with 1439 an expectation that the service will present a specific certificate 1440 (or a certificate matching some externally defined reference 1441 identity) rather than one matching the dynamic URI's origin server 1442 identifier. 1444 In special cases, it might be appropriate for a client to simply 1445 ignore the server's identity, but it must be understood that this 1446 leaves a connection open to active attack. 1448 If the certificate is not valid for the URI's origin server, a user 1449 agent MUST either notify the user (user agents MAY give the user an 1450 option to continue with the connection in any case) or terminate the 1451 connection with a bad certificate error. Automated clients MUST log 1452 the error to an appropriate audit log (if available) and SHOULD 1453 terminate the connection (with a bad certificate error). Automated 1454 clients MAY provide a configuration setting that disables this check, 1455 but MUST provide a setting which enables it. 1457 4.3.5. IP-ID reference identity 1459 A server that is identified using an IP address literal in the "host" 1460 field of an "https" URI has a reference identity of type IP-ID. An 1461 IP version 4 address uses the "IPv4address" ABNF rule and an IP 1462 version 6 address uses the "IP-literal" production with the 1463 "IPv6address" option; see Section 3.2.2 of [RFC3986]. A reference 1464 identity of IP-ID contains the decoded bytes of the IP address. 1466 An IP version 4 address is 4 octets and an IP version 6 address is 16 1467 octets. Use of IP-ID is not defined for any other IP version. The 1468 iPAddress choice in the certificate subjectAltName extension does not 1469 explicitly include the IP version and so relies on the length of the 1470 address to distinguish versions; see Section 4.2.1.6 of [RFC5280]. 1472 A reference identity of type IP-ID matches if the address is 1473 identical to an iPAddress value of the subjectAltName extension of 1474 the certificate. 1476 5. Fields 1478 HTTP uses _fields_ to provide data in the form of extensible key/ 1479 value pairs with a registered key namespace. Fields are sent and 1480 received within the header and trailer sections of messages 1481 (Section 6). 1483 5.1. Field Names 1485 A field name labels the corresponding field value as having the 1486 semantics defined by that name. For example, the Date header field 1487 is defined in Section 10.2.2 as containing the origination timestamp 1488 for the message in which it appears. 1490 field-name = token 1492 Field names are case-insensitive and ought to be registered within 1493 the "Hypertext Transfer Protocol (HTTP) Field Name Registry"; see 1494 Section 16.3.1. 1496 The interpretation of a field does not change between minor versions 1497 of the same major HTTP version, though the default behavior of a 1498 recipient in the absence of such a field can change. Unless 1499 specified otherwise, fields are defined for all versions of HTTP. In 1500 particular, the Host and Connection fields ought to be recognized by 1501 all HTTP implementations whether or not they advertise conformance 1502 with HTTP/1.1. 1504 New fields can be introduced without changing the protocol version if 1505 their defined semantics allow them to be safely ignored by recipients 1506 that do not recognize them; see Section 16.3. 1508 A proxy MUST forward unrecognized header fields unless the field name 1509 is listed in the Connection header field (Section 7.6.1) or the proxy 1510 is specifically configured to block, or otherwise transform, such 1511 fields. Other recipients SHOULD ignore unrecognized header and 1512 trailer fields. Adhering to these requirements allows HTTP's 1513 functionality to be extended without updating or removing deployed 1514 intermediaries. 1516 5.2. Field Lines and Combined Field Value 1518 Field sections are composed of any number of _field lines_, each with 1519 a _field name_ (see Section 5.1) identifying the field, and a _field 1520 line value_ that conveys data for that instance of the field. 1522 When a field name is only present once in a section, the combined 1523 _field value_ for that field consists of the corresponding field line 1524 value. When a field name is repeated within a section, its combined 1525 field value consists of the list of corresponding field line values 1526 within that section, concatenated in order, with each field line 1527 value separated by a comma. 1529 For example, this section: 1531 Example-Field: Foo, Bar 1532 Example-Field: Baz 1534 contains two field lines, both with the field name "Example-Field". 1535 The first field line has a field line value of "Foo, Bar", while the 1536 second field line value is "Baz". The field value for "Example- 1537 Field" is a list with three members: "Foo", "Bar", and "Baz". 1539 5.3. Field Order 1541 A recipient MAY combine multiple field lines within a field section 1542 that have the same field name into one field line, without changing 1543 the semantics of the message, by appending each subsequent field line 1544 value to the initial field line value in order, separated by a comma 1545 (",") and optional whitespace (OWS, defined in Section 5.6.3). For 1546 consistency, use comma SP. 1548 The order in which field lines with the same name are received is 1549 therefore significant to the interpretation of the field value; a 1550 proxy MUST NOT change the order of these field line values when 1551 forwarding a message. 1553 This means that, aside from the well-known exception noted below, a 1554 sender MUST NOT generate multiple field lines with the same name in a 1555 message (whether in the headers or trailers), or append a field line 1556 when a field line of the same name already exists in the message, 1557 unless that field's definition allows multiple field line values to 1558 be recombined as a comma-separated list [i.e., at least one 1559 alternative of the field's definition allows a comma-separated list, 1560 such as an ABNF rule of #(values) defined in Section 5.6.1]. 1562 | *Note:* In practice, the "Set-Cookie" header field ([RFC6265]) 1563 | often appears in a response message across multiple field lines 1564 | and does not use the list syntax, violating the above 1565 | requirements on multiple field lines with the same field name. 1566 | Since it cannot be combined into a single field value, 1567 | recipients ought to handle "Set-Cookie" as a special case while 1568 | processing fields. (See Appendix A.2.3 of [Kri2001] for 1569 | details.) 1571 The order in which field lines with differing field names are 1572 received in a section is not significant. However, it is good 1573 practice to send header fields that contain additional control data 1574 first, such as Host on requests and Date on responses, so that 1575 implementations can decide when not to handle a message as early as 1576 possible. 1578 A server MUST NOT apply a request to the target resource until it 1579 receives the entire request header section, since later header field 1580 lines might include conditionals, authentication credentials, or 1581 deliberately misleading duplicate header fields that could impact 1582 request processing. 1584 5.4. Field Limits 1586 HTTP does not place a predefined limit on the length of each field 1587 line, field value, or on the length of a header or trailer section as 1588 a whole, as described in Section 2. Various ad hoc limitations on 1589 individual lengths are found in practice, often depending on the 1590 specific field's semantics. 1592 A server that receives a request header field line, field value, or 1593 set of fields larger than it wishes to process MUST respond with an 1594 appropriate 4xx (Client Error) status code. Ignoring such header 1595 fields would increase the server's vulnerability to request smuggling 1596 attacks (Section 11.2 of [Messaging]). 1598 A client MAY discard or truncate received field lines that are larger 1599 than the client wishes to process if the field semantics are such 1600 that the dropped value(s) can be safely ignored without changing the 1601 message framing or response semantics. 1603 5.5. Field Values 1605 HTTP field values consist of a sequence of characters in a format 1606 defined by the field's grammar. Each field's grammar is usually 1607 defined using ABNF ([RFC5234]). 1609 field-value = *field-content 1610 field-content = field-vchar 1611 [ 1*( SP / HTAB / field-vchar ) field-vchar ] 1612 field-vchar = VCHAR / obs-text 1614 A field value does not include leading or trailing whitespace. When 1615 a specific version of HTTP allows such whitespace to appear in a 1616 message, a field parsing implementation MUST exclude such whitespace 1617 prior to evaluating the field value. 1619 Field values are usually constrained to the range of US-ASCII 1620 characters [USASCII]. Fields needing a greater range of characters 1621 can use an encoding, such as the one defined in [RFC8187]. 1622 Historically, HTTP allowed field content with text in the ISO-8859-1 1623 charset [ISO-8859-1], supporting other charsets only through use of 1624 [RFC2047] encoding. Specifications for newly defined fields SHOULD 1625 limit their values to visible US-ASCII octets (VCHAR), SP, and HTAB. 1626 A recipient SHOULD treat other octets in field content (obs-text) as 1627 opaque data. 1629 Field values containing CR or NUL characters are invalid and 1630 dangerous, due to the varying ways that implementations might parse 1631 and interpret those characters; a recipient of CR or NUL within a 1632 field value MUST either reject the message or replace each of those 1633 characters with SP before further processing or forwarding of that 1634 message. Field values containing other CTL characters are also 1635 invalid; however, recipients MAY retain such characters for the sake 1636 of robustness if they only appear within safe field value contexts 1637 (e.g., opaque data). 1639 Fields that only anticipate a single member as the field value are 1640 referred to as _singleton fields_. 1642 Fields that allow multiple members as the field value are referred to 1643 as _list-based fields_. The list operator extension of Section 5.6.1 1644 is used as a common notation for defining field values that can 1645 contain multiple members. 1647 Because commas (",") are used as the delimiter between members, they 1648 need to be treated with care if they are allowed as data within a 1649 member. This is true for both list-based and singleton fields, since 1650 a singleton field might be erroneously sent with multiple members and 1651 detecting such errors improves interoperability. Fields that expect 1652 to contain a comma within a member, such as within an HTTP-date or 1653 URI-reference element, ought to be defined with delimiters around 1654 that element to distinguish any comma within that data from potential 1655 list separators. 1657 For example, a textual date and a URI (either of which might contain 1658 a comma) could be safely carried in list-based field values like 1659 these: 1661 Example-URIs: "http://example.com/a.html,foo", 1662 "http://without-a-comma.example.com/" 1663 Example-Dates: "Sat, 04 May 1996", "Wed, 14 Sep 2005" 1665 Note that double-quote delimiters are almost always used with the 1666 quoted-string production; using a different syntax inside double- 1667 quotes will likely cause unnecessary confusion. 1669 Many fields (such as Content-Type, defined in Section 8.3) use a 1670 common syntax for parameters that allows both unquoted (token) and 1671 quoted (quoted-string) syntax for a parameter value (Section 5.6.6). 1672 Use of common syntax allows recipients to reuse existing parser 1673 components. When allowing both forms, the meaning of a parameter 1674 value ought to be the same whether it was received as a token or a 1675 quoted string. 1677 Historically, HTTP field values could be extended over multiple lines 1678 by preceding each extra line with at least one space or horizontal 1679 tab (obs-fold). This document assumes that any such obsolete line 1680 folding has been removed prior to interpreting the field value (e.g., 1681 as described in Section 5.2 of [Messaging]). 1683 | *Note:* For defining field value syntax, this specification 1684 | uses an ABNF rule named after the field name to define the 1685 | allowed grammar for that field's value (after said value has 1686 | been extracted from the underlying messaging syntax and 1687 | multiple instances combined into a list). 1689 5.6. Common Rules for Defining Field Values 1691 5.6.1. Lists (#rule ABNF Extension) 1693 A #rule extension to the ABNF rules of [RFC5234] is used to improve 1694 readability in the definitions of some list-based field values. 1696 A construct "#" is defined, similar to "*", for defining comma- 1697 delimited lists of elements. The full form is "#element" 1698 indicating at least and at most elements, each separated by a 1699 single comma (",") and optional whitespace (OWS, defined in 1700 Section 5.6.3). 1702 5.6.1.1. Sender Requirements 1704 In any production that uses the list construct, a sender MUST NOT 1705 generate empty list elements. In other words, a sender MUST generate 1706 lists that satisfy the following syntax: 1708 1#element => element *( OWS "," OWS element ) 1710 and: 1712 #element => [ 1#element ] 1714 and for n >= 1 and m > 1: 1716 #element => element *( OWS "," OWS element ) 1718 Appendix A shows the collected ABNF for senders after the list 1719 constructs have been expanded. 1721 5.6.1.2. Recipient Requirements 1723 Empty elements do not contribute to the count of elements present. A 1724 recipient MUST parse and ignore a reasonable number of empty list 1725 elements: enough to handle common mistakes by senders that merge 1726 values, but not so much that they could be used as a denial-of- 1727 service mechanism. In other words, a recipient MUST accept lists 1728 that satisfy the following syntax: 1730 #element => [ element ] *( OWS "," OWS [ element ] ) 1732 Note that because of the potential presence of empty list elements, 1733 the RFC 5234 ABNF cannot enforce the cardinality of list elements, 1734 and consequently all cases are mapped as if there was no cardinality 1735 specified. 1737 For example, given these ABNF productions: 1739 example-list = 1#example-list-elmt 1740 example-list-elmt = token ; see Section 5.6.2 1742 Then the following are valid values for example-list (not including 1743 the double quotes, which are present for delimitation only): 1745 "foo,bar" 1746 "foo ,bar," 1747 "foo , ,bar,charlie" 1749 In contrast, the following values would be invalid, since at least 1750 one non-empty element is required by the example-list production: 1752 "" 1753 "," 1754 ", ," 1756 5.6.2. Tokens 1758 Tokens are short textual identifiers that do not include whitespace 1759 or delimiters. 1761 token = 1*tchar 1763 tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" 1764 / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" 1765 / DIGIT / ALPHA 1766 ; any VCHAR, except delimiters 1768 Many HTTP field values are defined using common syntax components, 1769 separated by whitespace or specific delimiting characters. 1770 Delimiters are chosen from the set of US-ASCII visual characters not 1771 allowed in a token (DQUOTE and "(),/:;<=>?@[\]{}"). 1773 5.6.3. Whitespace 1775 This specification uses three rules to denote the use of linear 1776 whitespace: OWS (optional whitespace), RWS (required whitespace), and 1777 BWS ("bad" whitespace). 1779 The OWS rule is used where zero or more linear whitespace octets 1780 might appear. For protocol elements where optional whitespace is 1781 preferred to improve readability, a sender SHOULD generate the 1782 optional whitespace as a single SP; otherwise, a sender SHOULD NOT 1783 generate optional whitespace except as needed to overwrite invalid or 1784 unwanted protocol elements during in-place message filtering. 1786 The RWS rule is used when at least one linear whitespace octet is 1787 required to separate field tokens. A sender SHOULD generate RWS as a 1788 single SP. 1790 OWS and RWS have the same semantics as a single SP. Any content 1791 known to be defined as OWS or RWS MAY be replaced with a single SP 1792 before interpreting it or forwarding the message downstream. 1794 The BWS rule is used where the grammar allows optional whitespace 1795 only for historical reasons. A sender MUST NOT generate BWS in 1796 messages. A recipient MUST parse for such bad whitespace and remove 1797 it before interpreting the protocol element. 1799 BWS has no semantics. Any content known to be defined as BWS MAY be 1800 removed before interpreting it or forwarding the message downstream. 1802 OWS = *( SP / HTAB ) 1803 ; optional whitespace 1804 RWS = 1*( SP / HTAB ) 1805 ; required whitespace 1806 BWS = OWS 1807 ; "bad" whitespace 1809 5.6.4. Quoted Strings 1811 A string of text is parsed as a single value if it is quoted using 1812 double-quote marks. 1814 quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE 1815 qdtext = HTAB / SP / %x21 / %x23-5B / %x5D-7E / obs-text 1816 obs-text = %x80-FF 1818 The backslash octet ("\") can be used as a single-octet quoting 1819 mechanism within quoted-string and comment constructs. Recipients 1820 that process the value of a quoted-string MUST handle a quoted-pair 1821 as if it were replaced by the octet following the backslash. 1823 quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) 1825 A sender SHOULD NOT generate a quoted-pair in a quoted-string except 1826 where necessary to quote DQUOTE and backslash octets occurring within 1827 that string. A sender SHOULD NOT generate a quoted-pair in a comment 1828 except where necessary to quote parentheses ["(" and ")"] and 1829 backslash octets occurring within that comment. 1831 5.6.5. Comments 1833 Comments can be included in some HTTP fields by surrounding the 1834 comment text with parentheses. Comments are only allowed in fields 1835 containing "comment" as part of their field value definition. 1837 comment = "(" *( ctext / quoted-pair / comment ) ")" 1838 ctext = HTAB / SP / %x21-27 / %x2A-5B / %x5D-7E / obs-text 1840 5.6.6. Parameters 1842 Parameters are instances of name=value pairs; they are often used in 1843 field values as a common syntax for appending auxiliary information 1844 to an item. Each parameter is usually delimited by an immediately 1845 preceding semicolon. 1847 parameters = *( OWS ";" OWS [ parameter ] ) 1848 parameter = parameter-name "=" parameter-value 1849 parameter-name = token 1850 parameter-value = ( token / quoted-string ) 1852 Parameter names are case-insensitive. Parameter values might or 1853 might not be case-sensitive, depending on the semantics of the 1854 parameter name. Examples of parameters and some equivalent forms can 1855 be seen in media types (Section 8.3.1) and the Accept header field 1856 (Section 12.5.1). 1858 A parameter value that matches the token production can be 1859 transmitted either as a token or within a quoted-string. The quoted 1860 and unquoted values are equivalent. 1862 | *Note:* Parameters do not allow whitespace (not even "bad" 1863 | whitespace) around the "=" character. 1865 5.6.7. Date/Time Formats 1867 Prior to 1995, there were three different formats commonly used by 1868 servers to communicate timestamps. For compatibility with old 1869 implementations, all three are defined here. The preferred format is 1870 a fixed-length and single-zone subset of the date and time 1871 specification used by the Internet Message Format [RFC5322]. 1873 HTTP-date = IMF-fixdate / obs-date 1875 An example of the preferred format is 1877 Sun, 06 Nov 1994 08:49:37 GMT ; IMF-fixdate 1879 Examples of the two obsolete formats are 1881 Sunday, 06-Nov-94 08:49:37 GMT ; obsolete RFC 850 format 1882 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format 1884 A recipient that parses a timestamp value in an HTTP field MUST 1885 accept all three HTTP-date formats. When a sender generates a field 1886 that contains one or more timestamps defined as HTTP-date, the sender 1887 MUST generate those timestamps in the IMF-fixdate format. 1889 An HTTP-date value represents time as an instance of Coordinated 1890 Universal Time (UTC). The first two formats indicate UTC by the 1891 three-letter abbreviation for Greenwich Mean Time, "GMT", a 1892 predecessor of the UTC name; values in the asctime format are assumed 1893 to be in UTC. A sender that generates HTTP-date values from a local 1894 clock ought to use NTP ([RFC5905]) or some similar protocol to 1895 synchronize its clock to UTC. 1897 Preferred format: 1899 IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT 1900 ; fixed length/zone/capitalization subset of the format 1901 ; see Section 3.3 of [RFC5322] 1903 day-name = %s"Mon" / %s"Tue" / %s"Wed" 1904 / %s"Thu" / %s"Fri" / %s"Sat" / %s"Sun" 1906 date1 = day SP month SP year 1907 ; e.g., 02 Jun 1982 1909 day = 2DIGIT 1910 month = %s"Jan" / %s"Feb" / %s"Mar" / %s"Apr" 1911 / %s"May" / %s"Jun" / %s"Jul" / %s"Aug" 1912 / %s"Sep" / %s"Oct" / %s"Nov" / %s"Dec" 1913 year = 4DIGIT 1915 GMT = %s"GMT" 1917 time-of-day = hour ":" minute ":" second 1918 ; 00:00:00 - 23:59:60 (leap second) 1920 hour = 2DIGIT 1921 minute = 2DIGIT 1922 second = 2DIGIT 1924 Obsolete formats: 1926 obs-date = rfc850-date / asctime-date 1928 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 1929 date2 = day "-" month "-" 2DIGIT 1930 ; e.g., 02-Jun-82 1932 day-name-l = %s"Monday" / %s"Tuesday" / %s"Wednesday" 1933 / %s"Thursday" / %s"Friday" / %s"Saturday" 1934 / %s"Sunday" 1936 asctime-date = day-name SP date3 SP time-of-day SP year 1937 date3 = month SP ( 2DIGIT / ( SP 1DIGIT )) 1938 ; e.g., Jun 2 1940 HTTP-date is case sensitive. Note that Section 4.2 of [Caching] 1941 relaxes this for cache recipients. 1943 A sender MUST NOT generate additional whitespace in an HTTP-date 1944 beyond that specifically included as SP in the grammar. The 1945 semantics of day-name, day, month, year, and time-of-day are the same 1946 as those defined for the Internet Message Format constructs with the 1947 corresponding name ([RFC5322], Section 3.3). 1949 Recipients of a timestamp value in rfc850-date format, which uses a 1950 two-digit year, MUST interpret a timestamp that appears to be more 1951 than 50 years in the future as representing the most recent year in 1952 the past that had the same last two digits. 1954 Recipients of timestamp values are encouraged to be robust in parsing 1955 timestamps unless otherwise restricted by the field definition. For 1956 example, messages are occasionally forwarded over HTTP from a non- 1957 HTTP source that might generate any of the date and time 1958 specifications defined by the Internet Message Format. 1960 | *Note:* HTTP requirements for the date/time stamp format apply 1961 | only to their usage within the protocol stream. 1962 | Implementations are not required to use these formats for user 1963 | presentation, request logging, etc. 1965 6. Message Abstraction 1967 Each major version of HTTP defines its own syntax for communicating 1968 messages. This section defines an abstract data type for HTTP 1969 messages based on a generalization of those message characteristics, 1970 common structure, and capacity for conveying semantics. This 1971 abstraction is used to define requirements on senders and recipients 1972 that are independent of the HTTP version, such that a message in one 1973 version can be relayed through other versions without changing its 1974 meaning. 1976 A _message_ consists of control data to describe and route the 1977 message, a headers lookup table of key/value pairs for extending that 1978 control data and conveying additional information about the sender, 1979 message, content, or context, a potentially unbounded stream of 1980 content, and a trailers lookup table of key/value pairs for 1981 communicating information obtained while sending the content. 1983 Framing and control data is sent first, followed by a header section 1984 containing fields for the headers table. When a message includes 1985 content, the content is sent after the header section, potentially 1986 followed by a trailer section that might contain fields for the 1987 trailers table. 1989 Messages are expected to be processed as a stream, wherein the 1990 purpose of that stream and its continued processing is revealed while 1991 being read. Hence, control data describes what the recipient needs 1992 to know immediately, header fields describe what needs to be known 1993 before receiving content, the content (when present) presumably 1994 contains what the recipient wants or needs to fulfill the message 1995 semantics, and trailer fields provide optional metadata that was 1996 unknown prior to sending the content. 1998 Messages are intended to be _self-descriptive_: everything a 1999 recipient needs to know about the message can be determined by 2000 looking at the message itself, after decoding or reconstituting parts 2001 that have been compressed or elided in transit, without requiring an 2002 understanding of the sender's current application state (established 2003 via prior messages). However, a client MUST retain knowledge of the 2004 request when parsing, interpreting, or caching a corresponding 2005 response. For example, responses to the HEAD method look just like 2006 the beginning of a response to GET, but cannot be parsed in the same 2007 manner. 2009 Note that this message abstraction is a generalization across many 2010 versions of HTTP, including features that might not be found in some 2011 versions. For example, trailers were introduced within the HTTP/1.1 2012 chunked transfer coding as a trailer section after the content. An 2013 equivalent feature is present in HTTP/2 and HTTP/3 within the header 2014 block that terminates each stream. 2016 6.1. Framing and Completeness 2018 Message framing indicates how each message begins and ends, such that 2019 each message can be distinguished from other messages or noise on the 2020 same connection. Each major version of HTTP defines its own framing 2021 mechanism. 2023 HTTP/0.9 and early deployments of HTTP/1.0 used closure of the 2024 underlying connection to end a response. For backwards 2025 compatibility, this implicit framing is also allowed in HTTP/1.1. 2026 However, implicit framing can fail to distinguish an incomplete 2027 response if the connection closes early. For that reason, almost all 2028 modern implementations use explicit framing in the form of length- 2029 delimited sequences of message data. 2031 A message is considered _complete_ when all of the octets indicated 2032 by its framing are available. Note that, when no explicit framing is 2033 used, a response message that is ended by the underlying connection's 2034 close is considered complete even though it might be 2035 indistinguishable from an incomplete response, unless a transport- 2036 level error indicates that it is not complete. 2038 6.2. Control Data 2040 Messages start with control data that describe its primary purpose. 2041 Request message control data includes a request method (Section 9), 2042 request target (Section 7.1), and protocol version (Section 2.5). 2043 Response message control data includes a status code (Section 15), 2044 optional reason phrase, and protocol version. 2046 In HTTP/1.1 ([Messaging]) and earlier, control data is sent as the 2047 first line of a message. In HTTP/2 ([RFC7540]) and HTTP/3 ([HTTP3]), 2048 control data is sent as pseudo-header fields with a reserved name 2049 prefix (e.g., ":authority"). 2051 Every HTTP message has a protocol version. Depending on the version 2052 in use, it might be identified within the message explicitly or 2053 inferred by the connection over which the message is received. 2054 Recipients use that version information to determine limitations or 2055 potential for later communication with that sender. 2057 When a message is forwarded by an intermediary, the protocol version 2058 is updated to reflect the version used by that intermediary. The Via 2059 header field (Section 7.6.3) is used to communicate upstream protocol 2060 information within a forwarded message. 2062 A client SHOULD send a request version equal to the highest version 2063 to which the client is conformant and whose major version is no 2064 higher than the highest version supported by the server, if this is 2065 known. A client MUST NOT send a version to which it is not 2066 conformant. 2068 A client MAY send a lower request version if it is known that the 2069 server incorrectly implements the HTTP specification, but only after 2070 the client has attempted at least one normal request and determined 2071 from the response status code or header fields (e.g., Server) that 2072 the server improperly handles higher request versions. 2074 A server SHOULD send a response version equal to the highest version 2075 to which the server is conformant that has a major version less than 2076 or equal to the one received in the request. A server MUST NOT send 2077 a version to which it is not conformant. A server can send a 505 2078 (HTTP Version Not Supported) response if it wishes, for any reason, 2079 to refuse service of the client's major protocol version. 2081 A recipient that receives a message with a major version number that 2082 it implements and a minor version number higher than what it 2083 implements SHOULD process the message as if it were in the highest 2084 minor version within that major version to which the recipient is 2085 conformant. A recipient can assume that a message with a higher 2086 minor version, when sent to a recipient that has not yet indicated 2087 support for that higher version, is sufficiently backwards-compatible 2088 to be safely processed by any implementation of the same major 2089 version. 2091 6.3. Header Fields 2093 Fields (Section 5) that are sent/received before the content are 2094 referred to as "header fields" (or just "headers", colloquially). 2096 The _header section_ of a message consists of a sequence of header 2097 field lines. Each header field might modify or extend message 2098 semantics, describe the sender, define the content, or provide 2099 additional context. 2101 | *Note:* We refer to named fields specifically as a "header 2102 | field" when they are only allowed to be sent in the header 2103 | section. 2105 6.4. Content 2107 HTTP messages often transfer a complete or partial representation as 2108 the message _content_: a stream of octets sent after the header 2109 section, as delineated by the message framing. 2111 This abstract definition of content reflects the data after it has 2112 been extracted from the message framing. For example, an HTTP/1.1 2113 message body (Section 6 of [Messaging]) might consist of a stream of 2114 data encoded with the chunked transfer coding - a sequence of data 2115 chunks, one zero-length chunk, and a trailer section - whereas the 2116 content of that same message includes only the data stream after the 2117 transfer coding has been decoded; it does not include the chunk 2118 lengths, chunked framing syntax, nor the trailer fields 2119 (Section 6.5). 2121 6.4.1. Content Semantics 2123 The purpose of content in a request is defined by the method 2124 semantics (Section 9). 2126 For example, a representation in the content of a PUT request 2127 (Section 9.3.4) represents the desired state of the target resource 2128 after the request is successfully applied, whereas a representation 2129 in the content of a POST request (Section 9.3.3) represents 2130 information to be processed by the target resource. 2132 In a response, the content's purpose is defined by both the request 2133 method and the response status code (Section 15). For example, the 2134 content of a 200 (OK) response to GET (Section 9.3.1) represents the 2135 current state of the target resource, as observed at the time of the 2136 message origination date (Section 10.2.2), whereas the content of the 2137 same status code in a response to POST might represent either the 2138 processing result or the new state of the target resource after 2139 applying the processing. 2141 The content of a 206 (Partial Content) response to GET contains 2142 either a single part of the selected representation or a multipart 2143 message body containing multiple parts of that representation, as 2144 described in Section 15.3.7. 2146 Response messages with an error status code usually contain content 2147 that represents the error condition, such that the content describes 2148 the error state and what steps are suggested for resolving it. 2150 Responses to the HEAD request method (Section 9.3.2) never include 2151 content; the associated response header fields indicate only what 2152 their values would have been if the request method had been GET 2153 (Section 9.3.1). 2155 2xx (Successful) responses to a CONNECT request method 2156 (Section 9.3.6) switch the connection to tunnel mode instead of 2157 having content. 2159 All 1xx (Informational), 204 (No Content), and 304 (Not Modified) 2160 responses do not include content. 2162 All other responses do include content, although that content might 2163 be of zero length. 2165 6.4.2. Identifying Content 2167 When a complete or partial representation is transferred as message 2168 content, it is often desirable for the sender to supply, or the 2169 recipient to determine, an identifier for a resource corresponding to 2170 that representation. 2172 For a request message: 2174 * If the request has a Content-Location header field, then the 2175 sender asserts that the content is a representation of the 2176 resource identified by the Content-Location field value. However, 2177 such an assertion cannot be trusted unless it can be verified by 2178 other means (not defined by this specification). The information 2179 might still be useful for revision history links. 2181 * Otherwise, the content is unidentified. 2183 For a response message, the following rules are applied in order 2184 until a match is found: 2186 1. If the request method is HEAD or the response status code is 204 2187 (No Content) or 304 (Not Modified), there is no content in the 2188 response. 2190 2. If the request method is GET and the response status code is 200 2191 (OK), the content is a representation of the resource identified 2192 by the target URI (Section 7.1). 2194 3. If the request method is GET and the response status code is 203 2195 (Non-Authoritative Information), the content is a potentially 2196 modified or enhanced representation of the target resource as 2197 provided by an intermediary. 2199 4. If the request method is GET and the response status code is 206 2200 (Partial Content), the content is one or more parts of a 2201 representation of the resource identified by the target URI 2202 (Section 7.1). 2204 5. If the response has a Content-Location header field and its field 2205 value is a reference to the same URI as the target URI, the 2206 content is a representation of the target resource. 2208 6. If the response has a Content-Location header field and its field 2209 value is a reference to a URI different from the target URI, then 2210 the sender asserts that the content is a representation of the 2211 resource identified by the Content-Location field value. 2212 However, such an assertion cannot be trusted unless it can be 2213 verified by other means (not defined by this specification). 2215 7. Otherwise, the content is unidentified. 2217 6.5. Trailer Fields 2219 Fields (Section 5) that are located within a _trailer section_ are 2220 are referred to as "trailer fields" (or just "trailers", 2221 colloquially). Trailer fields can be useful for supplying message 2222 integrity checks, digital signatures, delivery metrics, or post- 2223 processing status information. 2225 Trailer fields ought to be processed and stored separately from the 2226 fields in the header section to avoid contradicting message semantics 2227 known at the time the header section was complete. The presence or 2228 absence of certain header fields might impact choices made for the 2229 routing or processing of the message as a whole before the trailers 2230 are received; those choices cannot be unmade by the later discovery 2231 of trailer fields. 2233 6.5.1. Limitations on use of Trailers 2235 A trailer section is only possible when supported by the version of 2236 HTTP in use and enabled by an explicit framing mechanism. For 2237 example, the chunked coding in HTTP/1.1 allows a trailer section to 2238 be sent after the content (Section 7.1.2 of [Messaging]). 2240 Many fields cannot be processed outside the header section because 2241 their evaluation is necessary prior to receiving the content, such as 2242 those that describe message framing, routing, authentication, request 2243 modifiers, response controls, or content format. A sender MUST NOT 2244 generate a trailer field unless the sender knows the corresponding 2245 header field name's definition permits the field to be sent in 2246 trailers. 2248 Trailer fields can be difficult to process by intermediaries that 2249 forward messages from one protocol version to another. If the entire 2250 message can be buffered in transit, some intermediaries could merge 2251 trailer fields into the header section (as appropriate) before it is 2252 forwarded. However, in most cases, the trailers are simply 2253 discarded. A recipient MUST NOT merge a trailer field into a header 2254 section unless the recipient understands the corresponding header 2255 field definition and that definition explicitly permits and defines 2256 how trailer field values can be safely merged. 2258 The presence of the keyword "trailers" in the TE header field 2259 (Section 10.1.4) of a request indicates that the client is willing to 2260 accept trailer fields, on behalf of itself and any downstream 2261 clients. For requests from an intermediary, this implies that all 2262 downstream clients are willing to accept trailer fields in the 2263 forwarded response. Note that the presence of "trailers" does not 2264 mean that the client(s) will process any particular trailer field in 2265 the response; only that the trailer section(s) will not be dropped by 2266 any of the clients. 2268 Because of the potential for trailer fields to be discarded in 2269 transit, a server SHOULD NOT generate trailer fields that it believes 2270 are necessary for the user agent to receive. 2272 6.5.2. Processing Trailer Fields 2274 The "Trailer" header field (Section 10.1.5) can be sent to indicate 2275 fields likely to be sent in the trailer section, which allows 2276 recipients to prepare for their receipt before processing the 2277 content. For example, this could be useful if a field name indicates 2278 that a dynamic checksum should be calculated as the content is 2279 received and then immediately checked upon receipt of the trailer 2280 field value. 2282 Like header fields, trailer fields with the same name are processed 2283 in the order received; multiple trailer field lines with the same 2284 name have the equivalent semantics as appending the multiple values 2285 as a list of members. Trailer fields that might be generated more 2286 than once during a message MUST be defined as a list-based field even 2287 if each member value is only processed once per field line received. 2289 At the end of a message, a recipient MAY treat the set of received 2290 trailer fields as a data structure of key/value pairs, similar to 2291 (but separate from) the header fields. Additional processing 2292 expectations, if any, can be defined within the field specification 2293 for a field intended for use in trailers. 2295 7. Routing HTTP Messages 2297 HTTP request message routing is determined by each client based on 2298 the target resource, the client's proxy configuration, and 2299 establishment or reuse of an inbound connection. The corresponding 2300 response routing follows the same connection chain back to the 2301 client. 2303 7.1. Determining the Target Resource 2305 Although HTTP is used in a wide variety of applications, most clients 2306 rely on the same resource identification mechanism and configuration 2307 techniques as general-purpose Web browsers. Even when communication 2308 options are hard-coded in a client's configuration, we can think of 2309 their combined effect as a URI reference (Section 4.1). 2311 A URI reference is resolved to its absolute form in order to obtain 2312 the _target URI_. The target URI excludes the reference's fragment 2313 component, if any, since fragment identifiers are reserved for 2314 client-side processing ([RFC3986], Section 3.5). 2316 To perform an action on a _target resource_, the client sends a 2317 request message containing enough components of its parsed target URI 2318 to enable recipients to identify that same resource. For historical 2319 reasons, the parsed target URI components, collectively referred to 2320 as the _request target_, are sent within the message control data and 2321 the Host header field (Section 7.2). 2323 There are two unusual cases for which the request target components 2324 are in a method-specific form: 2326 * For CONNECT (Section 9.3.6), the request target is the host name 2327 and port number of the tunnel destination, separated by a colon. 2329 * For OPTIONS (Section 9.3.7), the request target can be a single 2330 asterisk ("*"). 2332 See the respective method definitions for details. These forms MUST 2333 NOT be used with other methods. 2335 Upon receipt of a client's request, a server reconstructs the target 2336 URI from the received components in accordance with their local 2337 configuration and incoming connection context. This reconstruction 2338 is specific to each major protocol version. For example, Appendix of 2339 [Messaging] defines how a server determines the target URI of an 2340 HTTP/1.1 request. 2342 | *Note:* Previous specifications defined the recomposed target 2343 | URI as a distinct concept, the _effective request URI_. 2345 7.2. Host and :authority 2347 The "Host" header field in a request provides the host and port 2348 information from the target URI, enabling the origin server to 2349 distinguish among resources while servicing requests for multiple 2350 host names. 2352 In HTTP/2 [RFC7540] and HTTP/3 [HTTP3], the Host header field is, in 2353 some cases, supplanted by the ":authority" pseudo-header field of a 2354 request's control data. 2356 Host = uri-host [ ":" port ] ; Section 4 2358 The target URI's authority information is critical for handling a 2359 request. A user agent MUST generate a Host header field in a request 2360 unless it sends that information as an ":authority" pseudo-header 2361 field. A user agent that sends Host SHOULD send it as the first 2362 field in the header section of a request. 2364 For example, a GET request to the origin server for 2365 would begin with: 2367 GET /pub/WWW/ HTTP/1.1 2368 Host: www.example.org 2370 Since the host and port information acts as an application-level 2371 routing mechanism, it is a frequent target for malware seeking to 2372 poison a shared cache or redirect a request to an unintended server. 2373 An interception proxy is particularly vulnerable if it relies on the 2374 host and port information for redirecting requests to internal 2375 servers, or for use as a cache key in a shared cache, without first 2376 verifying that the intercepted connection is targeting a valid IP 2377 address for that host. 2379 7.3. Routing Inbound Requests 2381 Once the target URI and its origin are determined, a client decides 2382 whether a network request is necessary to accomplish the desired 2383 semantics and, if so, where that request is to be directed. 2385 7.3.1. To a Cache 2387 If the client has a cache [Caching] and the request can be satisfied 2388 by it, then the request is usually directed there first. 2390 7.3.2. To a Proxy 2392 If the request is not satisfied by a cache, then a typical client 2393 will check its configuration to determine whether a proxy is to be 2394 used to satisfy the request. Proxy configuration is implementation- 2395 dependent, but is often based on URI prefix matching, selective 2396 authority matching, or both, and the proxy itself is usually 2397 identified by an "http" or "https" URI. If a proxy is applicable, 2398 the client connects inbound by establishing (or reusing) a connection 2399 to that proxy. 2401 7.3.3. To the Origin 2403 If no proxy is applicable, a typical client will invoke a handler 2404 routine, usually specific to the target URI's scheme, to connect 2405 directly to an origin for the target resource. How that is 2406 accomplished is dependent on the target URI scheme and defined by its 2407 associated specification. 2409 7.4. Rejecting Misdirected Requests 2411 Before performing a request, a server decides whether or not to 2412 provide service for the target URI via the connection in which the 2413 request is received. For example, a request might have been 2414 misdirected, deliberately or accidentally, such that the information 2415 within a received Host header field differs from the connection's 2416 host or port. 2418 If the connection is from a trusted gateway, such inconsistency might 2419 be expected; otherwise, it might indicate an attempt to bypass 2420 security filters, trick the server into delivering non-public 2421 content, or poison a cache. See Section 17 for security 2422 considerations regarding message routing. 2424 The 421 (Misdirected Request) status code in a response indicates 2425 that the origin server has rejected the request because it appears to 2426 have been misdirected (Section 15.5.20). 2428 7.5. Response Correlation 2430 A connection might be used for multiple request/response exchanges. 2431 The mechanism used to correlate between request and response messages 2432 is version dependent; some versions of HTTP use implicit ordering of 2433 messages, while others use an explicit identifier. 2435 All responses, regardless of the status code (including interim 2436 responses) can be sent at any time after a request is received, even 2437 if the request is not yet complete. A response can complete before 2438 its corresponding request is complete. Likewise, clients are not 2439 expected to wait any specific amount of time for a response. Clients 2440 (including intermediaries) might abandon a request if the response is 2441 not forthcoming within a reasonable period of time. 2443 A client that receives a response while it is still sending the 2444 associated request SHOULD continue sending that request, unless it 2445 receives an explicit indication to the contrary (see, e.g., 2446 Section 9.5 of [Messaging] and Section 6.4 of [RFC7540]). 2448 7.6. Message Forwarding 2450 As described in Section 3.7, intermediaries can serve a variety of 2451 roles in the processing of HTTP requests and responses. Some 2452 intermediaries are used to improve performance or availability. 2453 Others are used for access control or to filter content. Since an 2454 HTTP stream has characteristics similar to a pipe-and-filter 2455 architecture, there are no inherent limits to the extent an 2456 intermediary can enhance (or interfere) with either direction of the 2457 stream. 2459 Intermediaries are expected to forward messages even when protocol 2460 elements are not recognized (e.g., new methods, status codes, or 2461 field names), since that preserves extensibility for downstream 2462 recipients. 2464 An intermediary not acting as a tunnel MUST implement the Connection 2465 header field, as specified in Section 7.6.1, and exclude fields from 2466 being forwarded that are only intended for the incoming connection. 2468 An intermediary MUST NOT forward a message to itself unless it is 2469 protected from an infinite request loop. In general, an intermediary 2470 ought to recognize its own server names, including any aliases, local 2471 variations, or literal IP addresses, and respond to such requests 2472 directly. 2474 An HTTP message can be parsed as a stream for incremental processing 2475 or forwarding downstream. However, recipients cannot rely on 2476 incremental delivery of partial messages, since some implementations 2477 will buffer or delay message forwarding for the sake of network 2478 efficiency, security checks, or content transformations. 2480 7.6.1. Connection 2482 The "Connection" header field allows the sender to list desired 2483 control options for the current connection. 2485 When a field aside from Connection is used to supply control 2486 information for or about the current connection, the sender MUST list 2487 the corresponding field name within the Connection header field. 2488 Note that some versions of HTTP prohibit the use of fields for such 2489 information, and therefore do not allow the Connection field. 2491 Intermediaries MUST parse a received Connection header field before a 2492 message is forwarded and, for each connection-option in this field, 2493 remove any header or trailer field(s) from the message with the same 2494 name as the connection-option, and then remove the Connection header 2495 field itself (or replace it with the intermediary's own connection 2496 options for the forwarded message). 2498 Hence, the Connection header field provides a declarative way of 2499 distinguishing fields that are only intended for the immediate 2500 recipient ("hop-by-hop") from those fields that are intended for all 2501 recipients on the chain ("end-to-end"), enabling the message to be 2502 self-descriptive and allowing future connection-specific extensions 2503 to be deployed without fear that they will be blindly forwarded by 2504 older intermediaries. 2506 Furthermore, intermediaries SHOULD remove or replace field(s) whose 2507 semantics are known to require removal before forwarding, whether or 2508 not they appear as a Connection option, after applying those fields' 2509 semantics. This includes but is not limited to: 2511 * Proxy-Connection (Appendix C.2.2 of [Messaging]) 2513 * Keep-Alive (Section 19.7.1 of [RFC2068]) 2515 * TE (Section 10.1.4) 2517 * Transfer-Encoding (Section 6.1 of [Messaging]) 2519 * Upgrade (Section 7.8) 2521 The Connection header field's value has the following grammar: 2523 Connection = #connection-option 2524 connection-option = token 2526 Connection options are case-insensitive. 2528 A sender MUST NOT send a connection option corresponding to a field 2529 that is intended for all recipients of the content. For example, 2530 Cache-Control is never appropriate as a connection option 2531 (Section 5.2 of [Caching]). 2533 Connection options do not always correspond to a field present in the 2534 message, since a connection-specific field might not be needed if 2535 there are no parameters associated with a connection option. In 2536 contrast, a connection-specific field received without a 2537 corresponding connection option usually indicates that the field has 2538 been improperly forwarded by an intermediary and ought to be ignored 2539 by the recipient. 2541 When defining a new connection option that does not correspond to a 2542 field, specification authors ought to reserve the corresponding field 2543 name anyway in order to avoid later collisions. Such reserved field 2544 names are registered in the Hypertext Transfer Protocol (HTTP) Field 2545 Name Registry (Section 16.3.1). 2547 7.6.2. Max-Forwards 2549 The "Max-Forwards" header field provides a mechanism with the TRACE 2550 (Section 9.3.8) and OPTIONS (Section 9.3.7) request methods to limit 2551 the number of times that the request is forwarded by proxies. This 2552 can be useful when the client is attempting to trace a request that 2553 appears to be failing or looping mid-chain. 2555 Max-Forwards = 1*DIGIT 2557 The Max-Forwards value is a decimal integer indicating the remaining 2558 number of times this request message can be forwarded. 2560 Each intermediary that receives a TRACE or OPTIONS request containing 2561 a Max-Forwards header field MUST check and update its value prior to 2562 forwarding the request. If the received value is zero (0), the 2563 intermediary MUST NOT forward the request; instead, the intermediary 2564 MUST respond as the final recipient. If the received Max-Forwards 2565 value is greater than zero, the intermediary MUST generate an updated 2566 Max-Forwards field in the forwarded message with a field value that 2567 is the lesser of a) the received value decremented by one (1) or b) 2568 the recipient's maximum supported value for Max-Forwards. 2570 A recipient MAY ignore a Max-Forwards header field received with any 2571 other request methods. 2573 7.6.3. Via 2575 The "Via" header field indicates the presence of intermediate 2576 protocols and recipients between the user agent and the server (on 2577 requests) or between the origin server and the client (on responses), 2578 similar to the "Received" header field in email (Section 3.6.7 of 2579 [RFC5322]). Via can be used for tracking message forwards, avoiding 2580 request loops, and identifying the protocol capabilities of senders 2581 along the request/response chain. 2583 Via = #( received-protocol RWS received-by [ RWS comment ] ) 2585 received-protocol = [ protocol-name "/" ] protocol-version 2586 ; see Section 7.8 2587 received-by = pseudonym [ ":" port ] 2588 pseudonym = token 2590 Each member of the Via field value represents a proxy or gateway that 2591 has forwarded the message. Each intermediary appends its own 2592 information about how the message was received, such that the end 2593 result is ordered according to the sequence of forwarding recipients. 2595 A proxy MUST send an appropriate Via header field, as described 2596 below, in each message that it forwards. An HTTP-to-HTTP gateway 2597 MUST send an appropriate Via header field in each inbound request 2598 message and MAY send a Via header field in forwarded response 2599 messages. 2601 For each intermediary, the received-protocol indicates the protocol 2602 and protocol version used by the upstream sender of the message. 2603 Hence, the Via field value records the advertised protocol 2604 capabilities of the request/response chain such that they remain 2605 visible to downstream recipients; this can be useful for determining 2606 what backwards-incompatible features might be safe to use in 2607 response, or within a later request, as described in Section 2.5. 2608 For brevity, the protocol-name is omitted when the received protocol 2609 is HTTP. 2611 The received-by portion is normally the host and optional port number 2612 of a recipient server or client that subsequently forwarded the 2613 message. However, if the real host is considered to be sensitive 2614 information, a sender MAY replace it with a pseudonym. If a port is 2615 not provided, a recipient MAY interpret that as meaning it was 2616 received on the default TCP port, if any, for the received-protocol. 2618 A sender MAY generate comments to identify the software of each 2619 recipient, analogous to the User-Agent and Server header fields. 2620 However, comments in Via are optional, and a recipient MAY remove 2621 them prior to forwarding the message. 2623 For example, a request message could be sent from an HTTP/1.0 user 2624 agent to an internal proxy code-named "fred", which uses HTTP/1.1 to 2625 forward the request to a public proxy at p.example.net, which 2626 completes the request by forwarding it to the origin server at 2627 www.example.com. The request received by www.example.com would then 2628 have the following Via header field: 2630 Via: 1.0 fred, 1.1 p.example.net 2632 An intermediary used as a portal through a network firewall SHOULD 2633 NOT forward the names and ports of hosts within the firewall region 2634 unless it is explicitly enabled to do so. If not enabled, such an 2635 intermediary SHOULD replace each received-by host of any host behind 2636 the firewall by an appropriate pseudonym for that host. 2638 An intermediary MAY combine an ordered subsequence of Via header 2639 field list members into a single member if the entries have identical 2640 received-protocol values. For example, 2642 Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy 2644 could be collapsed to 2646 Via: 1.0 ricky, 1.1 mertz, 1.0 lucy 2648 A sender SHOULD NOT combine multiple list members unless they are all 2649 under the same organizational control and the hosts have already been 2650 replaced by pseudonyms. A sender MUST NOT combine members that have 2651 different received-protocol values. 2653 7.7. Message Transformations 2655 Some intermediaries include features for transforming messages and 2656 their content. A proxy might, for example, convert between image 2657 formats in order to save cache space or to reduce the amount of 2658 traffic on a slow link. However, operational problems might occur 2659 when these transformations are applied to content intended for 2660 critical applications, such as medical imaging or scientific data 2661 analysis, particularly when integrity checks or digital signatures 2662 are used to ensure that the content received is identical to the 2663 original. 2665 An HTTP-to-HTTP proxy is called a _transforming proxy_ if it is 2666 designed or configured to modify messages in a semantically 2667 meaningful way (i.e., modifications, beyond those required by normal 2668 HTTP processing, that change the message in a way that would be 2669 significant to the original sender or potentially significant to 2670 downstream recipients). For example, a transforming proxy might be 2671 acting as a shared annotation server (modifying responses to include 2672 references to a local annotation database), a malware filter, a 2673 format transcoder, or a privacy filter. Such transformations are 2674 presumed to be desired by whichever client (or client organization) 2675 chose the proxy. 2677 If a proxy receives a target URI with a host name that is not a fully 2678 qualified domain name, it MAY add its own domain to the host name it 2679 received when forwarding the request. A proxy MUST NOT change the 2680 host name if the target URI contains a fully qualified domain name. 2682 A proxy MUST NOT modify the "absolute-path" and "query" parts of the 2683 received target URI when forwarding it to the next inbound server, 2684 except as noted above to replace an empty path with "/" or "*". 2686 A proxy MUST NOT transform the content (Section 6.4) of a message 2687 that contains a no-transform cache-control response directive 2688 (Section 5.2 of [Caching]). Note that this does not include changes 2689 to the message body that do not affect the content, such as transfer 2690 codings (Section 7 of [Messaging]). 2692 A proxy MAY transform the content of a message that does not contain 2693 a no-transform cache-control directive. A proxy that transforms the 2694 content of a 200 (OK) response can inform downstream recipients that 2695 a transformation has been applied by changing the response status 2696 code to 203 (Non-Authoritative Information) (Section 15.3.4). 2698 A proxy SHOULD NOT modify header fields that provide information 2699 about the endpoints of the communication chain, the resource state, 2700 or the selected representation (other than the content) unless the 2701 field's definition specifically allows such modification or the 2702 modification is deemed necessary for privacy or security. 2704 7.8. Upgrade 2706 The "Upgrade" header field is intended to provide a simple mechanism 2707 for transitioning from HTTP/1.1 to some other protocol on the same 2708 connection. 2710 A client MAY send a list of protocol names in the Upgrade header 2711 field of a request to invite the server to switch to one or more of 2712 the named protocols, in order of descending preference, before 2713 sending the final response. A server MAY ignore a received Upgrade 2714 header field if it wishes to continue using the current protocol on 2715 that connection. Upgrade cannot be used to insist on a protocol 2716 change. 2718 Upgrade = #protocol 2720 protocol = protocol-name ["/" protocol-version] 2721 protocol-name = token 2722 protocol-version = token 2724 Although protocol names are registered with a preferred case, 2725 recipients SHOULD use case-insensitive comparison when matching each 2726 protocol-name to supported protocols. 2728 A server that sends a 101 (Switching Protocols) response MUST send an 2729 Upgrade header field to indicate the new protocol(s) to which the 2730 connection is being switched; if multiple protocol layers are being 2731 switched, the sender MUST list the protocols in layer-ascending 2732 order. A server MUST NOT switch to a protocol that was not indicated 2733 by the client in the corresponding request's Upgrade header field. A 2734 server MAY choose to ignore the order of preference indicated by the 2735 client and select the new protocol(s) based on other factors, such as 2736 the nature of the request or the current load on the server. 2738 A server that sends a 426 (Upgrade Required) response MUST send an 2739 Upgrade header field to indicate the acceptable protocols, in order 2740 of descending preference. 2742 A server MAY send an Upgrade header field in any other response to 2743 advertise that it implements support for upgrading to the listed 2744 protocols, in order of descending preference, when appropriate for a 2745 future request. 2747 The following is a hypothetical example sent by a client: 2749 GET /hello HTTP/1.1 2750 Host: www.example.com 2751 Connection: upgrade 2752 Upgrade: websocket, IRC/6.9, RTA/x11 2753 The capabilities and nature of the application-level communication 2754 after the protocol change is entirely dependent upon the new 2755 protocol(s) chosen. However, immediately after sending the 101 2756 (Switching Protocols) response, the server is expected to continue 2757 responding to the original request as if it had received its 2758 equivalent within the new protocol (i.e., the server still has an 2759 outstanding request to satisfy after the protocol has been changed, 2760 and is expected to do so without requiring the request to be 2761 repeated). 2763 For example, if the Upgrade header field is received in a GET request 2764 and the server decides to switch protocols, it first responds with a 2765 101 (Switching Protocols) message in HTTP/1.1 and then immediately 2766 follows that with the new protocol's equivalent of a response to a 2767 GET on the target resource. This allows a connection to be upgraded 2768 to protocols with the same semantics as HTTP without the latency cost 2769 of an additional round trip. A server MUST NOT switch protocols 2770 unless the received message semantics can be honored by the new 2771 protocol; an OPTIONS request can be honored by any protocol. 2773 The following is an example response to the above hypothetical 2774 request: 2776 HTTP/1.1 101 Switching Protocols 2777 Connection: upgrade 2778 Upgrade: websocket 2780 [... data stream switches to websocket with an appropriate response 2781 (as defined by new protocol) to the "GET /hello" request ...] 2783 A sender of Upgrade MUST also send an "Upgrade" connection option in 2784 the Connection header field (Section 7.6.1) to inform intermediaries 2785 not to forward this field. A server that receives an Upgrade header 2786 field in an HTTP/1.0 request MUST ignore that Upgrade field. 2788 A client cannot begin using an upgraded protocol on the connection 2789 until it has completely sent the request message (i.e., the client 2790 can't change the protocol it is sending in the middle of a message). 2791 If a server receives both an Upgrade and an Expect header field with 2792 the "100-continue" expectation (Section 10.1.1), the server MUST send 2793 a 100 (Continue) response before sending a 101 (Switching Protocols) 2794 response. 2796 The Upgrade header field only applies to switching protocols on top 2797 of the existing connection; it cannot be used to switch the 2798 underlying connection (transport) protocol, nor to switch the 2799 existing communication to a different connection. For those 2800 purposes, it is more appropriate to use a 3xx (Redirection) response 2801 (Section 15.4). 2803 This specification only defines the protocol name "HTTP" for use by 2804 the family of Hypertext Transfer Protocols, as defined by the HTTP 2805 version rules of Section 2.5 and future updates to this 2806 specification. Additional protocol names ought to be registered 2807 using the registration procedure defined in Section 16.7. 2809 8. Representation Data and Metadata 2811 8.1. Representation Data 2813 The representation data associated with an HTTP message is either 2814 provided as the content of the message or referred to by the message 2815 semantics and the target URI. The representation data is in a format 2816 and encoding defined by the representation metadata header fields. 2818 The data type of the representation data is determined via the header 2819 fields Content-Type and Content-Encoding. These define a two-layer, 2820 ordered encoding model: 2822 representation-data := Content-Encoding( Content-Type( data ) ) 2824 8.2. Representation Metadata 2826 Representation header fields provide metadata about the 2827 representation. When a message includes content, the representation 2828 header fields describe how to interpret that data. In a response to 2829 a HEAD request, the representation header fields describe the 2830 representation data that would have been enclosed in the content if 2831 the same request had been a GET. 2833 8.3. Content-Type 2835 The "Content-Type" header field indicates the media type of the 2836 associated representation: either the representation enclosed in the 2837 message content or the selected representation, as determined by the 2838 message semantics. The indicated media type defines both the data 2839 format and how that data is intended to be processed by a recipient, 2840 within the scope of the received message semantics, after any content 2841 codings indicated by Content-Encoding are decoded. 2843 Content-Type = media-type 2845 Media types are defined in Section 8.3.1. An example of the field is 2847 Content-Type: text/html; charset=ISO-8859-4 2849 A sender that generates a message containing content SHOULD generate 2850 a Content-Type header field in that message unless the intended media 2851 type of the enclosed representation is unknown to the sender. If a 2852 Content-Type header field is not present, the recipient MAY either 2853 assume a media type of "application/octet-stream" ([RFC2046], 2854 Section 4.5.1) or examine the data to determine its type. 2856 In practice, resource owners do not always properly configure their 2857 origin server to provide the correct Content-Type for a given 2858 representation. Some user agents examine the content and, in certain 2859 cases, override the received type (for example, see [Sniffing]). 2860 This "MIME sniffing" risks drawing incorrect conclusions about the 2861 data, which might expose the user to additional security risks (e.g., 2862 "privilege escalation"). Furthermore, it is impossible to determine 2863 the sender's intended processing model by examining the data format: 2864 many data formats match multiple media types that differ only in 2865 processing semantics. Implementers are encouraged to provide a means 2866 to disable such sniffing. 2868 Furthermore, although Content-Type is defined as a singleton field, 2869 it is sometimes incorrectly generated multiple times, resulting in a 2870 combined field value that appears to be a list. Recipients often 2871 attempt to handle this error by using the last syntactically valid 2872 member of the list, but note that some implementations might have 2873 different error handling behaviors, leading to interoperability and/ 2874 or security issues. 2876 8.3.1. Media Type 2878 HTTP uses media types [RFC2046] in the Content-Type (Section 8.3) and 2879 Accept (Section 12.5.1) header fields in order to provide open and 2880 extensible data typing and type negotiation. Media types define both 2881 a data format and various processing models: how to process that data 2882 in accordance with the message context. 2884 media-type = type "/" subtype parameters 2885 type = token 2886 subtype = token 2888 The type and subtype tokens are case-insensitive. 2890 The type/subtype MAY be followed by semicolon-delimited parameters 2891 (Section 5.6.6) in the form of name=value pairs. The presence or 2892 absence of a parameter might be significant to the processing of a 2893 media type, depending on its definition within the media type 2894 registry. Parameter values might or might not be case-sensitive, 2895 depending on the semantics of the parameter name. 2897 For example, the following media types are equivalent in describing 2898 HTML text data encoded in the UTF-8 character encoding scheme, but 2899 the first is preferred for consistency (the "charset" parameter value 2900 is defined as being case-insensitive in [RFC2046], Section 4.1.2): 2902 text/html;charset=utf-8 2903 Text/HTML;Charset="utf-8" 2904 text/html; charset="utf-8" 2905 text/html;charset=UTF-8 2907 Media types ought to be registered with IANA according to the 2908 procedures defined in [BCP13]. 2910 8.3.2. Charset 2912 HTTP uses _charset_ names to indicate or negotiate the character 2913 encoding scheme ([RFC6365], Section 1.3) of a textual representation. 2914 In the fields defined by this document, charset names appear either 2915 in parameters (Content-Type), or, for Accept-Encoding, in the form of 2916 a plain token. In both cases, charset names are matched case- 2917 insensitively. 2919 Charset names ought to be registered in the IANA "Character Sets" 2920 registry () 2921 according to the procedures defined in Section 2 of [RFC2978]. 2923 | *Note:* In theory, charset names are defined by the "mime- 2924 | charset" ABNF rule defined in Section 2.3 of [RFC2978] (as 2925 | corrected in [Err1912]). That rule allows two characters that 2926 | are not included in "token" ("{" and "}"), but no charset name 2927 | registered at the time of this writing includes braces (see 2928 | [Err5433]). 2930 8.3.3. Multipart Types 2932 MIME provides for a number of "multipart" types - encapsulations of 2933 one or more representations within a single message body. All 2934 multipart types share a common syntax, as defined in Section 5.1.1 of 2935 [RFC2046], and include a boundary parameter as part of the media type 2936 value. The message body is itself a protocol element; a sender MUST 2937 generate only CRLF to represent line breaks between body parts. 2939 HTTP message framing does not use the multipart boundary as an 2940 indicator of message body length, though it might be used by 2941 implementations that generate or process the content. For example, 2942 the "multipart/form-data" type is often used for carrying form data 2943 in a request, as described in [RFC7578], and the "multipart/ 2944 byteranges" type is defined by this specification for use in some 206 2945 (Partial Content) responses (see Section 15.3.7). 2947 8.4. Content-Encoding 2949 The "Content-Encoding" header field indicates what content codings 2950 have been applied to the representation, beyond those inherent in the 2951 media type, and thus what decoding mechanisms have to be applied in 2952 order to obtain data in the media type referenced by the Content-Type 2953 header field. Content-Encoding is primarily used to allow a 2954 representation's data to be compressed without losing the identity of 2955 its underlying media type. 2957 Content-Encoding = #content-coding 2959 An example of its use is 2961 Content-Encoding: gzip 2963 If one or more encodings have been applied to a representation, the 2964 sender that applied the encodings MUST generate a Content-Encoding 2965 header field that lists the content codings in the order in which 2966 they were applied. Note that the coding named "identity" is reserved 2967 for its special role in Accept-Encoding, and thus SHOULD NOT be 2968 included. 2970 Additional information about the encoding parameters can be provided 2971 by other header fields not defined by this specification. 2973 Unlike Transfer-Encoding (Section 6.1 of [Messaging]), the codings 2974 listed in Content-Encoding are a characteristic of the 2975 representation; the representation is defined in terms of the coded 2976 form, and all other metadata about the representation is about the 2977 coded form unless otherwise noted in the metadata definition. 2978 Typically, the representation is only decoded just prior to rendering 2979 or analogous usage. 2981 If the media type includes an inherent encoding, such as a data 2982 format that is always compressed, then that encoding would not be 2983 restated in Content-Encoding even if it happens to be the same 2984 algorithm as one of the content codings. Such a content coding would 2985 only be listed if, for some bizarre reason, it is applied a second 2986 time to form the representation. Likewise, an origin server might 2987 choose to publish the same data as multiple representations that 2988 differ only in whether the coding is defined as part of Content-Type 2989 or Content-Encoding, since some user agents will behave differently 2990 in their handling of each response (e.g., open a "Save as ..." dialog 2991 instead of automatic decompression and rendering of content). 2993 An origin server MAY respond with a status code of 415 (Unsupported 2994 Media Type) if a representation in the request message has a content 2995 coding that is not acceptable. 2997 8.4.1. Content Codings 2999 Content coding values indicate an encoding transformation that has 3000 been or can be applied to a representation. Content codings are 3001 primarily used to allow a representation to be compressed or 3002 otherwise usefully transformed without losing the identity of its 3003 underlying media type and without loss of information. Frequently, 3004 the representation is stored in coded form, transmitted directly, and 3005 only decoded by the final recipient. 3007 content-coding = token 3009 All content codings are case-insensitive and ought to be registered 3010 within the "HTTP Content Coding Registry", as described in 3011 Section 16.6 3013 Content-coding values are used in the Accept-Encoding 3014 (Section 12.5.3) and Content-Encoding (Section 8.4) header fields. 3016 8.4.1.1. Compress Coding 3018 The "compress" coding is an adaptive Lempel-Ziv-Welch (LZW) coding 3019 [Welch] that is commonly produced by the UNIX file compression 3020 program "compress". A recipient SHOULD consider "x-compress" to be 3021 equivalent to "compress". 3023 8.4.1.2. Deflate Coding 3025 The "deflate" coding is a "zlib" data format [RFC1950] containing a 3026 "deflate" compressed data stream [RFC1951] that uses a combination of 3027 the Lempel-Ziv (LZ77) compression algorithm and Huffman coding. 3029 | *Note:* Some non-conformant implementations send the "deflate" 3030 | compressed data without the zlib wrapper. 3032 8.4.1.3. Gzip Coding 3034 The "gzip" coding is an LZ77 coding with a 32-bit Cyclic Redundancy 3035 Check (CRC) that is commonly produced by the gzip file compression 3036 program [RFC1952]. A recipient SHOULD consider "x-gzip" to be 3037 equivalent to "gzip". 3039 8.5. Content-Language 3041 The "Content-Language" header field describes the natural language(s) 3042 of the intended audience for the representation. Note that this 3043 might not be equivalent to all the languages used within the 3044 representation. 3046 Content-Language = #language-tag 3048 Language tags are defined in Section 8.5.1. The primary purpose of 3049 Content-Language is to allow a user to identify and differentiate 3050 representations according to the users' own preferred language. 3051 Thus, if the content is intended only for a Danish-literate audience, 3052 the appropriate field is 3054 Content-Language: da 3056 If no Content-Language is specified, the default is that the content 3057 is intended for all language audiences. This might mean that the 3058 sender does not consider it to be specific to any natural language, 3059 or that the sender does not know for which language it is intended. 3061 Multiple languages MAY be listed for content that is intended for 3062 multiple audiences. For example, a rendition of the "Treaty of 3063 Waitangi", presented simultaneously in the original Maori and English 3064 versions, would call for 3066 Content-Language: mi, en 3068 However, just because multiple languages are present within a 3069 representation does not mean that it is intended for multiple 3070 linguistic audiences. An example would be a beginner's language 3071 primer, such as "A First Lesson in Latin", which is clearly intended 3072 to be used by an English-literate audience. In this case, the 3073 Content-Language would properly only include "en". 3075 Content-Language MAY be applied to any media type - it is not limited 3076 to textual documents. 3078 8.5.1. Language Tags 3080 A language tag, as defined in [RFC5646], identifies a natural 3081 language spoken, written, or otherwise conveyed by human beings for 3082 communication of information to other human beings. Computer 3083 languages are explicitly excluded. 3085 HTTP uses language tags within the Accept-Language and 3086 Content-Language header fields. Accept-Language uses the broader 3087 language-range production defined in Section 12.5.4, whereas 3088 Content-Language uses the language-tag production defined below. 3090 language-tag = 3092 A language tag is a sequence of one or more case-insensitive subtags, 3093 each separated by a hyphen character ("-", %x2D). In most cases, a 3094 language tag consists of a primary language subtag that identifies a 3095 broad family of related languages (e.g., "en" = English), which is 3096 optionally followed by a series of subtags that refine or narrow that 3097 language's range (e.g., "en-CA" = the variety of English as 3098 communicated in Canada). Whitespace is not allowed within a language 3099 tag. Example tags include: 3101 fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN 3103 See [RFC5646] for further information. 3105 8.6. Content-Length 3107 The "Content-Length" header field indicates the associated 3108 representation's data length as a decimal non-negative integer number 3109 of octets. When transferring a representation as content, Content- 3110 Length refers specifically to the amount of data enclosed so that it 3111 can be used to delimit framing (e.g., Section 6.2 of [Messaging]). 3112 In other cases, Content-Length indicates the selected 3113 representation's current length, which can be used by recipients to 3114 estimate transfer time or compare to previously stored 3115 representations. 3117 Content-Length = 1*DIGIT 3119 An example is 3121 Content-Length: 3495 3123 A user agent SHOULD send Content-Length in a request when the method 3124 defines a meaning for enclosed content and it is not sending 3125 Transfer-Encoding. For example, a user agent normally sends Content- 3126 Length in a POST request even when the value is 0 (indicating empty 3127 content). A user agent SHOULD NOT send a Content-Length header field 3128 when the request message does not contain content and the method 3129 semantics do not anticipate such data. 3131 A server MAY send a Content-Length header field in a response to a 3132 HEAD request (Section 9.3.2); a server MUST NOT send Content-Length 3133 in such a response unless its field value equals the decimal number 3134 of octets that would have been sent in the content of a response if 3135 the same request had used the GET method. 3137 A server MAY send a Content-Length header field in a 304 (Not 3138 Modified) response to a conditional GET request (Section 15.4.5); a 3139 server MUST NOT send Content-Length in such a response unless its 3140 field value equals the decimal number of octets that would have been 3141 sent in the content of a 200 (OK) response to the same request. 3143 A server MUST NOT send a Content-Length header field in any response 3144 with a status code of 1xx (Informational) or 204 (No Content). A 3145 server MUST NOT send a Content-Length header field in any 2xx 3146 (Successful) response to a CONNECT request (Section 9.3.6). 3148 Aside from the cases defined above, in the absence of Transfer- 3149 Encoding, an origin server SHOULD send a Content-Length header field 3150 when the content size is known prior to sending the complete header 3151 section. This will allow downstream recipients to measure transfer 3152 progress, know when a received message is complete, and potentially 3153 reuse the connection for additional requests. 3155 Any Content-Length field value greater than or equal to zero is 3156 valid. Since there is no predefined limit to the length of content, 3157 a recipient MUST anticipate potentially large decimal numerals and 3158 prevent parsing errors due to integer conversion overflows or 3159 precision loss due to integer conversion (Section 17.5). 3161 Because Content-Length is used for message delimitation in HTTP/1.1, 3162 its field value can impact how the message is parsed by downstream 3163 recipients even when the immediate connection is not using HTTP/1.1. 3164 If the message is forwarded by a downstream intermediary, a Content- 3165 Length field value that is inconsistent with the received message 3166 framing might cause a security failure due to request smuggling or 3167 response splitting. 3169 As a result, a sender MUST NOT forward a message with a Content- 3170 Length header field value that is known to be incorrect. 3172 Likewise, a sender MUST NOT forward a message with a Content-Length 3173 header field value that does not match the ABNF above, with one 3174 exception: A recipient of a Content-Length header field value 3175 consisting of the same decimal value repeated as a comma-separated 3176 list (e.g, "Content-Length: 42, 42"), MAY either reject the message 3177 as invalid or replace that invalid field value with a single instance 3178 of the decimal value, since this likely indicates that a duplicate 3179 was generated or combined by an upstream message processor. 3181 8.7. Content-Location 3183 The "Content-Location" header field references a URI that can be used 3184 as an identifier for a specific resource corresponding to the 3185 representation in this message's content. In other words, if one 3186 were to perform a GET request on this URI at the time of this 3187 message's generation, then a 200 (OK) response would contain the same 3188 representation that is enclosed as content in this message. 3190 Content-Location = absolute-URI / partial-URI 3192 The field value is either an absolute-URI or a partial-URI. In the 3193 latter case (Section 4), the referenced URI is relative to the target 3194 URI ([RFC3986], Section 5). 3196 The Content-Location value is not a replacement for the target URI 3197 (Section 7.1). It is representation metadata. It has the same 3198 syntax and semantics as the header field of the same name defined for 3199 MIME body parts in Section 4 of [RFC2557]. However, its appearance 3200 in an HTTP message has some special implications for HTTP recipients. 3202 If Content-Location is included in a 2xx (Successful) response 3203 message and its value refers (after conversion to absolute form) to a 3204 URI that is the same as the target URI, then the recipient MAY 3205 consider the content to be a current representation of that resource 3206 at the time indicated by the message origination date. For a GET 3207 (Section 9.3.1) or HEAD (Section 9.3.2) request, this is the same as 3208 the default semantics when no Content-Location is provided by the 3209 server. For a state-changing request like PUT (Section 9.3.4) or 3210 POST (Section 9.3.3), it implies that the server's response contains 3211 the new representation of that resource, thereby distinguishing it 3212 from representations that might only report about the action (e.g., 3213 "It worked!"). This allows authoring applications to update their 3214 local copies without the need for a subsequent GET request. 3216 If Content-Location is included in a 2xx (Successful) response 3217 message and its field value refers to a URI that differs from the 3218 target URI, then the origin server claims that the URI is an 3219 identifier for a different resource corresponding to the enclosed 3220 representation. Such a claim can only be trusted if both identifiers 3221 share the same resource owner, which cannot be programmatically 3222 determined via HTTP. 3224 * For a response to a GET or HEAD request, this is an indication 3225 that the target URI refers to a resource that is subject to 3226 content negotiation and the Content-Location field value is a more 3227 specific identifier for the selected representation. 3229 * For a 201 (Created) response to a state-changing method, a 3230 Content-Location field value that is identical to the Location 3231 field value indicates that this content is a current 3232 representation of the newly created resource. 3234 * Otherwise, such a Content-Location indicates that this content is 3235 a representation reporting on the requested action's status and 3236 that the same report is available (for future access with GET) at 3237 the given URI. For example, a purchase transaction made via a 3238 POST request might include a receipt document as the content of 3239 the 200 (OK) response; the Content-Location field value provides 3240 an identifier for retrieving a copy of that same receipt in the 3241 future. 3243 A user agent that sends Content-Location in a request message is 3244 stating that its value refers to where the user agent originally 3245 obtained the content of the enclosed representation (prior to any 3246 modifications made by that user agent). In other words, the user 3247 agent is providing a back link to the source of the original 3248 representation. 3250 An origin server that receives a Content-Location field in a request 3251 message MUST treat the information as transitory request context 3252 rather than as metadata to be saved verbatim as part of the 3253 representation. An origin server MAY use that context to guide in 3254 processing the request or to save it for other uses, such as within 3255 source links or versioning metadata. However, an origin server MUST 3256 NOT use such context information to alter the request semantics. 3258 For example, if a client makes a PUT request on a negotiated resource 3259 and the origin server accepts that PUT (without redirection), then 3260 the new state of that resource is expected to be consistent with the 3261 one representation supplied in that PUT; the Content-Location cannot 3262 be used as a form of reverse content selection identifier to update 3263 only one of the negotiated representations. If the user agent had 3264 wanted the latter semantics, it would have applied the PUT directly 3265 to the Content-Location URI. 3267 8.8. Validator Fields 3269 Validator fields convey metadata about the selected representation 3270 (Section 3.2). In responses to safe requests, validator fields 3271 describe the selected representation chosen by the origin server 3272 while handling the response. Note that, depending on the status code 3273 semantics, the selected representation for a given response is not 3274 necessarily the same as the representation enclosed as response 3275 content. 3277 In a successful response to a state-changing request, validator 3278 fields describe the new representation that has replaced the prior 3279 selected representation as a result of processing the request. 3281 For example, an ETag field in a 201 (Created) response communicates 3282 the entity-tag of the newly created resource's representation, so 3283 that it can be used in later conditional requests to prevent the 3284 "lost update" problem (Section 13.1). 3286 This specification defines two forms of metadata that are commonly 3287 used to observe resource state and test for preconditions: 3288 modification dates (Section 8.8.2) and opaque entity tags 3289 (Section 8.8.3). Additional metadata that reflects resource state 3290 has been defined by various extensions of HTTP, such as Web 3291 Distributed Authoring and Versioning (WebDAV, [RFC4918]), that are 3292 beyond the scope of this specification. A resource metadata value is 3293 referred to as a _validator_ when it is used within a precondition. 3295 8.8.1. Weak versus Strong 3297 Validators come in two flavors: strong or weak. Weak validators are 3298 easy to generate but are far less useful for comparisons. Strong 3299 validators are ideal for comparisons but can be very difficult (and 3300 occasionally impossible) to generate efficiently. Rather than impose 3301 that all forms of resource adhere to the same strength of validator, 3302 HTTP exposes the type of validator in use and imposes restrictions on 3303 when weak validators can be used as preconditions. 3305 A _strong validator_ is representation metadata that changes value 3306 whenever a change occurs to the representation data that would be 3307 observable in the content of a 200 (OK) response to GET. 3309 A strong validator might change for reasons other than a change to 3310 the representation data, such as when a semantically significant part 3311 of the representation metadata is changed (e.g., Content-Type), but 3312 it is in the best interests of the origin server to only change the 3313 value when it is necessary to invalidate the stored responses held by 3314 remote caches and authoring tools. 3316 Cache entries might persist for arbitrarily long periods, regardless 3317 of expiration times. Thus, a cache might attempt to validate an 3318 entry using a validator that it obtained in the distant past. A 3319 strong validator is unique across all versions of all representations 3320 associated with a particular resource over time. However, there is 3321 no implication of uniqueness across representations of different 3322 resources (i.e., the same strong validator might be in use for 3323 representations of multiple resources at the same time and does not 3324 imply that those representations are equivalent). 3326 There are a variety of strong validators used in practice. The best 3327 are based on strict revision control, wherein each change to a 3328 representation always results in a unique node name and revision 3329 identifier being assigned before the representation is made 3330 accessible to GET. A collision-resistant hash function applied to 3331 the representation data is also sufficient if the data is available 3332 prior to the response header fields being sent and the digest does 3333 not need to be recalculated every time a validation request is 3334 received. However, if a resource has distinct representations that 3335 differ only in their metadata, such as might occur with content 3336 negotiation over media types that happen to share the same data 3337 format, then the origin server needs to incorporate additional 3338 information in the validator to distinguish those representations. 3340 In contrast, a _weak validator_ is representation metadata that might 3341 not change for every change to the representation data. This 3342 weakness might be due to limitations in how the value is calculated, 3343 such as clock resolution, an inability to ensure uniqueness for all 3344 possible representations of the resource, or a desire of the resource 3345 owner to group representations by some self-determined set of 3346 equivalency rather than unique sequences of data. An origin server 3347 SHOULD change a weak entity-tag whenever it considers prior 3348 representations to be unacceptable as a substitute for the current 3349 representation. In other words, a weak entity-tag ought to change 3350 whenever the origin server wants caches to invalidate old responses. 3352 For example, the representation of a weather report that changes in 3353 content every second, based on dynamic measurements, might be grouped 3354 into sets of equivalent representations (from the origin server's 3355 perspective) with the same weak validator in order to allow cached 3356 representations to be valid for a reasonable period of time (perhaps 3357 adjusted dynamically based on server load or weather quality). 3358 Likewise, a representation's modification time, if defined with only 3359 one-second resolution, might be a weak validator if it is possible 3360 for the representation to be modified twice during a single second 3361 and retrieved between those modifications. 3363 Likewise, a validator is weak if it is shared by two or more 3364 representations of a given resource at the same time, unless those 3365 representations have identical representation data. For example, if 3366 the origin server sends the same validator for a representation with 3367 a gzip content coding applied as it does for a representation with no 3368 content coding, then that validator is weak. However, two 3369 simultaneous representations might share the same strong validator if 3370 they differ only in the representation metadata, such as when two 3371 different media types are available for the same representation data. 3373 Strong validators are usable for all conditional requests, including 3374 cache validation, partial content ranges, and "lost update" 3375 avoidance. Weak validators are only usable when the client does not 3376 require exact equality with previously obtained representation data, 3377 such as when validating a cache entry or limiting a web traversal to 3378 recent changes. 3380 8.8.2. Last-Modified 3382 The "Last-Modified" header field in a response provides a timestamp 3383 indicating the date and time at which the origin server believes the 3384 selected representation was last modified, as determined at the 3385 conclusion of handling the request. 3387 Last-Modified = HTTP-date 3389 An example of its use is 3391 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 3393 8.8.2.1. Generation 3395 An origin server SHOULD send Last-Modified for any selected 3396 representation for which a last modification date can be reasonably 3397 and consistently determined, since its use in conditional requests 3398 and evaluating cache freshness ([Caching]) can substantially reduce 3399 unnecessary transfers and significantly improve service availability 3400 and scalability. 3402 A representation is typically the sum of many parts behind the 3403 resource interface. The last-modified time would usually be the most 3404 recent time that any of those parts were changed. How that value is 3405 determined for any given resource is an implementation detail beyond 3406 the scope of this specification. 3408 An origin server SHOULD obtain the Last-Modified value of the 3409 representation as close as possible to the time that it generates the 3410 Date field value for its response. This allows a recipient to make 3411 an accurate assessment of the representation's modification time, 3412 especially if the representation changes near the time that the 3413 response is generated. 3415 An origin server with a clock MUST NOT send a Last-Modified date that 3416 is later than the server's time of message origination (Date). If 3417 the last modification time is derived from implementation-specific 3418 metadata that evaluates to some time in the future, according to the 3419 origin server's clock, then the origin server MUST replace that value 3420 with the message origination date. This prevents a future 3421 modification date from having an adverse impact on cache validation. 3423 An origin server without a clock MUST NOT assign Last-Modified values 3424 to a response unless these values were associated with the resource 3425 by some other system or user with a reliable clock. 3427 8.8.2.2. Comparison 3429 A Last-Modified time, when used as a validator in a request, is 3430 implicitly weak unless it is possible to deduce that it is strong, 3431 using the following rules: 3433 * The validator is being compared by an origin server to the actual 3434 current validator for the representation and, 3436 * That origin server reliably knows that the associated 3437 representation did not change twice during the second covered by 3438 the presented validator; 3440 or 3442 * The validator is about to be used by a client in an 3443 If-Modified-Since, If-Unmodified-Since, or If-Range header field, 3444 because the client has a cache entry for the associated 3445 representation, and 3447 * That cache entry includes a Date value which is at least one 3448 second after the Last-Modified value and the client has reason to 3449 believe that they were generated by the same clock or that there 3450 is enough difference between the Last-Modified and Date values to 3451 make clock synchronization issues unlikely; 3453 or 3455 * The validator is being compared by an intermediate cache to the 3456 validator stored in its cache entry for the representation, and 3458 * That cache entry includes a Date value which is at least one 3459 second after the Last-Modified value and the cache has reason to 3460 believe that they were generated by the same clock or that there 3461 is enough difference between the Last-Modified and Date values to 3462 make clock synchronization issues unlikely. 3464 This method relies on the fact that if two different responses were 3465 sent by the origin server during the same second, but both had the 3466 same Last-Modified time, then at least one of those responses would 3467 have a Date value equal to its Last-Modified time. 3469 8.8.3. ETag 3471 The "ETag" field in a response provides the current entity-tag for 3472 the selected representation, as determined at the conclusion of 3473 handling the request. An entity-tag is an opaque validator for 3474 differentiating between multiple representations of the same 3475 resource, regardless of whether those multiple representations are 3476 due to resource state changes over time, content negotiation 3477 resulting in multiple representations being valid at the same time, 3478 or both. An entity-tag consists of an opaque quoted string, possibly 3479 prefixed by a weakness indicator. 3481 ETag = entity-tag 3483 entity-tag = [ weak ] opaque-tag 3484 weak = %s"W/" 3485 opaque-tag = DQUOTE *etagc DQUOTE 3486 etagc = %x21 / %x23-7E / obs-text 3487 ; VCHAR except double quotes, plus obs-text 3489 | *Note:* Previously, opaque-tag was defined to be a quoted- 3490 | string ([RFC2616], Section 3.11); thus, some recipients might 3491 | perform backslash unescaping. Servers therefore ought to avoid 3492 | backslash characters in entity tags. 3494 An entity-tag can be more reliable for validation than a modification 3495 date in situations where it is inconvenient to store modification 3496 dates, where the one-second resolution of HTTP date values is not 3497 sufficient, or where modification dates are not consistently 3498 maintained. 3500 Examples: 3502 ETag: "xyzzy" 3503 ETag: W/"xyzzy" 3504 ETag: "" 3505 An entity-tag can be either a weak or strong validator, with strong 3506 being the default. If an origin server provides an entity-tag for a 3507 representation and the generation of that entity-tag does not satisfy 3508 all of the characteristics of a strong validator (Section 8.8.1), 3509 then the origin server MUST mark the entity-tag as weak by prefixing 3510 its opaque value with "W/" (case-sensitive). 3512 A sender MAY send the Etag field in a trailer section (see 3513 Section 6.5). However, since trailers are often ignored, it is 3514 preferable to send Etag as a header field unless the entity-tag is 3515 generated while sending the content. 3517 8.8.3.1. Generation 3519 The principle behind entity-tags is that only the service author 3520 knows the implementation of a resource well enough to select the most 3521 accurate and efficient validation mechanism for that resource, and 3522 that any such mechanism can be mapped to a simple sequence of octets 3523 for easy comparison. Since the value is opaque, there is no need for 3524 the client to be aware of how each entity-tag is constructed. 3526 For example, a resource that has implementation-specific versioning 3527 applied to all changes might use an internal revision number, perhaps 3528 combined with a variance identifier for content negotiation, to 3529 accurately differentiate between representations. Other 3530 implementations might use a collision-resistant hash of 3531 representation content, a combination of various file attributes, or 3532 a modification timestamp that has sub-second resolution. 3534 An origin server SHOULD send an ETag for any selected representation 3535 for which detection of changes can be reasonably and consistently 3536 determined, since the entity-tag's use in conditional requests and 3537 evaluating cache freshness ([Caching]) can substantially reduce 3538 unnecessary transfers and significantly improve service availability, 3539 scalability, and reliability. 3541 8.8.3.2. Comparison 3543 There are two entity-tag comparison functions, depending on whether 3544 or not the comparison context allows the use of weak validators: 3546 _Strong comparison_: two entity-tags are equivalent if both are not 3547 weak and their opaque-tags match character-by-character. 3549 _Weak comparison_: two entity-tags are equivalent if their opaque- 3550 tags match character-by-character, regardless of either or both 3551 being tagged as "weak". 3553 The example below shows the results for a set of entity-tag pairs and 3554 both the weak and strong comparison function results: 3556 +========+========+===================+=================+ 3557 | ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | 3558 +========+========+===================+=================+ 3559 | W/"1" | W/"1" | no match | match | 3560 +--------+--------+-------------------+-----------------+ 3561 | W/"1" | W/"2" | no match | no match | 3562 +--------+--------+-------------------+-----------------+ 3563 | W/"1" | "1" | no match | match | 3564 +--------+--------+-------------------+-----------------+ 3565 | "1" | "1" | match | match | 3566 +--------+--------+-------------------+-----------------+ 3568 Table 3 3570 8.8.3.3. Example: Entity-Tags Varying on Content-Negotiated Resources 3572 Consider a resource that is subject to content negotiation 3573 (Section 12), and where the representations sent in response to a GET 3574 request vary based on the Accept-Encoding request header field 3575 (Section 12.5.3): 3577 >> Request: 3579 GET /index HTTP/1.1 3580 Host: www.example.com 3581 Accept-Encoding: gzip 3583 In this case, the response might or might not use the gzip content 3584 coding. If it does not, the response might look like: 3586 >> Response: 3588 HTTP/1.1 200 OK 3589 Date: Fri, 26 Mar 2010 00:05:00 GMT 3590 ETag: "123-a" 3591 Content-Length: 70 3592 Vary: Accept-Encoding 3593 Content-Type: text/plain 3595 Hello World! 3596 Hello World! 3597 Hello World! 3598 Hello World! 3599 Hello World! 3600 An alternative representation that does use gzip content coding would 3601 be: 3603 >> Response: 3605 HTTP/1.1 200 OK 3606 Date: Fri, 26 Mar 2010 00:05:00 GMT 3607 ETag: "123-b" 3608 Content-Length: 43 3609 Vary: Accept-Encoding 3610 Content-Type: text/plain 3611 Content-Encoding: gzip 3613 ...binary data... 3615 | *Note:* Content codings are a property of the representation 3616 | data, so a strong entity-tag for a content-encoded 3617 | representation has to be distinct from the entity tag of an 3618 | unencoded representation to prevent potential conflicts during 3619 | cache updates and range requests. In contrast, transfer 3620 | codings (Section 7 of [Messaging]) apply only during message 3621 | transfer and do not result in distinct entity-tags. 3623 8.8.4. When to Use Entity-Tags and Last-Modified Dates 3625 In 200 (OK) responses to GET or HEAD, an origin server: 3627 * SHOULD send an entity-tag validator unless it is not feasible to 3628 generate one. 3630 * MAY send a weak entity-tag instead of a strong entity-tag, if 3631 performance considerations support the use of weak entity-tags, or 3632 if it is unfeasible to send a strong entity-tag. 3634 * SHOULD send a Last-Modified value if it is feasible to send one. 3636 In other words, the preferred behavior for an origin server is to 3637 send both a strong entity-tag and a Last-Modified value in successful 3638 responses to a retrieval request. 3640 A client: 3642 * MUST send that entity-tag in any cache validation request (using 3643 If-Match or If-None-Match) if an entity-tag has been provided by 3644 the origin server. 3646 * SHOULD send the Last-Modified value in non-subrange cache 3647 validation requests (using If-Modified-Since) if only a Last- 3648 Modified value has been provided by the origin server. 3650 * MAY send the Last-Modified value in subrange cache validation 3651 requests (using If-Unmodified-Since) if only a Last-Modified value 3652 has been provided by an HTTP/1.0 origin server. The user agent 3653 SHOULD provide a way to disable this, in case of difficulty. 3655 * SHOULD send both validators in cache validation requests if both 3656 an entity-tag and a Last-Modified value have been provided by the 3657 origin server. This allows both HTTP/1.0 and HTTP/1.1 caches to 3658 respond appropriately. 3660 9. Methods 3662 9.1. Overview 3664 The request method token is the primary source of request semantics; 3665 it indicates the purpose for which the client has made this request 3666 and what is expected by the client as a successful result. 3668 The request method's semantics might be further specialized by the 3669 semantics of some header fields when present in a request if those 3670 additional semantics do not conflict with the method. For example, a 3671 client can send conditional request header fields (Section 13.1) to 3672 make the requested action conditional on the current state of the 3673 target resource. 3675 HTTP is designed to be usable as an interface to distributed object 3676 systems. The request method invokes an action to be applied to a 3677 target resource in much the same way that a remote method invocation 3678 can be sent to an identified object. 3680 method = token 3682 The method token is case-sensitive because it might be used as a 3683 gateway to object-based systems with case-sensitive method names. By 3684 convention, standardized methods are defined in all-uppercase US- 3685 ASCII letters. 3687 Unlike distributed objects, the standardized request methods in HTTP 3688 are not resource-specific, since uniform interfaces provide for 3689 better visibility and reuse in network-based systems [REST]. Once 3690 defined, a standardized method ought to have the same semantics when 3691 applied to any resource, though each resource determines for itself 3692 whether those semantics are implemented or allowed. 3694 This specification defines a number of standardized methods that are 3695 commonly used in HTTP, as outlined by the following table. 3697 +=========+============================================+=======+ 3698 | Method | Description | Ref. | 3699 +=========+============================================+=======+ 3700 | GET | Transfer a current representation of the | 9.3.1 | 3701 | | target resource. | | 3702 +---------+--------------------------------------------+-------+ 3703 | HEAD | Same as GET, but do not transfer the | 9.3.2 | 3704 | | response content. | | 3705 +---------+--------------------------------------------+-------+ 3706 | POST | Perform resource-specific processing on | 9.3.3 | 3707 | | the request content. | | 3708 +---------+--------------------------------------------+-------+ 3709 | PUT | Replace all current representations of the | 9.3.4 | 3710 | | target resource with the request content. | | 3711 +---------+--------------------------------------------+-------+ 3712 | DELETE | Remove all current representations of the | 9.3.5 | 3713 | | target resource. | | 3714 +---------+--------------------------------------------+-------+ 3715 | CONNECT | Establish a tunnel to the server | 9.3.6 | 3716 | | identified by the target resource. | | 3717 +---------+--------------------------------------------+-------+ 3718 | OPTIONS | Describe the communication options for the | 9.3.7 | 3719 | | target resource. | | 3720 +---------+--------------------------------------------+-------+ 3721 | TRACE | Perform a message loop-back test along the | 9.3.8 | 3722 | | path to the target resource. | | 3723 +---------+--------------------------------------------+-------+ 3725 Table 4 3727 All general-purpose servers MUST support the methods GET and HEAD. 3728 All other methods are OPTIONAL. 3730 The set of methods allowed by a target resource can be listed in an 3731 Allow header field (Section 10.2.1). However, the set of allowed 3732 methods can change dynamically. An origin server that receives a 3733 request method that is unrecognized or not implemented SHOULD respond 3734 with the 501 (Not Implemented) status code. An origin server that 3735 receives a request method that is recognized and implemented, but not 3736 allowed for the target resource, SHOULD respond with the 405 (Method 3737 Not Allowed) status code. 3739 Additional methods, outside the scope of this specification, have 3740 been specified for use in HTTP. All such methods ought to be 3741 registered within the "Hypertext Transfer Protocol (HTTP) Method 3742 Registry", as described in Section 16.1. 3744 9.2. Common Method Properties 3746 9.2.1. Safe Methods 3748 Request methods are considered _safe_ if their defined semantics are 3749 essentially read-only; i.e., the client does not request, and does 3750 not expect, any state change on the origin server as a result of 3751 applying a safe method to a target resource. Likewise, reasonable 3752 use of a safe method is not expected to cause any harm, loss of 3753 property, or unusual burden on the origin server. 3755 This definition of safe methods does not prevent an implementation 3756 from including behavior that is potentially harmful, that is not 3757 entirely read-only, or that causes side effects while invoking a safe 3758 method. What is important, however, is that the client did not 3759 request that additional behavior and cannot be held accountable for 3760 it. For example, most servers append request information to access 3761 log files at the completion of every response, regardless of the 3762 method, and that is considered safe even though the log storage might 3763 become full and crash the server. Likewise, a safe request initiated 3764 by selecting an advertisement on the Web will often have the side 3765 effect of charging an advertising account. 3767 Of the request methods defined by this specification, the GET, HEAD, 3768 OPTIONS, and TRACE methods are defined to be safe. 3770 The purpose of distinguishing between safe and unsafe methods is to 3771 allow automated retrieval processes (spiders) and cache performance 3772 optimization (pre-fetching) to work without fear of causing harm. In 3773 addition, it allows a user agent to apply appropriate constraints on 3774 the automated use of unsafe methods when processing potentially 3775 untrusted content. 3777 A user agent SHOULD distinguish between safe and unsafe methods when 3778 presenting potential actions to a user, such that the user can be 3779 made aware of an unsafe action before it is requested. 3781 When a resource is constructed such that parameters within the target 3782 URI have the effect of selecting an action, it is the resource 3783 owner's responsibility to ensure that the action is consistent with 3784 the request method semantics. For example, it is common for Web- 3785 based content editing software to use actions within query 3786 parameters, such as "page?do=delete". If the purpose of such a 3787 resource is to perform an unsafe action, then the resource owner MUST 3788 disable or disallow that action when it is accessed using a safe 3789 request method. Failure to do so will result in unfortunate side 3790 effects when automated processes perform a GET on every URI reference 3791 for the sake of link maintenance, pre-fetching, building a search 3792 index, etc. 3794 9.2.2. Idempotent Methods 3796 A request method is considered _idempotent_ if the intended effect on 3797 the server of multiple identical requests with that method is the 3798 same as the effect for a single such request. Of the request methods 3799 defined by this specification, PUT, DELETE, and safe request methods 3800 are idempotent. 3802 Like the definition of safe, the idempotent property only applies to 3803 what has been requested by the user; a server is free to log each 3804 request separately, retain a revision control history, or implement 3805 other non-idempotent side effects for each idempotent request. 3807 Idempotent methods are distinguished because the request can be 3808 repeated automatically if a communication failure occurs before the 3809 client is able to read the server's response. For example, if a 3810 client sends a PUT request and the underlying connection is closed 3811 before any response is received, then the client can establish a new 3812 connection and retry the idempotent request. It knows that repeating 3813 the request will have the same intended effect, even if the original 3814 request succeeded, though the response might differ. 3816 A client SHOULD NOT automatically retry a request with a non- 3817 idempotent method unless it has some means to know that the request 3818 semantics are actually idempotent, regardless of the method, or some 3819 means to detect that the original request was never applied. 3821 For example, a user agent can repeat a POST request automatically if 3822 it knows (through design or configuration) that the request is safe 3823 for that resource. Likewise, a user agent designed specifically to 3824 operate on a version control repository might be able to recover from 3825 partial failure conditions by checking the target resource 3826 revision(s) after a failed connection, reverting or fixing any 3827 changes that were partially applied, and then automatically retrying 3828 the requests that failed. 3830 Some clients take a riskier approach and attempt to guess when an 3831 automatic retry is possible. For example, a client might 3832 automatically retry a POST request if the underlying transport 3833 connection closed before any part of a response is received, 3834 particularly if an idle persistent connection was used. 3836 A proxy MUST NOT automatically retry non-idempotent requests. A 3837 client SHOULD NOT automatically retry a failed automatic retry. 3839 9.2.3. Methods and Caching 3841 For a cache to store and use a response, the associated method needs 3842 to explicitly allow caching, and detail under what conditions a 3843 response can be used to satisfy subsequent requests; a method 3844 definition which does not do so cannot be cached. For additional 3845 requirements see [Caching]. 3847 This specification defines caching semantics for GET, HEAD, and POST, 3848 although the overwhelming majority of cache implementations only 3849 support GET and HEAD. 3851 9.3. Method Definitions 3853 9.3.1. GET 3855 The GET method requests transfer of a current selected representation 3856 for the target resource. 3858 GET is the primary mechanism of information retrieval and the focus 3859 of almost all performance optimizations. Hence, when people speak of 3860 retrieving some identifiable information via HTTP, they are generally 3861 referring to making a GET request. A successful response reflects 3862 the quality of "sameness" identified by the target URI. In turn, 3863 constructing applications such that they produce a URI for each 3864 important resource results in more resources being available for 3865 other applications, producing a network effect that promotes further 3866 expansion of the Web. 3868 It is tempting to think of resource identifiers as remote file system 3869 pathnames and of representations as being a copy of the contents of 3870 such files. In fact, that is how many resources are implemented (see 3871 Section 17.3 for related security considerations). However, there 3872 are no such limitations in practice. 3874 The HTTP interface for a resource is just as likely to be implemented 3875 as a tree of content objects, a programmatic view on various database 3876 records, or a gateway to other information systems. Even when the 3877 URI mapping mechanism is tied to a file system, an origin server 3878 might be configured to execute the files with the request as input 3879 and send the output as the representation rather than transfer the 3880 files directly. Regardless, only the origin server needs to know how 3881 each of its resource identifiers corresponds to an implementation and 3882 how each implementation manages to select and send a current 3883 representation of the target resource in a response to GET. 3885 A client can alter the semantics of GET to be a "range request", 3886 requesting transfer of only some part(s) of the selected 3887 representation, by sending a Range header field in the request 3888 (Section 14.2). 3890 A client SHOULD NOT generate content in a GET request. Content 3891 received in a GET request has no defined semantics, cannot alter the 3892 meaning or target of the request, and might lead some implementations 3893 to reject the request and close the connection because of its 3894 potential as a request smuggling attack (Section 11.2 of 3895 [Messaging]). 3897 The response to a GET request is cacheable; a cache MAY use it to 3898 satisfy subsequent GET and HEAD requests unless otherwise indicated 3899 by the Cache-Control header field (Section 5.2 of [Caching]). 3901 When information retrieval is performed with a mechanism that 3902 constructs a target URI from user-provided information, such as the 3903 query fields of a form using GET, potentially sensitive data might be 3904 provided that would not be appropriate for disclosure within a URI 3905 (see Section 17.9). In some cases, the data can be filtered or 3906 transformed such that it would not reveal such information. In 3907 others, particularly when there is no benefit from caching a 3908 response, using the POST method (Section 9.3.3) instead of GET can 3909 transmit such information in the request content rather than within 3910 the target URI. 3912 9.3.2. HEAD 3914 The HEAD method is identical to GET except that the server MUST NOT 3915 send content in the response. HEAD is used to obtain metadata about 3916 the selected representation without transferring its representation 3917 data, often for the sake of testing hypertext links or finding recent 3918 modifications. 3920 The server SHOULD send the same header fields in response to a HEAD 3921 request as it would have sent if the request method had been GET. 3922 However, a server MAY omit header fields for which a value is 3923 determined only while generating the content. For example, some 3924 servers buffer a dynamic response to GET until a minimum amount of 3925 data is generated so that they can more efficiently delimit small 3926 responses or make late decisions with regard to content selection. 3927 Such a response to GET might contain Content-Length and Vary fields, 3928 for example, that are not generated within a HEAD response. These 3929 minor inconsistencies are considered preferable to generating and 3930 discarding the content for a HEAD request, since HEAD is usually 3931 requested for the sake of efficiency. 3933 A client SHOULD NOT generate content in a HEAD request. Content 3934 received in a HEAD request has no defined semantics, cannot alter the 3935 meaning or target of the request, and might lead some implementations 3936 to reject the request and close the connection because of its 3937 potential as a request smuggling attack (Section 11.2 of 3938 [Messaging]). 3940 The response to a HEAD request is cacheable; a cache MAY use it to 3941 satisfy subsequent HEAD requests unless otherwise indicated by the 3942 Cache-Control header field (Section 5.2 of [Caching]). A HEAD 3943 response might also affect previously cached responses to GET; see 3944 Section 4.3.5 of [Caching]. 3946 9.3.3. POST 3948 The POST method requests that the target resource process the 3949 representation enclosed in the request according to the resource's 3950 own specific semantics. For example, POST is used for the following 3951 functions (among others): 3953 * Providing a block of data, such as the fields entered into an HTML 3954 form, to a data-handling process; 3956 * Posting a message to a bulletin board, newsgroup, mailing list, 3957 blog, or similar group of articles; 3959 * Creating a new resource that has yet to be identified by the 3960 origin server; and 3962 * Appending data to a resource's existing representation(s). 3964 An origin server indicates response semantics by choosing an 3965 appropriate status code depending on the result of processing the 3966 POST request; almost all of the status codes defined by this 3967 specification could be received in a response to POST (the exceptions 3968 being 206 (Partial Content), 304 (Not Modified), and 416 (Range Not 3969 Satisfiable)). 3971 If one or more resources has been created on the origin server as a 3972 result of successfully processing a POST request, the origin server 3973 SHOULD send a 201 (Created) response containing a Location header 3974 field that provides an identifier for the primary resource created 3975 (Section 10.2.3) and a representation that describes the status of 3976 the request while referring to the new resource(s). 3978 Responses to POST requests are only cacheable when they include 3979 explicit freshness information (see Section 4.2.1 of [Caching]) and a 3980 Content-Location header field that has the same value as the POST's 3981 target URI (Section 8.7). A cached POST response can be reused to 3982 satisfy a later GET or HEAD request, but not a POST request, since 3983 POST is required to be written through to the origin server, because 3984 it is unsafe; see Section 4 of [Caching]. 3986 If the result of processing a POST would be equivalent to a 3987 representation of an existing resource, an origin server MAY redirect 3988 the user agent to that resource by sending a 303 (See Other) response 3989 with the existing resource's identifier in the Location field. This 3990 has the benefits of providing the user agent a resource identifier 3991 and transferring the representation via a method more amenable to 3992 shared caching, though at the cost of an extra request if the user 3993 agent does not already have the representation cached. 3995 9.3.4. PUT 3997 The PUT method requests that the state of the target resource be 3998 created or replaced with the state defined by the representation 3999 enclosed in the request message content. A successful PUT of a given 4000 representation would suggest that a subsequent GET on that same 4001 target resource will result in an equivalent representation being 4002 sent in a 200 (OK) response. However, there is no guarantee that 4003 such a state change will be observable, since the target resource 4004 might be acted upon by other user agents in parallel, or might be 4005 subject to dynamic processing by the origin server, before any 4006 subsequent GET is received. A successful response only implies that 4007 the user agent's intent was achieved at the time of its processing by 4008 the origin server. 4010 If the target resource does not have a current representation and the 4011 PUT successfully creates one, then the origin server MUST inform the 4012 user agent by sending a 201 (Created) response. If the target 4013 resource does have a current representation and that representation 4014 is successfully modified in accordance with the state of the enclosed 4015 representation, then the origin server MUST send either a 200 (OK) or 4016 a 204 (No Content) response to indicate successful completion of the 4017 request. 4019 An origin server SHOULD verify that the PUT representation is 4020 consistent with any constraints the server has for the target 4021 resource that cannot or will not be changed by the PUT. This is 4022 particularly important when the origin server uses internal 4023 configuration information related to the URI in order to set the 4024 values for representation metadata on GET responses. When a PUT 4025 representation is inconsistent with the target resource, the origin 4026 server SHOULD either make them consistent, by transforming the 4027 representation or changing the resource configuration, or respond 4028 with an appropriate error message containing sufficient information 4029 to explain why the representation is unsuitable. The 409 (Conflict) 4030 or 415 (Unsupported Media Type) status codes are suggested, with the 4031 latter being specific to constraints on Content-Type values. 4033 For example, if the target resource is configured to always have a 4034 Content-Type of "text/html" and the representation being PUT has a 4035 Content-Type of "image/jpeg", the origin server ought to do one of: 4037 a. reconfigure the target resource to reflect the new media type; 4039 b. transform the PUT representation to a format consistent with that 4040 of the resource before saving it as the new resource state; or, 4042 c. reject the request with a 415 (Unsupported Media Type) response 4043 indicating that the target resource is limited to "text/html", 4044 perhaps including a link to a different resource that would be a 4045 suitable target for the new representation. 4047 HTTP does not define exactly how a PUT method affects the state of an 4048 origin server beyond what can be expressed by the intent of the user 4049 agent request and the semantics of the origin server response. It 4050 does not define what a resource might be, in any sense of that word, 4051 beyond the interface provided via HTTP. It does not define how 4052 resource state is "stored", nor how such storage might change as a 4053 result of a change in resource state, nor how the origin server 4054 translates resource state into representations. Generally speaking, 4055 all implementation details behind the resource interface are 4056 intentionally hidden by the server. 4058 This extends to how header and trailer fields are stored; while 4059 common header fields like Content-Type will typically be stored and 4060 returned upon subsequent GET requests, header and trailer field 4061 handling is specific to the resource that received the request. As a 4062 result, an origin server SHOULD ignore unrecognized header and 4063 trailer fields received in a PUT request (i.e., do not save them as 4064 part of the resource state). 4066 An origin server MUST NOT send a validator field (Section 8.8), such 4067 as an ETag or Last-Modified field, in a successful response to PUT 4068 unless the request's representation data was saved without any 4069 transformation applied to the content (i.e., the resource's new 4070 representation data is identical to the content received in the PUT 4071 request) and the validator field value reflects the new 4072 representation. This requirement allows a user agent to know when 4073 the representation it sent (and retains in memory) is the result of 4074 the PUT, and thus doesn't need to be retrieved again from the origin 4075 server. The new validator(s) received in the response can be used 4076 for future conditional requests in order to prevent accidental 4077 overwrites (Section 13.1). 4079 The fundamental difference between the POST and PUT methods is 4080 highlighted by the different intent for the enclosed representation. 4081 The target resource in a POST request is intended to handle the 4082 enclosed representation according to the resource's own semantics, 4083 whereas the enclosed representation in a PUT request is defined as 4084 replacing the state of the target resource. Hence, the intent of PUT 4085 is idempotent and visible to intermediaries, even though the exact 4086 effect is only known by the origin server. 4088 Proper interpretation of a PUT request presumes that the user agent 4089 knows which target resource is desired. A service that selects a 4090 proper URI on behalf of the client, after receiving a state-changing 4091 request, SHOULD be implemented using the POST method rather than PUT. 4092 If the origin server will not make the requested PUT state change to 4093 the target resource and instead wishes to have it applied to a 4094 different resource, such as when the resource has been moved to a 4095 different URI, then the origin server MUST send an appropriate 3xx 4096 (Redirection) response; the user agent MAY then make its own decision 4097 regarding whether or not to redirect the request. 4099 A PUT request applied to the target resource can have side effects on 4100 other resources. For example, an article might have a URI for 4101 identifying "the current version" (a resource) that is separate from 4102 the URIs identifying each particular version (different resources 4103 that at one point shared the same state as the current version 4104 resource). A successful PUT request on "the current version" URI 4105 might therefore create a new version resource in addition to changing 4106 the state of the target resource, and might also cause links to be 4107 added between the related resources. 4109 Some origin servers support use of the Content-Range header field 4110 (Section 14.4) as a request modifier to perform a partial PUT, as 4111 described in Section 14.5. 4113 Responses to the PUT method are not cacheable. If a successful PUT 4114 request passes through a cache that has one or more stored responses 4115 for the target URI, those stored responses will be invalidated (see 4116 Section 4.4 of [Caching]). 4118 9.3.5. DELETE 4120 The DELETE method requests that the origin server remove the 4121 association between the target resource and its current 4122 functionality. In effect, this method is similar to the "rm" command 4123 in UNIX: it expresses a deletion operation on the URI mapping of the 4124 origin server rather than an expectation that the previously 4125 associated information be deleted. 4127 If the target resource has one or more current representations, they 4128 might or might not be destroyed by the origin server, and the 4129 associated storage might or might not be reclaimed, depending 4130 entirely on the nature of the resource and its implementation by the 4131 origin server (which are beyond the scope of this specification). 4132 Likewise, other implementation aspects of a resource might need to be 4133 deactivated or archived as a result of a DELETE, such as database or 4134 gateway connections. In general, it is assumed that the origin 4135 server will only allow DELETE on resources for which it has a 4136 prescribed mechanism for accomplishing the deletion. 4138 Relatively few resources allow the DELETE method - its primary use is 4139 for remote authoring environments, where the user has some direction 4140 regarding its effect. For example, a resource that was previously 4141 created using a PUT request, or identified via the Location header 4142 field after a 201 (Created) response to a POST request, might allow a 4143 corresponding DELETE request to undo those actions. Similarly, 4144 custom user agent implementations that implement an authoring 4145 function, such as revision control clients using HTTP for remote 4146 operations, might use DELETE based on an assumption that the server's 4147 URI space has been crafted to correspond to a version repository. 4149 If a DELETE method is successfully applied, the origin server SHOULD 4150 send 4152 * a 202 (Accepted) status code if the action will likely succeed but 4153 has not yet been enacted, 4155 * a 204 (No Content) status code if the action has been enacted and 4156 no further information is to be supplied, or 4158 * a 200 (OK) status code if the action has been enacted and the 4159 response message includes a representation describing the status. 4161 A client SHOULD NOT generate content in a DELETE request. Content 4162 received in a DELETE request has no defined semantics, cannot alter 4163 the meaning or target of the request, and might lead some 4164 implementations to reject the request. 4166 Responses to the DELETE method are not cacheable. If a successful 4167 DELETE request passes through a cache that has one or more stored 4168 responses for the target URI, those stored responses will be 4169 invalidated (see Section 4.4 of [Caching]). 4171 9.3.6. CONNECT 4173 The CONNECT method requests that the recipient establish a tunnel to 4174 the destination origin server identified by the request target and, 4175 if successful, thereafter restrict its behavior to blind forwarding 4176 of data, in both directions, until the tunnel is closed. Tunnels are 4177 commonly used to create an end-to-end virtual connection, through one 4178 or more proxies, which can then be secured using TLS (Transport Layer 4179 Security, [RFC8446]). 4181 CONNECT uses a special form of request target, unique to this method, 4182 consisting of only the host and port number of the tunnel 4183 destination, separated by a colon. There is no default port; a 4184 client MUST send the port number even if the CONNECT request is based 4185 on a URI reference that contains an authority component with an 4186 elided port (Section 4.1). For example, 4188 CONNECT server.example.com:80 HTTP/1.1 4189 Host: server.example.com 4191 A server MUST reject a CONNECT request that targets an empty or 4192 invalid port number, typically by responding with a 400 (Bad Request) 4193 status code. 4195 Because CONNECT changes the request/response nature of an HTTP 4196 connection, specific HTTP versions might have different ways of 4197 mapping its semantics into the protocol's wire format. 4199 CONNECT is intended for use in requests to a proxy. The recipient 4200 can establish a tunnel either by directly connecting to the server 4201 identified by the request target or, if configured to use another 4202 proxy, by forwarding the CONNECT request to the next inbound proxy. 4203 An origin server MAY accept a CONNECT request, but most origin 4204 servers do not implement CONNECT. 4206 Any 2xx (Successful) response indicates that the sender (and all 4207 inbound proxies) will switch to tunnel mode immediately after the 4208 response header section; data received after that header section is 4209 from the server identified by the request target. Any response other 4210 than a successful response indicates that the tunnel has not yet been 4211 formed. 4213 A tunnel is closed when a tunnel intermediary detects that either 4214 side has closed its connection: the intermediary MUST attempt to send 4215 any outstanding data that came from the closed side to the other 4216 side, close both connections, and then discard any remaining data 4217 left undelivered. 4219 Proxy authentication might be used to establish the authority to 4220 create a tunnel. For example, 4222 CONNECT server.example.com:443 HTTP/1.1 4223 Host: server.example.com:443 4224 Proxy-Authorization: basic aGVsbG86d29ybGQ= 4226 There are significant risks in establishing a tunnel to arbitrary 4227 servers, particularly when the destination is a well-known or 4228 reserved TCP port that is not intended for Web traffic. For example, 4229 a CONNECT to "example.com:25" would suggest that the proxy connect to 4230 the reserved port for SMTP traffic; if allowed, that could trick the 4231 proxy into relaying spam email. Proxies that support CONNECT SHOULD 4232 restrict its use to a limited set of known ports or a configurable 4233 list of safe request targets. 4235 A server MUST NOT send any Transfer-Encoding or Content-Length header 4236 fields in a 2xx (Successful) response to CONNECT. A client MUST 4237 ignore any Content-Length or Transfer-Encoding header fields received 4238 in a successful response to CONNECT. 4240 A CONNECT request message does not have content. The interpretation 4241 of and allowability of data sent after the header section of the 4242 CONNECT request message is specific to the version of HTTP in use. 4244 Responses to the CONNECT method are not cacheable. 4246 9.3.7. OPTIONS 4248 The OPTIONS method requests information about the communication 4249 options available for the target resource, at either the origin 4250 server or an intervening intermediary. This method allows a client 4251 to determine the options and/or requirements associated with a 4252 resource, or the capabilities of a server, without implying a 4253 resource action. 4255 An OPTIONS request with an asterisk ("*") as the request target 4256 (Section 7.1) applies to the server in general rather than to a 4257 specific resource. Since a server's communication options typically 4258 depend on the resource, the "*" request is only useful as a "ping" or 4259 "no-op" type of method; it does nothing beyond allowing the client to 4260 test the capabilities of the server. For example, this can be used 4261 to test a proxy for HTTP/1.1 conformance (or lack thereof). 4263 If the request target is not an asterisk, the OPTIONS request applies 4264 to the options that are available when communicating with the target 4265 resource. 4267 A server generating a successful response to OPTIONS SHOULD send any 4268 header that might indicate optional features implemented by the 4269 server and applicable to the target resource (e.g., Allow), including 4270 potential extensions not defined by this specification. The response 4271 content, if any, might also describe the communication options in a 4272 machine or human-readable representation. A standard format for such 4273 a representation is not defined by this specification, but might be 4274 defined by future extensions to HTTP. 4276 A client MAY send a Max-Forwards header field in an OPTIONS request 4277 to target a specific recipient in the request chain (see 4278 Section 7.6.2). A proxy MUST NOT generate a Max-Forwards header 4279 field while forwarding a request unless that request was received 4280 with a Max-Forwards field. 4282 A client that generates an OPTIONS request containing content MUST 4283 send a valid Content-Type header field describing the representation 4284 media type. Note that this specification does not define any use for 4285 such content. 4287 Responses to the OPTIONS method are not cacheable. 4289 9.3.8. TRACE 4291 The TRACE method requests a remote, application-level loop-back of 4292 the request message. The final recipient of the request SHOULD 4293 reflect the message received, excluding some fields described below, 4294 back to the client as the content of a 200 (OK) response. The 4295 "message/http" (Section 10.1 of [Messaging]) format is one way to do 4296 so. The final recipient is either the origin server or the first 4297 server to receive a Max-Forwards value of zero (0) in the request 4298 (Section 7.6.2). 4300 A client MUST NOT generate fields in a TRACE request containing 4301 sensitive data that might be disclosed by the response. For example, 4302 it would be foolish for a user agent to send stored user credentials 4303 (Section 11) or cookies [RFC6265] in a TRACE request. The final 4304 recipient of the request SHOULD exclude any request fields that are 4305 likely to contain sensitive data when that recipient generates the 4306 response content. 4308 TRACE allows the client to see what is being received at the other 4309 end of the request chain and use that data for testing or diagnostic 4310 information. The value of the Via header field (Section 7.6.3) is of 4311 particular interest, since it acts as a trace of the request chain. 4312 Use of the Max-Forwards header field allows the client to limit the 4313 length of the request chain, which is useful for testing a chain of 4314 proxies forwarding messages in an infinite loop. 4316 A client MUST NOT send content in a TRACE request. 4318 Responses to the TRACE method are not cacheable. 4320 10. Message Context 4322 10.1. Request Context Fields 4324 The request header fields below provide additional information about 4325 the request context, including information about the user, user 4326 agent, and resource behind the request. 4328 10.1.1. Expect 4330 The "Expect" header field in a request indicates a certain set of 4331 behaviors (expectations) that need to be supported by the server in 4332 order to properly handle this request. 4334 Expect = #expectation 4335 expectation = token [ "=" ( token / quoted-string ) parameters ] 4337 The Expect field value is case-insensitive. 4339 The only expectation defined by this specification is "100-continue" 4340 (with no defined parameters). 4342 A server that receives an Expect field value containing a member 4343 other than 100-continue MAY respond with a 417 (Expectation Failed) 4344 status code to indicate that the unexpected expectation cannot be 4345 met. 4347 A _100-continue_ expectation informs recipients that the client is 4348 about to send (presumably large) content in this request and wishes 4349 to receive a 100 (Continue) interim response if the method, target 4350 URI, and header fields are not sufficient to cause an immediate 4351 success, redirect, or error response. This allows the client to wait 4352 for an indication that it is worthwhile to send the content before 4353 actually doing so, which can improve efficiency when the data is huge 4354 or when the client anticipates that an error is likely (e.g., when 4355 sending a state-changing method, for the first time, without 4356 previously verified authentication credentials). 4358 For example, a request that begins with 4360 PUT /somewhere/fun HTTP/1.1 4361 Host: origin.example.com 4362 Content-Type: video/h264 4363 Content-Length: 1234567890987 4364 Expect: 100-continue 4366 allows the origin server to immediately respond with an error 4367 message, such as 401 (Unauthorized) or 405 (Method Not Allowed), 4368 before the client starts filling the pipes with an unnecessary data 4369 transfer. 4371 Requirements for clients: 4373 * A client MUST NOT generate a 100-continue expectation in a request 4374 that does not include content. 4376 * A client that will wait for a 100 (Continue) response before 4377 sending the request content MUST send an Expect header field 4378 containing a 100-continue expectation. 4380 * A client that sends a 100-continue expectation is not required to 4381 wait for any specific length of time; such a client MAY proceed to 4382 send the content even if it has not yet received a response. 4383 Furthermore, since 100 (Continue) responses cannot be sent through 4384 an HTTP/1.0 intermediary, such a client SHOULD NOT wait for an 4385 indefinite period before sending the content. 4387 * A client that receives a 417 (Expectation Failed) status code in 4388 response to a request containing a 100-continue expectation SHOULD 4389 repeat that request without a 100-continue expectation, since the 4390 417 response merely indicates that the response chain does not 4391 support expectations (e.g., it passes through an HTTP/1.0 server). 4393 Requirements for servers: 4395 * A server that receives a 100-continue expectation in an HTTP/1.0 4396 request MUST ignore that expectation. 4398 * A server MAY omit sending a 100 (Continue) response if it has 4399 already received some or all of the content for the corresponding 4400 request, or if the framing indicates that there is no content. 4402 * A server that sends a 100 (Continue) response MUST ultimately send 4403 a final status code, once it receives and processes the request 4404 content, unless the connection is closed prematurely. 4406 * A server that responds with a final status code before reading the 4407 entire request content SHOULD indicate whether it intends to close 4408 the connection (e.g., see Section 9.6 of [Messaging]) or continue 4409 reading the request content. 4411 An origin server MUST, upon receiving an HTTP/1.1 (or later) request 4412 that has a method, target URI, and complete header section that 4413 contains a 100-continue expectation and an indication that request 4414 content will follow, either send an immediate response with a final 4415 status code, if that status can be determined by examining just the 4416 method, target URI, and header fields, or send an immediate 100 4417 (Continue) response to encourage the client to send the request 4418 content. The origin server MUST NOT wait for the content before 4419 sending the 100 (Continue) response. 4421 A proxy MUST, upon receiving an HTTP/1.1 (or later) request that has 4422 a method, target URI, and complete header section that contains a 4423 100-continue expectation and indicates a request content will follow, 4424 either send an immediate response with a final status code, if that 4425 status can be determined by examining just the method, target URI, 4426 and header fields, or begin forwarding the request toward the origin 4427 server by sending a corresponding request-line and header section to 4428 the next inbound server. If the proxy believes (from configuration 4429 or past interaction) that the next inbound server only supports 4430 HTTP/1.0, the proxy MAY generate an immediate 100 (Continue) response 4431 to encourage the client to begin sending the content. 4433 10.1.2. From 4435 The "From" header field contains an Internet email address for a 4436 human user who controls the requesting user agent. The address ought 4437 to be machine-usable, as defined by "mailbox" in Section 3.4 of 4438 [RFC5322]: 4440 From = mailbox 4442 mailbox = 4444 An example is: 4446 From: webmaster@example.org 4448 The From header field is rarely sent by non-robotic user agents. A 4449 user agent SHOULD NOT send a From header field without explicit 4450 configuration by the user, since that might conflict with the user's 4451 privacy interests or their site's security policy. 4453 A robotic user agent SHOULD send a valid From header field so that 4454 the person responsible for running the robot can be contacted if 4455 problems occur on servers, such as if the robot is sending excessive, 4456 unwanted, or invalid requests. 4458 A server SHOULD NOT use the From header field for access control or 4459 authentication. 4461 10.1.3. Referer 4463 The "Referer" [sic] header field allows the user agent to specify a 4464 URI reference for the resource from which the target URI was obtained 4465 (i.e., the "referrer", though the field name is misspelled). A user 4466 agent MUST NOT include the fragment and userinfo components of the 4467 URI reference [RFC3986], if any, when generating the Referer field 4468 value. 4470 Referer = absolute-URI / partial-URI 4472 The field value is either an absolute-URI or a partial-URI. In the 4473 latter case (Section 4), the referenced URI is relative to the target 4474 URI ([RFC3986], Section 5). 4476 The Referer header field allows servers to generate back-links to 4477 other resources for simple analytics, logging, optimized caching, 4478 etc. It also allows obsolete or mistyped links to be found for 4479 maintenance. Some servers use the Referer header field as a means of 4480 denying links from other sites (so-called "deep linking") or 4481 restricting cross-site request forgery (CSRF), but not all requests 4482 contain it. 4484 Example: 4486 Referer: http://www.example.org/hypertext/Overview.html 4488 If the target URI was obtained from a source that does not have its 4489 own URI (e.g., input from the user keyboard, or an entry within the 4490 user's bookmarks/favorites), the user agent MUST either exclude the 4491 Referer header field or send it with a value of "about:blank". 4493 The Referer header field value need not convey the full URI of the 4494 referring resource; a user agent MAY truncate parts other than the 4495 referring origin. 4497 The Referer header field has the potential to reveal information 4498 about the request context or browsing history of the user, which is a 4499 privacy concern if the referring resource's identifier reveals 4500 personal information (such as an account name) or a resource that is 4501 supposed to be confidential (such as behind a firewall or internal to 4502 a secured service). Most general-purpose user agents do not send the 4503 Referer header field when the referring resource is a local "file" or 4504 "data" URI. A user agent SHOULD NOT send a Referer header field if 4505 the referring resource was accessed with a secure protocol and the 4506 request target has an origin differing from that of the referring 4507 resource, unless the referring resource explicitly allows Referer to 4508 be sent. A user agent MUST NOT send a Referer header field in an 4509 unsecured HTTP request if the referring resource was accessed with a 4510 secure protocol. See Section 17.9 for additional security 4511 considerations. 4513 Some intermediaries have been known to indiscriminately remove 4514 Referer header fields from outgoing requests. This has the 4515 unfortunate side effect of interfering with protection against CSRF 4516 attacks, which can be far more harmful to their users. 4517 Intermediaries and user agent extensions that wish to limit 4518 information disclosure in Referer ought to restrict their changes to 4519 specific edits, such as replacing internal domain names with 4520 pseudonyms or truncating the query and/or path components. An 4521 intermediary SHOULD NOT modify or delete the Referer header field 4522 when the field value shares the same scheme and host as the target 4523 URI. 4525 10.1.4. TE 4527 The "TE" header field in a request can be used to indicate that the 4528 sender will not discard trailer fields when it contains a "trailers" 4529 member, as described in Section 6.5. 4531 Additionally, specific HTTP versions can use it to indicate the 4532 transfer codings the client is willing to accept in the response. As 4533 of publication, only HTTP/1.1 uses transfer codings (see Section 7 of 4534 [Messaging]). 4536 The TE field value consists of a list of tokens, each allowing for 4537 optional parameters (except for the special case "trailers"). 4539 TE = #t-codings 4540 t-codings = "trailers" / ( transfer-coding [ weight ] ) 4541 transfer-coding = token *( OWS ";" OWS transfer-parameter ) 4542 transfer-parameter = token BWS "=" BWS ( token / quoted-string ) 4544 A sender of TE MUST also send a "TE" connection option within the 4545 Connection header field (Section 7.6.1) to inform intermediaries not 4546 to forward this field. 4548 10.1.5. Trailer 4550 The "Trailer" header field provides a list of field names that the 4551 sender anticipates sending as trailer fields within that message. 4552 This allows a recipient to prepare for receipt of the indicated 4553 metadata before it starts processing the content. 4555 Trailer = #field-name 4557 For example, a sender might indicate that a message integrity check 4558 will be computed as the content is being streamed and provide the 4559 final signature as a trailer field. This allows a recipient to 4560 perform the same check on the fly as it receives the content. 4562 Because the Trailer field is not removed by intermediaries, it can 4563 also be used by downstream recipients to discover when a trailer 4564 field has been removed from a message. 4566 A sender that intends to generate one or more trailer fields in a 4567 message SHOULD generate a Trailer header field in the header section 4568 of that message to indicate which fields might be present in the 4569 trailers. 4571 10.1.6. User-Agent 4573 The "User-Agent" header field contains information about the user 4574 agent originating the request, which is often used by servers to help 4575 identify the scope of reported interoperability problems, to work 4576 around or tailor responses to avoid particular user agent 4577 limitations, and for analytics regarding browser or operating system 4578 use. A user agent SHOULD send a User-Agent header field in each 4579 request unless specifically configured not to do so. 4581 User-Agent = product *( RWS ( product / comment ) ) 4583 The User-Agent field value consists of one or more product 4584 identifiers, each followed by zero or more comments (Section 5.6.5), 4585 which together identify the user agent software and its significant 4586 subproducts. By convention, the product identifiers are listed in 4587 decreasing order of their significance for identifying the user agent 4588 software. Each product identifier consists of a name and optional 4589 version. 4591 product = token ["/" product-version] 4592 product-version = token 4594 A sender SHOULD limit generated product identifiers to what is 4595 necessary to identify the product; a sender MUST NOT generate 4596 advertising or other nonessential information within the product 4597 identifier. A sender SHOULD NOT generate information in 4598 product-version that is not a version identifier (i.e., successive 4599 versions of the same product name ought to differ only in the 4600 product-version portion of the product identifier). 4602 Example: 4604 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 4606 A user agent SHOULD NOT generate a User-Agent header field containing 4607 needlessly fine-grained detail and SHOULD limit the addition of 4608 subproducts by third parties. Overly long and detailed User-Agent 4609 field values increase request latency and the risk of a user being 4610 identified against their wishes ("fingerprinting"). 4612 Likewise, implementations are encouraged not to use the product 4613 tokens of other implementations in order to declare compatibility 4614 with them, as this circumvents the purpose of the field. If a user 4615 agent masquerades as a different user agent, recipients can assume 4616 that the user intentionally desires to see responses tailored for 4617 that identified user agent, even if they might not work as well for 4618 the actual user agent being used. 4620 10.2. Response Context Fields 4622 Response header fields can supply control data that supplements the 4623 status code, directs caching, or instructs the client where to go 4624 next. 4626 The response header fields allow the server to pass additional 4627 information about the response beyond the status code. These header 4628 fields give information about the server, about further access to the 4629 target resource, or about related resources. 4631 Although each response header field has a defined meaning, in 4632 general, the precise semantics might be further refined by the 4633 semantics of the request method and/or response status code. 4635 The remaining response header fields provide more information about 4636 the target resource for potential use in later requests. 4638 10.2.1. Allow 4640 The "Allow" header field lists the set of methods advertised as 4641 supported by the target resource. The purpose of this field is 4642 strictly to inform the recipient of valid request methods associated 4643 with the resource. 4645 Allow = #method 4647 Example of use: 4649 Allow: GET, HEAD, PUT 4651 The actual set of allowed methods is defined by the origin server at 4652 the time of each request. An origin server MUST generate an Allow 4653 header field in a 405 (Method Not Allowed) response and MAY do so in 4654 any other response. An empty Allow field value indicates that the 4655 resource allows no methods, which might occur in a 405 response if 4656 the resource has been temporarily disabled by configuration. 4658 A proxy MUST NOT modify the Allow header field - it does not need to 4659 understand all of the indicated methods in order to handle them 4660 according to the generic message handling rules. 4662 10.2.2. Date 4664 The "Date" header field represents the date and time at which the 4665 message was originated, having the same semantics as the Origination 4666 Date Field (orig-date) defined in Section 3.6.1 of [RFC5322]. The 4667 field value is an HTTP-date, as defined in Section 5.6.7. 4669 Date = HTTP-date 4671 An example is 4673 Date: Tue, 15 Nov 1994 08:12:31 GMT 4675 A sender that generates a Date header field SHOULD generate its field 4676 value as the best available approximation of the date and time of 4677 message generation. In theory, the date ought to represent the 4678 moment just before generating the message content. In practice, a 4679 sender can generate the date value at any time during message 4680 origination. 4682 An origin server MUST NOT send a Date header field if it does not 4683 have a clock capable of providing a reasonable approximation of the 4684 current instance in Coordinated Universal Time. An origin server MAY 4685 send a Date header field if the response is in the 1xx 4686 (Informational) or 5xx (Server Error) class of status codes. An 4687 origin server MUST send a Date header field in all other cases. 4689 A recipient with a clock that receives a response message without a 4690 Date header field MUST record the time it was received and append a 4691 corresponding Date header field to the message's header section if it 4692 is cached or forwarded downstream. 4694 A recipient with a clock that receives a response with an invalid 4695 Date header field value MAY replace that value with the time that 4696 response was received. 4698 A user agent MAY send a Date header field in a request, though 4699 generally will not do so unless it is believed to convey useful 4700 information to the server. For example, custom applications of HTTP 4701 might convey a Date if the server is expected to adjust its 4702 interpretation of the user's request based on differences between the 4703 user agent and server clocks. 4705 10.2.3. Location 4707 The "Location" header field is used in some responses to refer to a 4708 specific resource in relation to the response. The type of 4709 relationship is defined by the combination of request method and 4710 status code semantics. 4712 Location = URI-reference 4714 The field value consists of a single URI-reference. When it has the 4715 form of a relative reference ([RFC3986], Section 4.2), the final 4716 value is computed by resolving it against the target URI ([RFC3986], 4717 Section 5). 4719 For 201 (Created) responses, the Location value refers to the primary 4720 resource created by the request. For 3xx (Redirection) responses, 4721 the Location value refers to the preferred target resource for 4722 automatically redirecting the request. 4724 If the Location value provided in a 3xx (Redirection) response does 4725 not have a fragment component, a user agent MUST process the 4726 redirection as if the value inherits the fragment component of the 4727 URI reference used to generate the target URI (i.e., the redirection 4728 inherits the original reference's fragment, if any). 4730 For example, a GET request generated for the URI reference 4731 "http://www.example.org/~tim" might result in a 303 (See Other) 4732 response containing the header field: 4734 Location: /People.html#tim 4736 which suggests that the user agent redirect to 4737 "http://www.example.org/People.html#tim" 4739 Likewise, a GET request generated for the URI reference 4740 "http://www.example.org/index.html#larry" might result in a 301 4741 (Moved Permanently) response containing the header field: 4743 Location: http://www.example.net/index.html 4745 which suggests that the user agent redirect to 4746 "http://www.example.net/index.html#larry", preserving the original 4747 fragment identifier. 4749 There are circumstances in which a fragment identifier in a Location 4750 value would not be appropriate. For example, the Location header 4751 field in a 201 (Created) response is supposed to provide a URI that 4752 is specific to the created resource. 4754 | *Note:* Some recipients attempt to recover from Location header 4755 | fields that are not valid URI references. This specification 4756 | does not mandate or define such processing, but does allow it 4757 | for the sake of robustness. A Location field value cannot 4758 | allow a list of members because the comma list separator is a 4759 | valid data character within a URI-reference. If an invalid 4760 | message is sent with multiple Location field lines, a recipient 4761 | along the path might combine those field lines into one value. 4762 | Recovery of a valid Location field value from that situation is 4763 | difficult and not interoperable across implementations. 4765 | *Note:* The Content-Location header field (Section 8.7) differs 4766 | from Location in that the Content-Location refers to the most 4767 | specific resource corresponding to the enclosed representation. 4768 | It is therefore possible for a response to contain both the 4769 | Location and Content-Location header fields. 4771 10.2.4. Retry-After 4773 Servers send the "Retry-After" header field to indicate how long the 4774 user agent ought to wait before making a follow-up request. When 4775 sent with a 503 (Service Unavailable) response, Retry-After indicates 4776 how long the service is expected to be unavailable to the client. 4777 When sent with any 3xx (Redirection) response, Retry-After indicates 4778 the minimum time that the user agent is asked to wait before issuing 4779 the redirected request. 4781 The Retry-After field value can be either an HTTP-date or a number of 4782 seconds to delay after receiving the response. 4784 Retry-After = HTTP-date / delay-seconds 4786 A delay-seconds value is a non-negative decimal integer, representing 4787 time in seconds. 4789 delay-seconds = 1*DIGIT 4791 Two examples of its use are 4793 Retry-After: Fri, 31 Dec 1999 23:59:59 GMT 4794 Retry-After: 120 4796 In the latter example, the delay is 2 minutes. 4798 10.2.5. Server 4800 The "Server" header field contains information about the software 4801 used by the origin server to handle the request, which is often used 4802 by clients to help identify the scope of reported interoperability 4803 problems, to work around or tailor requests to avoid particular 4804 server limitations, and for analytics regarding server or operating 4805 system use. An origin server MAY generate a Server header field in 4806 its responses. 4808 Server = product *( RWS ( product / comment ) ) 4810 The Server header field value consists of one or more product 4811 identifiers, each followed by zero or more comments (Section 5.6.5), 4812 which together identify the origin server software and its 4813 significant subproducts. By convention, the product identifiers are 4814 listed in decreasing order of their significance for identifying the 4815 origin server software. Each product identifier consists of a name 4816 and optional version, as defined in Section 10.1.6. 4818 Example: 4820 Server: CERN/3.0 libwww/2.17 4822 An origin server SHOULD NOT generate a Server header field containing 4823 needlessly fine-grained detail and SHOULD limit the addition of 4824 subproducts by third parties. Overly long and detailed Server field 4825 values increase response latency and potentially reveal internal 4826 implementation details that might make it (slightly) easier for 4827 attackers to find and exploit known security holes. 4829 11. HTTP Authentication 4831 11.1. Authentication Scheme 4833 HTTP provides a general framework for access control and 4834 authentication, via an extensible set of challenge-response 4835 authentication schemes, which can be used by a server to challenge a 4836 client request and by a client to provide authentication information. 4837 It uses a case-insensitive token to identify the authentication 4838 scheme 4840 auth-scheme = token 4842 Aside from the general framework, this document does not specify any 4843 authentication schemes. New and existing authentication schemes are 4844 specified independently and ought to be registered within the 4845 "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry". 4846 For example, the "basic" and "digest" authentication schemes are 4847 defined by RFC 7617 and RFC 7616, respectively. 4849 11.2. Authentication Parameters 4851 The authentication scheme is followed by additional information 4852 necessary for achieving authentication via that scheme as either a 4853 comma-separated list of parameters or a single sequence of characters 4854 capable of holding base64-encoded information. 4856 token68 = 1*( ALPHA / DIGIT / 4857 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 4859 The token68 syntax allows the 66 unreserved URI characters 4860 ([RFC3986]), plus a few others, so that it can hold a base64, 4861 base64url (URL and filename safe alphabet), base32, or base16 (hex) 4862 encoding, with or without padding, but excluding whitespace 4863 ([RFC4648]). 4865 Authentication parameters are name=value pairs, where the name token 4866 is matched case-insensitively and each parameter name MUST only occur 4867 once per challenge. 4869 auth-param = token BWS "=" BWS ( token / quoted-string ) 4871 Parameter values can be expressed either as "token" or as "quoted- 4872 string" (Section 5.6). Authentication scheme definitions need to 4873 accept both notations, both for senders and recipients, to allow 4874 recipients to use generic parsing components regardless of the 4875 authentication scheme. 4877 For backwards compatibility, authentication scheme definitions can 4878 restrict the format for senders to one of the two variants. This can 4879 be important when it is known that deployed implementations will fail 4880 when encountering one of the two formats. 4882 11.3. Challenge and Response 4884 A 401 (Unauthorized) response message is used by an origin server to 4885 challenge the authorization of a user agent, including a 4886 WWW-Authenticate header field containing at least one challenge 4887 applicable to the requested resource. 4889 A 407 (Proxy Authentication Required) response message is used by a 4890 proxy to challenge the authorization of a client, including a 4891 Proxy-Authenticate header field containing at least one challenge 4892 applicable to the proxy for the requested resource. 4894 challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ] 4896 | *Note:* Many clients fail to parse a challenge that contains an 4897 | unknown scheme. A workaround for this problem is to list well- 4898 | supported schemes (such as "basic") first. 4900 A user agent that wishes to authenticate itself with an origin server 4901 - usually, but not necessarily, after receiving a 401 (Unauthorized) 4902 - can do so by including an Authorization header field with the 4903 request. 4905 A client that wishes to authenticate itself with a proxy - usually, 4906 but not necessarily, after receiving a 407 (Proxy Authentication 4907 Required) - can do so by including a Proxy-Authorization header field 4908 with the request. 4910 11.4. Credentials 4912 Both the Authorization field value and the Proxy-Authorization field 4913 value contain the client's credentials for the realm of the resource 4914 being requested, based upon a challenge received in a response 4915 (possibly at some point in the past). When creating their values, 4916 the user agent ought to do so by selecting the challenge with what it 4917 considers to be the most secure auth-scheme that it understands, 4918 obtaining credentials from the user as appropriate. Transmission of 4919 credentials within header field values implies significant security 4920 considerations regarding the confidentiality of the underlying 4921 connection, as described in Section 17.16.1. 4923 credentials = auth-scheme [ 1*SP ( token68 / #auth-param ) ] 4925 Upon receipt of a request for a protected resource that omits 4926 credentials, contains invalid credentials (e.g., a bad password) or 4927 partial credentials (e.g., when the authentication scheme requires 4928 more than one round trip), an origin server SHOULD send a 401 4929 (Unauthorized) response that contains a WWW-Authenticate header field 4930 with at least one (possibly new) challenge applicable to the 4931 requested resource. 4933 Likewise, upon receipt of a request that omits proxy credentials or 4934 contains invalid or partial proxy credentials, a proxy that requires 4935 authentication SHOULD generate a 407 (Proxy Authentication Required) 4936 response that contains a Proxy-Authenticate header field with at 4937 least one (possibly new) challenge applicable to the proxy. 4939 A server that receives valid credentials that are not adequate to 4940 gain access ought to respond with the 403 (Forbidden) status code 4941 (Section 15.5.4). 4943 HTTP does not restrict applications to this simple challenge-response 4944 framework for access authentication. Additional mechanisms can be 4945 used, such as authentication at the transport level or via message 4946 encapsulation, and with additional header fields specifying 4947 authentication information. However, such additional mechanisms are 4948 not defined by this specification. 4950 Note that various custom mechanisms for user authentication use the 4951 Set-Cookie and Cookie header fields, defined in [RFC6265], for 4952 passing tokens related to authentication. 4954 11.5. Establishing a Protection Space (Realm) 4956 The _realm_ authentication parameter is reserved for use by 4957 authentication schemes that wish to indicate a scope of protection. 4959 A _protection space_ is defined by the origin (see Section 4.3.1) of 4960 the server being accessed, in combination with the realm value if 4961 present. These realms allow the protected resources on a server to 4962 be partitioned into a set of protection spaces, each with its own 4963 authentication scheme and/or authorization database. The realm value 4964 is a string, generally assigned by the origin server, that can have 4965 additional semantics specific to the authentication scheme. Note 4966 that a response can have multiple challenges with the same auth- 4967 scheme but with different realms. 4969 The protection space determines the domain over which credentials can 4970 be automatically applied. If a prior request has been authorized, 4971 the user agent MAY reuse the same credentials for all other requests 4972 within that protection space for a period of time determined by the 4973 authentication scheme, parameters, and/or user preferences (such as a 4974 configurable inactivity timeout). 4976 The extent of a protection space, and therefore the requests to which 4977 credentials might be automatically applied, is not necessarily known 4978 to clients without additional information. An authentication scheme 4979 might define parameters that describe the extent of a protection 4980 space. Unless specifically allowed by the authentication scheme, a 4981 single protection space cannot extend outside the scope of its 4982 server. 4984 For historical reasons, a sender MUST only generate the quoted-string 4985 syntax. Recipients might have to support both token and quoted- 4986 string syntax for maximum interoperability with existing clients that 4987 have been accepting both notations for a long time. 4989 11.6. Authenticating Users to Origin Servers 4991 11.6.1. WWW-Authenticate 4993 The "WWW-Authenticate" header field indicates the authentication 4994 scheme(s) and parameters applicable to the target resource. 4996 WWW-Authenticate = #challenge 4998 A server generating a 401 (Unauthorized) response MUST send a WWW- 4999 Authenticate header field containing at least one challenge. A 5000 server MAY generate a WWW-Authenticate header field in other response 5001 messages to indicate that supplying credentials (or different 5002 credentials) might affect the response. 5004 A proxy forwarding a response MUST NOT modify any WWW-Authenticate 5005 header fields in that response. 5007 User agents are advised to take special care in parsing the field 5008 value, as it might contain more than one challenge, and each 5009 challenge can contain a comma-separated list of authentication 5010 parameters. Furthermore, the header field itself can occur multiple 5011 times. 5013 For instance: 5015 WWW-Authenticate: Basic realm="simple", Newauth realm="apps", 5016 type=1, title="Login to \"apps\"" 5018 This header field contains two challenges; one for the "Basic" scheme 5019 with a realm value of "simple", and another for the "Newauth" scheme 5020 with a realm value of "apps", and two additional parameters "type" 5021 and "title". 5023 Some user agents do not recognise this form, however. As a result, 5024 sending a WWW-Authenticate field value with more than one member on 5025 the same field line might not be interoperable. 5027 | *Note:* The challenge grammar production uses the list syntax 5028 | as well. Therefore, a sequence of comma, whitespace, and comma 5029 | can be considered either as applying to the preceding 5030 | challenge, or to be an empty entry in the list of challenges. 5031 | In practice, this ambiguity does not affect the semantics of 5032 | the header field value and thus is harmless. 5034 11.6.2. Authorization 5036 The "Authorization" header field allows a user agent to authenticate 5037 itself with an origin server - usually, but not necessarily, after 5038 receiving a 401 (Unauthorized) response. Its value consists of 5039 credentials containing the authentication information of the user 5040 agent for the realm of the resource being requested. 5042 Authorization = credentials 5044 If a request is authenticated and a realm specified, the same 5045 credentials are presumed to be valid for all other requests within 5046 this realm (assuming that the authentication scheme itself does not 5047 require otherwise, such as credentials that vary according to a 5048 challenge value or using synchronized clocks). 5050 A proxy forwarding a request MUST NOT modify any Authorization header 5051 fields in that request. See Section 3.5 of [Caching] for details of 5052 and requirements pertaining to handling of the Authorization header 5053 field by HTTP caches. 5055 11.6.3. Authentication-Info 5057 HTTP authentication schemes can use the Authentication-Info response 5058 field to communicate information after the client's authentication 5059 credentials have been accepted. This information can include a 5060 finalization message from the server (e.g., it can contain the server 5061 authentication). 5063 The field value is a list of parameters (name/value pairs), using the 5064 "auth-param" syntax defined in Section 11.3. This specification only 5065 describes the generic format; authentication schemes using 5066 Authentication-Info will define the individual parameters. The 5067 "Digest" Authentication Scheme, for instance, defines multiple 5068 parameters in Section 3.5 of [RFC7616]. 5070 Authentication-Info = #auth-param 5072 The Authentication-Info field can be used in any HTTP response, 5073 independently of request method and status code. Its semantics are 5074 defined by the authentication scheme indicated by the Authorization 5075 header field (Section 11.6.2) of the corresponding request. 5077 A proxy forwarding a response is not allowed to modify the field 5078 value in any way. 5080 Authentication-Info can be sent as a trailer field (Section 6.5) when 5081 the authentication scheme explicitly allows this. 5083 11.7. Authenticating Clients to Proxies 5085 11.7.1. Proxy-Authenticate 5087 The "Proxy-Authenticate" header field consists of at least one 5088 challenge that indicates the authentication scheme(s) and parameters 5089 applicable to the proxy for this request. A proxy MUST send at least 5090 one Proxy-Authenticate header field in each 407 (Proxy Authentication 5091 Required) response that it generates. 5093 Proxy-Authenticate = #challenge 5095 Unlike WWW-Authenticate, the Proxy-Authenticate header field applies 5096 only to the next outbound client on the response chain. This is 5097 because only the client that chose a given proxy is likely to have 5098 the credentials necessary for authentication. However, when multiple 5099 proxies are used within the same administrative domain, such as 5100 office and regional caching proxies within a large corporate network, 5101 it is common for credentials to be generated by the user agent and 5102 passed through the hierarchy until consumed. Hence, in such a 5103 configuration, it will appear as if Proxy-Authenticate is being 5104 forwarded because each proxy will send the same challenge set. 5106 Note that the parsing considerations for WWW-Authenticate apply to 5107 this header field as well; see Section 11.6.1 for details. 5109 11.7.2. Proxy-Authorization 5111 The "Proxy-Authorization" header field allows the client to identify 5112 itself (or its user) to a proxy that requires authentication. Its 5113 value consists of credentials containing the authentication 5114 information of the client for the proxy and/or realm of the resource 5115 being requested. 5117 Proxy-Authorization = credentials 5119 Unlike Authorization, the Proxy-Authorization header field applies 5120 only to the next inbound proxy that demanded authentication using the 5121 Proxy-Authenticate header field. When multiple proxies are used in a 5122 chain, the Proxy-Authorization header field is consumed by the first 5123 inbound proxy that was expecting to receive credentials. A proxy MAY 5124 relay the credentials from the client request to the next proxy if 5125 that is the mechanism by which the proxies cooperatively authenticate 5126 a given request. 5128 11.7.3. Proxy-Authentication-Info 5130 The Proxy-Authentication-Info response header field is equivalent to 5131 Authentication-Info, except that it applies to proxy authentication 5132 (Section 11.3) and its semantics are defined by the authentication 5133 scheme indicated by the Proxy-Authorization header field 5134 (Section 11.7.2) of the corresponding request: 5136 Proxy-Authentication-Info = #auth-param 5138 However, unlike Authentication-Info, the Proxy-Authentication-Info 5139 header field applies only to the next outbound client on the response 5140 chain. This is because only the client that chose a given proxy is 5141 likely to have the credentials necessary for authentication. 5142 However, when multiple proxies are used within the same 5143 administrative domain, such as office and regional caching proxies 5144 within a large corporate network, it is common for credentials to be 5145 generated by the user agent and passed through the hierarchy until 5146 consumed. Hence, in such a configuration, it will appear as if 5147 Proxy-Authentication-Info is being forwarded because each proxy will 5148 send the same field value. 5150 12. Content Negotiation 5152 When responses convey content, whether indicating a success or an 5153 error, the origin server often has different ways of representing 5154 that information; for example, in different formats, languages, or 5155 encodings. Likewise, different users or user agents might have 5156 differing capabilities, characteristics, or preferences that could 5157 influence which representation, among those available, would be best 5158 to deliver. For this reason, HTTP provides mechanisms for content 5159 negotiation. 5161 This specification defines three patterns of content negotiation that 5162 can be made visible within the protocol: "proactive" negotiation, 5163 where the server selects the representation based upon the user 5164 agent's stated preferences, "reactive" negotiation, where the server 5165 provides a list of representations for the user agent to choose from, 5166 and "request content" negotiation, where the user agent selects the 5167 representation for a future request based upon the server's stated 5168 preferences in past responses. 5170 Other patterns of content negotiation include "conditional content", 5171 where the representation consists of multiple parts that are 5172 selectively rendered based on user agent parameters, "active 5173 content", where the representation contains a script that makes 5174 additional (more specific) requests based on the user agent 5175 characteristics, and "Transparent Content Negotiation" ([RFC2295]), 5176 where content selection is performed by an intermediary. These 5177 patterns are not mutually exclusive, and each has trade-offs in 5178 applicability and practicality. 5180 Note that, in all cases, HTTP is not aware of the resource semantics. 5181 The consistency with which an origin server responds to requests, 5182 over time and over the varying dimensions of content negotiation, and 5183 thus the "sameness" of a resource's observed representations over 5184 time, is determined entirely by whatever entity or algorithm selects 5185 or generates those responses. 5187 12.1. Proactive Negotiation 5189 When content negotiation preferences are sent by the user agent in a 5190 request to encourage an algorithm located at the server to select the 5191 preferred representation, it is called _proactive negotiation_ 5192 (a.k.a., _server-driven negotiation_). Selection is based on the 5193 available representations for a response (the dimensions over which 5194 it might vary, such as language, content coding, etc.) compared to 5195 various information supplied in the request, including both the 5196 explicit negotiation header fields below and implicit 5197 characteristics, such as the client's network address or parts of the 5198 User-Agent field. 5200 Proactive negotiation is advantageous when the algorithm for 5201 selecting from among the available representations is difficult to 5202 describe to a user agent, or when the server desires to send its 5203 "best guess" to the user agent along with the first response (hoping 5204 to avoid the round trip delay of a subsequent request if the "best 5205 guess" is good enough for the user). In order to improve the 5206 server's guess, a user agent MAY send request header fields that 5207 describe its preferences. 5209 Proactive negotiation has serious disadvantages: 5211 * It is impossible for the server to accurately determine what might 5212 be "best" for any given user, since that would require complete 5213 knowledge of both the capabilities of the user agent and the 5214 intended use for the response (e.g., does the user want to view it 5215 on screen or print it on paper?); 5217 * Having the user agent describe its capabilities in every request 5218 can be both very inefficient (given that only a small percentage 5219 of responses have multiple representations) and a potential risk 5220 to the user's privacy; 5222 * It complicates the implementation of an origin server and the 5223 algorithms for generating responses to a request; and, 5225 * It limits the reusability of responses for shared caching. 5227 A user agent cannot rely on proactive negotiation preferences being 5228 consistently honored, since the origin server might not implement 5229 proactive negotiation for the requested resource or might decide that 5230 sending a response that doesn't conform to the user agent's 5231 preferences is better than sending a 406 (Not Acceptable) response. 5233 A Vary header field (Section 12.5.5) is often sent in a response 5234 subject to proactive negotiation to indicate what parts of the 5235 request information were used in the selection algorithm. 5237 The request header fields Accept, Accept-Charset, Accept-Encoding, 5238 and Accept-Language are defined below for a user agent to engage in 5239 proactive negotiation of the response content. The preferences sent 5240 in these fields apply to any content in the response, including 5241 representations of the target resource, representations of error or 5242 processing status, and potentially even the miscellaneous text 5243 strings that might appear within the protocol. 5245 12.2. Reactive Negotiation 5247 With _reactive negotiation_ (a.k.a., _agent-driven negotiation_), 5248 selection of content (regardless of the status code) is performed by 5249 the user agent after receiving an initial response. The mechanism 5250 for reactive negotiation might be as simple as a list of references 5251 to alternative representations. 5253 If the user agent is not satisfied by the initial response content, 5254 it can perform a GET request on one or more of the alternative 5255 resources to obtain a different representation. Selection of such 5256 alternatives might be performed automatically (by the user agent) or 5257 manually (e.g., by the user selecting from a hypertext menu). 5259 A server might choose not to send an initial representation, other 5260 than the list of alternatives, and thereby indicate that reactive 5261 negotiation by the user agent is preferred. For example, the 5262 alternatives listed in responses with the 300 (Multiple Choices) and 5263 406 (Not Acceptable) status codes include information about available 5264 representations so that the user or user agent can react by making a 5265 selection. 5267 Reactive negotiation is advantageous when the response would vary 5268 over commonly used dimensions (such as type, language, or encoding), 5269 when the origin server is unable to determine a user agent's 5270 capabilities from examining the request, and generally when public 5271 caches are used to distribute server load and reduce network usage. 5273 Reactive negotiation suffers from the disadvantages of transmitting a 5274 list of alternatives to the user agent, which degrades user-perceived 5275 latency if transmitted in the header section, and needing a second 5276 request to obtain an alternate representation. Furthermore, this 5277 specification does not define a mechanism for supporting automatic 5278 selection, though it does not prevent such a mechanism from being 5279 developed as an extension. 5281 12.3. Request Content Negotiation 5283 When content negotiation preferences are sent in a server's response, 5284 the listed preferences are called _request content negotiation_ 5285 because they intend to influence selection of an appropriate content 5286 for subsequent requests to that resource. For example, the Accept 5287 (Section 12.5.1) and Accept-Encoding (Section 12.5.3) header fields 5288 can be sent in a response to indicate preferred media types and 5289 content codings for subsequent requests to that resource. 5291 Similarly, Section 3.1 of [RFC5789] defines the "Accept-Patch" 5292 response header field which allows discovery of which content types 5293 are accepted in PATCH requests. 5295 12.4. Content Negotiation Field Features 5297 12.4.1. Absence 5299 For each of the content negotiation fields, a request that does not 5300 contain the field implies that the sender has no preference on that 5301 axis of negotiation. 5303 If a content negotiation header field is present in a request and 5304 none of the available representations for the response can be 5305 considered acceptable according to it, the origin server can either 5306 honor the header field by sending a 406 (Not Acceptable) response or 5307 disregard the header field by treating the response as if it is not 5308 subject to content negotiation for that request header field. This 5309 does not imply, however, that the client will be able to use the 5310 representation. 5312 | *Note:* Sending these header fields makes it easier for a 5313 | server to identify an individual by virtue of the user agent's 5314 | request characteristics (Section 17.13). 5316 12.4.2. Quality Values 5318 The content negotiation fields defined by this specification use a 5319 common parameter, named "q" (case-insensitive), to assign a relative 5320 "weight" to the preference for that associated kind of content. This 5321 weight is referred to as a "quality value" (or "qvalue") because the 5322 same parameter name is often used within server configurations to 5323 assign a weight to the relative quality of the various 5324 representations that can be selected for a resource. 5326 The weight is normalized to a real number in the range 0 through 1, 5327 where 0.001 is the least preferred and 1 is the most preferred; a 5328 value of 0 means "not acceptable". If no "q" parameter is present, 5329 the default weight is 1. 5331 weight = OWS ";" OWS "q=" qvalue 5332 qvalue = ( "0" [ "." 0*3DIGIT ] ) 5333 / ( "1" [ "." 0*3("0") ] ) 5335 A sender of qvalue MUST NOT generate more than three digits after the 5336 decimal point. User configuration of these values ought to be 5337 limited in the same fashion. 5339 12.4.3. Wildcard Values 5341 Most of these header fields, where indicated, define a wildcard value 5342 ("*") to select unspecified values. If no wildcard is present, 5343 values that are not explicitly mentioned in the field are considered 5344 unacceptable, except for within Vary where it means the variance is 5345 unlimited. 5347 | *Note:* In practice, using wildcards in content negotiation has 5348 | limited practical value, because it is seldom useful to say, 5349 | for example, "I prefer image/* more or less than (some other 5350 | specific value)". Clients can explicitly request a 406 (Not 5351 | Acceptable) response if a more preferred format is not 5352 | available by sending Accept: */*;q=0, but they still need to be 5353 | able to handle a different response, since the server is 5354 | allowed to ignore their preference. 5356 12.5. Content Negotiation Fields 5358 12.5.1. Accept 5360 The "Accept" header field can be used by user agents to specify their 5361 preferences regarding response media types. For example, Accept 5362 header fields can be used to indicate that the request is 5363 specifically limited to a small set of desired types, as in the case 5364 of a request for an in-line image. 5366 When sent by a server in a response, Accept provides information 5367 about what content types are preferred in the content of a subsequent 5368 request to the same resource. 5370 Accept = #( media-range [ weight ] ) 5372 media-range = ( "*/*" 5373 / ( type "/" "*" ) 5374 / ( type "/" subtype ) 5375 ) parameters 5377 The asterisk "*" character is used to group media types into ranges, 5378 with "*/*" indicating all media types and "type/*" indicating all 5379 subtypes of that type. The media-range can include media type 5380 parameters that are applicable to that range. 5382 Each media-range might be followed by optional applicable media type 5383 parameters (e.g., charset), followed by an optional "q" parameter for 5384 indicating a relative weight (Section 12.4.2). 5386 Previous specifications allowed additional extension parameters to 5387 appear after the weight parameter. The accept extension grammar 5388 (accept-ext) has been removed because it had a complicated 5389 definition, was not being used in practice, and is more easily 5390 deployed through new header fields. Senders using weights SHOULD 5391 send "q" last (after all media-range parameters). Recipients SHOULD 5392 process any parameter named "q" as weight, regardless of parameter 5393 ordering. 5395 | *Note:* Use of the "q" parameter name to control content 5396 | negotiation is due to historical practice. Although this 5397 | prevents any media type parameter named "q" from being used 5398 | with a media range, such an event is believed to be unlikely 5399 | given the lack of any "q" parameters in the IANA media type 5400 | registry and the rare usage of any media type parameters in 5401 | Accept. Future media types are discouraged from registering 5402 | any parameter named "q". 5404 The example 5406 Accept: audio/*; q=0.2, audio/basic 5408 is interpreted as "I prefer audio/basic, but send me any audio type 5409 if it is the best available after an 80% markdown in quality". 5411 A more elaborate example is 5413 Accept: text/plain; q=0.5, text/html, 5414 text/x-dvi; q=0.8, text/x-c 5416 Verbally, this would be interpreted as "text/html and text/x-c are 5417 the equally preferred media types, but if they do not exist, then 5418 send the text/x-dvi representation, and if that does not exist, send 5419 the text/plain representation". 5421 Media ranges can be overridden by more specific media ranges or 5422 specific media types. If more than one media range applies to a 5423 given type, the most specific reference has precedence. For example, 5425 Accept: text/*, text/plain, text/plain;format=flowed, */* 5427 have the following precedence: 5429 1. text/plain;format=flowed 5431 2. text/plain 5433 3. text/* 5435 4. */* 5437 The media type quality factor associated with a given type is 5438 determined by finding the media range with the highest precedence 5439 that matches the type. For example, 5441 Accept: text/*;q=0.3, text/plain;q=0.7, text/plain;format=flowed, 5442 text/plain;format=fixed;q=0.4, */*;q=0.5 5444 would cause the following values to be associated: 5446 +==========================+===============+ 5447 | Media Type | Quality Value | 5448 +==========================+===============+ 5449 | text/plain;format=flowed | 1 | 5450 +--------------------------+---------------+ 5451 | text/plain | 0.7 | 5452 +--------------------------+---------------+ 5453 | text/html | 0.3 | 5454 +--------------------------+---------------+ 5455 | image/jpeg | 0.5 | 5456 +--------------------------+---------------+ 5457 | text/plain;format=fixed | 0.4 | 5458 +--------------------------+---------------+ 5459 | text/html;level=3 | 0.7 | 5460 +--------------------------+---------------+ 5462 Table 5 5464 | *Note:* A user agent might be provided with a default set of 5465 | quality values for certain media ranges. However, unless the 5466 | user agent is a closed system that cannot interact with other 5467 | rendering agents, this default set ought to be configurable by 5468 | the user. 5470 12.5.2. Accept-Charset 5472 The "Accept-Charset" header field can be sent by a user agent to 5473 indicate its preferences for charsets in textual response content. 5474 For example, this field allows user agents capable of understanding 5475 more comprehensive or special-purpose charsets to signal that 5476 capability to an origin server that is capable of representing 5477 information in those charsets. 5479 Accept-Charset = #( ( token / "*" ) [ weight ] ) 5481 Charset names are defined in Section 8.3.2. A user agent MAY 5482 associate a quality value with each charset to indicate the user's 5483 relative preference for that charset, as defined in Section 12.4.2. 5484 An example is 5486 Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 5488 The special value "*", if present in the Accept-Charset header field, 5489 matches every charset that is not mentioned elsewhere in the field. 5491 | *Note:* Accept-Charset is deprecated because UTF-8 has become 5492 | nearly ubiquitous and sending a detailed list of user-preferred 5493 | charsets wastes bandwidth, increases latency, and makes passive 5494 | fingerprinting far too easy (Section 17.13). Most general- 5495 | purpose user agents do not send Accept-Charset, unless 5496 | specifically configured to do so. 5498 12.5.3. Accept-Encoding 5500 The "Accept-Encoding" header field can be used to indicate 5501 preferences regarding the use of content codings (Section 8.4.1). 5503 When sent by a user agent in a request, Accept-Encoding indicates the 5504 content codings acceptable in a response. 5506 When sent by a server in a response, Accept-Encoding provides 5507 information about what content codings are preferred in the content 5508 of a subsequent request to the same resource. 5510 An "identity" token is used as a synonym for "no encoding" in order 5511 to communicate when no encoding is preferred. 5513 Accept-Encoding = #( codings [ weight ] ) 5514 codings = content-coding / "identity" / "*" 5516 Each codings value MAY be given an associated quality value 5517 representing the preference for that encoding, as defined in 5518 Section 12.4.2. The asterisk "*" symbol in an Accept-Encoding field 5519 matches any available content coding not explicitly listed in the 5520 field. 5522 For example, 5524 Accept-Encoding: compress, gzip 5525 Accept-Encoding: 5526 Accept-Encoding: * 5527 Accept-Encoding: compress;q=0.5, gzip;q=1.0 5528 Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 5530 A server tests whether a content coding for a given representation is 5531 acceptable using these rules: 5533 1. If no Accept-Encoding header field is in the request, any content 5534 coding is considered acceptable by the user agent. 5536 2. If the representation has no content coding, then it is 5537 acceptable by default unless specifically excluded by the Accept- 5538 Encoding header field stating either "identity;q=0" or "*;q=0" 5539 without a more specific entry for "identity". 5541 3. If the representation's content coding is one of the content 5542 codings listed in the Accept-Encoding field value, then it is 5543 acceptable unless it is accompanied by a qvalue of 0. (As 5544 defined in Section 12.4.2, a qvalue of 0 means "not acceptable".) 5546 A representation could be encoded with multiple content codings. 5547 However, most content codings are alternative ways to accomplish the 5548 same purpose (e.g., data compression). When selecting between 5549 multiple content codings that have the same purpose, the acceptable 5550 content coding with the highest non-zero qvalue is preferred. 5552 An Accept-Encoding header field with a field value that is empty 5553 implies that the user agent does not want any content coding in 5554 response. If an Accept-Encoding header field is present in a request 5555 and none of the available representations for the response have a 5556 content coding that is listed as acceptable, the origin server SHOULD 5557 send a response without any content coding. 5559 When the Accept-Encoding header field is present in a response, it 5560 indicates what content codings the resource was willing to accept in 5561 the associated request. The field value is evaluated the same way as 5562 in a request. 5564 Note that this information is specific to the associated request; the 5565 set of supported encodings might be different for other resources on 5566 the same server and could change over time or depend on other aspects 5567 of the request (such as the request method). 5569 Servers that fail a request due to an unsupported content coding 5570 ought to respond with a 415 (Unsupported Media Type) status and 5571 include an Accept-Encoding header field in that response, allowing 5572 clients to distinguish between issues related to content codings and 5573 media types. In order to avoid confusion with issues related to 5574 media types, servers that fail a request with a 415 status for 5575 reasons unrelated to content codings MUST NOT include the Accept- 5576 Encoding header field. 5578 The most common use of Accept-Encoding is in responses with a 415 5579 (Unsupported Media Type) status code, in response to optimistic use 5580 of a content coding by clients. However, the header field can also 5581 be used to indicate to clients that content codings are supported, to 5582 optimize future interactions. For example, a resource might include 5583 it in a 2xx (Successful) response when the request content was big 5584 enough to justify use of a compression coding but the client failed 5585 do so. 5587 | *Note:* Most HTTP/1.0 applications do not recognize or obey 5588 | qvalues associated with content-codings. This means that 5589 | qvalues might not work and are not permitted with x-gzip or 5590 | x-compress. 5592 12.5.4. Accept-Language 5594 The "Accept-Language" header field can be used by user agents to 5595 indicate the set of natural languages that are preferred in the 5596 response. Language tags are defined in Section 8.5.1. 5598 Accept-Language = #( language-range [ weight ] ) 5599 language-range = 5600 5602 Each language-range can be given an associated quality value 5603 representing an estimate of the user's preference for the languages 5604 specified by that range, as defined in Section 12.4.2. For example, 5606 Accept-Language: da, en-gb;q=0.8, en;q=0.7 5607 would mean: "I prefer Danish, but will accept British English and 5608 other types of English". 5610 Note that some recipients treat the order in which language tags are 5611 listed as an indication of descending priority, particularly for tags 5612 that are assigned equal quality values (no value is the same as q=1). 5613 However, this behavior cannot be relied upon. For consistency and to 5614 maximize interoperability, many user agents assign each language tag 5615 a unique quality value while also listing them in order of decreasing 5616 quality. Additional discussion of language priority lists can be 5617 found in Section 2.3 of [RFC4647]. 5619 For matching, Section 3 of [RFC4647] defines several matching 5620 schemes. Implementations can offer the most appropriate matching 5621 scheme for their requirements. The "Basic Filtering" scheme 5622 ([RFC4647], Section 3.3.1) is identical to the matching scheme that 5623 was previously defined for HTTP in Section 14.4 of [RFC2616]. 5625 It might be contrary to the privacy expectations of the user to send 5626 an Accept-Language header field with the complete linguistic 5627 preferences of the user in every request (Section 17.13). 5629 Since intelligibility is highly dependent on the individual user, 5630 user agents need to allow user control over the linguistic preference 5631 (either through configuration of the user agent itself or by 5632 defaulting to a user controllable system setting). A user agent that 5633 does not provide such control to the user MUST NOT send an Accept- 5634 Language header field. 5636 | *Note:* User agents ought to provide guidance to users when 5637 | setting a preference, since users are rarely familiar with the 5638 | details of language matching as described above. For example, 5639 | users might assume that on selecting "en-gb", they will be 5640 | served any kind of English document if British English is not 5641 | available. A user agent might suggest, in such a case, to add 5642 | "en" to the list for better matching behavior. 5644 12.5.5. Vary 5646 The "Vary" header field in a response describes what parts of a 5647 request message, aside from the method and target URI, might 5648 influence the origin server's process for selecting and representing 5649 this response. 5651 Vary = #( "*" / field-name ) 5653 A Vary field value is a list of request field names, known as the 5654 selecting header fields, that might have a role in selecting the 5655 representation for this response. Potential selecting header fields 5656 are not limited to those defined by this specification. 5658 If the list contains "*", it signals that other aspects of the 5659 request might play a role in selecting the response representation, 5660 possibly including elements outside the message syntax (e.g., the 5661 client's network address). A recipient will not be able to determine 5662 whether this response is appropriate for a later request without 5663 forwarding the request to the origin server. A proxy MUST NOT 5664 generate "*" in a Vary field value. 5666 For example, a response that contains 5668 Vary: accept-encoding, accept-language 5670 indicates that the origin server might have used the request's 5671 Accept-Encoding and Accept-Language header fields (or lack thereof) 5672 as determining factors while choosing the content for this response. 5674 An origin server might send Vary with a list of header fields for two 5675 purposes: 5677 1. To inform cache recipients that they MUST NOT use this response 5678 to satisfy a later request unless the later request has the same 5679 values for the listed header fields as the original request 5680 (Section 4.1 of [Caching]). In other words, Vary expands the 5681 cache key required to match a new request to the stored cache 5682 entry. 5684 2. To inform user agent recipients that this response is subject to 5685 content negotiation (Section 12) and that a different 5686 representation might be sent in a subsequent request if 5687 additional parameters are provided in the listed header fields 5688 (proactive negotiation). 5690 An origin server SHOULD send a Vary header field when its algorithm 5691 for selecting a representation varies based on aspects of the request 5692 message other than the method and target URI, unless the variance 5693 cannot be crossed or the origin server has been deliberately 5694 configured to prevent cache transparency. For example, there is no 5695 need to send the Authorization field name in Vary because reuse 5696 across users is constrained by the field definition (Section 11.6.2). 5697 Likewise, an origin server might use Cache-Control response 5698 directives (Section 5.2 of [Caching]) to supplant Vary if it 5699 considers the variance less significant than the performance cost of 5700 Vary's impact on caching. 5702 13. Conditional Requests 5704 A conditional request is an HTTP request with one or more request 5705 header fields that indicate a precondition to be tested before 5706 applying the request method to the target resource. Section 13.2 5707 defines when to evaluate preconditions and their order of precedence 5708 when more than one precondition is present. 5710 Conditional GET requests are the most efficient mechanism for HTTP 5711 cache updates [Caching]. Conditionals can also be applied to state- 5712 changing methods, such as PUT and DELETE, to prevent the "lost 5713 update" problem: one client accidentally overwriting the work of 5714 another client that has been acting in parallel. 5716 13.1. Preconditions 5718 Preconditions are usually defined with respect to a state of the 5719 target resource as a whole (its current value set) or the state as 5720 observed in a previously obtained representation (one value in that 5721 set). If a resource has multiple current representations, each with 5722 its own observable state, a precondition will assume that the mapping 5723 of each request to a selected representation (Section 3.2) is 5724 consistent over time. Regardless, if the mapping is inconsistent or 5725 the server is unable to select an appropriate representation, then no 5726 harm will result when the precondition evaluates to false. 5728 Each precondition defined below consists of a comparison between a 5729 set of validators obtained from prior representations of the target 5730 resource to the current state of validators for the selected 5731 representation (Section 8.8). Hence, these preconditions evaluate 5732 whether the state of the target resource has changed since a given 5733 state known by the client. The effect of such an evaluation depends 5734 on the method semantics and choice of conditional, as defined in 5735 Section 13.2. 5737 Other preconditions, defined by other specifications as extension 5738 fields, might place conditions on all recipients, on the state of the 5739 target resource in general, or on a group of resources. For 5740 instance, the "If" header field in WebDAV can make a request 5741 conditional on various aspects of multiple resources, such as locks, 5742 if the recipient understands and implements that field ([RFC4918], 5743 Section 10.4). 5745 Extensibility of preconditions is only possible when the precondition 5746 can be safely ignored if unknown (like If-Modified-Since), when 5747 deployment can be assumed for a given use case, or when 5748 implementation is signaled by some other property of the target 5749 resource. This encourages a focus on mutually agreed deployment of 5750 common standards. 5752 13.1.1. If-Match 5754 The "If-Match" header field makes the request method conditional on 5755 the recipient origin server either having at least one current 5756 representation of the target resource, when the field value is "*", 5757 or having a current representation of the target resource that has an 5758 entity-tag matching a member of the list of entity-tags provided in 5759 the field value. 5761 An origin server MUST use the strong comparison function when 5762 comparing entity-tags for If-Match (Section 8.8.3.2), since the 5763 client intends this precondition to prevent the method from being 5764 applied if there have been any changes to the representation data. 5766 If-Match = "*" / #entity-tag 5768 Examples: 5770 If-Match: "xyzzy" 5771 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 5772 If-Match: * 5774 If-Match is most often used with state-changing methods (e.g., POST, 5775 PUT, DELETE) to prevent accidental overwrites when multiple user 5776 agents might be acting in parallel on the same resource (i.e., to 5777 prevent the "lost update" problem). It can also be used with any 5778 method to abort a request if the selected representation does not 5779 match one that the client has already stored (or partially stored) 5780 from a prior request. 5782 An origin server that receives an If-Match header field MUST evaluate 5783 the condition as per Section 13.2 prior to performing the method. 5785 To evaluate a received If-Match header field: 5787 1. If the field value is "*", the condition is true if the origin 5788 server has a current representation for the target resource. 5790 2. If the field value is a list of entity-tags, the condition is 5791 true if any of the listed tags match the entity-tag of the 5792 selected representation. 5794 3. Otherwise, the condition is false. 5796 An origin server MUST NOT perform the requested method if a received 5797 If-Match condition evaluates to false. Instead, the origin server 5798 MAY indicate that the conditional request failed by responding with a 5799 412 (Precondition Failed) status code. Alternatively, if the request 5800 is a state-changing operation that appears to have already been 5801 applied to the selected representation, the origin server MAY respond 5802 with a 2xx (Successful) status code (i.e., the change requested by 5803 the user agent has already succeeded, but the user agent might not be 5804 aware of it, perhaps because the prior response was lost or an 5805 equivalent change was made by some other user agent). 5807 Allowing an origin server to send a success response when a change 5808 request appears to have already been applied is more efficient for 5809 many authoring use cases, but comes with some risk if multiple user 5810 agents are making change requests that are very similar but not 5811 cooperative. For example, multiple user agents writing to a common 5812 resource as a semaphore (e.g., a non-atomic increment) are likely to 5813 collide and potentially lose important state transitions. For those 5814 kinds of resources, an origin server is better off being stringent in 5815 sending 412 for every failed precondition on an unsafe method. In 5816 other cases, excluding the ETag field from a success response might 5817 encourage the user agent to perform a GET as its next request to 5818 eliminate confusion about the resource's current state. 5820 The If-Match header field can be ignored by caches and intermediaries 5821 because it is not applicable to a stored response. 5823 Note that an If-Match header field with a list value containing "*" 5824 and other values (including other instances of "*") is unlikely to be 5825 interoperable. 5827 13.1.2. If-None-Match 5829 The "If-None-Match" header field makes the request method conditional 5830 on a recipient cache or origin server either not having any current 5831 representation of the target resource, when the field value is "*", 5832 or having a selected representation with an entity-tag that does not 5833 match any of those listed in the field value. 5835 A recipient MUST use the weak comparison function when comparing 5836 entity-tags for If-None-Match (Section 8.8.3.2), since weak entity- 5837 tags can be used for cache validation even if there have been changes 5838 to the representation data. 5840 If-None-Match = "*" / #entity-tag 5842 Examples: 5844 If-None-Match: "xyzzy" 5845 If-None-Match: W/"xyzzy" 5846 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 5847 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 5848 If-None-Match: * 5850 If-None-Match is primarily used in conditional GET requests to enable 5851 efficient updates of cached information with a minimum amount of 5852 transaction overhead. When a client desires to update one or more 5853 stored responses that have entity-tags, the client SHOULD generate an 5854 If-None-Match header field containing a list of those entity-tags 5855 when making a GET request; this allows recipient servers to send a 5856 304 (Not Modified) response to indicate when one of those stored 5857 responses matches the selected representation. 5859 If-None-Match can also be used with a value of "*" to prevent an 5860 unsafe request method (e.g., PUT) from inadvertently modifying an 5861 existing representation of the target resource when the client 5862 believes that the resource does not have a current representation 5863 (Section 9.2.1). This is a variation on the "lost update" problem 5864 that might arise if more than one client attempts to create an 5865 initial representation for the target resource. 5867 An origin server that receives an If-None-Match header field MUST 5868 evaluate the condition as per Section 13.2 prior to performing the 5869 method. 5871 To evaluate a received If-None-Match header field: 5873 1. If the field value is "*", the condition is false if the origin 5874 server has a current representation for the target resource. 5876 2. If the field value is a list of entity-tags, the condition is 5877 false if one of the listed tags matches the entity-tag of the 5878 selected representation. 5880 3. Otherwise, the condition is true. 5882 An origin server MUST NOT perform the requested method if a received 5883 If-None-Match condition evaluates to false; instead, the origin 5884 server MUST respond with either a) the 304 (Not Modified) status code 5885 if the request method is GET or HEAD or b) the 412 (Precondition 5886 Failed) status code for all other request methods. 5888 Requirements on cache handling of a received If-None-Match header 5889 field are defined in Section 4.3.2 of [Caching]. 5891 Note that an If-None-Match header field with a list value containing 5892 "*" and other values (including other instances of "*") is unlikely 5893 to be interoperable. 5895 13.1.3. If-Modified-Since 5897 The "If-Modified-Since" header field makes a GET or HEAD request 5898 method conditional on the selected representation's modification date 5899 being more recent than the date provided in the field value. 5900 Transfer of the selected representation's data is avoided if that 5901 data has not changed. 5903 If-Modified-Since = HTTP-date 5905 An example of the field is: 5907 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 5909 A recipient MUST ignore If-Modified-Since if the request contains an 5910 If-None-Match header field; the condition in If-None-Match is 5911 considered to be a more accurate replacement for the condition in If- 5912 Modified-Since, and the two are only combined for the sake of 5913 interoperating with older intermediaries that might not implement 5914 If-None-Match. 5916 A recipient MUST ignore the If-Modified-Since header field if the 5917 received field value is not a valid HTTP-date, the field value has 5918 more than one member, or if the request method is neither GET nor 5919 HEAD. 5921 A recipient MUST interpret an If-Modified-Since field value's 5922 timestamp in terms of the origin server's clock. 5924 If-Modified-Since is typically used for two distinct purposes: 1) to 5925 allow efficient updates of a cached representation that does not have 5926 an entity-tag and 2) to limit the scope of a web traversal to 5927 resources that have recently changed. 5929 When used for cache updates, a cache will typically use the value of 5930 the cached message's Last-Modified header field to generate the field 5931 value of If-Modified-Since. This behavior is most interoperable for 5932 cases where clocks are poorly synchronized or when the server has 5933 chosen to only honor exact timestamp matches (due to a problem with 5934 Last-Modified dates that appear to go "back in time" when the origin 5935 server's clock is corrected or a representation is restored from an 5936 archived backup). However, caches occasionally generate the field 5937 value based on other data, such as the Date header field of the 5938 cached message or the local clock time that the message was received, 5939 particularly when the cached message does not contain a Last-Modified 5940 header field. 5942 When used for limiting the scope of retrieval to a recent time 5943 window, a user agent will generate an If-Modified-Since field value 5944 based on either its own local clock or a Date header field received 5945 from the server in a prior response. Origin servers that choose an 5946 exact timestamp match based on the selected representation's 5947 Last-Modified header field will not be able to help the user agent 5948 limit its data transfers to only those changed during the specified 5949 window. 5951 An origin server that receives an If-Modified-Since header field 5952 SHOULD evaluate the condition as per Section 13.2 prior to performing 5953 the method. 5955 To evaluate a received If-Modified-Since header field: 5957 1. If the selected representation's last modification date is 5958 earlier or equal to the date provided in the field value, the 5959 condition is false. 5961 2. Otherwise, the condition is true. 5963 An origin server SHOULD NOT perform the requested method if a 5964 received If-Modified-Since condition evaluates to false; instead, the 5965 origin server SHOULD generate a 304 (Not Modified) response, 5966 including only those metadata that are useful for identifying or 5967 updating a previously cached response. 5969 Requirements on cache handling of a received If-Modified-Since header 5970 field are defined in Section 4.3.2 of [Caching]. 5972 13.1.4. If-Unmodified-Since 5974 The "If-Unmodified-Since" header field makes the request method 5975 conditional on the selected representation's last modification date 5976 being earlier than or equal to the date provided in the field value. 5977 This field accomplishes the same purpose as If-Match for cases where 5978 the user agent does not have an entity-tag for the representation. 5980 If-Unmodified-Since = HTTP-date 5982 An example of the field is: 5984 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 5986 A recipient MUST ignore If-Unmodified-Since if the request contains 5987 an If-Match header field; the condition in If-Match is considered to 5988 be a more accurate replacement for the condition in If-Unmodified- 5989 Since, and the two are only combined for the sake of interoperating 5990 with older intermediaries that might not implement If-Match. 5992 A recipient MUST ignore the If-Unmodified-Since header field if the 5993 received field value is not a valid HTTP-date (including when the 5994 field value appears to be a list of dates). 5996 A recipient MUST interpret an If-Unmodified-Since field value's 5997 timestamp in terms of the origin server's clock. 5999 If-Unmodified-Since is most often used with state-changing methods 6000 (e.g., POST, PUT, DELETE) to prevent accidental overwrites when 6001 multiple user agents might be acting in parallel on a resource that 6002 does not supply entity-tags with its representations (i.e., to 6003 prevent the "lost update" problem). It can also be used with any 6004 method to abort a request if the selected representation does not 6005 match one that the client already stored (or partially stored) from a 6006 prior request. 6008 An origin server that receives an If-Unmodified-Since header field 6009 without an If-Match header field MUST evaluate the condition as per 6010 Section 13.2 prior to performing the method. 6012 To evaluate a received If-Unmodified-Since header field: 6014 1. If the selected representation's last modification date is 6015 earlier than or equal to the date provided in the field value, 6016 the condition is true. 6018 2. Otherwise, the condition is false. 6020 An origin server MUST NOT perform the requested method if an If- 6021 Unmodified-Since condition evaluates to false. Instead, the origin 6022 server MAY indicate that the conditional request failed by responding 6023 with a 412 (Precondition Failed) status code. Alternatively, if the 6024 request is a state-changing operation that appears to have already 6025 been applied to the selected representation, the origin server MAY 6026 respond with a 2xx (Successful) status code (i.e., the change 6027 requested by the user agent has already succeeded, but the user agent 6028 might not be aware of it, perhaps because the prior response was lost 6029 or an equivalent change was made by some other user agent). 6031 Allowing an origin server to send a success response when a change 6032 request appears to have already been applied is more efficient for 6033 many authoring use cases, but comes with some risk if multiple user 6034 agents are making change requests that are very similar but not 6035 cooperative. In those cases, an origin server is better off being 6036 stringent in sending 412 for every failed precondition on an unsafe 6037 method. 6039 The If-Unmodified-Since header field can be ignored by caches and 6040 intermediaries because it is not applicable to a stored response. 6042 13.1.5. If-Range 6044 The "If-Range" header field provides a special conditional request 6045 mechanism that is similar to the If-Match and If-Unmodified-Since 6046 header fields but that instructs the recipient to ignore the Range 6047 header field if the validator doesn't match, resulting in transfer of 6048 the new selected representation instead of a 412 (Precondition 6049 Failed) response. 6051 If a client has a partial copy of a representation and wishes to have 6052 an up-to-date copy of the entire representation, it could use the 6053 Range header field with a conditional GET (using either or both of 6054 If-Unmodified-Since and If-Match.) However, if the precondition 6055 fails because the representation has been modified, the client would 6056 then have to make a second request to obtain the entire current 6057 representation. 6059 The "If-Range" header field allows a client to "short-circuit" the 6060 second request. Informally, its meaning is as follows: if the 6061 representation is unchanged, send me the part(s) that I am requesting 6062 in Range; otherwise, send me the entire representation. 6064 If-Range = entity-tag / HTTP-date 6066 A valid entity-tag can be distinguished from a valid HTTP-date by 6067 examining the first three characters for a DQUOTE. 6069 A client MUST NOT generate an If-Range header field in a request that 6070 does not contain a Range header field. A server MUST ignore an If- 6071 Range header field received in a request that does not contain a 6072 Range header field. An origin server MUST ignore an If-Range header 6073 field received in a request for a target resource that does not 6074 support Range requests. 6076 A client MUST NOT generate an If-Range header field containing an 6077 entity-tag that is marked as weak. A client MUST NOT generate an If- 6078 Range header field containing an HTTP-date unless the client has no 6079 entity-tag for the corresponding representation and the date is a 6080 strong validator in the sense defined by Section 8.8.2.2. 6082 A server that receives an If-Range header field on a Range request 6083 MUST evaluate the condition as per Section 13.2 prior to performing 6084 the method. 6086 To evaluate a received If-Range header field containing an HTTP-date: 6088 1. If the HTTP-date validator provided is not a strong validator in 6089 the sense defined by Section 8.8.2.2, the condition is false. 6091 2. If the HTTP-date validator provided exactly matches the 6092 Last-Modified field value for the selected representation, the 6093 condition is true. 6095 3. Otherwise, the condition is false. 6097 To evaluate a received If-Range header field containing an 6098 entity-tag: 6100 1. If the entity-tag validator provided exactly matches the ETag 6101 field value for the selected representation using the strong 6102 comparison function (Section 8.8.3.2), the condition is true. 6104 2. Otherwise, the condition is false. 6106 A recipient of an If-Range header field MUST ignore the Range header 6107 field if the If-Range condition evaluates to false. Otherwise, the 6108 recipient SHOULD process the Range header field as requested. 6110 Note that the If-Range comparison by exact match, including when the 6111 validator is an HTTP-date, differs from the "earlier than or equal 6112 to" comparison used when evaluating an If-Unmodified-Since 6113 conditional. 6115 13.2. Evaluation of Preconditions 6116 13.2.1. When to Evaluate 6118 Except when excluded below, a recipient cache or origin server MUST 6119 evaluate received request preconditions after it has successfully 6120 performed its normal request checks and just before it would process 6121 the request content (if any) or perform the action associated with 6122 the request method. A server MUST ignore all received preconditions 6123 if its response to the same request without those conditions, prior 6124 to processing the request content, would have been a status code 6125 other than a 2xx (Successful) or 412 (Precondition Failed). In other 6126 words, redirects and failures that can be detected before significant 6127 processing occurs take precedence over the evaluation of 6128 preconditions. 6130 A server that is not the origin server for the target resource and 6131 cannot act as a cache for requests on the target resource MUST NOT 6132 evaluate the conditional request header fields defined by this 6133 specification, and it MUST forward them if the request is forwarded, 6134 since the generating client intends that they be evaluated by a 6135 server that can provide a current representation. Likewise, a server 6136 MUST ignore the conditional request header fields defined by this 6137 specification when received with a request method that does not 6138 involve the selection or modification of a selected representation, 6139 such as CONNECT, OPTIONS, or TRACE. 6141 Note that protocol extensions can modify the conditions under which 6142 revalidation is triggered. For example, the "immutable" cache 6143 directive (defined by [RFC8246]) instructs caches to forgo 6144 revalidation of fresh responses even when requested by the client. 6146 Although conditional request header fields are defined as being 6147 usable with the HEAD method (to keep HEAD's semantics consistent with 6148 those of GET), there is no point in sending a conditional HEAD 6149 because a successful response is around the same size as a 304 (Not 6150 Modified) response and more useful than a 412 (Precondition Failed) 6151 response. 6153 13.2.2. Precedence of Preconditions 6155 When more than one conditional request header field is present in a 6156 request, the order in which the fields are evaluated becomes 6157 important. In practice, the fields defined in this document are 6158 consistently implemented in a single, logical order, since "lost 6159 update" preconditions have more strict requirements than cache 6160 validation, a validated cache is more efficient than a partial 6161 response, and entity tags are presumed to be more accurate than date 6162 validators. 6164 A recipient cache or origin server MUST evaluate the request 6165 preconditions defined by this specification in the following order: 6167 1. When recipient is the origin server and If-Match is present, 6168 evaluate the If-Match precondition: 6170 * if true, continue to step 3 6172 * if false, respond 412 (Precondition Failed) unless it can be 6173 determined that the state-changing request has already 6174 succeeded (see Section 13.1.1) 6176 2. When recipient is the origin server, If-Match is not present, and 6177 If-Unmodified-Since is present, evaluate the If-Unmodified-Since 6178 precondition: 6180 * if true, continue to step 3 6182 * if false, respond 412 (Precondition Failed) unless it can be 6183 determined that the state-changing request has already 6184 succeeded (see Section 13.1.4) 6186 3. When If-None-Match is present, evaluate the If-None-Match 6187 precondition: 6189 * if true, continue to step 5 6191 * if false for GET/HEAD, respond 304 (Not Modified) 6193 * if false for other methods, respond 412 (Precondition Failed) 6195 4. When the method is GET or HEAD, If-None-Match is not present, and 6196 If-Modified-Since is present, evaluate the If-Modified-Since 6197 precondition: 6199 * if true, continue to step 5 6201 * if false, respond 304 (Not Modified) 6203 5. When the method is GET and both Range and If-Range are present, 6204 evaluate the If-Range precondition: 6206 * if the validator matches and the Range specification is 6207 applicable to the selected representation, respond 206 6208 (Partial Content) 6210 6. Otherwise, 6211 * all conditions are met, so perform the requested action and 6212 respond according to its success or failure. 6214 Any extension to HTTP that defines additional conditional request 6215 header fields ought to define its own expectations regarding the 6216 order for evaluating such fields in relation to those defined in this 6217 document and other conditionals that might be found in practice. 6219 14. Range Requests 6221 Clients often encounter interrupted data transfers as a result of 6222 canceled requests or dropped connections. When a client has stored a 6223 partial representation, it is desirable to request the remainder of 6224 that representation in a subsequent request rather than transfer the 6225 entire representation. Likewise, devices with limited local storage 6226 might benefit from being able to request only a subset of a larger 6227 representation, such as a single page of a very large document, or 6228 the dimensions of an embedded image. 6230 Range requests are an OPTIONAL feature of HTTP, designed so that 6231 recipients not implementing this feature (or not supporting it for 6232 the target resource) can respond as if it is a normal GET request 6233 without impacting interoperability. Partial responses are indicated 6234 by a distinct status code to not be mistaken for full responses by 6235 caches that might not implement the feature. 6237 14.1. Range Units 6239 Representation data can be partitioned into subranges when there are 6240 addressable structural units inherent to that data's content coding 6241 or media type. For example, octet (a.k.a., byte) boundaries are a 6242 structural unit common to all representation data, allowing 6243 partitions of the data to be identified as a range of bytes at some 6244 offset from the start or end of that data. 6246 This general notion of a _range unit_ is used in the Accept-Ranges 6247 (Section 14.3) response header field to advertise support for range 6248 requests, the Range (Section 14.2) request header field to delineate 6249 the parts of a representation that are requested, and the 6250 Content-Range (Section 14.4) header field to describe which part of a 6251 representation is being transferred. 6253 range-unit = token 6255 All range unit names are case-insensitive and ought to be registered 6256 within the "HTTP Range Unit Registry", as defined in Section 16.5.1 6257 Range units are intended to be extensible, as described in 6258 Section 16.5. 6260 14.1.1. Range Specifiers 6262 Ranges are expressed in terms of a range unit paired with a set of 6263 range specifiers. The range unit name determines what kinds of 6264 range-spec are applicable to its own specifiers. Hence, the 6265 following gramar is generic: each range unit is expected to specify 6266 requirements on when int-range, suffix-range, and other-range are 6267 allowed. 6269 A range request can specify a single range or a set of ranges within 6270 a single representation. 6272 ranges-specifier = range-unit "=" range-set 6273 range-set = 1#range-spec 6274 range-spec = int-range 6275 / suffix-range 6276 / other-range 6278 An int-range is a range expressed as two non-negative integers or as 6279 one non-negative integer through to the end of the representation 6280 data. The range unit specifies what the integers mean (e.g., they 6281 might indicate unit offsets from the beginning, inclusive numbered 6282 parts, etc.). 6284 int-range = first-pos "-" [ last-pos ] 6285 first-pos = 1*DIGIT 6286 last-pos = 1*DIGIT 6288 An int-range is invalid if the last-pos value is present and less 6289 than the first-pos. 6291 A suffix-range is a range expressed as a suffix of the representation 6292 data with the provided non-negative integer maximum length (in range 6293 units). In other words, the last N units of the representation data. 6295 suffix-range = "-" suffix-length 6296 suffix-length = 1*DIGIT 6298 To provide for extensibility, the other-range rule is a mostly 6299 unconstrained grammar that allows application-specific or future 6300 range units to define additional range specifiers. 6302 other-range = 1*( %x21-2B / %x2D-7E ) 6303 ; 1*(VCHAR excluding comma) 6305 14.1.2. Byte Ranges 6307 The "bytes" range unit is used to express subranges of a 6308 representation data's octet sequence. Each byte range is expressed 6309 as an integer range at some offset, relative to either the beginning 6310 (int-range) or end (suffix-range) of the representation data. Byte 6311 ranges do not use the other-range specifier. 6313 The first-pos value in a bytes int-range gives the offset of the 6314 first byte in a range. The last-pos value gives the offset of the 6315 last byte in the range; that is, the byte positions specified are 6316 inclusive. Byte offsets start at zero. 6318 If the representation data has a content coding applied, each byte 6319 range is calculated with respect to the encoded sequence of bytes, 6320 not the sequence of underlying bytes that would be obtained after 6321 decoding. 6323 Examples of bytes range specifiers: 6325 * The first 500 bytes (byte offsets 0-499, inclusive): 6327 bytes=0-499 6329 * The second 500 bytes (byte offsets 500-999, inclusive): 6331 bytes=500-999 6333 A client can limit the number of bytes requested without knowing the 6334 size of the selected representation. If the last-pos value is 6335 absent, or if the value is greater than or equal to the current 6336 length of the representation data, the byte range is interpreted as 6337 the remainder of the representation (i.e., the server replaces the 6338 value of last-pos with a value that is one less than the current 6339 length of the selected representation). 6341 A client can request the last N bytes (N > 0) of the selected 6342 representation using a suffix-range. If the selected representation 6343 is shorter than the specified suffix-length, the entire 6344 representation is used. 6346 Additional examples, assuming a representation of length 10000: 6348 * The final 500 bytes (byte offsets 9500-9999, inclusive): 6350 bytes=-500 6352 Or: 6354 bytes=9500- 6356 * The first and last bytes only (bytes 0 and 9999): 6358 bytes=0-0,-1 6360 * The first, middle, and last 1000 bytes: 6362 bytes= 0-999, 4500-5499, -1000 6364 * Other valid (but not canonical) specifications of the second 500 6365 bytes (byte offsets 500-999, inclusive): 6367 bytes=500-600,601-999 6368 bytes=500-700,601-999 6370 If a valid bytes range-set includes at least one range-spec with a 6371 first-pos that is less than the current length of the representation, 6372 or at least one suffix-range with a non-zero suffix-length, then the 6373 bytes range-set is satisfiable. Otherwise, the bytes range-set is 6374 unsatisfiable. 6376 If the selected representation has zero length, the only satisfiable 6377 form of range-spec is a suffix-range with a non-zero suffix-length. 6379 In the byte-range syntax, first-pos, last-pos, and suffix-length are 6380 expressed as decimal number of octets. Since there is no predefined 6381 limit to the length of content, recipients MUST anticipate 6382 potentially large decimal numerals and prevent parsing errors due to 6383 integer conversion overflows. 6385 14.2. Range 6387 The "Range" header field on a GET request modifies the method 6388 semantics to request transfer of only one or more subranges of the 6389 selected representation data (Section 8.1), rather than the entire 6390 selected representation. 6392 Range = ranges-specifier 6394 A server MAY ignore the Range header field. However, origin servers 6395 and intermediate caches ought to support byte ranges when possible, 6396 since they support efficient recovery from partially failed transfers 6397 and partial retrieval of large representations. 6399 A server MUST ignore a Range header field received with a request 6400 method which is unrecognized or for which range handling is not 6401 defined. For this specification, GET is the only method for which 6402 range handling is defined. 6404 An origin server MUST ignore a Range header field that contains a 6405 range unit it does not understand. A proxy MAY discard a Range 6406 header field that contains a range unit it does not understand. 6408 A server that supports range requests MAY ignore or reject a Range 6409 header field that consists of more than two overlapping ranges, or a 6410 set of many small ranges that are not listed in ascending order, 6411 since both are indications of either a broken client or a deliberate 6412 denial-of-service attack (Section 17.15). A client SHOULD NOT 6413 request multiple ranges that are inherently less efficient to process 6414 and transfer than a single range that encompasses the same data. 6416 A server that supports range requests MAY ignore a Range header field 6417 when the selected representation has no content (i.e., the selected 6418 representation's data is of zero length). 6420 A client that is requesting multiple ranges SHOULD list those ranges 6421 in ascending order (the order in which they would typically be 6422 received in a complete representation) unless there is a specific 6423 need to request a later part earlier. For example, a user agent 6424 processing a large representation with an internal catalog of parts 6425 might need to request later parts first, particularly if the 6426 representation consists of pages stored in reverse order and the user 6427 agent wishes to transfer one page at a time. 6429 The Range header field is evaluated after evaluating the precondition 6430 header fields defined in Section 13.1, and only if the result in 6431 absence of the Range header field would be a 200 (OK) response. In 6432 other words, Range is ignored when a conditional GET would result in 6433 a 304 (Not Modified) response. 6435 The If-Range header field (Section 13.1.5) can be used as a 6436 precondition to applying the Range header field. 6438 If all of the preconditions are true, the server supports the Range 6439 header field for the target resource, and the specified range(s) are 6440 valid and satisfiable (as defined in Section 14.1.2), the server 6441 SHOULD send a 206 (Partial Content) response with a content 6442 containing one or more partial representations that correspond to the 6443 satisfiable ranges requested. 6445 The above does not imply that a server will send all requested 6446 ranges. In some cases, it may only be possible (or efficient) to 6447 send a portion of the requested ranges first, while expecting the 6448 client to re-request the remaining portions later if they are still 6449 desired (see Section 15.3.7). 6451 If all of the preconditions are true, the server supports the Range 6452 header field for the target resource, and the specified range(s) are 6453 invalid or unsatisfiable, the server SHOULD send a 416 (Range Not 6454 Satisfiable) response. 6456 14.3. Accept-Ranges 6458 The "Accept-Ranges" header field allows a server to indicate that it 6459 supports range requests for the target resource. 6461 Accept-Ranges = acceptable-ranges 6462 acceptable-ranges = 1#range-unit / "none" 6464 An origin server that supports byte-range requests for a given target 6465 resource MAY send 6467 Accept-Ranges: bytes 6469 to indicate what range units are supported. A client MAY generate 6470 range requests without having received this header field for the 6471 resource involved. Range units are defined in Section 14.1. 6473 A server that does not support any kind of range request for the 6474 target resource MAY send 6476 Accept-Ranges: none 6478 to advise the client not to attempt a range request. 6480 14.4. Content-Range 6482 The "Content-Range" header field is sent in a single part 206 6483 (Partial Content) response to indicate the partial range of the 6484 selected representation enclosed as the message content, sent in each 6485 part of a multipart 206 response to indicate the range enclosed 6486 within each body part, and sent in 416 (Range Not Satisfiable) 6487 responses to provide information about the selected representation. 6489 Content-Range = range-unit SP 6490 ( range-resp / unsatisfied-range ) 6492 range-resp = incl-range "/" ( complete-length / "*" ) 6493 incl-range = first-pos "-" last-pos 6494 unsatisfied-range = "*/" complete-length 6496 complete-length = 1*DIGIT 6498 If a 206 (Partial Content) response contains a Content-Range header 6499 field with a range unit (Section 14.1) that the recipient does not 6500 understand, the recipient MUST NOT attempt to recombine it with a 6501 stored representation. A proxy that receives such a message SHOULD 6502 forward it downstream. 6504 Content-Range might also be sent as a request modifier to request a 6505 partial PUT, as described in Section 14.5, based on private 6506 agreements between client and origin server. A server MUST ignore a 6507 Content-Range header field received in a request with a method for 6508 which Content-Range support is not defined. 6510 For byte ranges, a sender SHOULD indicate the complete length of the 6511 representation from which the range has been extracted, unless the 6512 complete length is unknown or difficult to determine. An asterisk 6513 character ("*") in place of the complete-length indicates that the 6514 representation length was unknown when the header field was 6515 generated. 6517 The following example illustrates when the complete length of the 6518 selected representation is known by the sender to be 1234 bytes: 6520 Content-Range: bytes 42-1233/1234 6522 and this second example illustrates when the complete length is 6523 unknown: 6525 Content-Range: bytes 42-1233/* 6527 A Content-Range field value is invalid if it contains a range-resp 6528 that has a last-pos value less than its first-pos value, or a 6529 complete-length value less than or equal to its last-pos value. The 6530 recipient of an invalid Content-Range MUST NOT attempt to recombine 6531 the received content with a stored representation. 6533 A server generating a 416 (Range Not Satisfiable) response to a byte- 6534 range request SHOULD send a Content-Range header field with an 6535 unsatisfied-range value, as in the following example: 6537 Content-Range: bytes */1234 6539 The complete-length in a 416 response indicates the current length of 6540 the selected representation. 6542 The Content-Range header field has no meaning for status codes that 6543 do not explicitly describe its semantic. For this specification, 6544 only the 206 (Partial Content) and 416 (Range Not Satisfiable) status 6545 codes describe a meaning for Content-Range. 6547 The following are examples of Content-Range values in which the 6548 selected representation contains a total of 1234 bytes: 6550 * The first 500 bytes: 6552 Content-Range: bytes 0-499/1234 6554 * The second 500 bytes: 6556 Content-Range: bytes 500-999/1234 6558 * All except for the first 500 bytes: 6560 Content-Range: bytes 500-1233/1234 6562 * The last 500 bytes: 6564 Content-Range: bytes 734-1233/1234 6566 14.5. Partial PUT 6568 Some origin servers support PUT of a partial representation when the 6569 user agent sends a Content-Range header field (Section 14.4) in the 6570 request, though such support is inconsistent and depends on private 6571 agreements with user agents. In general, it requests that the state 6572 of the target resource be partly replaced with the enclosed content 6573 at an offset and length indicated by the Content-Range value, where 6574 the offset is relative to the current selected representation. 6576 An origin server SHOULD respond with a 400 (Bad Request) status code 6577 if it receives Content-Range on a PUT for a target resource that does 6578 not support partial PUT requests. 6580 Partial PUT is not backwards compatible with the original definition 6581 of PUT. It may result in the content being written as a complete 6582 replacement for the current representation. 6584 Partial resource updates are also possible by targeting a separately 6585 identified resource with state that overlaps or extends a portion of 6586 the larger resource, or by using a different method that has been 6587 specifically defined for partial updates (for example, the PATCH 6588 method defined in [RFC5789]). 6590 14.6. Media Type multipart/byteranges 6592 When a 206 (Partial Content) response message includes the content of 6593 multiple ranges, they are transmitted as body parts in a multipart 6594 message body ([RFC2046], Section 5.1) with the media type of 6595 "multipart/byteranges". 6597 The multipart/byteranges media type includes one or more body parts, 6598 each with its own Content-Type and Content-Range fields. The 6599 required boundary parameter specifies the boundary string used to 6600 separate each body part. 6602 Implementation Notes: 6604 1. Additional CRLFs might precede the first boundary string in the 6605 body. 6607 2. Although [RFC2046] permits the boundary string to be quoted, some 6608 existing implementations handle a quoted boundary string 6609 incorrectly. 6611 3. A number of clients and servers were coded to an early draft of 6612 the byteranges specification that used a media type of multipart/ 6613 x-byteranges , which is almost (but not quite) compatible with 6614 this type. 6616 Despite the name, the "multipart/byteranges" media type is not 6617 limited to byte ranges. The following example uses an "exampleunit" 6618 range unit: 6620 HTTP/1.1 206 Partial Content 6621 Date: Tue, 14 Nov 1995 06:25:24 GMT 6622 Last-Modified: Tue, 14 July 04:58:08 GMT 6623 Content-Length: 2331785 6624 Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 6626 --THIS_STRING_SEPARATES 6627 Content-Type: video/example 6628 Content-Range: exampleunit 1.2-4.3/25 6630 ...the first range... 6631 --THIS_STRING_SEPARATES 6632 Content-Type: video/example 6633 Content-Range: exampleunit 11.2-14.3/25 6635 ...the second range 6636 --THIS_STRING_SEPARATES-- 6638 The following information serves as the registration form for the 6639 multipart/byteranges media type. 6641 Type name: multipart 6643 Subtype name: byteranges 6645 Required parameters: boundary 6647 Optional parameters: N/A 6649 Encoding considerations: only "7bit", "8bit", or "binary" are 6650 permitted 6652 Security considerations: see Section 17 6654 Interoperability considerations: N/A 6656 Published specification: This specification (see Section 14.6). 6658 Applications that use this media type: HTTP components supporting 6659 multiple ranges in a single request. 6661 Fragment identifier considerations: N/A 6663 Additional information: Deprecated alias names for this type: N/A 6665 Magic number(s): N/A 6667 File extension(s): N/A 6668 Macintosh file type code(s): N/A 6670 Person and email address to contact for further information: See Aut 6671 hors' Addresses section. 6673 Intended usage: COMMON 6675 Restrictions on usage: N/A 6677 Author: See Authors' Addresses section. 6679 Change controller: IESG 6681 15. Status Codes 6683 The status code of a response is a three-digit integer code that 6684 describes the result of the request and the semantics of the 6685 response, including whether the request was successful and what 6686 content is enclosed (if any). All valid status codes are within the 6687 range of 100 to 599, inclusive. 6689 The first digit of the status code defines the class of response. 6690 The last two digits do not have any categorization role. There are 6691 five values for the first digit: 6693 * 1xx (Informational): The request was received, continuing process 6695 * 2xx (Successful): The request was successfully received, 6696 understood, and accepted 6698 * 3xx (Redirection): Further action needs to be taken in order to 6699 complete the request 6701 * 4xx (Client Error): The request contains bad syntax or cannot be 6702 fulfilled 6704 * 5xx (Server Error): The server failed to fulfill an apparently 6705 valid request 6707 HTTP status codes are extensible. A client is not required to 6708 understand the meaning of all registered status codes, though such 6709 understanding is obviously desirable. However, a client MUST 6710 understand the class of any status code, as indicated by the first 6711 digit, and treat an unrecognized status code as being equivalent to 6712 the x00 status code of that class. 6714 For example, if a client receives an unrecognized status code of 471, 6715 it can see from the first digit that there was something wrong with 6716 its request and treat the response as if it had received a 400 (Bad 6717 Request) status code. The response message will usually contain a 6718 representation that explains the status. 6720 Values outside the range 100..599 are invalid. Implementations often 6721 use three-digit integer values outside of that range (i.e., 600..999) 6722 for internal communication of non-HTTP status (e.g., library errors). 6723 A client that receives a response with an invalid status code SHOULD 6724 process the response as if it had a 5xx (Server Error) status code. 6726 A single request can have multiple associated responses: zero or more 6727 _interim_ (non-final) responses with status codes in the 6728 "informational" (1xx) range, followed by exactly one _final_ response 6729 with a status code in one of the other ranges. 6731 15.1. Overview of Status Codes 6733 The status codes listed below are defined in this specification. The 6734 reason phrases listed here are only recommendations - they can be 6735 replaced by local equivalents or left out altogether without 6736 affecting the protocol. 6738 Responses with status codes that are defined as heuristically 6739 cacheable (e.g., 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 6740 414, and 501 in this specification) can be reused by a cache with 6741 heuristic expiration unless otherwise indicated by the method 6742 definition or explicit cache controls [Caching]; all other status 6743 codes are not heuristically cacheable. 6745 Additional status codes, outside the scope of this specification, 6746 have been specified for use in HTTP. All such status codes ought to 6747 be registered within the "Hypertext Transfer Protocol (HTTP) Status 6748 Code Registry", as described in Section 16.2. 6750 15.2. Informational 1xx 6752 The _1xx (Informational)_ class of status code indicates an interim 6753 response for communicating connection status or request progress 6754 prior to completing the requested action and sending a final 6755 response. Since HTTP/1.0 did not define any 1xx status codes, a 6756 server MUST NOT send a 1xx response to an HTTP/1.0 client. 6758 A 1xx response is terminated by the end of the header section; it 6759 cannot contain content or trailers. 6761 A client MUST be able to parse one or more 1xx responses received 6762 prior to a final response, even if the client does not expect one. A 6763 user agent MAY ignore unexpected 1xx responses. 6765 A proxy MUST forward 1xx responses unless the proxy itself requested 6766 the generation of the 1xx response. For example, if a proxy adds an 6767 "Expect: 100-continue" header field when it forwards a request, then 6768 it need not forward the corresponding 100 (Continue) response(s). 6770 15.2.1. 100 Continue 6772 The _100 (Continue)_ status code indicates that the initial part of a 6773 request has been received and has not yet been rejected by the 6774 server. The server intends to send a final response after the 6775 request has been fully received and acted upon. 6777 When the request contains an Expect header field that includes a 6778 100-continue expectation, the 100 response indicates that the server 6779 wishes to receive the request content, as described in 6780 Section 10.1.1. The client ought to continue sending the request and 6781 discard the 100 response. 6783 If the request did not contain an Expect header field containing the 6784 100-continue expectation, the client can simply discard this interim 6785 response. 6787 15.2.2. 101 Switching Protocols 6789 The _101 (Switching Protocols)_ status code indicates that the server 6790 understands and is willing to comply with the client's request, via 6791 the Upgrade header field (Section 7.8), for a change in the 6792 application protocol being used on this connection. The server MUST 6793 generate an Upgrade header field in the response that indicates which 6794 protocol(s) will be in effect after this response. 6796 It is assumed that the server will only agree to switch protocols 6797 when it is advantageous to do so. For example, switching to a newer 6798 version of HTTP might be advantageous over older versions, and 6799 switching to a real-time, synchronous protocol might be advantageous 6800 when delivering resources that use such features. 6802 15.3. Successful 2xx 6804 The _2xx (Successful)_ class of status code indicates that the 6805 client's request was successfully received, understood, and accepted. 6807 15.3.1. 200 OK 6809 The _200 (OK)_ status code indicates that the request has succeeded. 6810 The content sent in a 200 response depends on the request method. 6811 For the methods defined by this specification, the intended meaning 6812 of the content can be summarized as: 6814 +================+============================================+ 6815 | request method | response content is a representation of | 6816 +================+============================================+ 6817 | GET | the target resource | 6818 +----------------+--------------------------------------------+ 6819 | HEAD | the target resource, like GET, but without | 6820 | | transferring the representation data | 6821 +----------------+--------------------------------------------+ 6822 | POST | the status of, or results obtained from, | 6823 | | the action | 6824 +----------------+--------------------------------------------+ 6825 | PUT, DELETE | the status of the action | 6826 +----------------+--------------------------------------------+ 6827 | OPTIONS | communication options for the target | 6828 | | resource | 6829 +----------------+--------------------------------------------+ 6830 | TRACE | the request message as received by the | 6831 | | server returning the trace | 6832 +----------------+--------------------------------------------+ 6834 Table 6 6836 Aside from responses to CONNECT, a 200 response always has content, 6837 though an origin server MAY generate content of zero length. If no 6838 content is desired, an origin server ought to send _204 (No Content)_ 6839 instead. For CONNECT, no content is allowed because the successful 6840 result is a tunnel, which begins immediately after the 200 response 6841 header section. 6843 A 200 response is heuristically cacheable; i.e., unless otherwise 6844 indicated by the method definition or explicit cache controls (see 6845 Section 4.2.2 of [Caching]). 6847 15.3.2. 201 Created 6849 The _201 (Created)_ status code indicates that the request has been 6850 fulfilled and has resulted in one or more new resources being 6851 created. The primary resource created by the request is identified 6852 by either a Location header field in the response or, if no Location 6853 header field is received, by the target URI. 6855 The 201 response content typically describes and links to the 6856 resource(s) created. See Section 8.8 for a discussion of the meaning 6857 and purpose of validator fields, such as ETag and Last-Modified, in a 6858 201 response. 6860 15.3.3. 202 Accepted 6862 The _202 (Accepted)_ status code indicates that the request has been 6863 accepted for processing, but the processing has not been completed. 6864 The request might or might not eventually be acted upon, as it might 6865 be disallowed when processing actually takes place. There is no 6866 facility in HTTP for re-sending a status code from an asynchronous 6867 operation. 6869 The 202 response is intentionally noncommittal. Its purpose is to 6870 allow a server to accept a request for some other process (perhaps a 6871 batch-oriented process that is only run once per day) without 6872 requiring that the user agent's connection to the server persist 6873 until the process is completed. The representation sent with this 6874 response ought to describe the request's current status and point to 6875 (or embed) a status monitor that can provide the user with an 6876 estimate of when the request will be fulfilled. 6878 15.3.4. 203 Non-Authoritative Information 6880 The _203 (Non-Authoritative Information)_ status code indicates that 6881 the request was successful but the enclosed content has been modified 6882 from that of the origin server's 200 (OK) response by a transforming 6883 proxy (Section 7.7). This status code allows the proxy to notify 6884 recipients when a transformation has been applied, since that 6885 knowledge might impact later decisions regarding the content. For 6886 example, future cache validation requests for the content might only 6887 be applicable along the same request path (through the same proxies). 6889 A 203 response is heuristically cacheable; i.e., unless otherwise 6890 indicated by the method definition or explicit cache controls (see 6891 Section 4.2.2 of [Caching]). 6893 15.3.5. 204 No Content 6895 The _204 (No Content)_ status code indicates that the server has 6896 successfully fulfilled the request and that there is no additional 6897 content to send in the response content. Metadata in the response 6898 header fields refer to the target resource and its selected 6899 representation after the requested action was applied. 6901 For example, if a 204 status code is received in response to a PUT 6902 request and the response contains an ETag field, then the PUT was 6903 successful and the ETag field value contains the entity-tag for the 6904 new representation of that target resource. 6906 The 204 response allows a server to indicate that the action has been 6907 successfully applied to the target resource, while implying that the 6908 user agent does not need to traverse away from its current "document 6909 view" (if any). The server assumes that the user agent will provide 6910 some indication of the success to its user, in accord with its own 6911 interface, and apply any new or updated metadata in the response to 6912 its active representation. 6914 For example, a 204 status code is commonly used with document editing 6915 interfaces corresponding to a "save" action, such that the document 6916 being saved remains available to the user for editing. It is also 6917 frequently used with interfaces that expect automated data transfers 6918 to be prevalent, such as within distributed version control systems. 6920 A 204 response is terminated by the end of the header section; it 6921 cannot contain content or trailers. 6923 A 204 response is heuristically cacheable; i.e., unless otherwise 6924 indicated by the method definition or explicit cache controls (see 6925 Section 4.2.2 of [Caching]). 6927 15.3.6. 205 Reset Content 6929 The _205 (Reset Content)_ status code indicates that the server has 6930 fulfilled the request and desires that the user agent reset the 6931 "document view", which caused the request to be sent, to its original 6932 state as received from the origin server. 6934 This response is intended to support a common data entry use case 6935 where the user receives content that supports data entry (a form, 6936 notepad, canvas, etc.), enters or manipulates data in that space, 6937 causes the entered data to be submitted in a request, and then the 6938 data entry mechanism is reset for the next entry so that the user can 6939 easily initiate another input action. 6941 Since the 205 status code implies that no additional content will be 6942 provided, a server MUST NOT generate content in a 205 response. 6944 15.3.7. 206 Partial Content 6946 The _206 (Partial Content)_ status code indicates that the server is 6947 successfully fulfilling a range request for the target resource by 6948 transferring one or more parts of the selected representation. 6950 A server that supports range requests (Section 14) will usually 6951 attempt to satisfy all of the requested ranges, since sending less 6952 data will likely result in another client request for the remainder. 6953 However, a server might want to send only a subset of the data 6954 requested for reasons of its own, such as temporary unavailability, 6955 cache efficiency, load balancing, etc. Since a 206 response is self- 6956 descriptive, the client can still understand a response that only 6957 partially satisfies its range request. 6959 A client MUST inspect a 206 response's Content-Type and Content-Range 6960 field(s) to determine what parts are enclosed and whether additional 6961 requests are needed. 6963 A server that generates a 206 response MUST generate the following 6964 header fields, in addition to those required in the subsections 6965 below, if the field would have been sent in a 200 (OK) response to 6966 the same request: Date, Cache-Control, ETag, Expires, 6967 Content-Location, and Vary. 6969 A Content-Length header field present in a 206 response indicates the 6970 number of octets in the content of this message, which is usually not 6971 the complete length of the selected representation. Each 6972 Content-Range header field includes information about the selected 6973 representation's complete length. 6975 A sender that generates a 206 response with an If-Range header field 6976 SHOULD NOT generate other representation header fields beyond those 6977 required, because the client already has a prior response containing 6978 those header fields. Otherwise, a sender MUST generate all of the 6979 representation header fields that would have been sent in a 200 (OK) 6980 response to the same request. 6982 A 206 response is heuristically cacheable; i.e., unless otherwise 6983 indicated by explicit cache controls (see Section 4.2.2 of 6984 [Caching]). 6986 15.3.7.1. Single Part 6988 If a single part is being transferred, the server generating the 206 6989 response MUST generate a Content-Range header field, describing what 6990 range of the selected representation is enclosed, and a content 6991 consisting of the range. For example: 6993 HTTP/1.1 206 Partial Content 6994 Date: Wed, 15 Nov 1995 06:25:24 GMT 6995 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 6996 Content-Range: bytes 21010-47021/47022 6997 Content-Length: 26012 6998 Content-Type: image/gif 7000 ... 26012 bytes of partial image data ... 7002 15.3.7.2. Multiple Parts 7004 If multiple parts are being transferred, the server generating the 7005 206 response MUST generate "multipart/byteranges" content, as defined 7006 in Section 14.6, and a Content-Type header field containing the 7007 multipart/byteranges media type and its required boundary parameter. 7008 To avoid confusion with single-part responses, a server MUST NOT 7009 generate a Content-Range header field in the HTTP header section of a 7010 multiple part response (this field will be sent in each part 7011 instead). 7013 Within the header area of each body part in the multipart content, 7014 the server MUST generate a Content-Range header field corresponding 7015 to the range being enclosed in that body part. If the selected 7016 representation would have had a Content-Type header field in a 200 7017 (OK) response, the server SHOULD generate that same Content-Type 7018 header field in the header area of each body part. For example: 7020 HTTP/1.1 206 Partial Content 7021 Date: Wed, 15 Nov 1995 06:25:24 GMT 7022 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 7023 Content-Length: 1741 7024 Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 7026 --THIS_STRING_SEPARATES 7027 Content-Type: application/pdf 7028 Content-Range: bytes 500-999/8000 7030 ...the first range... 7031 --THIS_STRING_SEPARATES 7032 Content-Type: application/pdf 7033 Content-Range: bytes 7000-7999/8000 7035 ...the second range 7036 --THIS_STRING_SEPARATES-- 7038 When multiple ranges are requested, a server MAY coalesce any of the 7039 ranges that overlap, or that are separated by a gap that is smaller 7040 than the overhead of sending multiple parts, regardless of the order 7041 in which the corresponding range-spec appeared in the received Range 7042 header field. Since the typical overhead between each part of a 7043 multipart/byteranges is around 80 bytes, depending on the selected 7044 representation's media type and the chosen boundary parameter length, 7045 it can be less efficient to transfer many small disjoint parts than 7046 it is to transfer the entire selected representation. 7048 A server MUST NOT generate a multipart response to a request for a 7049 single range, since a client that does not request multiple parts 7050 might not support multipart responses. However, a server MAY 7051 generate a multipart/byteranges response with only a single body part 7052 if multiple ranges were requested and only one range was found to be 7053 satisfiable or only one range remained after coalescing. A client 7054 that cannot process a multipart/byteranges response MUST NOT generate 7055 a request that asks for multiple ranges. 7057 A server that generates a multipart response SHOULD send the parts in 7058 the same order that the corresponding range-spec appeared in the 7059 received Range header field, excluding those ranges that were deemed 7060 unsatisfiable or that were coalesced into other ranges. A client 7061 that receives a multipart response MUST inspect the Content-Range 7062 header field present in each body part in order to determine which 7063 range is contained in that body part; a client cannot rely on 7064 receiving the same ranges that it requested, nor the same order that 7065 it requested. 7067 15.3.7.3. Combining Parts 7069 A response might transfer only a subrange of a representation if the 7070 connection closed prematurely or if the request used one or more 7071 Range specifications. After several such transfers, a client might 7072 have received several ranges of the same representation. These 7073 ranges can only be safely combined if they all have in common the 7074 same strong validator (Section 8.8.1). 7076 A client that has received multiple partial responses to GET requests 7077 on a target resource MAY combine those responses into a larger 7078 continuous range if they share the same strong validator. 7080 If the most recent response is an incomplete 200 (OK) response, then 7081 the header fields of that response are used for any combined response 7082 and replace those of the matching stored responses. 7084 If the most recent response is a 206 (Partial Content) response and 7085 at least one of the matching stored responses is a 200 (OK), then the 7086 combined response header fields consist of the most recent 200 7087 response's header fields. If all of the matching stored responses 7088 are 206 responses, then the stored response with the most recent 7089 header fields is used as the source of header fields for the combined 7090 response, except that the client MUST use other header fields 7091 provided in the new response, aside from Content-Range, to replace 7092 all instances of the corresponding header fields in the stored 7093 response. 7095 The combined response content consists of the union of partial 7096 content ranges in the new response and each of the selected 7097 responses. If the union consists of the entire range of the 7098 representation, then the client MUST process the combined response as 7099 if it were a complete 200 (OK) response, including a Content-Length 7100 header field that reflects the complete length. Otherwise, the 7101 client MUST process the set of continuous ranges as one of the 7102 following: an incomplete 200 (OK) response if the combined response 7103 is a prefix of the representation, a single 206 (Partial Content) 7104 response containing multipart/byteranges content, or multiple 206 7105 (Partial Content) responses, each with one continuous range that is 7106 indicated by a Content-Range header field. 7108 15.4. Redirection 3xx 7110 The _3xx (Redirection)_ class of status code indicates that further 7111 action needs to be taken by the user agent in order to fulfill the 7112 request. There are several types of redirects: 7114 1. Redirects that indicate this resource might be available at a 7115 different URI, as provided by the Location header field, as in 7116 the status codes 301 (Moved Permanently), 302 (Found), 307 7117 (Temporary Redirect), and 308 (Permanent Redirect). 7119 2. Redirection that offers a choice among matching resources capable 7120 of representing this resource, as in the 300 (Multiple Choices) 7121 status code. 7123 3. Redirection to a different resource, identified by the Location 7124 header field, that can represent an indirect response to the 7125 request, as in the 303 (See Other) status code. 7127 4. Redirection to a previously stored result, as in the 304 (Not 7128 Modified) status code. 7130 If a Location header field (Section 10.2.3) is provided, the user 7131 agent MAY automatically redirect its request to the URI referenced by 7132 the Location field value, even if the specific status code is not 7133 understood. Automatic redirection needs to be done with care for 7134 methods not known to be safe, as defined in Section 9.2.1, since the 7135 user might not wish to redirect an unsafe request. 7137 When automatically following a redirected request, the user agent 7138 SHOULD resend the original request message with the following 7139 modifications: 7141 1. Replace the target URI with the URI referenced by the redirection 7142 response's Location header field value after resolving it 7143 relative to the original request's target URI. 7145 2. Remove header fields that were automatically generated by the 7146 implementation, replacing them with updated values as appropriate 7147 to the new request. This includes: 7149 1. Connection-specific header fields (see Section 7.6.1), 7151 2. Header fields specific to the client's proxy configuration, 7152 including (but not limited to) Proxy-Authorization, 7154 3. Origin-specific header fields (if any), including (but not 7155 limited to) Host, 7157 4. Validating header fields that were added by the 7158 implementation's cache (e.g., If-None-Match, 7159 If-Modified-Since), 7161 5. Resource-specific header fields, including (but not limited 7162 to) Referer, Origin, Authorization, and Cookie. 7164 3. Consider removing header fields that were not automatically 7165 generated by the implementation (i.e., those present in the 7166 request because they were added by the calling context) where 7167 there are security implications; this includes but is not limited 7168 to Authorization and Cookie. 7170 4. Change the request method according to the redirecting status 7171 code's semantics, if applicable. 7173 5. If the request method has been changed to GET or HEAD, remove 7174 content-specific header fields, including (but not limited to) 7175 Content-Encoding, Content-Language, Content-Location, 7176 Content-Type, Content-Length, Digest, ETag, Last-Modified. 7178 | *Note:* In HTTP/1.0, the status codes 301 (Moved Permanently) 7179 | and 302 (Found) were defined for the first type of redirect 7180 | ([RFC1945], Section 9.3). Early user agents split on whether 7181 | the method applied to the redirect target would be the same as 7182 | the original request or would be rewritten as GET. Although 7183 | HTTP originally defined the former semantics for 301 and 302 7184 | (to match its original implementation at CERN), and defined 303 7185 | (See Other) to match the latter semantics, prevailing practice 7186 | gradually converged on the latter semantics for 301 and 302 as 7187 | well. The first revision of HTTP/1.1 added 307 (Temporary 7188 | Redirect) to indicate the former semantics of 302 without being 7189 | impacted by divergent practice. For the same reason, 308 7190 | (Permanent Redirect) was later on added in [RFC7538] to match 7191 | 301. Over 10 years later, most user agents still do method 7192 | rewriting for 301 and 302; therefore, [RFC7231] made that 7193 | behavior conformant when the original request is POST. 7195 A client SHOULD detect and intervene in cyclical redirections (i.e., 7196 "infinite" redirection loops). 7198 | *Note:* An earlier version of this specification recommended a 7199 | maximum of five redirections ([RFC2068], Section 10.3). 7200 | Content developers need to be aware that some clients might 7201 | implement such a fixed limitation. 7203 15.4.1. 300 Multiple Choices 7205 The _300 (Multiple Choices)_ status code indicates that the target 7206 resource has more than one representation, each with its own more 7207 specific identifier, and information about the alternatives is being 7208 provided so that the user (or user agent) can select a preferred 7209 representation by redirecting its request to one or more of those 7210 identifiers. In other words, the server desires that the user agent 7211 engage in reactive negotiation to select the most appropriate 7212 representation(s) for its needs (Section 12). 7214 If the server has a preferred choice, the server SHOULD generate a 7215 Location header field containing a preferred choice's URI reference. 7216 The user agent MAY use the Location field value for automatic 7217 redirection. 7219 For request methods other than HEAD, the server SHOULD generate 7220 content in the 300 response containing a list of representation 7221 metadata and URI reference(s) from which the user or user agent can 7222 choose the one most preferred. The user agent MAY make a selection 7223 from that list automatically if it understands the provided media 7224 type. A specific format for automatic selection is not defined by 7225 this specification because HTTP tries to remain orthogonal to the 7226 definition of its content. In practice, the representation is 7227 provided in some easily parsed format believed to be acceptable to 7228 the user agent, as determined by shared design or content 7229 negotiation, or in some commonly accepted hypertext format. 7231 A 300 response is heuristically cacheable; i.e., unless otherwise 7232 indicated by the method definition or explicit cache controls (see 7233 Section 4.2.2 of [Caching]). 7235 | *Note:* The original proposal for the 300 status code defined 7236 | the URI header field as providing a list of alternative 7237 | representations, such that it would be usable for 200, 300, and 7238 | 406 responses and be transferred in responses to the HEAD 7239 | method. However, lack of deployment and disagreement over 7240 | syntax led to both URI and Alternates (a subsequent proposal) 7241 | being dropped from this specification. It is possible to 7242 | communicate the list as a Link header field value [RFC8288] 7243 | whose members have a relationship of "alternate", though 7244 | deployment is a chicken-and-egg problem. 7246 15.4.2. 301 Moved Permanently 7248 The _301 (Moved Permanently)_ status code indicates that the target 7249 resource has been assigned a new permanent URI and any future 7250 references to this resource ought to use one of the enclosed URIs. 7251 Clients with link-editing capabilities ought to automatically re-link 7252 references to the target URI to one or more of the new references 7253 sent by the server, where possible. 7255 The server SHOULD generate a Location header field in the response 7256 containing a preferred URI reference for the new permanent URI. The 7257 user agent MAY use the Location field value for automatic 7258 redirection. The server's response content usually contains a short 7259 hypertext note with a hyperlink to the new URI(s). 7261 | *Note:* For historical reasons, a user agent MAY change the 7262 | request method from POST to GET for the subsequent request. If 7263 | this behavior is undesired, the 308 (Permanent Redirect) status 7264 | code can be used instead. 7266 A 301 response is heuristically cacheable; i.e., unless otherwise 7267 indicated by the method definition or explicit cache controls (see 7268 Section 4.2.2 of [Caching]). 7270 15.4.3. 302 Found 7272 The _302 (Found)_ status code indicates that the target resource 7273 resides temporarily under a different URI. Since the redirection 7274 might be altered on occasion, the client ought to continue to use the 7275 target URI for future requests. 7277 The server SHOULD generate a Location header field in the response 7278 containing a URI reference for the different URI. The user agent MAY 7279 use the Location field value for automatic redirection. The server's 7280 response content usually contains a short hypertext note with a 7281 hyperlink to the different URI(s). 7283 | *Note:* For historical reasons, a user agent MAY change the 7284 | request method from POST to GET for the subsequent request. If 7285 | this behavior is undesired, the 307 (Temporary Redirect) status 7286 | code can be used instead. 7288 15.4.4. 303 See Other 7290 The _303 (See Other)_ status code indicates that the server is 7291 redirecting the user agent to a different resource, as indicated by a 7292 URI in the Location header field, which is intended to provide an 7293 indirect response to the original request. A user agent can perform 7294 a retrieval request targeting that URI (a GET or HEAD request if 7295 using HTTP), which might also be redirected, and present the eventual 7296 result as an answer to the original request. Note that the new URI 7297 in the Location header field is not considered equivalent to the 7298 target URI. 7300 This status code is applicable to any HTTP method. It is primarily 7301 used to allow the output of a POST action to redirect the user agent 7302 to a selected resource, since doing so provides the information 7303 corresponding to the POST response in a form that can be separately 7304 identified, bookmarked, and cached, independent of the original 7305 request. 7307 A 303 response to a GET request indicates that the origin server does 7308 not have a representation of the target resource that can be 7309 transferred by the server over HTTP. However, the Location field 7310 value refers to a resource that is descriptive of the target 7311 resource, such that making a retrieval request on that other resource 7312 might result in a representation that is useful to recipients without 7313 implying that it represents the original target resource. Note that 7314 answers to the questions of what can be represented, what 7315 representations are adequate, and what might be a useful description 7316 are outside the scope of HTTP. 7318 Except for responses to a HEAD request, the representation of a 303 7319 response ought to contain a short hypertext note with a hyperlink to 7320 the same URI reference provided in the Location header field. 7322 15.4.5. 304 Not Modified 7324 The _304 (Not Modified)_ status code indicates that a conditional GET 7325 or HEAD request has been received and would have resulted in a 200 7326 (OK) response if it were not for the fact that the condition 7327 evaluated to false. In other words, there is no need for the server 7328 to transfer a representation of the target resource because the 7329 request indicates that the client, which made the request 7330 conditional, already has a valid representation; the server is 7331 therefore redirecting the client to make use of that stored 7332 representation as if it were the content of a 200 (OK) response. 7334 The server generating a 304 response MUST generate any of the 7335 following header fields that would have been sent in a 200 (OK) 7336 response to the same request: Cache-Control, Content-Location, Date, 7337 ETag, Expires, and Vary. 7339 Since the goal of a 304 response is to minimize information transfer 7340 when the recipient already has one or more cached representations, a 7341 sender SHOULD NOT generate representation metadata other than the 7342 above listed fields unless said metadata exists for the purpose of 7343 guiding cache updates (e.g., Last-Modified might be useful if the 7344 response does not have an ETag field). 7346 Requirements on a cache that receives a 304 response are defined in 7347 Section 4.3.4 of [Caching]. If the conditional request originated 7348 with an outbound client, such as a user agent with its own cache 7349 sending a conditional GET to a shared proxy, then the proxy SHOULD 7350 forward the 304 response to that client. 7352 A 304 response is terminated by the end of the header section; it 7353 cannot contain content or trailers. 7355 15.4.6. 305 Use Proxy 7357 The _305 (Use Proxy)_ status code was defined in a previous version 7358 of this specification and is now deprecated (Appendix B of 7359 [RFC7231]). 7361 15.4.7. 306 (Unused) 7363 The 306 status code was defined in a previous version of this 7364 specification, is no longer used, and the code is reserved. 7366 15.4.8. 307 Temporary Redirect 7368 The _307 (Temporary Redirect)_ status code indicates that the target 7369 resource resides temporarily under a different URI and the user agent 7370 MUST NOT change the request method if it performs an automatic 7371 redirection to that URI. Since the redirection can change over time, 7372 the client ought to continue using the original target URI for future 7373 requests. 7375 The server SHOULD generate a Location header field in the response 7376 containing a URI reference for the different URI. The user agent MAY 7377 use the Location field value for automatic redirection. The server's 7378 response content usually contains a short hypertext note with a 7379 hyperlink to the different URI(s). 7381 15.4.9. 308 Permanent Redirect 7383 The _308 (Permanent Redirect)_ status code indicates that the target 7384 resource has been assigned a new permanent URI and any future 7385 references to this resource ought to use one of the enclosed URIs. 7386 Clients with link editing capabilities ought to automatically re-link 7387 references to the target URI to one or more of the new references 7388 sent by the server, where possible. 7390 The server SHOULD generate a Location header field in the response 7391 containing a preferred URI reference for the new permanent URI. The 7392 user agent MAY use the Location field value for automatic 7393 redirection. The server's response content usually contains a short 7394 hypertext note with a hyperlink to the new URI(s). 7396 A 308 response is heuristically cacheable; i.e., unless otherwise 7397 indicated by the method definition or explicit cache controls (see 7398 Section 4.2.2 of [Caching]). 7400 | *Note:* This status code is much younger (June 2014) than its 7401 | sibling codes, and thus might not be recognized everywhere. 7402 | See Section 4 of [RFC7538] for deployment considerations. 7404 15.5. Client Error 4xx 7406 The _4xx (Client Error)_ class of status code indicates that the 7407 client seems to have erred. Except when responding to a HEAD 7408 request, the server SHOULD send a representation containing an 7409 explanation of the error situation, and whether it is a temporary or 7410 permanent condition. These status codes are applicable to any 7411 request method. User agents SHOULD display any included 7412 representation to the user. 7414 15.5.1. 400 Bad Request 7416 The _400 (Bad Request)_ status code indicates that the server cannot 7417 or will not process the request due to something that is perceived to 7418 be a client error (e.g., malformed request syntax, invalid request 7419 message framing, or deceptive request routing). 7421 15.5.2. 401 Unauthorized 7423 The _401 (Unauthorized)_ status code indicates that the request has 7424 not been applied because it lacks valid authentication credentials 7425 for the target resource. The server generating a 401 response MUST 7426 send a WWW-Authenticate header field (Section 11.6.1) containing at 7427 least one challenge applicable to the target resource. 7429 If the request included authentication credentials, then the 401 7430 response indicates that authorization has been refused for those 7431 credentials. The user agent MAY repeat the request with a new or 7432 replaced Authorization header field (Section 11.6.2). If the 401 7433 response contains the same challenge as the prior response, and the 7434 user agent has already attempted authentication at least once, then 7435 the user agent SHOULD present the enclosed representation to the 7436 user, since it usually contains relevant diagnostic information. 7438 15.5.3. 402 Payment Required 7440 The _402 (Payment Required)_ status code is reserved for future use. 7442 15.5.4. 403 Forbidden 7444 The _403 (Forbidden)_ status code indicates that the server 7445 understood the request but refuses to fulfill it. A server that 7446 wishes to make public why the request has been forbidden can describe 7447 that reason in the response content (if any). 7449 If authentication credentials were provided in the request, the 7450 server considers them insufficient to grant access. The client 7451 SHOULD NOT automatically repeat the request with the same 7452 credentials. The client MAY repeat the request with new or different 7453 credentials. However, a request might be forbidden for reasons 7454 unrelated to the credentials. 7456 An origin server that wishes to "hide" the current existence of a 7457 forbidden target resource MAY instead respond with a status code of 7458 404 (Not Found). 7460 15.5.5. 404 Not Found 7462 The _404 (Not Found)_ status code indicates that the origin server 7463 did not find a current representation for the target resource or is 7464 not willing to disclose that one exists. A 404 status code does not 7465 indicate whether this lack of representation is temporary or 7466 permanent; the 410 (Gone) status code is preferred over 404 if the 7467 origin server knows, presumably through some configurable means, that 7468 the condition is likely to be permanent. 7470 A 404 response is heuristically cacheable; i.e., unless otherwise 7471 indicated by the method definition or explicit cache controls (see 7472 Section 4.2.2 of [Caching]). 7474 15.5.6. 405 Method Not Allowed 7476 The _405 (Method Not Allowed)_ status code indicates that the method 7477 received in the request-line is known by the origin server but not 7478 supported by the target resource. The origin server MUST generate an 7479 Allow header field in a 405 response containing a list of the target 7480 resource's currently supported methods. 7482 A 405 response is heuristically cacheable; i.e., unless otherwise 7483 indicated by the method definition or explicit cache controls (see 7484 Section 4.2.2 of [Caching]). 7486 15.5.7. 406 Not Acceptable 7488 The _406 (Not Acceptable)_ status code indicates that the target 7489 resource does not have a current representation that would be 7490 acceptable to the user agent, according to the proactive negotiation 7491 header fields received in the request (Section 12.1), and the server 7492 is unwilling to supply a default representation. 7494 The server SHOULD generate content containing a list of available 7495 representation characteristics and corresponding resource identifiers 7496 from which the user or user agent can choose the one most 7497 appropriate. A user agent MAY automatically select the most 7498 appropriate choice from that list. However, this specification does 7499 not define any standard for such automatic selection, as described in 7500 Section 15.4.1. 7502 15.5.8. 407 Proxy Authentication Required 7504 The _407 (Proxy Authentication Required)_ status code is similar to 7505 401 (Unauthorized), but it indicates that the client needs to 7506 authenticate itself in order to use a proxy for this request. The 7507 proxy MUST send a Proxy-Authenticate header field (Section 11.7.1) 7508 containing a challenge applicable to that proxy for the request. The 7509 client MAY repeat the request with a new or replaced 7510 Proxy-Authorization header field (Section 11.7.2). 7512 15.5.9. 408 Request Timeout 7514 The _408 (Request Timeout)_ status code indicates that the server did 7515 not receive a complete request message within the time that it was 7516 prepared to wait. 7518 If the client has an outstanding request in transit, it MAY repeat 7519 that request. If the current connection is not usable (e.g., as it 7520 would be in HTTP/1.1, because request delimitation is lost), a new 7521 connection will be used. 7523 15.5.10. 409 Conflict 7525 The _409 (Conflict)_ status code indicates that the request could not 7526 be completed due to a conflict with the current state of the target 7527 resource. This code is used in situations where the user might be 7528 able to resolve the conflict and resubmit the request. The server 7529 SHOULD generate content that includes enough information for a user 7530 to recognize the source of the conflict. 7532 Conflicts are most likely to occur in response to a PUT request. For 7533 example, if versioning were being used and the representation being 7534 PUT included changes to a resource that conflict with those made by 7535 an earlier (third-party) request, the origin server might use a 409 7536 response to indicate that it can't complete the request. In this 7537 case, the response representation would likely contain information 7538 useful for merging the differences based on the revision history. 7540 15.5.11. 410 Gone 7542 The _410 (Gone)_ status code indicates that access to the target 7543 resource is no longer available at the origin server and that this 7544 condition is likely to be permanent. If the origin server does not 7545 know, or has no facility to determine, whether or not the condition 7546 is permanent, the status code 404 (Not Found) ought to be used 7547 instead. 7549 The 410 response is primarily intended to assist the task of web 7550 maintenance by notifying the recipient that the resource is 7551 intentionally unavailable and that the server owners desire that 7552 remote links to that resource be removed. Such an event is common 7553 for limited-time, promotional services and for resources belonging to 7554 individuals no longer associated with the origin server's site. It 7555 is not necessary to mark all permanently unavailable resources as 7556 "gone" or to keep the mark for any length of time - that is left to 7557 the discretion of the server owner. 7559 A 410 response is heuristically cacheable; i.e., unless otherwise 7560 indicated by the method definition or explicit cache controls (see 7561 Section 4.2.2 of [Caching]). 7563 15.5.12. 411 Length Required 7565 The _411 (Length Required)_ status code indicates that the server 7566 refuses to accept the request without a defined Content-Length 7567 (Section 8.6). The client MAY repeat the request if it adds a valid 7568 Content-Length header field containing the length of the request 7569 content. 7571 15.5.13. 412 Precondition Failed 7573 The _412 (Precondition Failed)_ status code indicates that one or 7574 more conditions given in the request header fields evaluated to false 7575 when tested on the server (Section 13). This response status code 7576 allows the client to place preconditions on the current resource 7577 state (its current representations and metadata) and, thus, prevent 7578 the request method from being applied if the target resource is in an 7579 unexpected state. 7581 15.5.14. 413 Content Too Large 7583 The _413 (Content Too Large)_ status code indicates that the server 7584 is refusing to process a request because the request content is 7585 larger than the server is willing or able to process. The server MAY 7586 terminate the request, if the protocol version in use allows it; 7587 otherwise, the server MAY close the connection. 7589 If the condition is temporary, the server SHOULD generate a 7590 Retry-After header field to indicate that it is temporary and after 7591 what time the client MAY try again. 7593 15.5.15. 414 URI Too Long 7595 The _414 (URI Too Long)_ status code indicates that the server is 7596 refusing to service the request because the target URI is longer than 7597 the server is willing to interpret. This rare condition is only 7598 likely to occur when a client has improperly converted a POST request 7599 to a GET request with long query information, when the client has 7600 descended into a "black hole" of redirection (e.g., a redirected URI 7601 prefix that points to a suffix of itself) or when the server is under 7602 attack by a client attempting to exploit potential security holes. 7604 A 414 response is heuristically cacheable; i.e., unless otherwise 7605 indicated by the method definition or explicit cache controls (see 7606 Section 4.2.2 of [Caching]). 7608 15.5.16. 415 Unsupported Media Type 7610 The _415 (Unsupported Media Type)_ status code indicates that the 7611 origin server is refusing to service the request because the content 7612 is in a format not supported by this method on the target resource. 7614 The format problem might be due to the request's indicated 7615 Content-Type or Content-Encoding, or as a result of inspecting the 7616 data directly. 7618 If the problem was caused by an unsupported content coding, the 7619 Accept-Encoding response header field (Section 12.5.3) ought to be 7620 used to indicate what (if any) content codings would have been 7621 accepted in the request. 7623 On the other hand, if the cause was an unsupported media type, the 7624 Accept response header field (Section 12.5.1) can be used to indicate 7625 what media types would have been accepted in the request. 7627 15.5.17. 416 Range Not Satisfiable 7629 The _416 (Range Not Satisfiable)_ status code indicates that the set 7630 of ranges in the request's Range header field (Section 14.2) has been 7631 rejected either because none of the requested ranges are satisfiable 7632 or because the client has requested an excessive number of small or 7633 overlapping ranges (a potential denial of service attack). 7635 Each range unit defines what is required for its own range sets to be 7636 satisfiable. For example, Section 14.1.2 defines what makes a bytes 7637 range set satisfiable. 7639 A server that generates a 416 response to a byte-range request SHOULD 7640 generate a Content-Range header field specifying the current length 7641 of the selected representation (Section 14.4). 7643 For example: 7645 HTTP/1.1 416 Range Not Satisfiable 7646 Date: Fri, 20 Jan 2012 15:41:54 GMT 7647 Content-Range: bytes */47022 7649 | *Note:* Because servers are free to ignore Range, many 7650 | implementations will respond with the entire selected 7651 | representation in a 200 (OK) response. That is partly because 7652 | most clients are prepared to receive a 200 (OK) to complete the 7653 | task (albeit less efficiently) and partly because clients might 7654 | not stop making an invalid range request until they have 7655 | received a complete representation. Thus, clients cannot 7656 | depend on receiving a 416 (Range Not Satisfiable) response even 7657 | when it is most appropriate. 7659 15.5.18. 417 Expectation Failed 7661 The _417 (Expectation Failed)_ status code indicates that the 7662 expectation given in the request's Expect header field 7663 (Section 10.1.1) could not be met by at least one of the inbound 7664 servers. 7666 15.5.19. 418 (Unused) 7668 [RFC2324] was an April 1 RFC that lampooned the various ways HTTP was 7669 abused; one such abuse was the definition of an application-specific 7670 418 status code. In the intervening years, this status code has been 7671 widely implemented as an "Easter Egg", and therefore is effectively 7672 consumed by this use. 7674 Therefore, the 418 status code is reserved in the IANA HTTP Status 7675 Code Registry. This indicates that the status code cannot be 7676 assigned to other applications currently. If future circumstances 7677 require its use (e.g., exhaustion of 4NN status codes), it can be re- 7678 assigned to another use. 7680 15.5.20. 421 Misdirected Request 7682 The 421 (Misdirected Request) status code indicates that the request 7683 was directed at a server that is unable or unwilling to produce an 7684 authoritative response for the target URI. An origin server (or 7685 gateway acting on behalf of the origin server) sends 421 to reject a 7686 target URI that does not match an origin for which the server has 7687 been configured (Section 4.3.1) or does not match the connection 7688 context over which the request was received (Section 7.4). 7690 A client that receives a 421 (Misdirected Request) response MAY retry 7691 the request, whether or not the request method is idempotent, over a 7692 different connection, such as a fresh connection specific to the 7693 target resource's origin, or via an alternative service [RFC7838]. 7695 A proxy MUST NOT generate a 421 response. 7697 15.5.21. 422 Unprocessable Content 7699 The 422 (Unprocessable Content) status code indicates that the server 7700 understands the content type of the request content (hence a 415 7701 (Unsupported Media Type) status code is inappropriate), and the 7702 syntax of the request content is correct, but was unable to process 7703 the contained instructions. For example, this status code can be 7704 sent if an XML request content contains well-formed (i.e., 7705 syntactically correct), but semantically erroneous XML instructions. 7707 15.5.22. 426 Upgrade Required 7709 The _426 (Upgrade Required)_ status code indicates that the server 7710 refuses to perform the request using the current protocol but might 7711 be willing to do so after the client upgrades to a different 7712 protocol. The server MUST send an Upgrade header field in a 426 7713 response to indicate the required protocol(s) (Section 7.8). 7715 Example: 7717 HTTP/1.1 426 Upgrade Required 7718 Upgrade: HTTP/3.0 7719 Connection: Upgrade 7720 Content-Length: 53 7721 Content-Type: text/plain 7723 This service requires use of the HTTP/3.0 protocol. 7725 15.6. Server Error 5xx 7727 The _5xx (Server Error)_ class of status code indicates that the 7728 server is aware that it has erred or is incapable of performing the 7729 requested method. Except when responding to a HEAD request, the 7730 server SHOULD send a representation containing an explanation of the 7731 error situation, and whether it is a temporary or permanent 7732 condition. A user agent SHOULD display any included representation 7733 to the user. These response codes are applicable to any request 7734 method. 7736 15.6.1. 500 Internal Server Error 7738 The _500 (Internal Server Error)_ status code indicates that the 7739 server encountered an unexpected condition that prevented it from 7740 fulfilling the request. 7742 15.6.2. 501 Not Implemented 7744 The _501 (Not Implemented)_ status code indicates that the server 7745 does not support the functionality required to fulfill the request. 7746 This is the appropriate response when the server does not recognize 7747 the request method and is not capable of supporting it for any 7748 resource. 7750 A 501 response is heuristically cacheable; i.e., unless otherwise 7751 indicated by the method definition or explicit cache controls (see 7752 Section 4.2.2 of [Caching]). 7754 15.6.3. 502 Bad Gateway 7756 The _502 (Bad Gateway)_ status code indicates that the server, while 7757 acting as a gateway or proxy, received an invalid response from an 7758 inbound server it accessed while attempting to fulfill the request. 7760 15.6.4. 503 Service Unavailable 7762 The _503 (Service Unavailable)_ status code indicates that the server 7763 is currently unable to handle the request due to a temporary overload 7764 or scheduled maintenance, which will likely be alleviated after some 7765 delay. The server MAY send a Retry-After header field 7766 (Section 10.2.4) to suggest an appropriate amount of time for the 7767 client to wait before retrying the request. 7769 | *Note:* The existence of the 503 status code does not imply 7770 | that a server has to use it when becoming overloaded. Some 7771 | servers might simply refuse the connection. 7773 15.6.5. 504 Gateway Timeout 7775 The _504 (Gateway Timeout)_ status code indicates that the server, 7776 while acting as a gateway or proxy, did not receive a timely response 7777 from an upstream server it needed to access in order to complete the 7778 request. 7780 15.6.6. 505 HTTP Version Not Supported 7782 The _505 (HTTP Version Not Supported)_ status code indicates that the 7783 server does not support, or refuses to support, the major version of 7784 HTTP that was used in the request message. The server is indicating 7785 that it is unable or unwilling to complete the request using the same 7786 major version as the client, as described in Section 2.5, other than 7787 with this error message. The server SHOULD generate a representation 7788 for the 505 response that describes why that version is not supported 7789 and what other protocols are supported by that server. 7791 16. Extending HTTP 7793 HTTP defines a number of generic extension points that can be used to 7794 introduce capabilities to the protocol without introducing a new 7795 version, including methods, status codes, field names, and further 7796 extensibility points within defined fields, such as authentication 7797 schemes and cache-directives (see Cache-Control extensions in 7798 Section 5.2.3 of [Caching]). Because the semantics of HTTP are not 7799 versioned, these extension points are persistent; the version of the 7800 protocol in use does not affect their semantics. 7802 Version-independent extensions are discouraged from depending on or 7803 interacting with the specific version of the protocol in use. When 7804 this is unavoidable, careful consideration needs to be given to how 7805 the extension can interoperate across versions. 7807 Additionally, specific versions of HTTP might have their own 7808 extensibility points, such as transfer-codings in HTTP/1.1 7809 (Section 6.1 of [Messaging]) and HTTP/2 ([RFC7540]) SETTINGS or frame 7810 types. These extension points are specific to the version of the 7811 protocol they occur within. 7813 Version-specific extensions cannot override or modify the semantics 7814 of a version-independent mechanism or extension point (like a method 7815 or header field) without explicitly being allowed by that protocol 7816 element. For example, the CONNECT method (Section 9.3.6) allows 7817 this. 7819 These guidelines assure that the protocol operates correctly and 7820 predictably, even when parts of the path implement different versions 7821 of HTTP. 7823 16.1. Method Extensibility 7825 16.1.1. Method Registry 7827 The "Hypertext Transfer Protocol (HTTP) Method Registry", maintained 7828 by IANA at , registers 7829 method names. 7831 HTTP method registrations MUST include the following fields: 7833 * Method Name (see Section 9) 7835 * Safe ("yes" or "no", see Section 9.2.1) 7837 * Idempotent ("yes" or "no", see Section 9.2.2) 7839 * Pointer to specification text 7841 Values to be added to this namespace require IETF Review (see 7842 [RFC8126], Section 4.8). 7844 16.1.2. Considerations for New Methods 7846 Standardized methods are generic; that is, they are potentially 7847 applicable to any resource, not just one particular media type, kind 7848 of resource, or application. As such, it is preferred that new 7849 methods be registered in a document that isn't specific to a single 7850 application or data format, since orthogonal technologies deserve 7851 orthogonal specification. 7853 Since message parsing (Section 6) needs to be independent of method 7854 semantics (aside from responses to HEAD), definitions of new methods 7855 cannot change the parsing algorithm or prohibit the presence of 7856 content on either the request or the response message. Definitions 7857 of new methods can specify that only a zero-length content is allowed 7858 by requiring a Content-Length header field with a value of "0". 7860 Likewise, new methods cannot use the special host:port and asterisk 7861 forms of request target that are allowed for CONNECT and OPTIONS, 7862 respectively (Section 7.1). A full URI in absolute form is needed 7863 for the target URI, which means either the request target needs to be 7864 sent in absolute form or the target URI will be reconstructed from 7865 the request context in the same way it is for other methods. 7867 A new method definition needs to indicate whether it is safe 7868 (Section 9.2.1), idempotent (Section 9.2.2), cacheable 7869 (Section 9.2.3), what semantics are to be associated with the request 7870 content (if any), and what refinements the method makes to header 7871 field or status code semantics. If the new method is cacheable, its 7872 definition ought to describe how, and under what conditions, a cache 7873 can store a response and use it to satisfy a subsequent request. The 7874 new method ought to describe whether it can be made conditional 7875 (Section 13.1) and, if so, how a server responds when the condition 7876 is false. Likewise, if the new method might have some use for 7877 partial response semantics (Section 14.2), it ought to document this, 7878 too. 7880 | *Note:* Avoid defining a method name that starts with "M-", 7881 | since that prefix might be misinterpreted as having the 7882 | semantics assigned to it by [RFC2774]. 7884 16.2. Status Code Extensibility 7886 16.2.1. Status Code Registry 7888 The "Hypertext Transfer Protocol (HTTP) Status Code Registry", 7889 maintained by IANA at , registers status code numbers. 7892 A registration MUST include the following fields: 7894 * Status Code (3 digits) 7896 * Short Description 7898 * Pointer to specification text 7900 Values to be added to the HTTP status code namespace require IETF 7901 Review (see [RFC8126], Section 4.8). 7903 16.2.2. Considerations for New Status Codes 7905 When it is necessary to express semantics for a response that are not 7906 defined by current status codes, a new status code can be registered. 7907 Status codes are generic; they are potentially applicable to any 7908 resource, not just one particular media type, kind of resource, or 7909 application of HTTP. As such, it is preferred that new status codes 7910 be registered in a document that isn't specific to a single 7911 application. 7913 New status codes are required to fall under one of the categories 7914 defined in Section 15. To allow existing parsers to process the 7915 response message, new status codes cannot disallow content, although 7916 they can mandate a zero-length content. 7918 Proposals for new status codes that are not yet widely deployed ought 7919 to avoid allocating a specific number for the code until there is 7920 clear consensus that it will be registered; instead, early drafts can 7921 use a notation such as "4NN", or "3N0" .. "3N9", to indicate the 7922 class of the proposed status code(s) without consuming a number 7923 prematurely. 7925 The definition of a new status code ought to explain the request 7926 conditions that would cause a response containing that status code 7927 (e.g., combinations of request header fields and/or method(s)) along 7928 with any dependencies on response header fields (e.g., what fields 7929 are required, what fields can modify the semantics, and what field 7930 semantics are further refined when used with the new status code). 7932 By default, a status code applies only to the request corresponding 7933 to the response it occurs within. If a status code applies to a 7934 larger scope of applicability - for example, all requests to the 7935 resource in question, or all requests to a server - this must be 7936 explicitly specified. When doing so, it should be noted that not all 7937 clients can be expected to consistently apply a larger scope, because 7938 they might not understand the new status code. 7940 The definition of a new status code ought to specify whether or not 7941 it is cacheable. Note that all status codes can be cached if the 7942 response they occur in has explicit freshness information; however, 7943 status codes that are defined as being cacheable are allowed to be 7944 cached without explicit freshness information. Likewise, the 7945 definition of a status code can place constraints upon cache 7946 behavior. See [Caching] for more information. 7948 Finally, the definition of a new status code ought to indicate 7949 whether the content has any implied association with an identified 7950 resource (Section 6.4.2). 7952 16.3. Field Extensibility 7954 HTTP's most widely used extensibility point is the definition of new 7955 header and trailer fields. 7957 New fields can be defined such that, when they are understood by a 7958 recipient, they override or enhance the interpretation of previously 7959 defined fields, define preconditions on request evaluation, or refine 7960 the meaning of responses. 7962 However, defining a field doesn't guarantee its deployment or 7963 recognition by recipients. Most fields are designed with the 7964 expectation that a recipient can safely ignore (but forward 7965 downstream) any field not recognized. In other cases, the sender's 7966 ability to understand a given field might be indicated by its prior 7967 communication, perhaps in the protocol version or fields that it sent 7968 in prior messages, or its use of a specific media type. Likewise, 7969 direct inspection of support might be possible through an OPTIONS 7970 request or by interacting with a defined well-known URI [RFC8615] if 7971 such inspection is defined along with the field being introduced. 7973 16.3.1. Field Name Registry 7975 The "Hypertext Transfer Protocol (HTTP) Field Name Registry" defines 7976 the namespace for HTTP field names. 7978 Any party can request registration of an HTTP field. See 7979 Section 16.3.2 for considerations to take into account when creating 7980 a new HTTP field. 7982 The "Hypertext Transfer Protocol (HTTP) Field Name Registry" is 7983 located at . 7984 Registration requests can be made by following the instructions 7985 located there or by sending an email to the "ietf-http-wg@ietf.org" 7986 mailing list. 7988 Field names are registered on the advice of a Designated Expert 7989 (appointed by the IESG or their delegate). Fields with the status 7990 'permanent' are Specification Required ([RFC8126], Section 4.6). 7992 Registration requests consist of at least the following information: 7994 Field name: 7995 The requested field name. It MUST conform to the field-name 7996 syntax defined in Section 5.1, and SHOULD be restricted to just 7997 letters, digits, hyphen ('-') and underscore ('_') characters, 7998 with the first character being a letter. 8000 Status: 8001 "permanent" or "provisional". 8003 Specification document(s): 8004 Reference to the document that specifies the field, preferably 8005 including a URI that can be used to retrieve a copy of the 8006 document. An indication of the relevant section(s) can also be 8007 included, but is not required. 8009 And, optionally: 8011 Comments: Additional information, such as about reserved entries. 8013 The Expert(s) can define additional fields to be collected in the 8014 registry, in consultation with the community. 8016 Standards-defined names have a status of "permanent". Other names 8017 can also be registered as permanent, if the Expert(s) find that they 8018 are in use, in consultation with the community. Other names should 8019 be registered as "provisional". 8021 Provisional entries can be removed by the Expert(s) if - in 8022 consultation with the community - the Expert(s) find that they are 8023 not in use. The Experts can change a provisional entry's status to 8024 permanent at any time. 8026 Note that names can be registered by third parties (including the 8027 Expert(s)), if the Expert(s) determines that an unregistered name is 8028 widely deployed and not likely to be registered in a timely manner 8029 otherwise. 8031 16.3.2. Considerations for New Fields 8033 HTTP header and trailer fields are a widely-used extension point for 8034 the protocol. While they can be used in an ad hoc fashion, fields 8035 that are intended for wider use need to be carefully documented to 8036 ensure interoperability. 8038 In particular, authors of specifications defining new fields are 8039 advised to consider and, where appropriate, document the following 8040 aspects: 8042 * Under what conditions the field can be used; e.g., only in 8043 responses or requests, in all messages, only on responses to a 8044 particular request method, etc. 8046 * Whether the field semantics are further refined by their context, 8047 such as their use with certain request methods or status codes. 8049 * The scope of applicability for the information conveyed. By 8050 default, fields apply only to the message they are associated 8051 with, but some response fields are designed to apply to all 8052 representations of a resource, the resource itself, or an even 8053 broader scope. Specifications that expand the scope of a response 8054 field will need to carefully consider issues such as content 8055 negotiation, the time period of applicability, and (in some cases) 8056 multi-tenant server deployments. 8058 * Under what conditions intermediaries are allowed to insert, 8059 delete, or modify the field's value. 8061 * If the field is allowable in trailers; by default, it will not be 8062 (see Section 6.5.1). 8064 * Whether it is appropriate to list the field name in the Connection 8065 header field (i.e., if the field is to be hop-by-hop; see 8066 Section 7.6.1). 8068 * Whether the field introduces any additional security 8069 considerations, such as disclosure of privacy-related data. 8071 Request header fields have additional considerations that need to be 8072 documented if the default behaviour is not appropriate: 8074 * If it is appropriate to list the field name in a Vary response 8075 header field (e.g., when the request header field is used by an 8076 origin server's content selection algorithm; see Section 12.5.5). 8078 * If the field is intended to be stored when received in a PUT 8079 request (see Section 9.3.4). 8081 * If the field ought to be removed when automatically redirecting a 8082 request, due to security concerns (see Section 15.4). 8084 16.3.2.1. Considerations for New Field Names 8086 Authors of specifications defining new fields are advised to choose a 8087 short but descriptive field name. Short names avoid needless data 8088 transmission; descriptive names avoid confusion and "squatting" on 8089 names that might have broader uses. 8091 To that end, limited-use fields (such as a header confined to a 8092 single application or use case) are encouraged to use a name that 8093 includes that use (or an abbreviation) as a prefix; for example, if 8094 the Foo Application needs a Description field, it might use "Foo- 8095 Desc"; "Description" is too generic, and "Foo-Description" is 8096 needlessly long. 8098 While the field-name syntax is defined to allow any token character, 8099 in practice some implementations place limits on the characters they 8100 accept in field-names. To be interoperable, new field names SHOULD 8101 constrain themselves to alphanumeric characters, "-", and ".", and 8102 SHOULD begin with an alphanumeric character. For example, the 8103 underscore ("_") character can be problematic when passed through 8104 non-HTTP gateway interfaces (see Section 17.10). 8106 Field names ought not be prefixed with "X-"; see [BCP178] for further 8107 information. 8109 Other prefixes are sometimes used in HTTP field names; for example, 8110 "Accept-" is used in many content negotiation headers. These 8111 prefixes are only an aid to recognizing the purpose of a field, and 8112 do not trigger automatic processing. 8114 16.3.2.2. Considerations for New Field Values 8116 A major task in the definition of a new HTTP field is the 8117 specification of the field value syntax: what senders should 8118 generate, and how recipients should infer semantics from what is 8119 received. 8121 Authors are encouraged (but not required) to use either the ABNF 8122 rules in this specification or those in [RFC8941] to define the 8123 syntax of new field values. 8125 Authors are advised to carefully consider how the combination of 8126 multiple field lines will impact them (see Section 5.3). Because 8127 senders might send erroneously send multiple values, and both 8128 intermediaries and HTTP libraries can perform combination 8129 automatically, this applies to all field values - even when only a 8130 single value is anticipated. 8132 Therefore, authors are advised to delimit or encode values that 8133 contain commas (e.g., with the quoted-string rule of Section 5.6.4, 8134 the String data type of [RFC8941]), or a field-specific encoding). 8135 This ensures that commas within field data are not confused with the 8136 commas that delimit a list value. 8138 For example, the Content-Type field value only allows commas inside 8139 quoted strings, which can be reliably parsed even when multiple 8140 values are present. The Location field value provides a counter- 8141 example that should not be emulated: because URIs can include commas, 8142 it is not possible to reliably distinguish between a single value 8143 that includes a comma from two values. 8145 Authors of fields with a singleton value (see Section 5.5) are 8146 additionally advised to document how to treat messages where the 8147 multiple members are present (a sensible default would be to ignore 8148 the field, but this might not always be the right choice). 8150 16.4. Authentication Scheme Extensibility 8151 16.4.1. Authentication Scheme Registry 8153 The "Hypertext Transfer Protocol (HTTP) Authentication Scheme 8154 Registry" defines the namespace for the authentication schemes in 8155 challenges and credentials. It is maintained at 8156 . 8158 Registrations MUST include the following fields: 8160 * Authentication Scheme Name 8162 * Pointer to specification text 8164 * Notes (optional) 8166 Values to be added to this namespace require IETF Review (see 8167 [RFC8126], Section 4.8). 8169 16.4.2. Considerations for New Authentication Schemes 8171 There are certain aspects of the HTTP Authentication framework that 8172 put constraints on how new authentication schemes can work: 8174 * HTTP authentication is presumed to be stateless: all of the 8175 information necessary to authenticate a request MUST be provided 8176 in the request, rather than be dependent on the server remembering 8177 prior requests. Authentication based on, or bound to, the 8178 underlying connection is outside the scope of this specification 8179 and inherently flawed unless steps are taken to ensure that the 8180 connection cannot be used by any party other than the 8181 authenticated user (see Section 3.7). 8183 * The authentication parameter "realm" is reserved for defining 8184 protection spaces as described in Section 11.5. New schemes MUST 8185 NOT use it in a way incompatible with that definition. 8187 * The "token68" notation was introduced for compatibility with 8188 existing authentication schemes and can only be used once per 8189 challenge or credential. Thus, new schemes ought to use the auth- 8190 param syntax instead, because otherwise future extensions will be 8191 impossible. 8193 * The parsing of challenges and credentials is defined by this 8194 specification and cannot be modified by new authentication 8195 schemes. When the auth-param syntax is used, all parameters ought 8196 to support both token and quoted-string syntax, and syntactical 8197 constraints ought to be defined on the field value after parsing 8198 (i.e., quoted-string processing). This is necessary so that 8199 recipients can use a generic parser that applies to all 8200 authentication schemes. 8202 *Note:* The fact that the value syntax for the "realm" parameter 8203 is restricted to quoted-string was a bad design choice not to be 8204 repeated for new parameters. 8206 * Definitions of new schemes ought to define the treatment of 8207 unknown extension parameters. In general, a "must-ignore" rule is 8208 preferable to a "must-understand" rule, because otherwise it will 8209 be hard to introduce new parameters in the presence of legacy 8210 recipients. Furthermore, it's good to describe the policy for 8211 defining new parameters (such as "update the specification" or 8212 "use this registry"). 8214 * Authentication schemes need to document whether they are usable in 8215 origin-server authentication (i.e., using WWW-Authenticate), and/ 8216 or proxy authentication (i.e., using Proxy-Authenticate). 8218 * The credentials carried in an Authorization header field are 8219 specific to the user agent and, therefore, have the same effect on 8220 HTTP caches as the "private" Cache-Control response directive 8221 (Section 5.2.2.7 of [Caching]), within the scope of the request in 8222 which they appear. 8224 Therefore, new authentication schemes that choose not to carry 8225 credentials in the Authorization header field (e.g., using a newly 8226 defined header field) will need to explicitly disallow caching, by 8227 mandating the use of Cache-Control response directives (e.g., 8228 "private"). 8230 * Schemes using Authentication-Info, Proxy-Authentication-Info, or 8231 any other authentication related response header field need to 8232 consider and document the related security considerations (see 8233 Section 17.16.4). 8235 16.5. Range Unit Extensibility 8236 16.5.1. Range Unit Registry 8238 The "HTTP Range Unit Registry" defines the namespace for the range 8239 unit names and refers to their corresponding specifications. It is 8240 maintained at . 8242 Registration of an HTTP Range Unit MUST include the following fields: 8244 * Name 8246 * Description 8248 * Pointer to specification text 8250 Values to be added to this namespace require IETF Review (see 8251 [RFC8126], Section 4.8). 8253 16.5.2. Considerations for New Range Units 8255 Other range units, such as format-specific boundaries like pages, 8256 sections, records, rows, or time, are potentially usable in HTTP for 8257 application-specific purposes, but are not commonly used in practice. 8258 Implementors of alternative range units ought to consider how they 8259 would work with content codings and general-purpose intermediaries. 8261 16.6. Content Coding Extensibility 8263 16.6.1. Content Coding Registry 8265 The "HTTP Content Coding Registry", maintained by IANA at 8266 , registers 8267 content-coding names. 8269 Content coding registrations MUST include the following fields: 8271 * Name 8273 * Description 8275 * Pointer to specification text 8277 Names of content codings MUST NOT overlap with names of transfer 8278 codings (as per the "HTTP Transfer Coding registry", located at 8279 ), unless the 8280 encoding transformation is identical (as is the case for the 8281 compression codings defined in Section 8.4.1). 8283 Values to be added to this namespace require IETF Review (see 8284 Section 4.8 of [RFC8126]) and MUST conform to the purpose of content 8285 coding defined in Section 8.4.1. 8287 16.6.2. Considerations for New Content Codings 8289 New content codings ought to be self-descriptive whenever possible, 8290 with optional parameters discoverable within the coding format 8291 itself, rather than rely on external metadata that might be lost 8292 during transit. 8294 16.7. Upgrade Token Registry 8296 The "Hypertext Transfer Protocol (HTTP) Upgrade Token Registry" 8297 defines the namespace for protocol-name tokens used to identify 8298 protocols in the Upgrade header field. The registry is maintained at 8299 . 8301 Each registered protocol name is associated with contact information 8302 and an optional set of specifications that details how the connection 8303 will be processed after it has been upgraded. 8305 Registrations happen on a "First Come First Served" basis (see 8306 Section 4.4 of [RFC8126]) and are subject to the following rules: 8308 1. A protocol-name token, once registered, stays registered forever. 8310 2. A protocol-name token is case-insensitive and registered with the 8311 preferred case to be generated by senders. 8313 3. The registration MUST name a responsible party for the 8314 registration. 8316 4. The registration MUST name a point of contact. 8318 5. The registration MAY name a set of specifications associated with 8319 that token. Such specifications need not be publicly available. 8321 6. The registration SHOULD name a set of expected "protocol-version" 8322 tokens associated with that token at the time of registration. 8324 7. The responsible party MAY change the registration at any time. 8325 The IANA will keep a record of all such changes, and make them 8326 available upon request. 8328 8. The IESG MAY reassign responsibility for a protocol token. This 8329 will normally only be used in the case when a responsible party 8330 cannot be contacted. 8332 17. Security Considerations 8334 This section is meant to inform developers, information providers, 8335 and users of known security concerns relevant to HTTP semantics and 8336 its use for transferring information over the Internet. 8337 Considerations related to caching are discussed in Section 7 of 8338 [Caching] and considerations related to HTTP/1.1 message syntax and 8339 parsing are discussed in Section 11 of [Messaging]. 8341 The list of considerations below is not exhaustive. Most security 8342 concerns related to HTTP semantics are about securing server-side 8343 applications (code behind the HTTP interface), securing user agent 8344 processing of content received via HTTP, or secure use of the 8345 Internet in general, rather than security of the protocol. Various 8346 organizations maintain topical information and links to current 8347 research on Web application security (e.g., [OWASP]). 8349 17.1. Establishing Authority 8351 HTTP relies on the notion of an _authoritative response_: a response 8352 that has been determined by (or at the direction of) the origin 8353 server identified within the target URI to be the most appropriate 8354 response for that request given the state of the target resource at 8355 the time of response message origination. 8357 When a registered name is used in the authority component, the "http" 8358 URI scheme (Section 4.2.1) relies on the user's local name resolution 8359 service to determine where it can find authoritative responses. This 8360 means that any attack on a user's network host table, cached names, 8361 or name resolution libraries becomes an avenue for attack on 8362 establishing authority for "http" URIs. Likewise, the user's choice 8363 of server for Domain Name Service (DNS), and the hierarchy of servers 8364 from which it obtains resolution results, could impact the 8365 authenticity of address mappings; DNS Security Extensions (DNSSEC, 8366 [RFC4033]) are one way to improve authenticity. 8368 Furthermore, after an IP address is obtained, establishing authority 8369 for an "http" URI is vulnerable to attacks on Internet Protocol 8370 routing. 8372 The "https" scheme (Section 4.2.2) is intended to prevent (or at 8373 least reveal) many of these potential attacks on establishing 8374 authority, provided that the negotiated connection is secured and the 8375 client properly verifies that the communicating server's identity 8376 matches the target URI's authority component (Section 4.3.4). 8377 Correctly implementing such verification can be difficult (see 8378 [Georgiev]). 8380 Authority for a given origin server can be delegated through protocol 8381 extensions; for example, [RFC7838]. Likewise, the set of servers for 8382 which a connection is considered authoritative can be changed with a 8383 protocol extension like [RFC8336]. 8385 Providing a response from a non-authoritative source, such as a 8386 shared proxy cache, is often useful to improve performance and 8387 availability, but only to the extent that the source can be trusted 8388 or the distrusted response can be safely used. 8390 Unfortunately, communicating authority to users can be difficult. 8391 For example, _phishing_ is an attack on the user's perception of 8392 authority, where that perception can be misled by presenting similar 8393 branding in hypertext, possibly aided by userinfo obfuscating the 8394 authority component (see Section 4.2.1). User agents can reduce the 8395 impact of phishing attacks by enabling users to easily inspect a 8396 target URI prior to making an action, by prominently distinguishing 8397 (or rejecting) userinfo when present, and by not sending stored 8398 credentials and cookies when the referring document is from an 8399 unknown or untrusted source. 8401 17.2. Risks of Intermediaries 8403 HTTP intermediaries are inherently situated for on-path attacks. 8404 Compromise of the systems on which the intermediaries run can result 8405 in serious security and privacy problems. Intermediaries might have 8406 access to security-related information, personal information about 8407 individual users and organizations, and proprietary information 8408 belonging to users and content providers. A compromised 8409 intermediary, or an intermediary implemented or configured without 8410 regard to security and privacy considerations, might be used in the 8411 commission of a wide range of potential attacks. 8413 Intermediaries that contain a shared cache are especially vulnerable 8414 to cache poisoning attacks, as described in Section 7 of [Caching]. 8416 Implementers need to consider the privacy and security implications 8417 of their design and coding decisions, and of the configuration 8418 options they provide to operators (especially the default 8419 configuration). 8421 Users need to be aware that intermediaries are no more trustworthy 8422 than the people who run them; HTTP itself cannot solve this problem. 8424 17.3. Attacks Based on File and Path Names 8426 Origin servers frequently make use of their local file system to 8427 manage the mapping from target URI to resource representations. Most 8428 file systems are not designed to protect against malicious file or 8429 path names. Therefore, an origin server needs to avoid accessing 8430 names that have a special significance to the system when mapping the 8431 target resource to files, folders, or directories. 8433 For example, UNIX, Microsoft Windows, and other operating systems use 8434 ".." as a path component to indicate a directory level above the 8435 current one, and they use specially named paths or file names to send 8436 data to system devices. Similar naming conventions might exist 8437 within other types of storage systems. Likewise, local storage 8438 systems have an annoying tendency to prefer user-friendliness over 8439 security when handling invalid or unexpected characters, 8440 recomposition of decomposed characters, and case-normalization of 8441 case-insensitive names. 8443 Attacks based on such special names tend to focus on either denial- 8444 of-service (e.g., telling the server to read from a COM port) or 8445 disclosure of configuration and source files that are not meant to be 8446 served. 8448 17.4. Attacks Based on Command, Code, or Query Injection 8450 Origin servers often use parameters within the URI as a means of 8451 identifying system services, selecting database entries, or choosing 8452 a data source. However, data received in a request cannot be 8453 trusted. An attacker could construct any of the request data 8454 elements (method, target URI, header fields, or content) to contain 8455 data that might be misinterpreted as a command, code, or query when 8456 passed through a command invocation, language interpreter, or 8457 database interface. 8459 For example, SQL injection is a common attack wherein additional 8460 query language is inserted within some part of the target URI or 8461 header fields (e.g., Host, Referer, etc.). If the received data is 8462 used directly within a SELECT statement, the query language might be 8463 interpreted as a database command instead of a simple string value. 8464 This type of implementation vulnerability is extremely common, in 8465 spite of being easy to prevent. 8467 In general, resource implementations ought to avoid use of request 8468 data in contexts that are processed or interpreted as instructions. 8469 Parameters ought to be compared to fixed strings and acted upon as a 8470 result of that comparison, rather than passed through an interface 8471 that is not prepared for untrusted data. Received data that isn't 8472 based on fixed parameters ought to be carefully filtered or encoded 8473 to avoid being misinterpreted. 8475 Similar considerations apply to request data when it is stored and 8476 later processed, such as within log files, monitoring tools, or when 8477 included within a data format that allows embedded scripts. 8479 17.5. Attacks via Protocol Element Length 8481 Because HTTP uses mostly textual, character-delimited fields, parsers 8482 are often vulnerable to attacks based on sending very long (or very 8483 slow) streams of data, particularly where an implementation is 8484 expecting a protocol element with no predefined length (Section 2.3). 8486 To promote interoperability, specific recommendations are made for 8487 minimum size limits on fields (Section 5.4). These are minimum 8488 recommendations, chosen to be supportable even by implementations 8489 with limited resources; it is expected that most implementations will 8490 choose substantially higher limits. 8492 A server can reject a message that has a target URI that is too long 8493 (Section 15.5.15) or request content that is too large 8494 (Section 15.5.14). Additional status codes related to capacity 8495 limits have been defined by extensions to HTTP [RFC6585]. 8497 Recipients ought to carefully limit the extent to which they process 8498 other protocol elements, including (but not limited to) request 8499 methods, response status phrases, field names, numeric values, and 8500 chunk lengths. Failure to limit such processing can result in buffer 8501 overflows, arithmetic overflows, or increased vulnerability to 8502 denial-of-service attacks. 8504 17.6. Attacks using Shared-dictionary Compression 8506 Some attacks on encrypted protocols use the differences in size 8507 created by dynamic compression to reveal confidential information; 8508 for example, [BREACH]. These attacks rely on creating a redundancy 8509 between attacker-controlled content and the confidential information, 8510 such that a dynamic compression algorithm using the same dictionary 8511 for both content will compress more efficiently when the attacker- 8512 controlled content matches parts of the confidential content. 8514 HTTP messages can be compressed in a number of ways, including using 8515 TLS compression, content codings, transfer codings, and other 8516 extension or version-specific mechanisms. 8518 The most effective mitigation for this risk is to disable compression 8519 on sensitive data, or to strictly separate sensitive data from 8520 attacker-controlled data so that they cannot share the same 8521 compression dictionary. With careful design, a compression scheme 8522 can be designed in a way that is not considered exploitable in 8523 limited use cases, such as HPACK ([RFC7541]). 8525 17.7. Disclosure of Personal Information 8527 Clients are often privy to large amounts of personal information, 8528 including both information provided by the user to interact with 8529 resources (e.g., the user's name, location, mail address, passwords, 8530 encryption keys, etc.) and information about the user's browsing 8531 activity over time (e.g., history, bookmarks, etc.). Implementations 8532 need to prevent unintentional disclosure of personal information. 8534 17.8. Privacy of Server Log Information 8536 A server is in the position to save personal data about a user's 8537 requests over time, which might identify their reading patterns or 8538 subjects of interest. In particular, log information gathered at an 8539 intermediary often contains a history of user agent interaction, 8540 across a multitude of sites, that can be traced to individual users. 8542 HTTP log information is confidential in nature; its handling is often 8543 constrained by laws and regulations. Log information needs to be 8544 securely stored and appropriate guidelines followed for its analysis. 8545 Anonymization of personal information within individual entries 8546 helps, but it is generally not sufficient to prevent real log traces 8547 from being re-identified based on correlation with other access 8548 characteristics. As such, access traces that are keyed to a specific 8549 client are unsafe to publish even if the key is pseudonymous. 8551 To minimize the risk of theft or accidental publication, log 8552 information ought to be purged of personally identifiable 8553 information, including user identifiers, IP addresses, and user- 8554 provided query parameters, as soon as that information is no longer 8555 necessary to support operational needs for security, auditing, or 8556 fraud control. 8558 17.9. Disclosure of Sensitive Information in URIs 8560 URIs are intended to be shared, not secured, even when they identify 8561 secure resources. URIs are often shown on displays, added to 8562 templates when a page is printed, and stored in a variety of 8563 unprotected bookmark lists. Many servers, proxies, and user agents 8564 log or display the target URI in places where it might be visible to 8565 third parties. It is therefore unwise to include information within 8566 a URI that is sensitive, personally identifiable, or a risk to 8567 disclose. 8569 When an application uses client-side mechanisms to construct a target 8570 URI out of user-provided information, such as the query fields of a 8571 form using GET, potentially sensitive data might be provided that 8572 would not be appropriate for disclosure within a URI. POST is often 8573 preferred in such cases because it usually doesn't construct a URI; 8574 instead, POST of a form transmits the potentially sensitive data in 8575 the request content. However, this hinders caching and uses an 8576 unsafe method for what would otherwise be a safe request. 8577 Alternative workarounds include transforming the user-provided data 8578 prior to constructing the URI, or filtering the data to only include 8579 common values that are not sensitive. Likewise, redirecting the 8580 result of a query to a different (server-generated) URI can remove 8581 potentially sensitive data from later links and provide a cacheable 8582 response for later reuse. 8584 Since the Referer header field tells a target site about the context 8585 that resulted in a request, it has the potential to reveal 8586 information about the user's immediate browsing history and any 8587 personal information that might be found in the referring resource's 8588 URI. Limitations on the Referer header field are described in 8589 Section 10.1.3 to address some of its security considerations. 8591 17.10. Application Handling of Field Names 8593 Servers often use non-HTTP gateway interfaces and frameworks to 8594 process a received request and produce content for the response. For 8595 historical reasons, such interfaces often pass received field names 8596 as external variable names, using a name mapping suitable for 8597 environment variables. 8599 For example, the Common Gateway Interface (CGI) mapping of protocol- 8600 specific meta-variables, defined by Section 4.1.18 of [RFC3875], is 8601 applied to received header fields that do not correspond to one of 8602 CGI's standard variables; the mapping consists of prepending "HTTP_" 8603 to each name and changing all instances of hyphen ("-") to underscore 8604 ("_"). This same mapping has been inherited by many other 8605 application frameworks in order to simplify moving applications from 8606 one platform to the next. 8608 In CGI, a received Content-Length field would be passed as the meta- 8609 variable "CONTENT_LENGTH" with a string value matching the received 8610 field's value. In contrast, a received "Content_Length" header field 8611 would be passed as the protocol-specific meta-variable 8612 "HTTP_CONTENT_LENGTH", which might lead to some confusion if an 8613 application mistakenly reads the protocol-specific meta-variable 8614 instead of the default one. (This historical practice is why 8615 Section 16.3.2.1 discourages the creation of new field names that 8616 contain an underscore.) 8618 Unfortunately, mapping field names to different interface names can 8619 lead to security vulnerabilities if the mapping is incomplete or 8620 ambiguous. For example, if an attacker were to send a field named 8621 "Transfer_Encoding", a naive interface might map that to the same 8622 variable name as the "Transfer-Encoding" field, resulting in a 8623 potential request smuggling vulnerability (Section 11.2 of 8624 [Messaging]). 8626 To mitigate the associated risks, implementations that perform such 8627 mappings are advised to make the mapping unambiguous and complete for 8628 the full range of potential octets received as a name (including 8629 those that are discouraged or forbidden by the HTTP grammar). For 8630 example, a field with an unusual name character might result in the 8631 request being blocked, the specific field being removed, or the name 8632 being passed with a different prefix to distinguish it from other 8633 fields. 8635 17.11. Disclosure of Fragment after Redirects 8637 Although fragment identifiers used within URI references are not sent 8638 in requests, implementers ought to be aware that they will be visible 8639 to the user agent and any extensions or scripts running as a result 8640 of the response. In particular, when a redirect occurs and the 8641 original request's fragment identifier is inherited by the new 8642 reference in Location (Section 10.2.3), this might have the effect of 8643 disclosing one site's fragment to another site. If the first site 8644 uses personal information in fragments, it ought to ensure that 8645 redirects to other sites include a (possibly empty) fragment 8646 component in order to block that inheritance. 8648 17.12. Disclosure of Product Information 8650 The User-Agent (Section 10.1.6), Via (Section 7.6.3), and Server 8651 (Section 10.2.5) header fields often reveal information about the 8652 respective sender's software systems. In theory, this can make it 8653 easier for an attacker to exploit known security holes; in practice, 8654 attackers tend to try all potential holes regardless of the apparent 8655 software versions being used. 8657 Proxies that serve as a portal through a network firewall ought to 8658 take special precautions regarding the transfer of header information 8659 that might identify hosts behind the firewall. The Via header field 8660 allows intermediaries to replace sensitive machine names with 8661 pseudonyms. 8663 17.13. Browser Fingerprinting 8665 Browser fingerprinting is a set of techniques for identifying a 8666 specific user agent over time through its unique set of 8667 characteristics. These characteristics might include information 8668 related to its TCP behavior, feature capabilities, and scripting 8669 environment, though of particular interest here is the set of unique 8670 characteristics that might be communicated via HTTP. Fingerprinting 8671 is considered a privacy concern because it enables tracking of a user 8672 agent's behavior over time ([Bujlow]) without the corresponding 8673 controls that the user might have over other forms of data collection 8674 (e.g., cookies). Many general-purpose user agents (i.e., Web 8675 browsers) have taken steps to reduce their fingerprints. 8677 There are a number of request header fields that might reveal 8678 information to servers that is sufficiently unique to enable 8679 fingerprinting. The From header field is the most obvious, though it 8680 is expected that From will only be sent when self-identification is 8681 desired by the user. Likewise, Cookie header fields are deliberately 8682 designed to enable re-identification, so fingerprinting concerns only 8683 apply to situations where cookies are disabled or restricted by the 8684 user agent's configuration. 8686 The User-Agent header field might contain enough information to 8687 uniquely identify a specific device, usually when combined with other 8688 characteristics, particularly if the user agent sends excessive 8689 details about the user's system or extensions. However, the source 8690 of unique information that is least expected by users is proactive 8691 negotiation (Section 12.1), including the Accept, Accept-Charset, 8692 Accept-Encoding, and Accept-Language header fields. 8694 In addition to the fingerprinting concern, detailed use of the 8695 Accept-Language header field can reveal information the user might 8696 consider to be of a private nature. For example, understanding a 8697 given language set might be strongly correlated to membership in a 8698 particular ethnic group. An approach that limits such loss of 8699 privacy would be for a user agent to omit the sending of Accept- 8700 Language except for sites that have been explicitly permitted, 8701 perhaps via interaction after detecting a Vary header field that 8702 indicates language negotiation might be useful. 8704 In environments where proxies are used to enhance privacy, user 8705 agents ought to be conservative in sending proactive negotiation 8706 header fields. General-purpose user agents that provide a high 8707 degree of header field configurability ought to inform users about 8708 the loss of privacy that might result if too much detail is provided. 8709 As an extreme privacy measure, proxies could filter the proactive 8710 negotiation header fields in relayed requests. 8712 17.14. Validator Retention 8714 The validators defined by this specification are not intended to 8715 ensure the validity of a representation, guard against malicious 8716 changes, or detect on-path attacks. At best, they enable more 8717 efficient cache updates and optimistic concurrent writes when all 8718 participants are behaving nicely. At worst, the conditions will fail 8719 and the client will receive a response that is no more harmful than 8720 an HTTP exchange without conditional requests. 8722 An entity-tag can be abused in ways that create privacy risks. For 8723 example, a site might deliberately construct a semantically invalid 8724 entity-tag that is unique to the user or user agent, send it in a 8725 cacheable response with a long freshness time, and then read that 8726 entity-tag in later conditional requests as a means of re-identifying 8727 that user or user agent. Such an identifying tag would become a 8728 persistent identifier for as long as the user agent retained the 8729 original cache entry. User agents that cache representations ought 8730 to ensure that the cache is cleared or replaced whenever the user 8731 performs privacy-maintaining actions, such as clearing stored cookies 8732 or changing to a private browsing mode. 8734 17.15. Denial-of-Service Attacks Using Range 8736 Unconstrained multiple range requests are susceptible to denial-of- 8737 service attacks because the effort required to request many 8738 overlapping ranges of the same data is tiny compared to the time, 8739 memory, and bandwidth consumed by attempting to serve the requested 8740 data in many parts. Servers ought to ignore, coalesce, or reject 8741 egregious range requests, such as requests for more than two 8742 overlapping ranges or for many small ranges in a single set, 8743 particularly when the ranges are requested out of order for no 8744 apparent reason. Multipart range requests are not designed to 8745 support random access. 8747 17.16. Authentication Considerations 8749 Everything about the topic of HTTP authentication is a security 8750 consideration, so the list of considerations below is not exhaustive. 8751 Furthermore, it is limited to security considerations regarding the 8752 authentication framework, in general, rather than discussing all of 8753 the potential considerations for specific authentication schemes 8754 (which ought to be documented in the specifications that define those 8755 schemes). Various organizations maintain topical information and 8756 links to current research on Web application security (e.g., 8757 [OWASP]), including common pitfalls for implementing and using the 8758 authentication schemes found in practice. 8760 17.16.1. Confidentiality of Credentials 8762 The HTTP authentication framework does not define a single mechanism 8763 for maintaining the confidentiality of credentials; instead, each 8764 authentication scheme defines how the credentials are encoded prior 8765 to transmission. While this provides flexibility for the development 8766 of future authentication schemes, it is inadequate for the protection 8767 of existing schemes that provide no confidentiality on their own, or 8768 that do not sufficiently protect against replay attacks. 8769 Furthermore, if the server expects credentials that are specific to 8770 each individual user, the exchange of those credentials will have the 8771 effect of identifying that user even if the content within 8772 credentials remains confidential. 8774 HTTP depends on the security properties of the underlying transport- 8775 or session-level connection to provide confidential transmission of 8776 fields. Services that depend on individual user authentication 8777 require a secured connection prior to exchanging credentials 8778 (Section 4.2.2). 8780 17.16.2. Credentials and Idle Clients 8782 Existing HTTP clients and user agents typically retain authentication 8783 information indefinitely. HTTP does not provide a mechanism for the 8784 origin server to direct clients to discard these cached credentials, 8785 since the protocol has no awareness of how credentials are obtained 8786 or managed by the user agent. The mechanisms for expiring or 8787 revoking credentials can be specified as part of an authentication 8788 scheme definition. 8790 Circumstances under which credential caching can interfere with the 8791 application's security model include but are not limited to: 8793 * Clients that have been idle for an extended period, following 8794 which the server might wish to cause the client to re-prompt the 8795 user for credentials. 8797 * Applications that include a session termination indication (such 8798 as a "logout" or "commit" button on a page) after which the server 8799 side of the application "knows" that there is no further reason 8800 for the client to retain the credentials. 8802 User agents that cache credentials are encouraged to provide a 8803 readily accessible mechanism for discarding cached credentials under 8804 user control. 8806 17.16.3. Protection Spaces 8808 Authentication schemes that solely rely on the "realm" mechanism for 8809 establishing a protection space will expose credentials to all 8810 resources on an origin server. Clients that have successfully made 8811 authenticated requests with a resource can use the same 8812 authentication credentials for other resources on the same origin 8813 server. This makes it possible for a different resource to harvest 8814 authentication credentials for other resources. 8816 This is of particular concern when an origin server hosts resources 8817 for multiple parties under the same origin (Section 11.5). Possible 8818 mitigation strategies include restricting direct access to 8819 authentication credentials (i.e., not making the content of the 8820 Authorization request header field available), and separating 8821 protection spaces by using a different host name (or port number) for 8822 each party. 8824 17.16.4. Additional Response Fields 8826 Adding information to responses that are sent over an unencrypted 8827 channel can affect security and privacy. The presence of the 8828 Authentication-Info and Proxy-Authentication-Info header fields alone 8829 indicates that HTTP authentication is in use. Additional information 8830 could be exposed by the contents of the authentication-scheme 8831 specific parameters; this will have to be considered in the 8832 definitions of these schemes. 8834 18. IANA Considerations 8836 The change controller for the following registrations is: "IETF 8837 (iesg@ietf.org) - Internet Engineering Task Force". 8839 18.1. URI Scheme Registration 8841 Please update the registry of URI Schemes [BCP35] at 8842 with the permanent 8843 schemes listed in the table in Section 4.2. 8845 18.2. Method Registration 8847 Please update the "Hypertext Transfer Protocol (HTTP) Method 8848 Registry" at with the 8849 registration procedure of Section 16.1.1 and the method names 8850 summarized in the following table. 8852 +=========+======+============+=======+ 8853 | Method | Safe | Idempotent | Ref. | 8854 +=========+======+============+=======+ 8855 | CONNECT | no | no | 9.3.6 | 8856 +---------+------+------------+-------+ 8857 | DELETE | no | yes | 9.3.5 | 8858 +---------+------+------------+-------+ 8859 | GET | yes | yes | 9.3.1 | 8860 +---------+------+------------+-------+ 8861 | HEAD | yes | yes | 9.3.2 | 8862 +---------+------+------------+-------+ 8863 | OPTIONS | yes | yes | 9.3.7 | 8864 +---------+------+------------+-------+ 8865 | POST | no | no | 9.3.3 | 8866 +---------+------+------------+-------+ 8867 | PUT | no | yes | 9.3.4 | 8868 +---------+------+------------+-------+ 8869 | TRACE | yes | yes | 9.3.8 | 8870 +---------+------+------------+-------+ 8871 | * | no | no | 18.2 | 8872 +---------+------+------------+-------+ 8874 Table 7 8876 The method name "*" is reserved, since using "*" as a method name 8877 would conflict with its usage as a wildcard in some fields (e.g., 8878 "Access-Control-Request-Method"). 8880 18.3. Status Code Registration 8882 Please update the "Hypertext Transfer Protocol (HTTP) Status Code 8883 Registry" at 8884 with the registration procedure of Section 16.2.1 and the status code 8885 values summarized in the following table. 8887 +=======+===============================+=========+ 8888 | Value | Description | Ref. | 8889 +=======+===============================+=========+ 8890 | 100 | Continue | 15.2.1 | 8891 +-------+-------------------------------+---------+ 8892 | 101 | Switching Protocols | 15.2.2 | 8893 +-------+-------------------------------+---------+ 8894 | 200 | OK | 15.3.1 | 8895 +-------+-------------------------------+---------+ 8896 | 201 | Created | 15.3.2 | 8897 +-------+-------------------------------+---------+ 8898 | 202 | Accepted | 15.3.3 | 8899 +-------+-------------------------------+---------+ 8900 | 203 | Non-Authoritative Information | 15.3.4 | 8901 +-------+-------------------------------+---------+ 8902 | 204 | No Content | 15.3.5 | 8903 +-------+-------------------------------+---------+ 8904 | 205 | Reset Content | 15.3.6 | 8905 +-------+-------------------------------+---------+ 8906 | 206 | Partial Content | 15.3.7 | 8907 +-------+-------------------------------+---------+ 8908 | 300 | Multiple Choices | 15.4.1 | 8909 +-------+-------------------------------+---------+ 8910 | 301 | Moved Permanently | 15.4.2 | 8911 +-------+-------------------------------+---------+ 8912 | 302 | Found | 15.4.3 | 8913 +-------+-------------------------------+---------+ 8914 | 303 | See Other | 15.4.4 | 8915 +-------+-------------------------------+---------+ 8916 | 304 | Not Modified | 15.4.5 | 8917 +-------+-------------------------------+---------+ 8918 | 305 | Use Proxy | 15.4.6 | 8919 +-------+-------------------------------+---------+ 8920 | 306 | (Unused) | 15.4.7 | 8921 +-------+-------------------------------+---------+ 8922 | 307 | Temporary Redirect | 15.4.8 | 8923 +-------+-------------------------------+---------+ 8924 | 308 | Permanent Redirect | 15.4.9 | 8925 +-------+-------------------------------+---------+ 8926 | 400 | Bad Request | 15.5.1 | 8927 +-------+-------------------------------+---------+ 8928 | 401 | Unauthorized | 15.5.2 | 8929 +-------+-------------------------------+---------+ 8930 | 402 | Payment Required | 15.5.3 | 8931 +-------+-------------------------------+---------+ 8932 | 403 | Forbidden | 15.5.4 | 8933 +-------+-------------------------------+---------+ 8934 | 404 | Not Found | 15.5.5 | 8935 +-------+-------------------------------+---------+ 8936 | 405 | Method Not Allowed | 15.5.6 | 8937 +-------+-------------------------------+---------+ 8938 | 406 | Not Acceptable | 15.5.7 | 8939 +-------+-------------------------------+---------+ 8940 | 407 | Proxy Authentication Required | 15.5.8 | 8941 +-------+-------------------------------+---------+ 8942 | 408 | Request Timeout | 15.5.9 | 8943 +-------+-------------------------------+---------+ 8944 | 409 | Conflict | 15.5.10 | 8945 +-------+-------------------------------+---------+ 8946 | 410 | Gone | 15.5.11 | 8947 +-------+-------------------------------+---------+ 8948 | 411 | Length Required | 15.5.12 | 8949 +-------+-------------------------------+---------+ 8950 | 412 | Precondition Failed | 15.5.13 | 8951 +-------+-------------------------------+---------+ 8952 | 413 | Content Too Large | 15.5.14 | 8953 +-------+-------------------------------+---------+ 8954 | 414 | URI Too Long | 15.5.15 | 8955 +-------+-------------------------------+---------+ 8956 | 415 | Unsupported Media Type | 15.5.16 | 8957 +-------+-------------------------------+---------+ 8958 | 416 | Range Not Satisfiable | 15.5.17 | 8959 +-------+-------------------------------+---------+ 8960 | 417 | Expectation Failed | 15.5.18 | 8961 +-------+-------------------------------+---------+ 8962 | 418 | (Unused) | 15.5.19 | 8963 +-------+-------------------------------+---------+ 8964 | 421 | Misdirected Request | 15.5.20 | 8965 +-------+-------------------------------+---------+ 8966 | 422 | Unprocessable Content | 15.5.21 | 8967 +-------+-------------------------------+---------+ 8968 | 426 | Upgrade Required | 15.5.22 | 8969 +-------+-------------------------------+---------+ 8970 | 500 | Internal Server Error | 15.6.1 | 8971 +-------+-------------------------------+---------+ 8972 | 501 | Not Implemented | 15.6.2 | 8973 +-------+-------------------------------+---------+ 8974 | 502 | Bad Gateway | 15.6.3 | 8975 +-------+-------------------------------+---------+ 8976 | 503 | Service Unavailable | 15.6.4 | 8977 +-------+-------------------------------+---------+ 8978 | 504 | Gateway Timeout | 15.6.5 | 8979 +-------+-------------------------------+---------+ 8980 | 505 | HTTP Version Not Supported | 15.6.6 | 8981 +-------+-------------------------------+---------+ 8982 Table 8 8984 18.4. Field Name Registration 8986 This specification updates the HTTP related aspects of the existing 8987 registration procedures for message header fields defined in 8988 [RFC3864]. It defines both a new registration procedure and moves 8989 HTTP field definitions into a separate registry. 8991 Please create a new registry as outlined in Section 16.3.1. 8993 After creating the registry, all entries in the Permanent and 8994 Provisional Message Header Registries with the protocol 'http' are to 8995 be moved to it, with the following changes applied: 8997 1. The 'Applicable Protocol' field is to be omitted. 8999 2. Entries with a status of 'standard', 'experimental', 'reserved', 9000 or 'informational' are to have a status of 'permanent'. 9002 3. Provisional entries without a status are to have a status of 9003 'provisional'. 9005 4. Permanent entries without a status (after confirmation that the 9006 registration document did not define one) will have a status of 9007 'provisional'. The Expert(s) can choose to update their status 9008 if there is evidence that another is more appropriate. 9010 Please annotate the Permanent and Provisional Message Header 9011 registries to indicate that HTTP field name registrations have moved, 9012 with an appropriate link. 9014 After that is complete, please update the new registry with the field 9015 names listed in the following table. 9017 +===========================+============+========+============+ 9018 | Field Name | Status | Ref. | Comments | 9019 +===========================+============+========+============+ 9020 | Accept | standard | 12.5.1 | | 9021 +---------------------------+------------+--------+------------+ 9022 | Accept-Charset | deprecated | 12.5.2 | | 9023 +---------------------------+------------+--------+------------+ 9024 | Accept-Encoding | standard | 12.5.3 | | 9025 +---------------------------+------------+--------+------------+ 9026 | Accept-Language | standard | 12.5.4 | | 9027 +---------------------------+------------+--------+------------+ 9028 | Accept-Ranges | standard | 14.3 | | 9029 +---------------------------+------------+--------+------------+ 9030 | Allow | standard | 10.2.1 | | 9031 +---------------------------+------------+--------+------------+ 9032 | Authentication-Info | standard | 11.6.3 | | 9033 +---------------------------+------------+--------+------------+ 9034 | Authorization | standard | 11.6.2 | | 9035 +---------------------------+------------+--------+------------+ 9036 | Connection | standard | 7.6.1 | | 9037 +---------------------------+------------+--------+------------+ 9038 | Content-Encoding | standard | 8.4 | | 9039 +---------------------------+------------+--------+------------+ 9040 | Content-Language | standard | 8.5 | | 9041 +---------------------------+------------+--------+------------+ 9042 | Content-Length | standard | 8.6 | | 9043 +---------------------------+------------+--------+------------+ 9044 | Content-Location | standard | 8.7 | | 9045 +---------------------------+------------+--------+------------+ 9046 | Content-Range | standard | 14.4 | | 9047 +---------------------------+------------+--------+------------+ 9048 | Content-Type | standard | 8.3 | | 9049 +---------------------------+------------+--------+------------+ 9050 | Date | standard | 10.2.2 | | 9051 +---------------------------+------------+--------+------------+ 9052 | ETag | standard | 8.8.3 | | 9053 +---------------------------+------------+--------+------------+ 9054 | Expect | standard | 10.1.1 | | 9055 +---------------------------+------------+--------+------------+ 9056 | From | standard | 10.1.2 | | 9057 +---------------------------+------------+--------+------------+ 9058 | Host | standard | 7.2 | | 9059 +---------------------------+------------+--------+------------+ 9060 | If-Match | standard | 13.1.1 | | 9061 +---------------------------+------------+--------+------------+ 9062 | If-Modified-Since | standard | 13.1.3 | | 9063 +---------------------------+------------+--------+------------+ 9064 | If-None-Match | standard | 13.1.2 | | 9065 +---------------------------+------------+--------+------------+ 9066 | If-Range | standard | 13.1.5 | | 9067 +---------------------------+------------+--------+------------+ 9068 | If-Unmodified-Since | standard | 13.1.4 | | 9069 +---------------------------+------------+--------+------------+ 9070 | Last-Modified | standard | 8.8.2 | | 9071 +---------------------------+------------+--------+------------+ 9072 | Location | standard | 10.2.3 | | 9073 +---------------------------+------------+--------+------------+ 9074 | Max-Forwards | standard | 7.6.2 | | 9075 +---------------------------+------------+--------+------------+ 9076 | Proxy-Authenticate | standard | 11.7.1 | | 9077 +---------------------------+------------+--------+------------+ 9078 | Proxy-Authentication-Info | standard | 11.7.3 | | 9079 +---------------------------+------------+--------+------------+ 9080 | Proxy-Authorization | standard | 11.7.2 | | 9081 +---------------------------+------------+--------+------------+ 9082 | Range | standard | 14.2 | | 9083 +---------------------------+------------+--------+------------+ 9084 | Referer | standard | 10.1.3 | | 9085 +---------------------------+------------+--------+------------+ 9086 | Retry-After | standard | 10.2.4 | | 9087 +---------------------------+------------+--------+------------+ 9088 | Server | standard | 10.2.5 | | 9089 +---------------------------+------------+--------+------------+ 9090 | TE | standard | 10.1.4 | | 9091 +---------------------------+------------+--------+------------+ 9092 | Trailer | standard | 10.1.5 | | 9093 +---------------------------+------------+--------+------------+ 9094 | Upgrade | standard | 7.8 | | 9095 +---------------------------+------------+--------+------------+ 9096 | User-Agent | standard | 10.1.6 | | 9097 +---------------------------+------------+--------+------------+ 9098 | Vary | standard | 12.5.5 | | 9099 +---------------------------+------------+--------+------------+ 9100 | Via | standard | 7.6.3 | | 9101 +---------------------------+------------+--------+------------+ 9102 | WWW-Authenticate | standard | 11.6.1 | | 9103 +---------------------------+------------+--------+------------+ 9104 | * | standard | 12.5.5 | (reserved) | 9105 +---------------------------+------------+--------+------------+ 9107 Table 9 9109 The field name "*" is reserved, since using that name as an HTTP 9110 header field might conflict with its special semantics in the Vary 9111 header field (Section 12.5.5). 9113 Finally, please update the "Content-MD5" entry in the new registry to 9114 have a status of 'obsoleted' with references to Section 14.15 of 9115 [RFC2616] (for the definition of the header field) and Appendix B of 9116 [RFC7231] (which removed the field definition from the updated 9117 specification). 9119 18.5. Authentication Scheme Registration 9121 Please update the "Hypertext Transfer Protocol (HTTP) Authentication 9122 Scheme Registry" at with the registration procedure of Section 16.4.1. No 9124 authentication schemes are defined in this document. 9126 18.6. Content Coding Registration 9128 Please update the "HTTP Content Coding Registry" at 9129 with the 9130 registration procedure of Section 16.6.1 and the content coding names 9131 summarized in the table below. 9133 +============+===========================================+=========+ 9134 | Name | Description | Ref. | 9135 +============+===========================================+=========+ 9136 | compress | UNIX "compress" data format [Welch] | 8.4.1.1 | 9137 +------------+-------------------------------------------+---------+ 9138 | deflate | "deflate" compressed data ([RFC1951]) | 8.4.1.2 | 9139 | | inside the "zlib" data format ([RFC1950]) | | 9140 +------------+-------------------------------------------+---------+ 9141 | gzip | GZIP file format [RFC1952] | 8.4.1.3 | 9142 +------------+-------------------------------------------+---------+ 9143 | identity | Reserved | 12.5.3 | 9144 +------------+-------------------------------------------+---------+ 9145 | x-compress | Deprecated (alias for compress) | 8.4.1.1 | 9146 +------------+-------------------------------------------+---------+ 9147 | x-gzip | Deprecated (alias for gzip) | 8.4.1.3 | 9148 +------------+-------------------------------------------+---------+ 9150 Table 10 9152 18.7. Range Unit Registration 9154 Please update the "HTTP Range Unit Registry" at 9155 with the 9156 registration procedure of Section 16.5.1 and the range unit names 9157 summarized in the table below. 9159 +=================+==================================+========+ 9160 | Range Unit Name | Description | Ref. | 9161 +=================+==================================+========+ 9162 | bytes | a range of octets | 14.1.2 | 9163 +-----------------+----------------------------------+--------+ 9164 | none | reserved as keyword to indicate | 14.3 | 9165 | | range requests are not supported | | 9166 +-----------------+----------------------------------+--------+ 9168 Table 11 9170 18.8. Media Type Registration 9172 Please update the "Media Types" registry at 9173 with the registration 9174 information in Section 14.6 for the media type "multipart/ 9175 byteranges". 9177 18.9. Port Registration 9179 Please update the "Service Name and Transport Protocol Port Number" 9180 registry at for the services on ports 80 and 443 that use UDP or TCP 9182 to: 9184 1. use this document as "Reference", and 9186 2. when currently unspecified, set "Assignee" to "IESG" and 9187 "Contact" to "IETF_Chair". 9189 18.10. Upgrade Token Registration 9191 Please update the "Hypertext Transfer Protocol (HTTP) Upgrade Token 9192 Registry" at 9193 with the registration procedure of Section 16.7 and the upgrade token 9194 names summarized in the following table. 9196 +======+===================+=========================+======+ 9197 | Name | Description | Expected Version Tokens | Ref. | 9198 +======+===================+=========================+======+ 9199 | HTTP | Hypertext | any DIGIT.DIGIT (e.g, | 2.5 | 9200 | | Transfer Protocol | "2.0") | | 9201 +------+-------------------+-------------------------+------+ 9203 Table 12 9205 19. References 9207 19.1. Normative References 9209 [Caching] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 9210 Ed., "HTTP Caching", Work in Progress, Internet-Draft, 9211 draft-ietf-httpbis-cache-16, 27 May 2021, 9212 . 9214 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 9215 RFC 793, DOI 10.17487/RFC0793, September 1981, 9216 . 9218 [RFC1950] Deutsch, L.P. and J-L. Gailly, "ZLIB Compressed Data 9219 Format Specification version 3.3", RFC 1950, 9220 DOI 10.17487/RFC1950, May 1996, 9221 . 9223 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 9224 version 1.3", RFC 1951, DOI 10.17487/RFC1951, May 1996, 9225 . 9227 [RFC1952] Deutsch, P., Gailly, J-L., Adler, M., Deutsch, L.P., and 9228 G. Randers-Pehrson, "GZIP file format specification 9229 version 4.3", RFC 1952, DOI 10.17487/RFC1952, May 1996, 9230 . 9232 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 9233 Extensions (MIME) Part Two: Media Types", RFC 2046, 9234 DOI 10.17487/RFC2046, November 1996, 9235 . 9237 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 9238 Requirement Levels", BCP 14, RFC 2119, 9239 DOI 10.17487/RFC2119, March 1997, 9240 . 9242 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 9243 Resource Identifier (URI): Generic Syntax", STD 66, 9244 RFC 3986, DOI 10.17487/RFC3986, January 2005, 9245 . 9247 [RFC4647] Phillips, A., Ed. and M. Davis, Ed., "Matching of Language 9248 Tags", BCP 47, RFC 4647, DOI 10.17487/RFC4647, September 9249 2006, . 9251 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 9252 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 9253 . 9255 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 9256 Specifications: ABNF", STD 68, RFC 5234, 9257 DOI 10.17487/RFC5234, January 2008, 9258 . 9260 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 9261 Housley, R., and W. Polk, "Internet X.509 Public Key 9262 Infrastructure Certificate and Certificate Revocation List 9263 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 9264 . 9266 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 9267 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 9268 September 2009, . 9270 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 9271 Verification of Domain-Based Application Service Identity 9272 within Internet Public Key Infrastructure Using X.509 9273 (PKIX) Certificates in the Context of Transport Layer 9274 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 9275 2011, . 9277 [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in 9278 Internationalization in the IETF", BCP 166, RFC 6365, 9279 DOI 10.17487/RFC6365, September 2011, 9280 . 9282 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 9283 RFC 7405, DOI 10.17487/RFC7405, December 2014, 9284 . 9286 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 9287 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 9288 May 2017, . 9290 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 9291 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 9292 . 9294 [USASCII] American National Standards Institute, "Coded Character 9295 Set -- 7-bit American Standard Code for Information 9296 Interchange", ANSI X3.4, 1986. 9298 [Welch] Welch, T. A., "A Technique for High-Performance Data 9299 Compression", IEEE Computer 17(6), 9300 DOI 10.1109/MC.1984.1659158, June 1984, 9301 . 9303 19.2. Informative References 9305 [BCP13] Freed, N., Klensin, J., and T. Hansen, "Media Type 9306 Specifications and Registration Procedures", BCP 13, 9307 RFC 6838, January 2013, 9308 . 9310 [BCP178] Saint-Andre, P., Crocker, D., and M. Nottingham, 9311 "Deprecating the "X-" Prefix and Similar Constructs in 9312 Application Protocols", BCP 178, RFC 6648, June 2012, 9313 . 9315 [BCP35] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 9316 and Registration Procedures for URI Schemes", BCP 35, 9317 RFC 7595, June 2015, 9318 . 9320 [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving the 9321 CRIME Attack", July 2013, 9322 . 9325 [Bujlow] Bujlow, T., Carela-Espanol, V., Sole-Pareta, J., and P. 9326 Barlet-Ros, "A Survey on Web Tracking: Mechanisms, 9327 Implications, and Defenses", 9328 DOI 10.1109/JPROC.2016.2637878, Proceedings of the 9329 IEEE 105(8), August 2017, 9330 . 9332 [Err1912] RFC Errata, Erratum ID 1912, RFC 2978, 9333 . 9335 [Err5433] RFC Errata, Erratum ID 5433, RFC 2978, 9336 . 9338 [Georgiev] Georgiev, M., Iyengar, S., Jana, S., Anubhai, R., Boneh, 9339 D., and V. Shmatikov, "The Most Dangerous Code in the 9340 World: Validating SSL Certificates in Non-browser 9341 Software", DOI 10.1145/2382196.2382204, In Proceedings of 9342 the 2012 ACM Conference on Computer and Communications 9343 Security (CCS '12), pp. 38-49, October 2012, 9344 . 9346 [HTTP3] Bishop, M., "Hypertext Transfer Protocol Version 3 9347 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 9348 quic-http-34, 2 February 2021, 9349 . 9351 [ISO-8859-1] 9352 International Organization for Standardization, 9353 "Information technology -- 8-bit single-byte coded graphic 9354 character sets -- Part 1: Latin alphabet No. 1", ISO/ 9355 IEC 8859-1:1998, 1998. 9357 [Kri2001] Kristol, D., "HTTP Cookies: Standards, Privacy, and 9358 Politics", ACM Transactions on Internet Technology 1(2), 9359 November 2001, . 9361 [Messaging] 9362 Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 9363 Ed., "HTTP/1.1", Work in Progress, Internet-Draft, draft- 9364 ietf-httpbis-messaging-16, 27 May 2021, 9365 . 9368 [OWASP] van der Stock, A., Ed., "A Guide to Building Secure Web 9369 Applications and Web Services", The Open Web Application 9370 Security Project (OWASP) 2.0.1, 27 July 2005, 9371 . 9373 [REST] Fielding, R.T., "Architectural Styles and the Design of 9374 Network-based Software Architectures", 9375 Doctoral Dissertation, University of California, Irvine, 9376 September 2000, 9377 . 9379 [RFC1919] Chatel, M., "Classical versus Transparent IP Proxies", 9380 RFC 1919, DOI 10.17487/RFC1919, March 1996, 9381 . 9383 [RFC1945] Berners-Lee, T., Fielding, R.T., and H.F. Nielsen, 9384 "Hypertext Transfer Protocol -- HTTP/1.0", RFC 1945, 9385 DOI 10.17487/RFC1945, May 1996, 9386 . 9388 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 9389 Part Three: Message Header Extensions for Non-ASCII Text", 9390 RFC 2047, DOI 10.17487/RFC2047, November 1996, 9391 . 9393 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T. 9394 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", 9395 RFC 2068, DOI 10.17487/RFC2068, January 1997, 9396 . 9398 [RFC2145] Mogul, J.C., Fielding, R.T., Gettys, J., and H.F. Nielsen, 9399 "Use and Interpretation of HTTP Version Numbers", 9400 RFC 2145, DOI 10.17487/RFC2145, May 1997, 9401 . 9403 [RFC2295] Holtman, K. and A.H. Mutz, "Transparent Content 9404 Negotiation in HTTP", RFC 2295, DOI 10.17487/RFC2295, 9405 March 1998, . 9407 [RFC2324] Masinter, L., "Hyper Text Coffee Pot Control Protocol 9408 (HTCPCP/1.0)", RFC 2324, DOI 10.17487/RFC2324, 1 April 9409 1998, . 9411 [RFC2557] Palme, F., Hopmann, A., Shelness, N., and E. Stefferud, 9412 "MIME Encapsulation of Aggregate Documents, such as HTML 9413 (MHTML)", RFC 2557, DOI 10.17487/RFC2557, March 1999, 9414 . 9416 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 9417 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 9418 Transfer Protocol -- HTTP/1.1", RFC 2616, 9419 DOI 10.17487/RFC2616, June 1999, 9420 . 9422 [RFC2617] Franks, J., Hallam-Baker, P.M., Hostetler, J.L., Lawrence, 9423 S.D., Leach, P.J., Luotonen, A., and L. Stewart, "HTTP 9424 Authentication: Basic and Digest Access Authentication", 9425 RFC 2617, DOI 10.17487/RFC2617, June 1999, 9426 . 9428 [RFC2774] Frystyk, H., Leach, P., and S. Lawrence, "An HTTP 9429 Extension Framework", RFC 2774, DOI 10.17487/RFC2774, 9430 February 2000, . 9432 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 9433 DOI 10.17487/RFC2818, May 2000, 9434 . 9436 [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration 9437 Procedures", BCP 19, RFC 2978, DOI 10.17487/RFC2978, 9438 October 2000, . 9440 [RFC3040] Cooper, I., Melve, I., and G. Tomlinson, "Internet Web 9441 Replication and Caching Taxonomy", RFC 3040, 9442 DOI 10.17487/RFC3040, January 2001, 9443 . 9445 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 9446 Procedures for Message Header Fields", BCP 90, RFC 3864, 9447 DOI 10.17487/RFC3864, September 2004, 9448 . 9450 [RFC3875] Robinson, D. and K. Coar, "The Common Gateway Interface 9451 (CGI) Version 1.1", RFC 3875, DOI 10.17487/RFC3875, 9452 October 2004, . 9454 [RFC4033] Arends, R., Austein, R., Larson, M., Massey, D., and S. 9455 Rose, "DNS Security Introduction and Requirements", 9456 RFC 4033, DOI 10.17487/RFC4033, March 2005, 9457 . 9459 [RFC4559] Jaganathan, K., Zhu, L., and J. Brezak, "SPNEGO-based 9460 Kerberos and NTLM HTTP Authentication in Microsoft 9461 Windows", RFC 4559, DOI 10.17487/RFC4559, June 2006, 9462 . 9464 [RFC4918] Dusseault, L.M., Ed., "HTTP Extensions for Web Distributed 9465 Authoring and Versioning (WebDAV)", RFC 4918, 9466 DOI 10.17487/RFC4918, June 2007, 9467 . 9469 [RFC5322] Resnick, P., "Internet Message Format", RFC 5322, 9470 DOI 10.17487/RFC5322, October 2008, 9471 . 9473 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 9474 RFC 5789, DOI 10.17487/RFC5789, March 2010, 9475 . 9477 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 9478 "Network Time Protocol Version 4: Protocol and Algorithms 9479 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 9480 . 9482 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 9483 DOI 10.17487/RFC6265, April 2011, 9484 . 9486 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 9487 DOI 10.17487/RFC6454, December 2011, 9488 . 9490 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 9491 Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, 9492 . 9494 [RFC7230] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9495 Transfer Protocol (HTTP/1.1): Message Syntax and Routing", 9496 RFC 7230, DOI 10.17487/RFC7230, June 2014, 9497 . 9499 [RFC7231] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9500 Transfer Protocol (HTTP/1.1): Semantics and Content", 9501 RFC 7231, DOI 10.17487/RFC7231, June 2014, 9502 . 9504 [RFC7232] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9505 Transfer Protocol (HTTP/1.1): Conditional Requests", 9506 RFC 7232, DOI 10.17487/RFC7232, June 2014, 9507 . 9509 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. F. Reschke, Ed., 9510 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 9511 RFC 7233, DOI 10.17487/RFC7233, June 2014, 9512 . 9514 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. F. Reschke, 9515 Ed., "Hypertext Transfer Protocol (HTTP): Caching", 9516 RFC 7234, DOI 10.17487/RFC7234, June 2014, 9517 . 9519 [RFC7235] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9520 Transfer Protocol (HTTP/1.1): Authentication", RFC 7235, 9521 DOI 10.17487/RFC7235, June 2014, 9522 . 9524 [RFC7538] Reschke, J. F., "The Hypertext Transfer Protocol Status 9525 Code 308 (Permanent Redirect)", RFC 7538, 9526 DOI 10.17487/RFC7538, April 2015, 9527 . 9529 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 9530 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 9531 DOI 10.17487/RFC7540, May 2015, 9532 . 9534 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 9535 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 9536 . 9538 [RFC7578] Masinter, L., "Returning Values from Forms: multipart/ 9539 form-data", RFC 7578, DOI 10.17487/RFC7578, July 2015, 9540 . 9542 [RFC7615] Reschke, J. F., "HTTP Authentication-Info and Proxy- 9543 Authentication-Info Response Header Fields", RFC 7615, 9544 DOI 10.17487/RFC7615, September 2015, 9545 . 9547 [RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP 9548 Digest Access Authentication", RFC 7616, 9549 DOI 10.17487/RFC7616, September 2015, 9550 . 9552 [RFC7617] Reschke, J. F., "The 'Basic' HTTP Authentication Scheme", 9553 RFC 7617, DOI 10.17487/RFC7617, September 2015, 9554 . 9556 [RFC7694] Reschke, J. F., "Hypertext Transfer Protocol (HTTP) 9557 Client-Initiated Content-Encoding", RFC 7694, 9558 DOI 10.17487/RFC7694, November 2015, 9559 . 9561 [RFC7838] Nottingham, M., McManus, P., and J. Reschke, "HTTP 9562 Alternative Services", RFC 7838, DOI 10.17487/RFC7838, 9563 April 2016, . 9565 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 9566 Writing an IANA Considerations Section in RFCs", BCP 26, 9567 RFC 8126, DOI 10.17487/RFC8126, June 2017, 9568 . 9570 [RFC8187] Reschke, J. F., "Indicating Character Encoding and 9571 Language for HTTP Header Field Parameters", RFC 8187, 9572 DOI 10.17487/RFC8187, September 2017, 9573 . 9575 [RFC8246] McManus, P., "HTTP Immutable Responses", RFC 8246, 9576 DOI 10.17487/RFC8246, September 2017, 9577 . 9579 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 9580 DOI 10.17487/RFC8288, October 2017, 9581 . 9583 [RFC8336] Nottingham, M. and E. Nygren, "The ORIGIN HTTP/2 Frame", 9584 RFC 8336, DOI 10.17487/RFC8336, March 2018, 9585 . 9587 [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers 9588 (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, 9589 . 9591 [RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for 9592 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 9593 . 9595 [Sniffing] WHATWG, "MIME Sniffing", 9596 . 9598 Appendix A. Collected ABNF 9600 In the collected ABNF below, list rules are expanded as per 9601 Section 5.6.1.1. 9603 Accept = [ ( media-range [ weight ] ) *( OWS "," OWS ( media-range [ 9604 weight ] ) ) ] 9605 Accept-Charset = [ ( ( token / "*" ) [ weight ] ) *( OWS "," OWS ( ( 9606 token / "*" ) [ weight ] ) ) ] 9607 Accept-Encoding = [ ( codings [ weight ] ) *( OWS "," OWS ( codings [ 9608 weight ] ) ) ] 9609 Accept-Language = [ ( language-range [ weight ] ) *( OWS "," OWS ( 9610 language-range [ weight ] ) ) ] 9611 Accept-Ranges = acceptable-ranges 9612 Allow = [ method *( OWS "," OWS method ) ] 9613 Authentication-Info = [ auth-param *( OWS "," OWS auth-param ) ] 9614 Authorization = credentials 9616 BWS = OWS 9618 Connection = [ connection-option *( OWS "," OWS connection-option ) 9619 ] 9620 Content-Encoding = [ content-coding *( OWS "," OWS content-coding ) 9621 ] 9622 Content-Language = [ language-tag *( OWS "," OWS language-tag ) ] 9623 Content-Length = 1*DIGIT 9624 Content-Location = absolute-URI / partial-URI 9625 Content-Range = range-unit SP ( range-resp / unsatisfied-range ) 9626 Content-Type = media-type 9628 Date = HTTP-date 9630 ETag = entity-tag 9631 Expect = [ expectation *( OWS "," OWS expectation ) ] 9633 From = mailbox 9635 GMT = %x47.4D.54 ; GMT 9637 HTTP-date = IMF-fixdate / obs-date 9638 Host = uri-host [ ":" port ] 9640 IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT 9641 If-Match = "*" / [ entity-tag *( OWS "," OWS entity-tag ) ] 9642 If-Modified-Since = HTTP-date 9643 If-None-Match = "*" / [ entity-tag *( OWS "," OWS entity-tag ) ] 9644 If-Range = entity-tag / HTTP-date 9645 If-Unmodified-Since = HTTP-date 9647 Last-Modified = HTTP-date 9648 Location = URI-reference 9650 Max-Forwards = 1*DIGIT 9652 OWS = *( SP / HTAB ) 9654 Proxy-Authenticate = [ challenge *( OWS "," OWS challenge ) ] 9655 Proxy-Authentication-Info = [ auth-param *( OWS "," OWS auth-param ) 9656 ] 9657 Proxy-Authorization = credentials 9659 RWS = 1*( SP / HTAB ) 9660 Range = ranges-specifier 9661 Referer = absolute-URI / partial-URI 9662 Retry-After = HTTP-date / delay-seconds 9664 Server = product *( RWS ( product / comment ) ) 9666 TE = [ t-codings *( OWS "," OWS t-codings ) ] 9667 Trailer = [ field-name *( OWS "," OWS field-name ) ] 9669 URI-reference = 9670 Upgrade = [ protocol *( OWS "," OWS protocol ) ] 9671 User-Agent = product *( RWS ( product / comment ) ) 9673 Vary = [ ( "*" / field-name ) *( OWS "," OWS ( "*" / field-name ) ) 9674 ] 9675 Via = [ ( received-protocol RWS received-by [ RWS comment ] ) *( OWS 9676 "," OWS ( received-protocol RWS received-by [ RWS comment ] ) ) ] 9678 WWW-Authenticate = [ challenge *( OWS "," OWS challenge ) ] 9680 absolute-URI = 9681 absolute-path = 1*( "/" segment ) 9682 acceptable-ranges = ( range-unit *( OWS "," OWS range-unit ) ) / 9683 "none" 9684 asctime-date = day-name SP date3 SP time-of-day SP year 9685 auth-param = token BWS "=" BWS ( token / quoted-string ) 9686 auth-scheme = token 9687 authority = 9689 challenge = auth-scheme [ 1*SP ( token68 / [ auth-param *( OWS "," 9690 OWS auth-param ) ] ) ] 9692 codings = content-coding / "identity" / "*" 9693 comment = "(" *( ctext / quoted-pair / comment ) ")" 9694 complete-length = 1*DIGIT 9695 connection-option = token 9696 content-coding = token 9697 credentials = auth-scheme [ 1*SP ( token68 / [ auth-param *( OWS "," 9698 OWS auth-param ) ] ) ] 9699 ctext = HTAB / SP / %x21-27 ; '!'-''' 9700 / %x2A-5B ; '*'-'[' 9701 / %x5D-7E ; ']'-'~' 9702 / obs-text 9704 date1 = day SP month SP year 9705 date2 = day "-" month "-" 2DIGIT 9706 date3 = month SP ( 2DIGIT / ( SP DIGIT ) ) 9707 day = 2DIGIT 9708 day-name = %x4D.6F.6E ; Mon 9709 / %x54.75.65 ; Tue 9710 / %x57.65.64 ; Wed 9711 / %x54.68.75 ; Thu 9712 / %x46.72.69 ; Fri 9713 / %x53.61.74 ; Sat 9714 / %x53.75.6E ; Sun 9715 day-name-l = %x4D.6F.6E.64.61.79 ; Monday 9716 / %x54.75.65.73.64.61.79 ; Tuesday 9717 / %x57.65.64.6E.65.73.64.61.79 ; Wednesday 9718 / %x54.68.75.72.73.64.61.79 ; Thursday 9719 / %x46.72.69.64.61.79 ; Friday 9720 / %x53.61.74.75.72.64.61.79 ; Saturday 9721 / %x53.75.6E.64.61.79 ; Sunday 9722 delay-seconds = 1*DIGIT 9724 entity-tag = [ weak ] opaque-tag 9725 etagc = "!" / %x23-7E ; '#'-'~' 9726 / obs-text 9727 expectation = token [ "=" ( token / quoted-string ) parameters ] 9729 field-content = field-vchar [ 1*( SP / HTAB / field-vchar ) 9730 field-vchar ] 9731 field-name = token 9732 field-value = *field-content 9733 field-vchar = VCHAR / obs-text 9734 first-pos = 1*DIGIT 9736 hour = 2DIGIT 9737 http-URI = "http://" authority path-abempty [ "?" query ] 9738 https-URI = "https://" authority path-abempty [ "?" query ] 9739 incl-range = first-pos "-" last-pos 9740 int-range = first-pos "-" [ last-pos ] 9742 language-range = 9743 language-tag = 9744 last-pos = 1*DIGIT 9746 mailbox = 9747 media-range = ( "*/*" / ( type "/*" ) / ( type "/" subtype ) ) 9748 parameters 9749 media-type = type "/" subtype parameters 9750 method = token 9751 minute = 2DIGIT 9752 month = %x4A.61.6E ; Jan 9753 / %x46.65.62 ; Feb 9754 / %x4D.61.72 ; Mar 9755 / %x41.70.72 ; Apr 9756 / %x4D.61.79 ; May 9757 / %x4A.75.6E ; Jun 9758 / %x4A.75.6C ; Jul 9759 / %x41.75.67 ; Aug 9760 / %x53.65.70 ; Sep 9761 / %x4F.63.74 ; Oct 9762 / %x4E.6F.76 ; Nov 9763 / %x44.65.63 ; Dec 9765 obs-date = rfc850-date / asctime-date 9766 obs-text = %x80-FF 9767 opaque-tag = DQUOTE *etagc DQUOTE 9768 other-range = 1*( %x21-2B ; '!'-'+' 9769 / %x2D-7E ; '-'-'~' 9770 ) 9772 parameter = parameter-name "=" parameter-value 9773 parameter-name = token 9774 parameter-value = ( token / quoted-string ) 9775 parameters = *( OWS ";" OWS [ parameter ] ) 9776 partial-URI = relative-part [ "?" query ] 9777 path-abempty = 9778 port = 9779 product = token [ "/" product-version ] 9780 product-version = token 9781 protocol = protocol-name [ "/" protocol-version ] 9782 protocol-name = token 9783 protocol-version = token 9784 pseudonym = token 9786 qdtext = HTAB / SP / "!" / %x23-5B ; '#'-'[' 9787 / %x5D-7E ; ']'-'~' 9788 / obs-text 9789 query = 9790 quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) 9791 quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE 9792 qvalue = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] ) 9794 range-resp = incl-range "/" ( complete-length / "*" ) 9795 range-set = range-spec *( OWS "," OWS range-spec ) 9796 range-spec = int-range / suffix-range / other-range 9797 range-unit = token 9798 ranges-specifier = range-unit "=" range-set 9799 received-by = pseudonym [ ":" port ] 9800 received-protocol = [ protocol-name "/" ] protocol-version 9801 relative-part = 9802 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 9804 second = 2DIGIT 9805 segment = 9806 subtype = token 9807 suffix-length = 1*DIGIT 9808 suffix-range = "-" suffix-length 9810 t-codings = "trailers" / ( transfer-coding [ weight ] ) 9811 tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / 9812 "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA 9813 time-of-day = hour ":" minute ":" second 9814 token = 1*tchar 9815 token68 = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" ) 9816 *"=" 9817 transfer-coding = token *( OWS ";" OWS transfer-parameter ) 9818 transfer-parameter = token BWS "=" BWS ( token / quoted-string ) 9819 type = token 9821 unsatisfied-range = "*/" complete-length 9822 uri-host = 9824 weak = %x57.2F ; W/ 9825 weight = OWS ";" OWS "q=" qvalue 9827 year = 4DIGIT 9829 Appendix B. Changes from previous RFCs 9831 B.1. Changes from RFC 2818 9833 None. 9835 B.2. Changes from RFC 7230 9837 The sections introducing HTTP's design goals, history, architecture, 9838 conformance criteria, protocol versioning, URIs, message routing, and 9839 header fields have been moved here. 9841 The requirement on semantic conformance has been replaced with 9842 permission to ignore/workaround implementation-specific failures. 9843 (Section 2.2) 9845 The description of an origin and authoritative access to origin 9846 servers has been extended for both "http" and "https" URIs to account 9847 for alternative services and secured connections that are not 9848 necessarily based on TCP. (Section 4.2.1, Section 4.2.2, 9849 Section 4.3.1, Section 7.3.3) 9851 Parameters in media type, media range, and expectation can be empty 9852 via one or more trailing semicolons. (Section 5.6.6) 9854 "Field value" now refers to the value after multiple field lines are 9855 combined with commas - by far the most common use. To refer to a 9856 single header line's value, use "field line value". (Section 6.3) 9858 Trailer field semantics now transcend the specifics of chunked 9859 encoding. Use of trailer fields has been further limited to only 9860 allow generation as a trailer field when the sender knows the field 9861 defines that usage and to only allow merging into the header section 9862 if the recipient knows the corresponding field definition permits and 9863 defines how to merge. In all other cases, implementations are 9864 encouraged to either store the trailer fields separately or discard 9865 them instead of merging. (Section 6.5.1) 9867 Made the priority of the absolute form of the request URI over the 9868 Host header by origin servers explicit, to align with proxy handling. 9869 (Section 7.2) 9871 The grammar definition for the Via field's "received-by" was expanded 9872 in 7230 due to changes in the URI grammar for host [RFC3986] that are 9873 not desirable for Via. For simplicity, we have removed uri-host from 9874 the received-by production because it can be encompassed by the 9875 existing grammar for pseudonym. In particular, this change removed 9876 comma from the allowed set of charaters for a host name in received- 9877 by. (Section 7.6.3) 9879 B.3. Changes from RFC 7231 9881 Minimum URI lengths to be supported by implementations are now 9882 recommended. (Section 3.1) 9883 Clarified that CR and NUL in field values are to be rejected or 9884 mapped to SP and that leading and trailing whitespace need to be 9885 stripped from field values before they are consumed. (Section 5.5) 9887 Parameters in media type, media range, and expectation can be empty 9888 via one or more trailing semicolons. (Section 5.6.6) 9890 An abstract data type for HTTP messages has been introduced to define 9891 the components of a message and their semantics as an abstraction 9892 across multiple HTTP versions, rather than in terms of the specific 9893 syntax form of HTTP/1.1 in [Messaging], and reflect the contents 9894 after the message is parsed. This makes it easier to distinguish 9895 between requirements on the content (what is conveyed) versus 9896 requirements on the messaging syntax (how it is conveyed) and avoids 9897 baking limitations of early protocol versions into the future of 9898 HTTP. (Section 6) 9900 The terms "payload" and "payload body" have been replaced with 9901 "content", to better align with its usage elsewhere (e.g., in field 9902 names) and to avoid confusion with frame payloads in HTTP/2 and 9903 HTTP/3. (Section 6.4) 9905 The term "effective request URI" has been replaced with "target URI". 9906 (Section 7.1) 9908 Restrictions on client retries have been loosened, to reflect 9909 implementation behavior. (Section 9.2.2) 9911 Clarified that request bodies on GET, HEAD, and DELETE are not 9912 interoperable. (Section 9.3.1, Section 9.3.2, Section 9.3.5) 9914 Allowed use of the Content-Range header field (Section 14.4) as a 9915 request modifier on PUT. (Section 9.3.4) 9917 Removed a superfluous requirement about setting Content-Length from 9918 the description of the OPTIONS method. (Section 9.3.7) 9920 Removed normative requirement to use the "message/http" media type in 9921 TRACE responses. (Section 9.3.8) 9923 Restore list-based grammar for Expect for compatibility with RFC 9924 2616. (Section 10.1.1) 9926 Allow Accept and Accept-Encoding in response messages; the latter was 9927 introduced by [RFC7694]. (Section 12.3) 9929 "Accept Parameters" (accept-params) have been removed from the 9930 definition of the Accept field. (Section 12.5.1) 9931 The semantics of "*" in the Vary header field when other values are 9932 present was clarified. (Section 12.5.5) 9934 Range units are compared in a case insensitive fashion. 9935 (Section 14.1) 9937 The process of creating a redirected request has been clarified. 9938 (Section 15.4) 9940 Added status code 308 (previously defined in [RFC7538]) so that it's 9941 defined closer to status codes 301, 302, and 307. (Section 15.4.9) 9943 Added status code 421 (previously defined in Section 9.1.2 of 9944 [RFC7540]) because of its general applicability. 421 is no longer 9945 defined as heuristically cacheable, since the response is specific to 9946 the connection (not the target resource). (Section 15.5.20) 9948 Added status code 422 (previously defined in Section 11.2 of 9949 [RFC4918]) because of its general applicability. (Section 15.5.21) 9951 B.4. Changes from RFC 7232 9953 Previous revisions of HTTP imposed an arbitrary 60-second limit on 9954 the determination of whether Last-Modified was a strong validator to 9955 guard against the possibility that the Date and Last-Modified values 9956 are generated from different clocks or at somewhat different times 9957 during the preparation of the response. This specification has 9958 relaxed that to allow reasonable discretion. (Section 8.8.2.2) 9960 Removed edge case requirement on If-Match and If-Unmodified-Since 9961 that a validator not be sent in a 2xx response when validation fails 9962 and the server decides that the same change request has already been 9963 applied. (Section 13.1.1 and Section 13.1.4) 9965 Clarified that If-Unmodified-Since doesn't apply to a resource 9966 without a concept of modification time. (Section 13.1.4) 9968 Preconditions can now be evaluated before the request content is 9969 processed rather than waiting until the response would otherwise be 9970 successful. (Section 13.2) 9972 B.5. Changes from RFC 7233 9974 Refactored the range-unit and ranges-specifier grammars to simplify 9975 and reduce artificial distinctions between bytes and other 9976 (extension) range units, removing the overlapping grammar of other- 9977 range-unit by defining range units generically as a token and placing 9978 extensions within the scope of a range-spec (other-range). This 9979 disambiguates the role of list syntax (commas) in all range sets, 9980 including extension range units, for indicating a range-set of more 9981 than one range. Moving the extension grammar into range specifiers 9982 also allows protocol specific to byte ranges to be specified 9983 separately. 9985 It is now possible to define Range handling on extension methods. 9986 (Section 14.2) 9988 Described use of the Content-Range header field (Section 14.4) as a 9989 request modifier to perform a partial PUT. (Section 14.5) 9991 B.6. Changes from RFC 7235 9993 None. 9995 B.7. Changes from RFC 7538 9997 None. 9999 B.8. Changes from RFC 7615 10001 None. 10003 B.9. Changes from RFC 7694 10005 This specification includes the extension defined in [RFC7694], but 10006 leaves out examples and deployment considerations. 10008 Appendix C. Change Log 10010 This section is to be removed before publishing as an RFC. 10012 C.1. Between RFC723x and draft 00 10014 The changes were purely editorial: 10016 * Change boilerplate and abstract to indicate the "draft" status, 10017 and update references to ancestor specifications. 10019 * Remove version "1.1" from document title, indicating that this 10020 specification applies to all HTTP versions. 10022 * Adjust historical notes. 10024 * Update links to sibling specifications. 10026 * Replace sections listing changes from RFC 2616 by new empty 10027 sections referring to RFC 723x. 10029 * Remove acknowledgements specific to RFC 723x. 10031 * Move "Acknowledgements" to the very end and make them unnumbered. 10033 C.2. Since draft-ietf-httpbis-semantics-00 10035 The changes in this draft are editorial, with respect to HTTP as a 10036 whole, to merge core HTTP semantics into this document: 10038 * Merged introduction, architecture, conformance, and ABNF 10039 extensions from RFC 7230 (Messaging). 10041 * Rearranged architecture to extract conformance, http(s) schemes, 10042 and protocol versioning into a separate major section. 10044 * Moved discussion of MIME differences to [Messaging] since that is 10045 primarily concerned with transforming 1.1 messages. 10047 * Merged entire content of RFC 7232 (Conditional Requests). 10049 * Merged entire content of RFC 7233 (Range Requests). 10051 * Merged entire content of RFC 7235 (Auth Framework). 10053 * Moved all extensibility tips, registration procedures, and 10054 registry tables from the IANA considerations to normative 10055 sections, reducing the IANA considerations to just instructions 10056 that will be removed prior to publication as an RFC. 10058 C.3. Since draft-ietf-httpbis-semantics-01 10060 * Improve [Welch] citation () 10063 * Remove HTTP/1.1-ism about Range Requests 10064 () 10066 * Cite RFC 8126 instead of RFC 5226 () 10069 * Cite RFC 7538 instead of RFC 7238 () 10072 * Cite RFC 8288 instead of RFC 5988 () 10075 * Cite RFC 8187 instead of RFC 5987 () 10078 * Cite RFC 7578 instead of RFC 2388 () 10081 * Cite RFC 7595 instead of RFC 4395 () 10084 * improve ABNF readability for qdtext (, ) 10087 * Clarify "resource" vs "representation" in definition of status 10088 code 416 (, 10089 ) 10091 * Resolved erratum 4072, no change needed here 10092 (, 10093 ) 10095 * Clarify DELETE status code suggestions 10096 (, 10097 ) 10099 * In Section 14.4, fix ABNF for "other-range-resp" to use VCHAR 10100 instead of CHAR (, 10101 ) 10103 * Resolved erratum 5162, no change needed here 10104 (, 10105 ) 10107 * Replace "response code" with "response status code" and "status- 10108 code" (the ABNF production name from the HTTP/1.1 message format) 10109 by "status code" (, 10110 ) 10112 * Added a missing word in Section 15.4 (, ) 10115 * In Section 5.6.1, fixed an example that had trailing whitespace 10116 where it shouldn't (, ) 10119 * In Section 15.3.7, remove words that were potentially misleading 10120 with respect to the relation to the requested ranges 10121 (, 10122 ) 10124 C.4. Since draft-ietf-httpbis-semantics-02 10126 * Included (Proxy-)Auth-Info header field definition from RFC 7615 10127 () 10129 * In Section 9.3.3, clarify POST caching 10130 () 10132 * Add Section 15.5.19 to reserve the 418 status code 10133 () 10135 * In Section 3.4 and Section 10.1.1, clarified when a response can 10136 be sent () 10138 * In Section 8.3.2, explain the difference between the "token" 10139 production, the RFC 2978 ABNF for charset names, and the actual 10140 registration practice (, ) 10143 * In Section 3.1, removed the fragment component in the URI scheme 10144 definitions as per Section 4.3 of [RFC3986], furthermore moved 10145 fragment discussion into a separate section 10146 (, 10147 , ) 10150 * In Section 2.5, add language about minor HTTP version number 10151 defaulting () 10153 * Added Section 15.5.21 for status code 422, previously defined in 10154 Section 11.2 of [RFC4918] () 10157 * In Section 15.5.17, fixed prose about byte range comparison 10158 (, 10159 ) 10161 * In Section 3.4, explain that request/response correlation is 10162 version specific () 10165 C.5. Since draft-ietf-httpbis-semantics-03 10167 * In Section 15.4.9, include status code 308 from RFC 7538 10168 () 10170 * In Section 8.3.1, clarify that the charset parameter value is 10171 case-insensitive due to the definition in RFC 2046 10172 () 10174 * Define a separate registry for HTTP header field names 10175 () 10177 * In Section 12.1, refactor and clarify description of wildcard 10178 ("*") handling () 10180 * Deprecate Accept-Charset () 10183 * In Section 13.2, mention Cache-Control: immutable 10184 () 10186 * In Section 5.3, clarify when header field combination is allowed 10187 () 10189 * In Section 18.4, instruct IANA to mark Content-MD5 as obsolete 10190 () 10192 * Use RFC 7405 ABNF notation for case-sensitive string constants 10193 () 10195 * Rework Section 3.4 to be more version-independent 10196 () 10198 * In Section 9.3.5, clarify that DELETE needs to be successful to 10199 invalidate cache (, ) 10202 C.6. Since draft-ietf-httpbis-semantics-04 10204 * In Section 5.5, fix field-content ABNF 10205 (, 10206 ) 10208 * Move Section 5.6.6 into its own section 10209 () 10211 * In Section 8.3, reference MIME Sniffing 10212 () 10214 * In Section 5.6.1, simplify the #rule mapping for recipients 10215 (, 10216 ) 10218 * In Section 9.3.7, remove misleading text about "extension" of HTTP 10219 is needed to define method content () 10222 * Fix editorial issue in Section 3.2 () 10225 * In Section 15.5.21, rephrase language not to use "entity" anymore, 10226 and also avoid lowercase "may" () 10229 * Move discussion of retries from [Messaging] into Section 9.2.2 10230 () 10232 C.7. Since draft-ietf-httpbis-semantics-05 10234 * Moved transport-independent part of the description of trailers 10235 into Section 6.5 () 10237 * Loosen requirements on retries based upon implementation behavior 10238 () 10240 * In Section 18.9, update IANA port registry for TCP/UDP on ports 80 10241 and 443 () 10243 * In Section 16.3.2.2, revise guidelines for new header field names 10244 () 10246 * In Section 9.2.3, remove concept of "cacheable methods" in favor 10247 of prose (, 10248 ) 10250 * In Section 17.1, mention that the concept of authority can be 10251 modified by protocol extensions () 10254 * Create new subsection on content in Section 6.4, taken from 10255 portions of message body () 10258 * Moved definition of "Whitespace" into new container "Generic 10259 Syntax" () 10261 * In Section 3.1, recommend minimum URI size support for 10262 implementations () 10264 * In Section 14.1, refactored the range-unit and ranges-specifier 10265 grammars (, 10266 ) 10268 * In Section 9.3.1, caution against a request content more strongly 10269 () 10271 * Reorganized text in Section 16.3.2.2 () 10274 * In Section 15.5.4, replace "authorize" with "fulfill" 10275 () 10277 * In Section 9.3.7, removed a misleading statement about Content- 10278 Length (, 10279 ) 10281 * In Section 17.1, add text from RFC 2818 10282 () 10284 * Changed "cacheable by default" to "heuristically cacheable" 10285 throughout () 10287 C.8. Since draft-ietf-httpbis-semantics-06 10289 * In Section 7.6.3, simplify received-by grammar (and disallow comma 10290 character) () 10292 * In Section 5.1, give guidance on interoperable field names 10293 () 10295 * In Section 5.6.3, define the semantics and possible replacement of 10296 whitespace when it is known to occur (, ) 10299 * In Section 6.3, introduce field terminology and distinguish 10300 between field line values and field values; use terminology 10301 consistently throughout () 10304 * Moved #rule definition into Section 5.5 and whitespace into 10305 Section 2.1 () 10307 * In Section 14.1, explicitly call out range unit names as case- 10308 insensitive, and encourage registration 10309 () 10311 * In Section 8.4.1, explicitly call out content codings as case- 10312 insensitive, and encourage registration 10313 () 10315 * In Section 5.1, explicitly call out field names as case- 10316 insensitive () 10318 * In Section 17.13, cite [Bujlow] () 10321 * In Section 15, formally define "final" and "interim" status codes 10322 () 10324 * In Section 9.3.5, caution against a request content more strongly 10325 () 10327 * In Section 8.8.3, note that Etag can be used in trailers 10328 () 10330 * In Section 18.4, consider reserved fields as well 10331 () 10333 * In Section 4.2.4, be more correct about what was deprecated by RFC 10334 3986 (, 10335 ) 10337 * In Section 5.3, recommend comma SP when combining field lines 10338 () 10340 * In Section 7.2, make explicit requirements on origin server to use 10341 authority from absolute-form when available 10342 () 10344 * In Section 4.2.1, Section 4.2.2, Section 4.3.1, and Section 7.3.3, 10345 refactored schemes to define origin and authoritative access to an 10346 origin server for both "http" and "https" URIs to account for 10347 alternative services and secured connections that are not 10348 necessarily based on TCP () 10351 * In Section 2.2, reference RFC 8174 as well 10352 () 10354 C.9. Since draft-ietf-httpbis-semantics-07 10356 * In Section 14.2, explicitly reference the definition of 10357 representation data as including any content codings 10358 () 10360 * Move TE: trailers from [Messaging] into Section 6.5.1 10361 () 10363 * In Section 8.6, adjust requirements for handling multiple content- 10364 length values () 10366 * In Section 13.1.1 and Section 13.1.2, clarified condition 10367 evaluation () 10369 * In Section 5.5, remove concept of obs-fold, as that is 10370 HTTP/1-specific () 10372 * In Section 12, introduce the concept of request content 10373 negotiation (Section 12.3) and define for Accept-Encoding 10374 () 10376 * In Section 15.3.6, Section 15.5.9, and Section 15.5.14, remove 10377 HTTP/1-specific, connection-related requirements 10378 () 10380 * In Section 9.3.6, correct language about what is forwarded 10381 () 10383 * Throughout, replace "effective request URI", "request-target" and 10384 similar with "target URI" () 10387 * In Section 16.3.2.2 and Section 16.2.2, describe how extensions 10388 should consider scope of applicability 10389 () 10391 * In Section 3.4, don't rely on the HTTP/1.1 Messaging specification 10392 to define "message" () 10395 * In Section 8.7 and Section 10.1.3, note that URL resolution is 10396 necessary () 10398 * In Section 3.2, explicitly reference 206 as one of the status 10399 codes that provide representation data 10400 () 10402 * In Section 13.1.4, refine requirements so that they don't apply to 10403 resources without a concept of modification time 10404 () 10406 * In Section 11.7.1, specify the scope as a request, not a target 10407 resource () 10409 * In Section 3.4, introduce concept of "complete" messages 10410 () 10412 * In Section 7.1, Section 9.3.6, and Section 9.3.7, refine use of 10413 "request target" () 10416 * Throughout, remove "status-line" and "request-line", as these are 10417 HTTP/1.1-specific () 10420 C.10. Since draft-ietf-httpbis-semantics-08 10422 * In Section 15.5.17, remove duplicate definition of what makes a 10423 range satisfiable and refer instead to each range unit's 10424 definition () 10426 * In Section 14.1.2 and Section 14.2, clarify that a selected 10427 representation of zero length can only be satisfiable as a suffix 10428 range and that a server can still ignore Range for that case 10429 () 10431 * In Section 12.5.1 and Section 15.5.16, allow "Accept" as response 10432 field () 10434 * Appendix A now uses the sender variant of the "#" list expansion 10435 () 10437 * In Section 12.5.5, make the field list-based even when "*" is 10438 present () 10440 * In Section 16.3.1, add optional "Comments" entry 10441 () 10443 * In Section 18.4, reserve "*" as field name 10444 () 10446 * In Section 18.2, reserve "*" as method name 10447 () 10449 * In Section 13.1.1 and Section 13.1.2, state that multiple "*" is 10450 unlikely to be interoperable () 10453 * In Section 12.5.1, avoid use of obsolete media type parameter on 10454 text/html (, 10455 ) 10457 * Rephrase prose in Section 3.4 to become version-agnostic 10458 () 10460 * In Section 5.5, instruct recipients how to deal with control 10461 characters in field values () 10464 * In Section 5.5, update note about field ABNF 10465 () 10467 * Add Section 16 about Extending and Versioning HTTP 10468 () 10470 * In Section 15.1, include status 308 in list of heuristically 10471 cacheable status codes () 10474 * In Section 8.4, make it clearer that "identity" is not to be 10475 included () 10477 C.11. Since draft-ietf-httpbis-semantics-09 10479 * Switch to xml2rfc v3 mode for draft generation 10480 () 10482 C.12. Since draft-ietf-httpbis-semantics-10 10484 * In Section 17.6, mention compression attacks 10485 () 10487 * In Section 16.6.1, advise to make new content codings self- 10488 descriptive () 10490 * In Section 5.6.6, introduced the "parameters" ABNF rule, allowing 10491 empty parameters and trailing semicolons within media type, media 10492 range, and expectation () 10495 * In Section 15.4, explain how to create a redirected request 10496 () 10498 * In Section 8.3, defined error handling for multiple members 10499 () 10501 * In Section 1, revise the introduction and introduce HTTP/2 and 10502 HTTP/3 () 10504 * In Section 8.6, added a definition for Content-Length that 10505 encompasses its various roles in describing message content or 10506 selected representation length; in Section 15.3.7, noted that 10507 Content-Length counts only the message content (not the selected 10508 representation) and that the representation length is in each 10509 Content-Range () 10511 * Noted that "WWW-Authenticate" with more than one value on a line 10512 is sometimes not interoperable [Messaging] 10513 () 10515 * In Section 13.1.1 and Section 13.1.4, removed requirement that a 10516 validator not be sent in a 2xx response when validation fails and 10517 the server decides that the same change request has already been 10518 applied () 10520 * Moved requirements specific to HTTP/1.1 from Section 7.2 to 10521 [Messaging] () 10523 * In Section 5.5, introduce the terms "singleton field" and "list- 10524 based field" (also - in various places - discuss what to do when a 10525 singleton field is received as a list) 10526 () 10528 * In Section 10.1.1, change the ABNF back to be a list of 10529 expectations, as defined in RFC 2616 () 10532 * In Section 10.1.5 (Trailer), Section 7.6.3 (Via), Section 7.8 10533 (Upgrade), Section 7.6.1 (Connection), Section 8.4 10534 (Content-Encoding), Section 8.5 (Content-Language), Section 10.1.1 10535 (Expect), Section 13.1.1 (If-Match), Section 13.1.2 10536 (If-None-Match), Section 12.5.2 (Accept-Charset), Section 12.5.4 10537 (Accept-Language), Section 12.5.5 (Vary), Section 11.6.1 10538 (WWW-Authenticate), and Section 11.7.1 (Proxy-Authenticate), 10539 adjust ABNF to allow empty lists () 10542 * In Section 9.3.1 and Section 17.9, provide a more nuanced 10543 explanation of sensitive data in GET-based forms and describe 10544 workarounds () 10546 * In Section 13.2, allow preconditions to be evaluated before the 10547 request content (if any) is processed () 10550 * In Section 6.3 and Section 6.5.2, allow for trailer fields in 10551 multiple trailer sections, depending on the HTTP version and 10552 framing in use, with processing being iterative as each section is 10553 received () 10555 * Moved definitions of "TE" and "Upgrade" from [Messaging] 10556 () 10558 * Moved 1.1-specific discussion of TLS to Messaging and rewrote 10559 Section 4.3.4 to refer to RFC6125 () 10562 * Moved definition of "Connection" from [Messaging] 10563 () 10565 C.13. Since draft-ietf-httpbis-semantics-11 10567 * The entire document has been reorganized, with no changes to 10568 content except editorial for the reorganization 10569 () 10571 * Move IANA Upgrade Token Registry instructions from [Messaging] 10572 () 10574 C.14. Since draft-ietf-httpbis-semantics-12 10576 * In Appendix "Acknowledgments" (Appendix "Acknowledgments"), added 10577 acks for the work since 2014 () 10580 * In Section 15.3.7, specifically require that a client check the 10581 206 response header fields to determine what ranges are enclosed, 10582 since it cannot assume they exactly match those requested 10583 () 10585 * In Section 16.3, explain why new fields need to be backwards- 10586 compatible () 10588 * In Section 5.3, constrain field combination to be within a section 10589 () 10591 * In Section 5.6.7, mention that caching relaxes date sensitivity 10592 () 10594 * In Section 18.4, moved "*" field registration into main table 10595 () 10597 * In Section 1.2, reference HTTP/0.9 () 10600 * In Section 9.3.4, clarify handling of unrecognized fields 10601 () 10603 * In Section 15.2, align language about bodies and trailers with 204 10604 and 304 () 10606 * Moved table of content codings into Section 18.6, moved table of 10607 range units into Section 18.7 () 10610 * In Section 6, add an abstract data type for message to help define 10611 semantics without being dependent on the specific structure of 10612 HTTP/1.1 () 10614 * In Section 8.8.2.2, relax arbitrary 60-second comparison limit 10615 () 10617 * In Section 7.2, add ":authority" pseudo-header to Host discussion 10618 and make section applicable to both () 10621 * In Section 18.4, note that this document updates [RFC3864] 10622 () 10624 * Moved transfer-coding ABNF from [Messaging] to Section 10.1.4 and 10625 replaced "t-ranking" ABNF by equivalent "weight" 10626 () 10628 * In Section 11.5, replace "canonical root URI" by "origin" 10629 () 10631 * In Section 10.1.1, remove obsolete note about a change in RFC 723x 10632 () 10634 * Changed to using "payload" when defining requirements about the 10635 data being conveyed within a message, instead of the terms 10636 "payload body" or "response body" or "representation body", since 10637 they often get confused with the HTTP/1.1 message body (which 10638 includes transfer coding) () 10641 * Rewrite definition of HEAD method () 10644 * In Section 13.1.5, fix an off-by-one bug about how many chars to 10645 consider when checking for etags () 10648 * In Section 15.1, clarify that "no reason phrase" is fine as well 10649 () 10651 * In Section 15.3.4, remove an obsolete reference to the Warning 10652 response header field () 10655 * In Section 15.5.9, rephrase prose about connection re-use 10656 () 10658 * In Section 14.2, potentially allow Range handling on methods other 10659 than GET () 10661 * In Section 18.3, remove redundant text about status code 418 10662 () 10664 * In Section 17.16.1, rewrite requirement to refer to "secured 10665 connection" () 10667 * Make reference to [RFC8446] normative () 10670 C.15. Since draft-ietf-httpbis-semantics-13 10672 * In Section 12.5.1, remove the unused "accept parameters" 10673 () 10675 * In Section 1.2, mention that RFC 1945 describes HTTP/0.9 as well 10676 () 10678 * In Section 14.5, describe non-standard use of the Content-Range 10679 header field (Section 14.4) as a request modifier to perform a 10680 partial PUT () 10682 * In Section 15.5.20, import the 421 (Misdirected Request) status 10683 code from [RFC7540] () 10686 * In Section 2.3, rephrase the actual recipient parsing requirements 10687 () 10689 * In Section 16.1.2, mention request target forms in considerations 10690 for new methods () 10692 * Changed to using "content" instead of "payload" or "payload data" 10693 to avoid confusion with the payload of version-specific messaging 10694 frames () 10696 * In Section 13.1.3, Section 13.1.4, and Section 13.1.5, specify 10697 evaluation in a way similar to other conditional header fields 10698 () 10700 * In Section 10.2.2, specify that recipients can replace an invalid 10701 Date header field value with the time received 10702 () 10704 C.16. Since draft-ietf-httpbis-semantics-14 10706 * In Section 5.5, relax prohibition of characters in field values to 10707 CR and NUL () 10709 * In Section 15, clarify that status code values outside the range 10710 100..599 are invalid, and recommend error handling 10711 () 10713 * In Section 2.2, replaced requirement on semantic conformance with 10714 permission to ignore/workaround implementation-specific failures 10715 () 10717 * Avoid the term "whitelist" () 10720 * In Section 9.3.8, remove the normative requirement to use the 10721 message/http media type () 10724 * In Section 7.6, discuss extensibility () 10727 * In Section 5.5, tighten the recommendation for characters in newly 10728 defined fields, making it consistent with obs-text 10729 () 10731 * In Section 5.5, leading/trailing whitespace removal is at time of 10732 use, not parsing () 10735 * In Section 6, clarify that HTTP self-descriptive messages have an 10736 exception in that the request must be understood in order to parse 10737 and interpret the response () 10740 * Remove "Canonicalization and Text Defaults" 10741 () 10743 * In Section 10.1.3, refine what can be sent in Referer, and when 10744 () 10746 * In Section 11.5, explain that the protection space is not defined 10747 without additional information () 10750 * Simplify description of reactive content negotiation in 10751 Section 12.2 () 10753 * In Section 8.3.2, remove the "charset" ABNF production, and 10754 clarify where charsets appear () 10757 * In Section 12.5.3, clarify that selection _between_ multiple 10758 acceptable codings is only relevant when they have the same 10759 purpose () 10761 * In Section 13, rewrite introduction, mentioning extensibility 10762 () 10764 * Throughout, be consistent about 'content coding' vs 'content- 10765 coding' () 10767 * In Section 9.3.6, clarify that the port is mandatory in a CONNECT 10768 request target () 10769 and that the tunnel begins after the header section 10770 () 10772 * In Section 6.5, remove mid-stream trailers 10773 () 10775 * In Section 3.3, clarify duplexing semantics 10776 () 10778 * In Section 3.3, explain the implications of statelessness more 10779 clearly () 10781 * In Section 8.6, be more explicit about invalid and incorrect 10782 values ( and 10783 ) 10785 * Move discussion of statelessness from Section 3.7 to Section 3.3 10786 () 10788 * In Section 15.2.2, clarify that the upgraded protocol is in effect 10789 after the 101 response () 10792 * In Section 9.3.6, state that data received after the headers of a 10793 CONNECT message is version-specific () 10796 * In Section 4.2.3, clarify how normalization works, and align with 10797 RF3986 () 10799 * In Section 10.1.5, note that the Trailer field can be used to 10800 discover deleted trailers () 10803 * Throughout, remove unneeded normative references to [Messaging] 10804 () 10806 * In Section 10.1.4, explicitly require listing in Connection 10807 () 10809 C.17. Since draft-ietf-httpbis-semantics-15 10811 * For [HTTP3], add an RFC Editor note to rename to "RFCnnn" before 10812 publication () 10814 * In Section 9.3.2, align prose about content in HEAD requests with 10815 description of GET () 10818 * In Section 5.3, remove the restriction to non-empty field line 10819 values () 10821 * Add forward references to definition of OWS 10822 () 10824 * In Section 17.10, add a security consideration regarding 10825 application handling of field names () 10828 Acknowledgments 10830 Aside from the current editors, the following individuals deserve 10831 special recognition for their contributions to early aspects of HTTP 10832 and its core specifications: Marc Andreessen, Tim Berners-Lee, Robert 10833 Cailliau, Daniel W. Connolly, Bob Denny, John Franks, Jim Gettys, 10834 Jean-François Groff, Phillip M. Hallam-Baker, Koen Holtman, Jeffery 10835 L. Hostetler, Shel Kaphan, Dave Kristol, Yves Lafon, Scott 10836 D. Lawrence, Paul J. Leach, Håkon W. Lie, Ari Luotonen, Larry 10837 Masinter, Rob McCool, Jeffrey C. Mogul, Lou Montulli, David Morris, 10838 Henrik Frystyk Nielsen, Dave Raggett, Eric Rescorla, Tony Sanders, 10839 Lawrence C. Stewart, Marc VanHeyningen, and Steve Zilles. 10841 This edition builds on the many contributions that went into past 10842 specifications of HTTP, including RFC 1945, RFC 2068, RFC 2145, RFC 10843 2616, RFC 2617, RFC 2818, RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 10844 7234, and RFC 7235. The acknowledgements within those documents 10845 still apply. 10847 Since 2014, the following contributors have helped improve this 10848 specification by reporting bugs, asking smart questions, drafting or 10849 reviewing text, and evaluating open issues: 10851 Alan Egerton, Alex Rousskov, Amichai Rothman, Amos Jeffries, Anders 10852 Kaseorg, Andreas Gebhardt, Anne van Kesteren, Armin Abfalterer, Aron 10853 Duby, Asanka Herath, Asbjørn Ulsberg, Attila Gulyas, Austin Wright, 10854 Barry Pollard, Ben Burkert, Björn Höhrmann, Brad Fitzpatrick, Chris 10855 Pacejo, Colin Bendell, Cory Benfield, Cory Nelson, Daisuke Miyakawa, 10856 Daniel Stenberg, Danil Suits, David Benjamin, David Matson, David 10857 Schinazi, Дилян Палаузов (Dilyan Palauzov), Eric Anderson, Eric 10858 Rescorla, Erwin Pe, Etan Kissling, Evert Pot, Evgeny Vrublevsky, 10859 Florian Best, Igor Lubashev, James Callahan, James Peach, Jeffrey 10860 Yasskin, Kalin Gyokov, Kannan Goundan, 奥 一穂 (Kazuho Oku), Ken 10861 Murchison, Krzysztof Maczyński, Lucas Pardue, Martin Dürst, Martin 10862 Thomson, Martynas Jusevičius, Matt Menke, Matthias Pigulla, Michael 10863 Osipov, Mike Bishop, Mike Pennisi, Mike Taylor, Mike West, Nathaniel 10864 J. Smith, Nicholas Hurley, Nikita Piskunov, Patrick McManus, Piotr 10865 Sikora, Poul-Henning Kamp, Rick van Rein, Roberto Polli, Samuel 10866 Williams, Semyon Kholodnov, Simon Pieters, Simon Schüppel, Todd 10867 Greer, Tommy Pauly, Vasiliy Faronov, Vladimir Lashchev, Wenbo Zhu, 10868 William A. Rowe Jr., Willy Tarreau, Xingwei Liu, and Yishuai Li. 10870 Index 10872 1 2 3 4 5 A B C D E F G H I L M N O P R S T U V W X 10874 1 10876 100 Continue (status code) Section 15.2.1 10877 100-continue (expect value) Section 10.1.1 10878 101 Switching Protocols (status code) Section 15.2.2 10879 1xx Informational (status code class) Section 15.2 10881 2 10883 200 OK (status code) Section 15.3.1 10884 201 Created (status code) Section 15.3.2 10885 202 Accepted (status code) Section 15.3.3 10886 203 Non-Authoritative Information (status code) Section 15.3.4 10887 204 No Content (status code) Section 15.3.5 10888 205 Reset Content (status code) Section 15.3.6 10889 206 Partial Content (status code) Section 15.3.7 10890 2xx Successful (status code class) Section 15.3 10892 3 10894 300 Multiple Choices (status code) Section 15.4.1 10895 301 Moved Permanently (status code) Section 15.4.2 10896 302 Found (status code) Section 15.4.3 10897 303 See Other (status code) Section 15.4.4 10898 304 Not Modified (status code) Section 15.4.5 10899 305 Use Proxy (status code) Section 15.4.6 10900 306 (Unused) (status code) Section 15.4.7 10901 307 Temporary Redirect (status code) Section 15.4.8 10902 308 Permanent Redirect (status code) Section 15.4.9 10903 3xx Redirection (status code class) Section 15.4 10905 4 10907 400 Bad Request (status code) Section 15.5.1 10908 401 Unauthorized (status code) Section 15.5.2 10909 402 Payment Required (status code) Section 15.5.3 10910 403 Forbidden (status code) Section 15.5.4 10911 404 Not Found (status code) Section 15.5.5 10912 405 Method Not Allowed (status code) Section 15.5.6 10913 406 Not Acceptable (status code) Section 15.5.7 10914 407 Proxy Authentication Required (status code) Section 15.5.8 10915 408 Request Timeout (status code) Section 15.5.9 10916 409 Conflict (status code) Section 15.5.10 10917 410 Gone (status code) Section 15.5.11 10918 411 Length Required (status code) Section 15.5.12 10919 412 Precondition Failed (status code) Section 15.5.13 10920 413 Content Too Large (status code) Section 15.5.14 10921 414 URI Too Long (status code) Section 15.5.15 10922 415 Unsupported Media Type (status code) Section 15.5.16 10923 416 Range Not Satisfiable (status code) Section 15.5.17 10924 417 Expectation Failed (status code) Section 15.5.18 10925 418 (Unused) (status code) Section 15.5.19 10926 421 Misdirected Request (status code) Section 15.5.20 10927 422 Unprocessable Content (status code) Section 15.5.21 10928 426 Upgrade Required (status code) Section 15.5.22 10929 4xx Client Error (status code class) Section 15.5 10931 5 10933 500 Internal Server Error (status code) Section 15.6.1 10934 501 Not Implemented (status code) Section 15.6.2 10935 502 Bad Gateway (status code) Section 15.6.3 10936 503 Service Unavailable (status code) Section 15.6.4 10937 504 Gateway Timeout (status code) Section 15.6.5 10938 505 HTTP Version Not Supported (status code) Section 15.6.6 10939 5xx Server Error (status code class) Section 15.6 10941 A 10943 Accept header field Section 12.5.1 10944 Accept-Charset header field Section 12.5.2 10945 Accept-Encoding header field Section 12.5.3 10946 Accept-Language header field Section 12.5.4 10947 Accept-Ranges header field Section 14.3 10948 Allow header field Section 10.2.1 10949 Authentication-Info header field Section 11.6.3 10950 Authorization header field Section 11.6.2 10951 accelerator Section 3.7, Paragraph 6 10952 authoritative response Section 17.1 10954 B 10956 browser Section 3.5 10958 C 10960 CONNECT method Section 9.3.6 10961 Connection header field Section 7.6.1 10962 Content-Encoding header field Section 8.4 10963 Content-Language header field Section 8.5 10964 Content-Length header field Section 8.6 10965 Content-Location header field Section 8.7 10966 Content-MD5 header field Section 18.4, Paragraph 9 10967 Content-Range header field Section 14.4; Section 14.5 10968 Content-Type header field Section 8.3 10969 cache Section 3.8 10970 cacheable Section 3.8, Paragraph 4 10971 client Section 3.3 10972 complete Section 6.1 10973 compress (Coding Format) Section 8.4.1.1 10974 compress (content coding) Section 8.4.1 10975 conditional request Section 13 10976 connection Section 3.3 10977 content Section 6.4 10978 content coding Section 8.4.1 10979 content negotiation Section 1.3, Paragraph 4 10980 control data Section 6.2 10982 D 10984 DELETE method Section 9.3.5 10985 Date header field Section 10.2.2 10986 Delimiters Section 5.6.2, Paragraph 3 10987 deflate (Coding Format) Section 8.4.1.2 10988 deflate (content coding) Section 8.4.1 10989 downstream Section 3.7, Paragraph 4 10991 E 10993 ETag field Section 8.8.3 10994 Expect header field Section 10.1.1 10995 effective request URI Section 7.1, Paragraph 8.1 10997 F 10999 Fields 11000 * Section 18.4, Paragraph 8 11001 Accept Section 12.5.1 11002 Accept-Charset Section 12.5.2 11003 Accept-Encoding Section 12.5.3 11004 Accept-Language Section 12.5.4 11005 Accept-Ranges Section 14.3 11006 Allow Section 10.2.1 11007 Authentication-Info Section 11.6.3 11008 Authorization Section 11.6.2 11009 Connection Section 7.6.1 11010 Content-Encoding Section 8.4 11011 Content-Language Section 8.5 11012 Content-Length Section 8.6 11013 Content-Location Section 8.7 11014 Content-MD5 Section 18.4, Paragraph 9 11015 Content-Range Section 14.4; Section 14.5 11016 Content-Type Section 8.3 11017 Date Section 10.2.2 11018 ETag Section 8.8.3 11019 Expect Section 10.1.1 11020 From Section 10.1.2 11021 Host Section 7.2 11022 If-Match Section 13.1.1 11023 If-Modified-Since Section 13.1.3 11024 If-None-Match Section 13.1.2 11025 If-Range Section 13.1.5 11026 If-Unmodified-Since Section 13.1.4 11027 Last-Modified Section 8.8.2 11028 Location Section 10.2.3 11029 Max-Forwards Section 7.6.2 11030 Proxy-Authenticate Section 11.7.1 11031 Proxy-Authentication-Info Section 11.7.3 11032 Proxy-Authorization Section 11.7.2 11033 Range Section 14.2 11034 Referer Section 10.1.3 11035 Retry-After Section 10.2.4 11036 Server Section 10.2.5 11037 TE Section 10.1.4 11038 Trailer Section 10.1.5 11039 Upgrade Section 7.8 11040 User-Agent Section 10.1.6 11041 Vary Section 12.5.5 11042 Via Section 7.6.3 11043 WWW-Authenticate Section 11.6.1 11044 Fragment Identifiers Section 4.2.5 11045 From header field Section 10.1.2 11046 field Section 5; Section 6.3 11047 field line Section 5.2, Paragraph 1 11048 field line value Section 5.2, Paragraph 1 11049 field name Section 5.2, Paragraph 1 11050 field value Section 5.2, Paragraph 2 11052 G 11054 GET method Section 9.3.1 11055 Grammar 11056 ALPHA Section 2.1 11057 Accept Section 12.5.1 11058 Accept-Charset Section 12.5.2 11059 Accept-Encoding Section 12.5.3 11060 Accept-Language Section 12.5.4 11061 Accept-Ranges Section 14.3 11062 Allow Section 10.2.1 11063 Authentication-Info Section 11.6.3 11064 Authorization Section 11.6.2 11065 BWS Section 5.6.3 11066 CR Section 2.1 11067 CRLF Section 2.1 11068 CTL Section 2.1 11069 Connection Section 7.6.1 11070 Content-Encoding Section 8.4 11071 Content-Language Section 8.5 11072 Content-Length Section 8.6 11073 Content-Location Section 8.7 11074 Content-Range Section 14.4 11075 Content-Type Section 8.3 11076 DIGIT Section 2.1 11077 DQUOTE Section 2.1 11078 Date Section 10.2.2 11079 ETag Section 8.8.3 11080 Expect Section 10.1.1 11081 From Section 10.1.2 11082 GMT Section 5.6.7 11083 HEXDIG Section 2.1 11084 HTAB Section 2.1 11085 HTTP-date Section 5.6.7 11086 Host Section 7.2 11087 IMF-fixdate Section 5.6.7 11088 If-Match Section 13.1.1 11089 If-Modified-Since Section 13.1.3 11090 If-None-Match Section 13.1.2 11091 If-Range Section 13.1.5 11092 If-Unmodified-Since Section 13.1.4 11093 LF Section 2.1 11094 Last-Modified Section 8.8.2 11095 Location Section 10.2.3 11096 Max-Forwards Section 7.6.2 11097 OCTET Section 2.1 11098 OWS Section 5.6.3 11099 Proxy-Authenticate Section 11.7.1 11100 Proxy-Authentication-Info Section 11.7.3 11101 Proxy-Authorization Section 11.7.2 11102 RWS Section 5.6.3 11103 Range Section 14.2 11104 Referer Section 10.1.3 11105 Retry-After Section 10.2.4 11106 SP Section 2.1 11107 Server Section 10.2.5 11108 TE Section 10.1.4 11109 Trailer Section 10.1.5 11110 URI-reference Section 4.1 11111 Upgrade Section 7.8 11112 User-Agent Section 10.1.6 11113 VCHAR Section 2.1 11114 Vary Section 12.5.5 11115 Via Section 7.6.3 11116 WWW-Authenticate Section 11.6.1 11117 absolute-URI Section 4.1 11118 absolute-path Section 4.1 11119 acceptable-ranges Section 14.3 11120 asctime-date Section 5.6.7 11121 auth-param Section 11.2 11122 auth-scheme Section 11.1 11123 authority Section 4.1 11124 challenge Section 11.3 11125 codings Section 12.5.3 11126 comment Section 5.6.5 11127 complete-length Section 14.4 11128 connection-option Section 7.6.1 11129 content-coding Section 8.4.1 11130 credentials Section 11.4 11131 ctext Section 5.6.5 11132 date1 Section 5.6.7 11133 day Section 5.6.7 11134 day-name Section 5.6.7 11135 day-name-l Section 5.6.7 11136 delay-seconds Section 10.2.4 11137 entity-tag Section 8.8.3 11138 etagc Section 8.8.3 11139 field-content Section 5.5 11140 field-name Section 5.1; Section 10.1.5 11141 field-value Section 5.5 11142 field-vchar Section 5.5 11143 first-pos Section 14.1.1; Section 14.4 11144 hour Section 5.6.7 11145 http-URI Section 4.2.1 11146 https-URI Section 4.2.2 11147 incl-range Section 14.4 11148 int-range Section 14.1.1 11149 language-range Section 12.5.4 11150 language-tag Section 8.5.1 11151 last-pos Section 14.1.1; Section 14.4 11152 media-range Section 12.5.1 11153 media-type Section 8.3.1 11154 method Section 9.1 11155 minute Section 5.6.7 11156 month Section 5.6.7 11157 obs-date Section 5.6.7 11158 obs-text Section 5.6.4 11159 opaque-tag Section 8.8.3 11160 other-range Section 14.1.1 11161 parameter Section 5.6.6 11162 parameter-name Section 5.6.6 11163 parameter-value Section 5.6.6 11164 parameters Section 5.6.6 11165 partial-URI Section 4.1 11166 port Section 4.1 11167 product Section 10.1.6 11168 product-version Section 10.1.6 11169 protocol-name Section 7.6.3 11170 protocol-version Section 7.6.3 11171 pseudonym Section 7.6.3 11172 qdtext Section 5.6.4 11173 query Section 4.1 11174 quoted-pair Section 5.6.4 11175 quoted-string Section 5.6.4 11176 qvalue Section 12.4.2 11177 range-resp Section 14.4 11178 range-set Section 14.1.1 11179 range-spec Section 14.1.1 11180 range-unit Section 14.1 11181 ranges-specifier Section 14.1.1 11182 received-by Section 7.6.3 11183 received-protocol Section 7.6.3 11184 rfc850-date Section 5.6.7 11185 second Section 5.6.7 11186 segment Section 4.1 11187 subtype Section 8.3.1 11188 suffix-length Section 14.1.1 11189 suffix-range Section 14.1.1 11190 t-codings Section 10.1.4 11191 tchar Section 5.6.2 11192 time-of-day Section 5.6.7 11193 token Section 5.6.2 11194 token68 Section 11.2 11195 transfer-coding Section 10.1.4 11196 transfer-parameter Section 10.1.4 11197 type Section 8.3.1 11198 unsatisfied-range Section 14.4 11199 uri-host Section 4.1 11200 weak Section 8.8.3 11201 weight Section 12.4.2 11202 year Section 5.6.7 11203 gateway Section 3.7, Paragraph 6 11204 gzip (Coding Format) Section 8.4.1.3 11205 gzip (content coding) Section 8.4.1 11207 H 11209 HEAD method Section 9.3.2 11210 Header Fields 11211 Accept Section 12.5.1 11212 Accept-Charset Section 12.5.2 11213 Accept-Encoding Section 12.5.3 11214 Accept-Language Section 12.5.4 11215 Accept-Ranges Section 14.3 11216 Allow Section 10.2.1 11217 Authentication-Info Section 11.6.3 11218 Authorization Section 11.6.2 11219 Connection Section 7.6.1 11220 Content-Encoding Section 8.4 11221 Content-Language Section 8.5 11222 Content-Length Section 8.6 11223 Content-Location Section 8.7 11224 Content-MD5 Section 18.4, Paragraph 9 11225 Content-Range Section 14.4; Section 14.5 11226 Content-Type Section 8.3 11227 Date Section 10.2.2 11228 ETag Section 8.8.3 11229 Expect Section 10.1.1 11230 From Section 10.1.2 11231 Host Section 7.2 11232 If-Match Section 13.1.1 11233 If-Modified-Since Section 13.1.3 11234 If-None-Match Section 13.1.2 11235 If-Range Section 13.1.5 11236 If-Unmodified-Since Section 13.1.4 11237 Last-Modified Section 8.8.2 11238 Location Section 10.2.3 11239 Max-Forwards Section 7.6.2 11240 Proxy-Authenticate Section 11.7.1 11241 Proxy-Authentication-Info Section 11.7.3 11242 Proxy-Authorization Section 11.7.2 11243 Range Section 14.2 11244 Referer Section 10.1.3 11245 Retry-After Section 10.2.4 11246 Server Section 10.2.5 11247 TE Section 10.1.4 11248 Trailer Section 10.1.5 11249 Upgrade Section 7.8 11250 User-Agent Section 10.1.6 11251 Vary Section 12.5.5 11252 Via Section 7.6.3 11253 WWW-Authenticate Section 11.6.1 11254 Host header field Section 7.2 11255 header section Section 6.3 11256 http URI scheme Section 4.2.1 11257 https URI scheme Section 4.2.2 11259 I 11261 If-Match header field Section 13.1.1 11262 If-Modified-Since header field Section 13.1.3 11263 If-None-Match header field Section 13.1.2 11264 If-Range header field Section 13.1.5 11265 If-Unmodified-Since header field Section 13.1.4 11266 idempotent Section 9.2.2 11267 inbound Section 3.7, Paragraph 4 11268 incomplete Section 6.1 11269 interception proxy Section 3.7, Paragraph 10 11270 intermediary Section 3.7 11272 L 11274 Last-Modified header field Section 8.8.2 11275 Location header field Section 10.2.3 11276 list-based field Section 5.5, Paragraph 7 11278 M 11280 Max-Forwards header field Section 7.6.2 11281 Media Type 11282 multipart/byteranges Section 14.6 11283 multipart/x-byteranges Section 14.6, Paragraph 4, Item 3 11284 Method 11285 * Section 18.2, Paragraph 3 11286 CONNECT Section 9.3.6 11287 DELETE Section 9.3.5 11288 GET Section 9.3.1 11289 HEAD Section 9.3.2 11290 OPTIONS Section 9.3.7 11291 POST Section 9.3.3 11292 PUT Section 9.3.4 11293 TRACE Section 9.3.8 11294 message Section 3.4; Section 6 11295 message abstraction Section 6 11296 messages Section 3.4 11297 metadata Section 8.8 11298 multipart/byteranges Media Type Section 14.6 11299 multipart/x-byteranges Media Type Section 14.6, Paragraph 4, 11300 Item 3 11302 N 11303 non-transforming proxy Section 7.7 11305 O 11307 OPTIONS method Section 9.3.7 11308 Origin Section 11.5 11309 origin Section 4.3.1 11310 origin server Section 3.6 11311 outbound Section 3.7, Paragraph 4 11313 P 11315 POST method Section 9.3.3 11316 PUT method Section 9.3.4 11317 Protection Space Section 11.5 11318 Proxy-Authenticate header field Section 11.7.1 11319 Proxy-Authentication-Info header field Section 11.7.3 11320 Proxy-Authorization header field Section 11.7.2 11321 phishing Section 17.1 11322 proxy Section 3.7, Paragraph 5 11324 R 11326 Range header field Section 14.2 11327 Realm Section 11.5 11328 Referer header field Section 10.1.3 11329 Retry-After header field Section 10.2.4 11330 recipient Section 3.4 11331 representation Section 3.2 11332 request Section 3.4 11333 request target Section 7.1 11334 resource Section 3.1; Section 4 11335 response Section 3.4 11336 reverse proxy Section 3.7, Paragraph 6 11338 S 11340 Server header field Section 10.2.5 11341 Status Code Section 15 11342 Status Codes 11343 Final Section 15, Paragraph 7 11344 Informational Section 15, Paragraph 7 11345 Interim Section 15, Paragraph 7 11346 Status Codes Classes 11347 1xx Informational Section 15.2 11348 2xx Successful Section 15.3 11349 3xx Redirection Section 15.4 11350 4xx Client Error Section 15.5 11351 5xx Server Error Section 15.6 11352 safe Section 9.2.1 11353 secured Section 4.2.2 11354 selected representation Section 3.2, Paragraph 4; Section 8.8; 11355 Section 13.1 11356 self-descriptive Section 6 11357 sender Section 3.4 11358 server Section 3.3 11359 singleton field Section 5.5, Paragraph 6 11360 spider Section 3.5 11362 T 11364 TE header field Section 10.1.4 11365 TRACE method Section 9.3.8 11366 Trailer Fields 11367 ETag Section 8.8.3 11368 Trailer header field Section 10.1.5 11369 target URI Section 7.1 11370 target resource Section 7.1 11371 trailer fields Section 6.5 11372 trailer section Section 6.5 11373 trailers Section 6.5 11374 transforming proxy Section 7.7 11375 transparent proxy Section 3.7, Paragraph 10 11376 tunnel Section 3.7, Paragraph 8 11378 U 11380 URI Section 4 11381 origin Section 4.3.1 11382 URI reference Section 4.1 11383 URI scheme 11384 http Section 4.2.1 11385 https Section 4.2.2 11386 Upgrade header field Section 7.8 11387 User-Agent header field Section 10.1.6 11388 upstream Section 3.7, Paragraph 4 11389 user agent Section 3.5 11391 V 11393 Vary header field Section 12.5.5 11394 Via header field Section 7.6.3 11395 validator Section 8.8 11396 strong Section 8.8.1 11397 weak Section 8.8.1 11399 W 11401 WWW-Authenticate header field Section 11.6.1 11403 X 11405 x-compress (content coding) Section 8.4.1 11406 x-gzip (content coding) Section 8.4.1 11408 Authors' Addresses 11410 Roy T. Fielding (editor) 11411 Adobe 11412 345 Park Ave 11413 San Jose, CA 95110 11414 United States of America 11416 Email: fielding@gbiv.com 11417 URI: https://roy.gbiv.com/ 11419 Mark Nottingham (editor) 11420 Fastly 11421 Prahran VIC 11422 Australia 11424 Email: mnot@mnot.net 11425 URI: https://www.mnot.net/ 11427 Julian Reschke (editor) 11428 greenbytes GmbH 11429 Hafenweg 16 11430 48155 Münster 11431 Germany 11433 Email: julian.reschke@greenbytes.de 11434 URI: https://greenbytes.de/tech/webdav/