idnits 2.17.1 draft-ietf-httpbis-semantics-18.txt: -(11103): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(11107): 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 11 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 (18 August 2021) is 981 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 9545, but no explicit reference was found in the text == Unused Reference: 'RFC2617' is defined on line 9569, but no explicit reference was found in the text == Unused Reference: 'RFC7234' is defined on line 9648, but no explicit reference was found in the text == Unused Reference: 'RFC7617' is defined on line 9677, but no explicit reference was found in the text == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-cache-18 -- Possible downref: Normative reference to a draft: ref. 'CACHING' ** 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) ** Obsolete normative reference: RFC 793 (ref. 'TCP') (Obsoleted by RFC 9293) -- 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'. -- 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 7615 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7694 (Obsoleted by RFC 9110) Summary: 5 errors (**), 0 flaws (~~), 8 warnings (==), 33 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: 19 February 2022 18 August 2021 10 HTTP Semantics 11 draft-ietf-httpbis-semantics-18 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.19. 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 19 February 2022. 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 . . . . 28 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 . . . . . . . . . . . . . . . . . . . . . . . 33 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 . . . . . . . . . . . . . . . . . . . . . 49 145 6.5.1. Limitations on use of Trailers . . . . . . . . . . . 49 146 6.5.2. Processing Trailer Fields . . . . . . . . . . . . . . 50 147 6.6. Message Metadata . . . . . . . . . . . . . . . . . . . . 50 148 6.6.1. Date . . . . . . . . . . . . . . . . . . . . . . . . 51 149 6.6.2. Trailer . . . . . . . . . . . . . . . . . . . . . . . 52 150 7. Routing HTTP Messages . . . . . . . . . . . . . . . . . . . . 52 151 7.1. Determining the Target Resource . . . . . . . . . . . . . 52 152 7.2. Host and :authority . . . . . . . . . . . . . . . . . . . 53 153 7.3. Routing Inbound Requests . . . . . . . . . . . . . . . . 54 154 7.3.1. To a Cache . . . . . . . . . . . . . . . . . . . . . 54 155 7.3.2. To a Proxy . . . . . . . . . . . . . . . . . . . . . 54 156 7.3.3. To the Origin . . . . . . . . . . . . . . . . . . . . 54 157 7.4. Rejecting Misdirected Requests . . . . . . . . . . . . . 55 158 7.5. Response Correlation . . . . . . . . . . . . . . . . . . 55 159 7.6. Message Forwarding . . . . . . . . . . . . . . . . . . . 56 160 7.6.1. Connection . . . . . . . . . . . . . . . . . . . . . 56 161 7.6.2. Max-Forwards . . . . . . . . . . . . . . . . . . . . 58 162 7.6.3. Via . . . . . . . . . . . . . . . . . . . . . . . . . 59 163 7.7. Message Transformations . . . . . . . . . . . . . . . . . 60 164 7.8. Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . 61 165 8. Representation Data and Metadata . . . . . . . . . . . . . . 64 166 8.1. Representation Data . . . . . . . . . . . . . . . . . . . 64 167 8.2. Representation Metadata . . . . . . . . . . . . . . . . . 64 168 8.3. Content-Type . . . . . . . . . . . . . . . . . . . . . . 64 169 8.3.1. Media Type . . . . . . . . . . . . . . . . . . . . . 65 170 8.3.2. Charset . . . . . . . . . . . . . . . . . . . . . . . 66 171 8.3.3. Multipart Types . . . . . . . . . . . . . . . . . . . 66 172 8.4. Content-Encoding . . . . . . . . . . . . . . . . . . . . 67 173 8.4.1. Content Codings . . . . . . . . . . . . . . . . . . . 68 174 8.4.1.1. Compress Coding . . . . . . . . . . . . . . . . . 68 175 8.4.1.2. Deflate Coding . . . . . . . . . . . . . . . . . 68 176 8.4.1.3. Gzip Coding . . . . . . . . . . . . . . . . . . . 69 177 8.5. Content-Language . . . . . . . . . . . . . . . . . . . . 69 178 8.5.1. Language Tags . . . . . . . . . . . . . . . . . . . . 70 179 8.6. Content-Length . . . . . . . . . . . . . . . . . . . . . 70 180 8.7. Content-Location . . . . . . . . . . . . . . . . . . . . 72 181 8.8. Validator Fields . . . . . . . . . . . . . . . . . . . . 74 182 8.8.1. Weak versus Strong . . . . . . . . . . . . . . . . . 74 183 8.8.2. Last-Modified . . . . . . . . . . . . . . . . . . . . 76 184 8.8.2.1. Generation . . . . . . . . . . . . . . . . . . . 76 185 8.8.2.2. Comparison . . . . . . . . . . . . . . . . . . . 77 186 8.8.3. ETag . . . . . . . . . . . . . . . . . . . . . . . . 78 187 8.8.3.1. Generation . . . . . . . . . . . . . . . . . . . 79 188 8.8.3.2. Comparison . . . . . . . . . . . . . . . . . . . 80 189 8.8.3.3. Example: Entity-Tags Varying on Content-Negotiated 190 Resources . . . . . . . . . . . . . . . . . . . . . 80 191 9. Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 192 9.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 81 193 9.2. Common Method Properties . . . . . . . . . . . . . . . . 84 194 9.2.1. Safe Methods . . . . . . . . . . . . . . . . . . . . 84 195 9.2.2. Idempotent Methods . . . . . . . . . . . . . . . . . 85 196 9.2.3. Methods and Caching . . . . . . . . . . . . . . . . . 86 197 9.3. Method Definitions . . . . . . . . . . . . . . . . . . . 86 198 9.3.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 86 199 9.3.2. HEAD . . . . . . . . . . . . . . . . . . . . . . . . 87 200 9.3.3. POST . . . . . . . . . . . . . . . . . . . . . . . . 88 201 9.3.4. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 89 202 9.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 92 203 9.3.6. CONNECT . . . . . . . . . . . . . . . . . . . . . . . 94 204 9.3.7. OPTIONS . . . . . . . . . . . . . . . . . . . . . . . 95 205 9.3.8. TRACE . . . . . . . . . . . . . . . . . . . . . . . . 96 206 10. Message Context . . . . . . . . . . . . . . . . . . . . . . . 97 207 10.1. Request Context Fields . . . . . . . . . . . . . . . . . 97 208 10.1.1. Expect . . . . . . . . . . . . . . . . . . . . . . . 97 209 10.1.2. From . . . . . . . . . . . . . . . . . . . . . . . . 99 210 10.1.3. Referer . . . . . . . . . . . . . . . . . . . . . . 100 211 10.1.4. TE . . . . . . . . . . . . . . . . . . . . . . . . . 101 212 10.1.5. User-Agent . . . . . . . . . . . . . . . . . . . . . 102 213 10.2. Response Context Fields . . . . . . . . . . . . . . . . 103 214 10.2.1. Allow . . . . . . . . . . . . . . . . . . . . . . . 103 215 10.2.2. Location . . . . . . . . . . . . . . . . . . . . . . 104 216 10.2.3. Retry-After . . . . . . . . . . . . . . . . . . . . 105 217 10.2.4. Server . . . . . . . . . . . . . . . . . . . . . . . 106 218 11. HTTP Authentication . . . . . . . . . . . . . . . . . . . . . 106 219 11.1. Authentication Scheme . . . . . . . . . . . . . . . . . 106 220 11.2. Authentication Parameters . . . . . . . . . . . . . . . 107 221 11.3. Challenge and Response . . . . . . . . . . . . . . . . . 107 222 11.4. Credentials . . . . . . . . . . . . . . . . . . . . . . 108 223 11.5. Establishing a Protection Space (Realm) . . . . . . . . 109 224 11.6. Authenticating Users to Origin Servers . . . . . . . . . 110 225 11.6.1. WWW-Authenticate . . . . . . . . . . . . . . . . . . 110 226 11.6.2. Authorization . . . . . . . . . . . . . . . . . . . 111 227 11.6.3. Authentication-Info . . . . . . . . . . . . . . . . 111 228 11.7. Authenticating Clients to Proxies . . . . . . . . . . . 112 229 11.7.1. Proxy-Authenticate . . . . . . . . . . . . . . . . . 112 230 11.7.2. Proxy-Authorization . . . . . . . . . . . . . . . . 112 231 11.7.3. Proxy-Authentication-Info . . . . . . . . . . . . . 113 232 12. Content Negotiation . . . . . . . . . . . . . . . . . . . . . 113 233 12.1. Proactive Negotiation . . . . . . . . . . . . . . . . . 114 234 12.2. Reactive Negotiation . . . . . . . . . . . . . . . . . . 115 235 12.3. Request Content Negotiation . . . . . . . . . . . . . . 116 236 12.4. Content Negotiation Field Features . . . . . . . . . . . 116 237 12.4.1. Absence . . . . . . . . . . . . . . . . . . . . . . 116 238 12.4.2. Quality Values . . . . . . . . . . . . . . . . . . . 117 239 12.4.3. Wildcard Values . . . . . . . . . . . . . . . . . . 117 240 12.5. Content Negotiation Fields . . . . . . . . . . . . . . . 118 241 12.5.1. Accept . . . . . . . . . . . . . . . . . . . . . . . 118 242 12.5.2. Accept-Charset . . . . . . . . . . . . . . . . . . . 120 243 12.5.3. Accept-Encoding . . . . . . . . . . . . . . . . . . 121 244 12.5.4. Accept-Language . . . . . . . . . . . . . . . . . . 123 245 12.5.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . 124 246 13. Conditional Requests . . . . . . . . . . . . . . . . . . . . 125 247 13.1. Preconditions . . . . . . . . . . . . . . . . . . . . . 125 248 13.1.1. If-Match . . . . . . . . . . . . . . . . . . . . . . 126 249 13.1.2. If-None-Match . . . . . . . . . . . . . . . . . . . 128 250 13.1.3. If-Modified-Since . . . . . . . . . . . . . . . . . 130 251 13.1.4. If-Unmodified-Since . . . . . . . . . . . . . . . . 132 252 13.1.5. If-Range . . . . . . . . . . . . . . . . . . . . . . 133 253 13.2. Evaluation of Preconditions . . . . . . . . . . . . . . 135 254 13.2.1. When to Evaluate . . . . . . . . . . . . . . . . . . 135 255 13.2.2. Precedence of Preconditions . . . . . . . . . . . . 136 256 14. Range Requests . . . . . . . . . . . . . . . . . . . . . . . 137 257 14.1. Range Units . . . . . . . . . . . . . . . . . . . . . . 138 258 14.1.1. Range Specifiers . . . . . . . . . . . . . . . . . . 138 259 14.1.2. Byte Ranges . . . . . . . . . . . . . . . . . . . . 139 260 14.2. Range . . . . . . . . . . . . . . . . . . . . . . . . . 141 261 14.3. Accept-Ranges . . . . . . . . . . . . . . . . . . . . . 142 262 14.4. Content-Range . . . . . . . . . . . . . . . . . . . . . 143 263 14.5. Partial PUT . . . . . . . . . . . . . . . . . . . . . . 145 264 14.6. Media Type multipart/byteranges . . . . . . . . . . . . 146 265 15. Status Codes . . . . . . . . . . . . . . . . . . . . . . . . 148 266 15.1. Overview of Status Codes . . . . . . . . . . . . . . . . 149 267 15.2. Informational 1xx . . . . . . . . . . . . . . . . . . . 149 268 15.2.1. 100 Continue . . . . . . . . . . . . . . . . . . . . 150 269 15.2.2. 101 Switching Protocols . . . . . . . . . . . . . . 150 270 15.3. Successful 2xx . . . . . . . . . . . . . . . . . . . . . 150 271 15.3.1. 200 OK . . . . . . . . . . . . . . . . . . . . . . . 150 272 15.3.2. 201 Created . . . . . . . . . . . . . . . . . . . . 152 273 15.3.3. 202 Accepted . . . . . . . . . . . . . . . . . . . . 152 274 15.3.4. 203 Non-Authoritative Information . . . . . . . . . 152 275 15.3.5. 204 No Content . . . . . . . . . . . . . . . . . . . 153 276 15.3.6. 205 Reset Content . . . . . . . . . . . . . . . . . 153 277 15.3.7. 206 Partial Content . . . . . . . . . . . . . . . . 154 278 15.3.7.1. Single Part . . . . . . . . . . . . . . . . . . 155 279 15.3.7.2. Multiple Parts . . . . . . . . . . . . . . . . . 155 280 15.3.7.3. Combining Parts . . . . . . . . . . . . . . . . 157 281 15.4. Redirection 3xx . . . . . . . . . . . . . . . . . . . . 157 282 15.4.1. 300 Multiple Choices . . . . . . . . . . . . . . . . 159 283 15.4.2. 301 Moved Permanently . . . . . . . . . . . . . . . 160 284 15.4.3. 302 Found . . . . . . . . . . . . . . . . . . . . . 161 285 15.4.4. 303 See Other . . . . . . . . . . . . . . . . . . . 161 286 15.4.5. 304 Not Modified . . . . . . . . . . . . . . . . . . 162 287 15.4.6. 305 Use Proxy . . . . . . . . . . . . . . . . . . . 163 288 15.4.7. 306 (Unused) . . . . . . . . . . . . . . . . . . . . 163 289 15.4.8. 307 Temporary Redirect . . . . . . . . . . . . . . . 163 290 15.4.9. 308 Permanent Redirect . . . . . . . . . . . . . . . 163 291 15.5. Client Error 4xx . . . . . . . . . . . . . . . . . . . . 164 292 15.5.1. 400 Bad Request . . . . . . . . . . . . . . . . . . 164 293 15.5.2. 401 Unauthorized . . . . . . . . . . . . . . . . . . 164 294 15.5.3. 402 Payment Required . . . . . . . . . . . . . . . . 164 295 15.5.4. 403 Forbidden . . . . . . . . . . . . . . . . . . . 164 296 15.5.5. 404 Not Found . . . . . . . . . . . . . . . . . . . 165 297 15.5.6. 405 Method Not Allowed . . . . . . . . . . . . . . . 165 298 15.5.7. 406 Not Acceptable . . . . . . . . . . . . . . . . . 165 299 15.5.8. 407 Proxy Authentication Required . . . . . . . . . 166 300 15.5.9. 408 Request Timeout . . . . . . . . . . . . . . . . 166 301 15.5.10. 409 Conflict . . . . . . . . . . . . . . . . . . . . 166 302 15.5.11. 410 Gone . . . . . . . . . . . . . . . . . . . . . . 167 303 15.5.12. 411 Length Required . . . . . . . . . . . . . . . . 167 304 15.5.13. 412 Precondition Failed . . . . . . . . . . . . . . 167 305 15.5.14. 413 Content Too Large . . . . . . . . . . . . . . . 167 306 15.5.15. 414 URI Too Long . . . . . . . . . . . . . . . . . . 168 307 15.5.16. 415 Unsupported Media Type . . . . . . . . . . . . . 168 308 15.5.17. 416 Range Not Satisfiable . . . . . . . . . . . . . 168 309 15.5.18. 417 Expectation Failed . . . . . . . . . . . . . . . 169 310 15.5.19. 418 (Unused) . . . . . . . . . . . . . . . . . . . . 169 311 15.5.20. 421 Misdirected Request . . . . . . . . . . . . . . 170 312 15.5.21. 422 Unprocessable Content . . . . . . . . . . . . . 170 313 15.5.22. 426 Upgrade Required . . . . . . . . . . . . . . . . 170 314 15.6. Server Error 5xx . . . . . . . . . . . . . . . . . . . . 171 315 15.6.1. 500 Internal Server Error . . . . . . . . . . . . . 171 316 15.6.2. 501 Not Implemented . . . . . . . . . . . . . . . . 171 317 15.6.3. 502 Bad Gateway . . . . . . . . . . . . . . . . . . 171 318 15.6.4. 503 Service Unavailable . . . . . . . . . . . . . . 171 319 15.6.5. 504 Gateway Timeout . . . . . . . . . . . . . . . . 172 320 15.6.6. 505 HTTP Version Not Supported . . . . . . . . . . . 172 321 16. Extending HTTP . . . . . . . . . . . . . . . . . . . . . . . 172 322 16.1. Method Extensibility . . . . . . . . . . . . . . . . . . 173 323 16.1.1. Method Registry . . . . . . . . . . . . . . . . . . 173 324 16.1.2. Considerations for New Methods . . . . . . . . . . . 173 325 16.2. Status Code Extensibility . . . . . . . . . . . . . . . 174 326 16.2.1. Status Code Registry . . . . . . . . . . . . . . . . 174 327 16.2.2. Considerations for New Status Codes . . . . . . . . 174 328 16.3. Field Extensibility . . . . . . . . . . . . . . . . . . 175 329 16.3.1. Field Name Registry . . . . . . . . . . . . . . . . 176 330 16.3.2. Considerations for New Fields . . . . . . . . . . . 177 331 16.3.2.1. Considerations for New Field Names . . . . . . . 178 332 16.3.2.2. Considerations for New Field Values . . . . . . 179 334 16.4. Authentication Scheme Extensibility . . . . . . . . . . 180 335 16.4.1. Authentication Scheme Registry . . . . . . . . . . . 180 336 16.4.2. Considerations for New Authentication Schemes . . . 180 337 16.5. Range Unit Extensibility . . . . . . . . . . . . . . . . 181 338 16.5.1. Range Unit Registry . . . . . . . . . . . . . . . . 182 339 16.5.2. Considerations for New Range Units . . . . . . . . . 182 340 16.6. Content Coding Extensibility . . . . . . . . . . . . . . 182 341 16.6.1. Content Coding Registry . . . . . . . . . . . . . . 182 342 16.6.2. Considerations for New Content Codings . . . . . . . 183 343 16.7. Upgrade Token Registry . . . . . . . . . . . . . . . . . 183 344 17. Security Considerations . . . . . . . . . . . . . . . . . . . 184 345 17.1. Establishing Authority . . . . . . . . . . . . . . . . . 184 346 17.2. Risks of Intermediaries . . . . . . . . . . . . . . . . 185 347 17.3. Attacks Based on File and Path Names . . . . . . . . . . 186 348 17.4. Attacks Based on Command, Code, or Query Injection . . . 186 349 17.5. Attacks via Protocol Element Length . . . . . . . . . . 187 350 17.6. Attacks using Shared-dictionary Compression . . . . . . 187 351 17.7. Disclosure of Personal Information . . . . . . . . . . . 188 352 17.8. Privacy of Server Log Information . . . . . . . . . . . 188 353 17.9. Disclosure of Sensitive Information in URIs . . . . . . 189 354 17.10. Application Handling of Field Names . . . . . . . . . . 189 355 17.11. Disclosure of Fragment after Redirects . . . . . . . . . 190 356 17.12. Disclosure of Product Information . . . . . . . . . . . 191 357 17.13. Browser Fingerprinting . . . . . . . . . . . . . . . . . 191 358 17.14. Validator Retention . . . . . . . . . . . . . . . . . . 192 359 17.15. Denial-of-Service Attacks Using Range . . . . . . . . . 192 360 17.16. Authentication Considerations . . . . . . . . . . . . . 193 361 17.16.1. Confidentiality of Credentials . . . . . . . . . . 193 362 17.16.2. Credentials and Idle Clients . . . . . . . . . . . 193 363 17.16.3. Protection Spaces . . . . . . . . . . . . . . . . . 194 364 17.16.4. Additional Response Fields . . . . . . . . . . . . 194 365 18. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 194 366 18.1. URI Scheme Registration . . . . . . . . . . . . . . . . 195 367 18.2. Method Registration . . . . . . . . . . . . . . . . . . 195 368 18.3. Status Code Registration . . . . . . . . . . . . . . . . 195 369 18.4. Field Name Registration . . . . . . . . . . . . . . . . 198 370 18.5. Authentication Scheme Registration . . . . . . . . . . . 200 371 18.6. Content Coding Registration . . . . . . . . . . . . . . 201 372 18.7. Range Unit Registration . . . . . . . . . . . . . . . . 201 373 18.8. Media Type Registration . . . . . . . . . . . . . . . . 202 374 18.9. Port Registration . . . . . . . . . . . . . . . . . . . 202 375 18.10. Upgrade Token Registration . . . . . . . . . . . . . . . 202 376 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 202 377 19.1. Normative References . . . . . . . . . . . . . . . . . . 202 378 19.2. Informative References . . . . . . . . . . . . . . . . . 204 379 Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 211 380 Appendix B. Changes from previous RFCs . . . . . . . . . . . . . 215 381 B.1. Changes from RFC 2818 . . . . . . . . . . . . . . . . . . 215 382 B.2. Changes from RFC 7230 . . . . . . . . . . . . . . . . . . 215 383 B.3. Changes from RFC 7231 . . . . . . . . . . . . . . . . . . 216 384 B.4. Changes from RFC 7232 . . . . . . . . . . . . . . . . . . 218 385 B.5. Changes from RFC 7233 . . . . . . . . . . . . . . . . . . 219 386 B.6. Changes from RFC 7235 . . . . . . . . . . . . . . . . . . 219 387 B.7. Changes from RFC 7538 . . . . . . . . . . . . . . . . . . 219 388 B.8. Changes from RFC 7615 . . . . . . . . . . . . . . . . . . 219 389 B.9. Changes from RFC 7694 . . . . . . . . . . . . . . . . . . 219 390 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 219 391 C.1. Between RFC723x and draft 00 . . . . . . . . . . . . . . 219 392 C.2. Since draft-ietf-httpbis-semantics-00 . . . . . . . . . . 220 393 C.3. Since draft-ietf-httpbis-semantics-01 . . . . . . . . . . 220 394 C.4. Since draft-ietf-httpbis-semantics-02 . . . . . . . . . . 222 395 C.5. Since draft-ietf-httpbis-semantics-03 . . . . . . . . . . 223 396 C.6. Since draft-ietf-httpbis-semantics-04 . . . . . . . . . . 223 397 C.7. Since draft-ietf-httpbis-semantics-05 . . . . . . . . . . 224 398 C.8. Since draft-ietf-httpbis-semantics-06 . . . . . . . . . . 225 399 C.9. Since draft-ietf-httpbis-semantics-07 . . . . . . . . . . 227 400 C.10. Since draft-ietf-httpbis-semantics-08 . . . . . . . . . . 228 401 C.11. Since draft-ietf-httpbis-semantics-09 . . . . . . . . . . 229 402 C.12. Since draft-ietf-httpbis-semantics-10 . . . . . . . . . . 229 403 C.13. Since draft-ietf-httpbis-semantics-11 . . . . . . . . . . 231 404 C.14. Since draft-ietf-httpbis-semantics-12 . . . . . . . . . . 231 405 C.15. Since draft-ietf-httpbis-semantics-13 . . . . . . . . . . 233 406 C.16. Since draft-ietf-httpbis-semantics-14 . . . . . . . . . . 234 407 C.17. Since draft-ietf-httpbis-semantics-15 . . . . . . . . . . 236 408 C.18. Since draft-ietf-httpbis-semantics-16 . . . . . . . . . . 237 409 C.19. Since draft-ietf-httpbis-semantics-17 . . . . . . . . . . 237 410 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 239 411 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 412 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 251 414 1. Introduction 416 1.1. Purpose 418 The Hypertext Transfer Protocol (HTTP) is a family of stateless, 419 application-level, request/response protocols that share a generic 420 interface, extensible semantics, and self-descriptive messages to 421 enable flexible interaction with network-based hypertext information 422 systems. 424 HTTP hides the details of how a service is implemented by presenting 425 a uniform interface to clients that is independent of the types of 426 resources provided. Likewise, servers do not need to be aware of 427 each client's purpose: a request can be considered in isolation 428 rather than being associated with a specific type of client or a 429 predetermined sequence of application steps. This allows general- 430 purpose implementations to be used effectively in many different 431 contexts, reduces interaction complexity, and enables independent 432 evolution over time. 434 HTTP is also designed for use as an intermediation protocol, wherein 435 proxies and gateways can translate non-HTTP information systems into 436 a more generic interface. 438 One consequence of this flexibility is that the protocol cannot be 439 defined in terms of what occurs behind the interface. Instead, we 440 are limited to defining the syntax of communication, the intent of 441 received communication, and the expected behavior of recipients. If 442 the communication is considered in isolation, then successful actions 443 ought to be reflected in corresponding changes to the observable 444 interface provided by servers. However, since multiple clients might 445 act in parallel and perhaps at cross-purposes, we cannot require that 446 such changes be observable beyond the scope of a single response. 448 1.2. History and Evolution 450 HTTP has been the primary information transfer protocol for the World 451 Wide Web since its introduction in 1990. It began as a trivial 452 mechanism for low-latency requests, with a single method (GET) to 453 request transfer of a presumed hypertext document identified by a 454 given pathname. As the Web grew, HTTP was extended to enclose 455 requests and responses within messages, transfer arbitrary data 456 formats using MIME-like media types, and route requests through 457 intermediaries. These protocols were eventually defined as HTTP/0.9 458 and HTTP/1.0 (see [HTTP/1.0]). 460 HTTP/1.1 was designed to refine the protocol's features while 461 retaining compatibility with the existing text-based messaging 462 syntax, improving its interoperability, scalability, and robustness 463 across the Internet. This included length-based data delimiters for 464 both fixed and dynamic (chunked) content, a consistent framework for 465 content negotiation, opaque validators for conditional requests, 466 cache controls for better cache consistency, range requests for 467 partial updates, and default persistent connections. HTTP/1.1 was 468 introduced in 1995 and published on the standards track in 1997 469 [RFC2068], revised in 1999 [RFC2616], and revised again in 2014 470 ([RFC7230] - [RFC7235]). 472 HTTP/2 ([HTTP/2]) introduced a multiplexed session layer on top of 473 the existing TLS and TCP protocols for exchanging concurrent HTTP 474 messages with efficient field compression and server push. HTTP/3 475 ([HTTP/3]) provides greater independence for concurrent messages by 476 using QUIC as a secure multiplexed transport over UDP instead of TCP. 478 All three major versions of HTTP rely on the semantics defined by 479 this document. They have not obsoleted each other because each one 480 has specific benefits and limitations depending on the context of 481 use. Implementations are expected to choose the most appropriate 482 transport and messaging syntax for their particular context. 484 This revision of HTTP separates the definition of semantics (this 485 document) and caching ([CACHING]) from the current HTTP/1.1 messaging 486 syntax ([HTTP/1.1]) to allow each major protocol version to progress 487 independently while referring to the same core semantics. 489 1.3. Core Semantics 491 HTTP provides a uniform interface for interacting with a resource 492 (Section 3.1) - regardless of its type, nature, or implementation - 493 by sending messages that manipulate or transfer representations 494 (Section 3.2). 496 Each message is either a request or a response. A client constructs 497 request messages that communicate its intentions and routes those 498 messages toward an identified origin server. A server listens for 499 requests, parses each message received, interprets the message 500 semantics in relation to the identified target resource, and responds 501 to that request with one or more response messages. The client 502 examines received responses to see if its intentions were carried 503 out, determining what to do next based on the status codes and 504 content received. 506 HTTP semantics include the intentions defined by each request method 507 (Section 9), extensions to those semantics that might be described in 508 request header fields, status codes that describe the response 509 (Section 15), and other control data and resource metadata that might 510 be given in response fields. 512 Semantics also include representation metadata that describe how 513 content is intended to be interpreted by a recipient, request header 514 fields that might influence content selection, and the various 515 selection algorithms that are collectively referred to as _content 516 negotiation_ (Section 12). 518 1.4. Specifications Obsoleted by this Document 520 This document obsoletes the following specifications: 522 +============================================+===========+=========+ 523 | Title | Reference | Changes | 524 +============================================+===========+=========+ 525 | HTTP Over TLS | [RFC2818] | B.1 | 526 +--------------------------------------------+-----------+---------+ 527 | HTTP/1.1 Message Syntax and Routing [*] | [RFC7230] | B.2 | 528 +--------------------------------------------+-----------+---------+ 529 | HTTP/1.1 Semantics and Content | [RFC7231] | B.3 | 530 +--------------------------------------------+-----------+---------+ 531 | HTTP/1.1 Conditional Requests | [RFC7232] | B.4 | 532 +--------------------------------------------+-----------+---------+ 533 | HTTP/1.1 Range Requests | [RFC7233] | B.5 | 534 +--------------------------------------------+-----------+---------+ 535 | HTTP/1.1 Authentication | [RFC7235] | B.6 | 536 +--------------------------------------------+-----------+---------+ 537 | HTTP Status Code 308 (Permanent Redirect) | [RFC7538] | B.7 | 538 +--------------------------------------------+-----------+---------+ 539 | HTTP Authentication-Info and Proxy- | [RFC7615] | B.8 | 540 | Authentication-Info Response Header Fields | | | 541 +--------------------------------------------+-----------+---------+ 542 | HTTP Client-Initiated Content-Encoding | [RFC7694] | B.9 | 543 +--------------------------------------------+-----------+---------+ 545 Table 1 547 [*] This document only obsoletes the portions of RFC 7230 that are 548 independent of the HTTP/1.1 messaging syntax and connection 549 management; the remaining bits of RFC 7230 are obsoleted by 550 "HTTP/1.1" [HTTP/1.1]. 552 2. Conformance 554 2.1. Syntax Notation 556 This specification uses the Augmented Backus-Naur Form (ABNF) 557 notation of [RFC5234], extended with the notation for case- 558 sensitivity in strings defined in [RFC7405]. 560 It also uses a list extension, defined in Section 5.6.1, that allows 561 for compact definition of comma-separated lists using a "#" operator 562 (similar to how the "*" operator indicates repetition). Appendix A 563 shows the collected grammar with all list operators expanded to 564 standard ABNF notation. 566 As a convention, ABNF rule names prefixed with "obs-" denote 567 "obsolete" grammar rules that appear for historical reasons. 569 The following core rules are included by reference, as defined in 570 Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), 571 CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double 572 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF 573 (line feed), OCTET (any 8-bit sequence of data), SP (space), and 574 VCHAR (any visible US-ASCII character). 576 Section 5.6 defines some generic syntactic components for field 577 values. 579 This specification uses the terms "character", "character encoding 580 scheme", "charset", and "protocol element" as they are defined in 581 [RFC6365]. 583 2.2. Requirements Notation 585 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 586 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 587 "OPTIONAL" in this document are to be interpreted as described in BCP 588 14 [RFC2119] [RFC8174] when, and only when, they appear in all 589 capitals, as shown here. 591 This specification targets conformance criteria according to the role 592 of a participant in HTTP communication. Hence, requirements are 593 placed on senders, recipients, clients, servers, user agents, 594 intermediaries, origin servers, proxies, gateways, or caches, 595 depending on what behavior is being constrained by the requirement. 596 Additional requirements are placed on implementations, resource 597 owners, and protocol element registrations when they apply beyond the 598 scope of a single communication. 600 The verb "generate" is used instead of "send" where a requirement 601 applies only to implementations that create the protocol element, 602 rather than an implementation that forwards a received element 603 downstream. 605 An implementation is considered conformant if it complies with all of 606 the requirements associated with the roles it partakes in HTTP. 608 A sender MUST NOT generate protocol elements that do not match the 609 grammar defined by the corresponding ABNF rules. Within a given 610 message, a sender MUST NOT generate protocol elements or syntax 611 alternatives that are only allowed to be generated by participants in 612 other roles (i.e., a role that the sender does not have for that 613 message). 615 Conformance to HTTP includes both conformance to the particular 616 messaging syntax of the protocol version in use and conformance to 617 the semantics of protocol elements sent. For example, a client that 618 claims conformance to HTTP/1.1 but fails to recognize the features 619 required of HTTP/1.1 recipients will fail to interoperate with 620 servers that adjust their responses in accordance with those claims. 621 Features that reflect user choices, such as content negotiation and 622 user-selected extensions, can impact application behavior beyond the 623 protocol stream; sending protocol elements that inaccurately reflect 624 a user's choices will confuse the user and inhibit choice. 626 When an implementation fails semantic conformance, recipients of that 627 implementation's messages will eventually develop workarounds to 628 adjust their behavior accordingly. A recipient MAY employ such 629 workarounds while remaining conformant to this protocol if the 630 workarounds are limited to the implementations at fault. For 631 example, servers often scan portions of the User-Agent field value, 632 and user agents often scan the Server field value, to adjust their 633 own behavior with respect to known bugs or poorly chosen defaults. 635 2.3. Length Requirements 637 A recipient SHOULD parse a received protocol element defensively, 638 with only marginal expectations that the element will conform to its 639 ABNF grammar and fit within a reasonable buffer size. 641 HTTP does not have specific length limitations for many of its 642 protocol elements because the lengths that might be appropriate will 643 vary widely, depending on the deployment context and purpose of the 644 implementation. Hence, interoperability between senders and 645 recipients depends on shared expectations regarding what is a 646 reasonable length for each protocol element. Furthermore, what is 647 commonly understood to be a reasonable length for some protocol 648 elements has changed over the course of the past two decades of HTTP 649 use and is expected to continue changing in the future. 651 At a minimum, a recipient MUST be able to parse and process protocol 652 element lengths that are at least as long as the values that it 653 generates for those same protocol elements in other messages. For 654 example, an origin server that publishes very long URI references to 655 its own resources needs to be able to parse and process those same 656 references when received as a target URI. 658 Many received protocol elements are only parsed to the extent 659 necessary to identify and forward that element downstream. For 660 example, an intermediary might parse a received field into its field 661 name and field value components, but then forward the field without 662 further parsing inside the field value. 664 2.4. Error Handling 666 A recipient MUST interpret a received protocol element according to 667 the semantics defined for it by this specification, including 668 extensions to this specification, unless the recipient has determined 669 (through experience or configuration) that the sender incorrectly 670 implements what is implied by those semantics. For example, an 671 origin server might disregard the contents of a received 672 Accept-Encoding header field if inspection of the User-Agent header 673 field indicates a specific implementation version that is known to 674 fail on receipt of certain content codings. 676 Unless noted otherwise, a recipient MAY attempt to recover a usable 677 protocol element from an invalid construct. HTTP does not define 678 specific error handling mechanisms except when they have a direct 679 impact on security, since different applications of the protocol 680 require different error handling strategies. For example, a Web 681 browser might wish to transparently recover from a response where the 682 Location header field doesn't parse according to the ABNF, whereas a 683 systems control client might consider any form of error recovery to 684 be dangerous. 686 Some requests can be automatically retried by a client in the event 687 of an underlying connection failure, as described in Section 9.2.2. 689 2.5. Protocol Version 691 HTTP's version number consists of two decimal digits separated by a 692 "." (period or decimal point). The first digit ("major version") 693 indicates the messaging syntax, whereas the second digit ("minor 694 version") indicates the highest minor version within that major 695 version to which the sender is conformant (able to understand for 696 future communication). 698 While HTTP's core semantics don't change between protocol versions, 699 the expression of them "on the wire" can change, and so the HTTP 700 version number changes when incompatible changes are made to the wire 701 format. Additionally, HTTP allows incremental, backwards-compatible 702 changes to be made to the protocol without changing its version 703 through the use of defined extension points (Section 16). 705 The protocol version as a whole indicates the sender's conformance 706 with the set of requirements laid out in that version's corresponding 707 specification of HTTP. For example, the version "HTTP/1.1" is 708 defined by the combined specifications of this document, "HTTP 709 Caching" [CACHING], and "HTTP/1.1" [HTTP/1.1]. 711 HTTP's major version number is incremented when an incompatible 712 message syntax is introduced. The minor number is incremented when 713 changes made to the protocol have the effect of adding to the message 714 semantics or implying additional capabilities of the sender. 716 The minor version advertises the sender's communication capabilities 717 even when the sender is only using a backwards-compatible subset of 718 the protocol, thereby letting the recipient know that more advanced 719 features can be used in response (by servers) or in future requests 720 (by clients). 722 When a major version of HTTP does not define any minor versions, the 723 minor version "0" is implied. The "0" is used when referring to that 724 protocol within elements that require a minor version identifier. 726 3. Terminology and Core Concepts 728 HTTP was created for the World Wide Web (WWW) architecture and has 729 evolved over time to support the scalability needs of a worldwide 730 hypertext system. Much of that architecture is reflected in the 731 terminology used to define HTTP. 733 3.1. Resources 735 The target of an HTTP request is called a _resource_. HTTP does not 736 limit the nature of a resource; it merely defines an interface that 737 might be used to interact with resources. Most resources are 738 identified by a Uniform Resource Identifier (URI), as described in 739 Section 4. 741 One design goal of HTTP is to separate resource identification from 742 request semantics, which is made possible by vesting the request 743 semantics in the request method (Section 9) and a few request- 744 modifying header fields. A resource cannot treat a request in a 745 manner inconsistent with the semantics of the method of the request. 746 For example, though the URI of a resource might imply semantics that 747 are not safe, a client can expect the resource to avoid actions that 748 are unsafe when processing a request with a safe method (see 749 Section 9.2.1). 751 HTTP relies upon the Uniform Resource Identifier (URI) standard [URI] 752 to indicate the target resource (Section 7.1) and relationships 753 between resources. 755 3.2. Representations 757 A _representation_ is information that is intended to reflect a past, 758 current, or desired state of a given resource, in a format that can 759 be readily communicated via the protocol. A representation consists 760 of a set of representation metadata and a potentially unbounded 761 stream of representation data (Section 8). 763 HTTP allows "information hiding" behind its uniform interface by 764 defining communication with respect to a transferable representation 765 of the resource state, rather than transferring the resource itself. 766 This allows the resource identified by a URI to be anything, 767 including temporal functions like "the current weather in Laguna 768 Beach", while potentially providing information that represents that 769 resource at the time a message is generated [REST]. 771 The uniform interface is similar to a window through which one can 772 observe and act upon a thing only through the communication of 773 messages to an independent actor on the other side. A shared 774 abstraction is needed to represent ("take the place of") the current 775 or desired state of that thing in our communications. When a 776 representation is hypertext, it can provide both a representation of 777 the resource state and processing instructions that help guide the 778 recipient's future interactions. 780 A target resource might be provided with, or be capable of 781 generating, multiple representations that are each intended to 782 reflect the resource's current state. An algorithm, usually based on 783 content negotiation (Section 12), would be used to select one of 784 those representations as being most applicable to a given request. 785 This _selected representation_ provides the data and metadata for 786 evaluating conditional requests (Section 13) and constructing the 787 content for 200 (OK), 206 (Partial Content), and 304 (Not Modified) 788 responses to GET (Section 9.3.1). 790 3.3. Connections, Clients and Servers 792 HTTP is a client/server protocol that operates over a reliable 793 transport- or session-layer _connection_. 795 An HTTP _client_ is a program that establishes a connection to a 796 server for the purpose of sending one or more HTTP requests. An HTTP 797 _server_ is a program that accepts connections in order to service 798 HTTP requests by sending HTTP responses. 800 The terms "client" and "server" refer only to the roles that these 801 programs perform for a particular connection. The same program might 802 act as a client on some connections and a server on others. 804 HTTP is defined as a stateless protocol, meaning that each request 805 message's semantics can be understood in isolation, and that the 806 relationship between connections and messages on them has no impact 807 on the interpretation of those messages. For example, a CONNECT 808 request (Section 9.3.6) or a request with the Upgrade header field 809 (Section 7.8) can occur at any time, not just in the first message on 810 a connection. Many implementations depend on HTTP's stateless design 811 in order to reuse proxied connections or dynamically load balance 812 requests across multiple servers. 814 As a result, a server MUST NOT assume that two requests on the same 815 connection are from the same user agent unless the connection is 816 secured and specific to that agent. Some non-standard HTTP 817 extensions (e.g., [RFC4559]) have been known to violate this 818 requirement, resulting in security and interoperability problems. 820 3.4. Messages 822 HTTP is a stateless request/response protocol for exchanging 823 _messages_ across a connection. The terms _sender_ and _recipient_ 824 refer to any implementation that sends or receives a given message, 825 respectively. 827 A client sends requests to a server in the form of a _request_ 828 message with a method (Section 9) and request target (Section 7.1). 829 The request might also contain header fields (Section 6.3) for 830 request modifiers, client information, and representation metadata, 831 content (Section 6.4) intended for processing in accordance with the 832 method, and trailer fields (Section 6.5) to communicate information 833 collected while sending the content. 835 A server responds to a client's request by sending one or more 836 _response_ messages, each including a status code (Section 15). The 837 response might also contain header fields for server information, 838 resource metadata, and representation metadata, content to be 839 interpreted in accordance with the status code, and trailer fields to 840 communicate information collected while sending the content. 842 3.5. User Agents 844 The term _user agent_ refers to any of the various client programs 845 that initiate a request. 847 The most familiar form of user agent is the general-purpose Web 848 browser, but that's only a small percentage of implementations. 849 Other common user agents include spiders (web-traversing robots), 850 command-line tools, billboard screens, household appliances, scales, 851 light bulbs, firmware update scripts, mobile apps, and communication 852 devices in a multitude of shapes and sizes. 854 Being a user agent does not imply that there is a human user directly 855 interacting with the software agent at the time of a request. In 856 many cases, a user agent is installed or configured to run in the 857 background and save its results for later inspection (or save only a 858 subset of those results that might be interesting or erroneous). 859 Spiders, for example, are typically given a start URI and configured 860 to follow certain behavior while crawling the Web as a hypertext 861 graph. 863 Many user agents cannot, or choose not to, make interactive 864 suggestions to their user or provide adequate warning for security or 865 privacy concerns. In the few cases where this specification requires 866 reporting of errors to the user, it is acceptable for such reporting 867 to only be observable in an error console or log file. Likewise, 868 requirements that an automated action be confirmed by the user before 869 proceeding might be met via advance configuration choices, run-time 870 options, or simple avoidance of the unsafe action; confirmation does 871 not imply any specific user interface or interruption of normal 872 processing if the user has already made that choice. 874 3.6. Origin Server 876 The term _origin server_ refers to a program that can originate 877 authoritative responses for a given target resource. 879 The most familiar form of origin server are large public websites. 880 However, like user agents being equated with browsers, it is easy to 881 be misled into thinking that all origin servers are alike. Common 882 origin servers also include home automation units, configurable 883 networking components, office machines, autonomous robots, news 884 feeds, traffic cameras, real-time ad selectors, and video-on-demand 885 platforms. 887 Most HTTP communication consists of a retrieval request (GET) for a 888 representation of some resource identified by a URI. In the simplest 889 case, this might be accomplished via a single bidirectional 890 connection (===) between the user agent (UA) and the origin server 891 (O). 893 request > 894 UA ======================================= O 895 < response 897 Figure 1 899 3.7. Intermediaries 901 HTTP enables the use of intermediaries to satisfy requests through a 902 chain of connections. There are three common forms of HTTP 903 _intermediary_: proxy, gateway, and tunnel. In some cases, a single 904 intermediary might act as an origin server, proxy, gateway, or 905 tunnel, switching behavior based on the nature of each request. 907 > > > > 908 UA =========== A =========== B =========== C =========== O 909 < < < < 911 Figure 2 913 The figure above shows three intermediaries (A, B, and C) between the 914 user agent and origin server. A request or response message that 915 travels the whole chain will pass through four separate connections. 916 Some HTTP communication options might apply only to the connection 917 with the nearest, non-tunnel neighbor, only to the endpoints of the 918 chain, or to all connections along the chain. Although the diagram 919 is linear, each participant might be engaged in multiple, 920 simultaneous communications. For example, B might be receiving 921 requests from many clients other than A, and/or forwarding requests 922 to servers other than C, at the same time that it is handling A's 923 request. Likewise, later requests might be sent through a different 924 path of connections, often based on dynamic configuration for load 925 balancing. 927 The terms _upstream_ and _downstream_ are used to describe 928 directional requirements in relation to the message flow: all 929 messages flow from upstream to downstream. The terms "inbound" and 930 "outbound" are used to describe directional requirements in relation 931 to the request route: _inbound_ means toward the origin server and 932 _outbound_ means toward the user agent. 934 A _proxy_ is a message-forwarding agent that is chosen by the client, 935 usually via local configuration rules, to receive requests for some 936 type(s) of absolute URI and attempt to satisfy those requests via 937 translation through the HTTP interface. Some translations are 938 minimal, such as for proxy requests for "http" URIs, whereas other 939 requests might require translation to and from entirely different 940 application-level protocols. Proxies are often used to group an 941 organization's HTTP requests through a common intermediary for the 942 sake of security, annotation services, or shared caching. Some 943 proxies are designed to apply transformations to selected messages or 944 content while they are being forwarded, as described in Section 7.7. 946 A _gateway_ (a.k.a. _reverse proxy_) is an intermediary that acts as 947 an origin server for the outbound connection but translates received 948 requests and forwards them inbound to another server or servers. 949 Gateways are often used to encapsulate legacy or untrusted 950 information services, to improve server performance through 951 _accelerator_ caching, and to enable partitioning or load balancing 952 of HTTP services across multiple machines. 954 All HTTP requirements applicable to an origin server also apply to 955 the outbound communication of a gateway. A gateway communicates with 956 inbound servers using any protocol that it desires, including private 957 extensions to HTTP that are outside the scope of this specification. 958 However, an HTTP-to-HTTP gateway that wishes to interoperate with 959 third-party HTTP servers needs to conform to user agent requirements 960 on the gateway's inbound connection. 962 A _tunnel_ acts as a blind relay between two connections without 963 changing the messages. Once active, a tunnel is not considered a 964 party to the HTTP communication, though the tunnel might have been 965 initiated by an HTTP request. A tunnel ceases to exist when both 966 ends of the relayed connection are closed. Tunnels are used to 967 extend a virtual connection through an intermediary, such as when 968 Transport Layer Security (TLS, [TLS13]) is used to establish 969 confidential communication through a shared firewall proxy. 971 The above categories for intermediary only consider those acting as 972 participants in the HTTP communication. There are also 973 intermediaries that can act on lower layers of the network protocol 974 stack, filtering or redirecting HTTP traffic without the knowledge or 975 permission of message senders. Network intermediaries are 976 indistinguishable (at a protocol level) from an on-path attacker, 977 often introducing security flaws or interoperability problems due to 978 mistakenly violating HTTP semantics. 980 For example, an _interception proxy_ [RFC3040] (also commonly known 981 as a _transparent proxy_ [RFC1919]) differs from an HTTP proxy 982 because it is not chosen by the client. Instead, an interception 983 proxy filters or redirects outgoing TCP port 80 packets (and 984 occasionally other common port traffic). Interception proxies are 985 commonly found on public network access points, as a means of 986 enforcing account subscription prior to allowing use of non-local 987 Internet services, and within corporate firewalls to enforce network 988 usage policies. 990 3.8. Caches 992 A _cache_ is a local store of previous response messages and the 993 subsystem that controls its message storage, retrieval, and deletion. 994 A cache stores cacheable responses in order to reduce the response 995 time and network bandwidth consumption on future, equivalent 996 requests. Any client or server MAY employ a cache, though a cache 997 cannot be used while acting as a tunnel. 999 The effect of a cache is that the request/response chain is shortened 1000 if one of the participants along the chain has a cached response 1001 applicable to that request. The following illustrates the resulting 1002 chain if B has a cached copy of an earlier response from O (via C) 1003 for a request that has not been cached by UA or A. 1005 > > 1006 UA =========== A =========== B - - - - - - C - - - - - - O 1007 < < 1009 Figure 3 1011 A response is _cacheable_ if a cache is allowed to store a copy of 1012 the response message for use in answering subsequent requests. Even 1013 when a response is cacheable, there might be additional constraints 1014 placed by the client or by the origin server on when that cached 1015 response can be used for a particular request. HTTP requirements for 1016 cache behavior and cacheable responses are defined in [CACHING]. 1018 There is a wide variety of architectures and configurations of caches 1019 deployed across the World Wide Web and inside large organizations. 1020 These include national hierarchies of proxy caches to save bandwidth 1021 and reduce latency, Content Delivery Networks that use gateway 1022 caching to optimise regional and global distribution of popular 1023 sites, collaborative systems that broadcast or multicast cache 1024 entries, archives of pre-fetched cache entries for use in off-line or 1025 high-latency environments, and so on. 1027 3.9. Example Message Exchange 1029 The following example illustrates a typical HTTP/1.1 message exchange 1030 for a GET request (Section 9.3.1) on the URI "http://www.example.com/ 1031 hello.txt": 1033 Client request: 1035 GET /hello.txt HTTP/1.1 1036 User-Agent: curl/7.64.1 1037 Host: www.example.com 1038 Accept-Language: en, mi 1040 Server response: 1042 HTTP/1.1 200 OK 1043 Date: Mon, 27 Jul 2009 12:28:53 GMT 1044 Server: Apache 1045 Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT 1046 ETag: "34aa387-d-1568eb00" 1047 Accept-Ranges: bytes 1048 Content-Length: 51 1049 Vary: Accept-Encoding 1050 Content-Type: text/plain 1052 Hello World! My content includes a trailing CRLF. 1054 4. Identifiers in HTTP 1056 Uniform Resource Identifiers (URIs) [URI] are used throughout HTTP as 1057 the means for identifying resources (Section 3.1). 1059 4.1. URI References 1061 URI references are used to target requests, indicate redirects, and 1062 define relationships. 1064 The definitions of "URI-reference", "absolute-URI", "relative-part", 1065 "authority", "port", "host", "path-abempty", "segment", and "query" 1066 are adopted from the URI generic syntax. An "absolute-path" rule is 1067 defined for protocol elements that can contain a non-empty path 1068 component. (This rule differs slightly from the path-abempty rule of 1069 RFC 3986, which allows for an empty path, and path-absolute rule, 1070 which does not allow paths that begin with "//".) A "partial-URI" 1071 rule is defined for protocol elements that can contain a relative URI 1072 but not a fragment component. 1074 URI-reference = 1075 absolute-URI = 1076 relative-part = 1077 authority = 1078 uri-host = 1079 port = 1080 path-abempty = 1081 segment = 1082 query = 1084 absolute-path = 1*( "/" segment ) 1085 partial-URI = relative-part [ "?" query ] 1087 Each protocol element in HTTP that allows a URI reference will 1088 indicate in its ABNF production whether the element allows any form 1089 of reference (URI-reference), only a URI in absolute form (absolute- 1090 URI), only the path and optional query components (partial-URI), or 1091 some combination of the above. Unless otherwise indicated, URI 1092 references are parsed relative to the target URI (Section 7.1). 1094 It is RECOMMENDED that all senders and recipients support, at a 1095 minimum, URIs with lengths of 8000 octets in protocol elements. Note 1096 that this implies some structures and on-wire representations (for 1097 example, the request line in HTTP/1.1) will necessarily be larger in 1098 some cases. 1100 4.2. HTTP-Related URI Schemes 1102 IANA maintains the registry of URI Schemes [BCP35] at 1103 . Although requests 1104 might target any URI scheme, the following schemes are inherent to 1105 HTTP servers: 1107 +============+====================================+=======+ 1108 | URI Scheme | Description | Ref. | 1109 +============+====================================+=======+ 1110 | http | Hypertext Transfer Protocol | 4.2.1 | 1111 +------------+------------------------------------+-------+ 1112 | https | Hypertext Transfer Protocol Secure | 4.2.2 | 1113 +------------+------------------------------------+-------+ 1115 Table 2 1117 Note that the presence of an "http" or "https" URI does not imply 1118 that there is always an HTTP server at the identified origin 1119 listening for connections. Anyone can mint a URI, whether or not a 1120 server exists and whether or not that server currently maps that 1121 identifier to a resource. The delegated nature of registered names 1122 and IP addresses creates a federated namespace whether or not an HTTP 1123 server is present. 1125 4.2.1. http URI Scheme 1127 The "http" URI scheme is hereby defined for minting identifiers 1128 within the hierarchical namespace governed by a potential HTTP origin 1129 server listening for TCP ([TCP]) connections on a given port. 1131 http-URI = "http" "://" authority path-abempty [ "?" query ] 1133 The origin server for an "http" URI is identified by the authority 1134 component, which includes a host identifier ([URI], Section 3.2.2) 1135 and optional port number ([URI], Section 3.2.3). If the port 1136 subcomponent is empty or not given, TCP port 80 (the reserved port 1137 for WWW services) is the default. The origin determines who has the 1138 right to respond authoritatively to requests that target the 1139 identified resource, as defined in Section 4.3.2. 1141 A sender MUST NOT generate an "http" URI with an empty host 1142 identifier. A recipient that processes such a URI reference MUST 1143 reject it as invalid. 1145 The hierarchical path component and optional query component identify 1146 the target resource within that origin server's name space. 1148 4.2.2. https URI Scheme 1150 The "https" URI scheme is hereby defined for minting identifiers 1151 within the hierarchical namespace governed by a potential origin 1152 server listening for TCP connections on a given port and capable of 1153 establishing a TLS ([TLS13]) connection that has been secured for 1154 HTTP communication. In this context, _secured_ specifically means 1155 that the server has been authenticated as acting on behalf of the 1156 identified authority and all HTTP communication with that server has 1157 confidentiality and integrity protection that is acceptable to both 1158 client and server. 1160 https-URI = "https" "://" authority path-abempty [ "?" query ] 1162 The origin server for an "https" URI is identified by the authority 1163 component, which includes a host identifier ([URI], Section 3.2.2) 1164 and optional port number ([URI], Section 3.2.3). If the port 1165 subcomponent is empty or not given, TCP port 443 (the reserved port 1166 for HTTP over TLS) is the default. The origin determines who has the 1167 right to respond authoritatively to requests that target the 1168 identified resource, as defined in Section 4.3.3. 1170 A sender MUST NOT generate an "https" URI with an empty host 1171 identifier. A recipient that processes such a URI reference MUST 1172 reject it as invalid. 1174 The hierarchical path component and optional query component identify 1175 the target resource within that origin server's name space. 1177 A client MUST ensure that its HTTP requests for an "https" resource 1178 are secured, prior to being communicated, and that it only accepts 1179 secured responses to those requests. Note that the definition of 1180 what cryptographic mechanisms are acceptable to client and server are 1181 usually negotiated and can change over time. 1183 Resources made available via the "https" scheme have no shared 1184 identity with the "http" scheme. They are distinct origins with 1185 separate namespaces. However, extensions to HTTP that are defined as 1186 applying to all origins with the same host, such as the Cookie 1187 protocol [COOKIE], allow information set by one service to impact 1188 communication with other services within a matching group of host 1189 domains. Such extensions ought to be designed with great care to 1190 prevent information obtained from a secured connection being 1191 inadvertently exchanged within an unsecured context. 1193 4.2.3. http(s) Normalization and Comparison 1195 The "http" and "https" URI are normalized and compared according to 1196 the methods defined in Section 6 of [URI], using the defaults 1197 described above for each scheme. 1199 HTTP does not require use of a specific method for determining 1200 equivalence. For example, a cache key might be compared as a simple 1201 string, after syntax-based normalization, or after scheme-based 1202 normalization. 1204 Scheme-based normalization (Section 6.2.3 of [URI]) of "http" and 1205 "https" URIs involves the following additional rules: 1207 * If the port is equal to the default port for a scheme, the normal 1208 form is to omit the port subcomponent. 1210 * When not being used as the target of an OPTIONS request, an empty 1211 path component is equivalent to an absolute path of "/", so the 1212 normal form is to provide a path of "/" instead. 1214 * The scheme and host are case-insensitive and normally provided in 1215 lowercase; all other components are compared in a case-sensitive 1216 manner. 1218 * Characters other than those in the "reserved" set are equivalent 1219 to their percent-encoded octets: the normal form is to not encode 1220 them (see Sections 2.1 and 2.2 of [URI]). 1222 For example, the following three URIs are equivalent: 1224 http://example.com:80/~smith/home.html 1225 http://EXAMPLE.com/%7Esmith/home.html 1226 http://EXAMPLE.com:/%7esmith/home.html 1228 Two HTTP URIs that are equivalent after normalization (using any 1229 method) can be assumed to identify the same resource, and any HTTP 1230 component MAY perform normalization. As a result, distinct resources 1231 SHOULD NOT be identified by HTTP URIs that are equivalent after 1232 normalization (using any method defined in Section 6.2 of [URI]). 1234 4.2.4. Deprecation of userinfo in http(s) URIs 1236 The URI generic syntax for authority also includes a userinfo 1237 subcomponent ([URI], Section 3.2.1) for including user authentication 1238 information in the URI. In that subcomponent, the use of the format 1239 "user:password" is deprecated. 1241 Some implementations make use of the userinfo component for internal 1242 configuration of authentication information, such as within command 1243 invocation options, configuration files, or bookmark lists, even 1244 though such usage might expose a user identifier or password. 1246 A sender MUST NOT generate the userinfo subcomponent (and its "@" 1247 delimiter) when an "http" or "https" URI reference is generated 1248 within a message as a target URI or field value. 1250 Before making use of an "http" or "https" URI reference received from 1251 an untrusted source, a recipient SHOULD parse for userinfo and treat 1252 its presence as an error; it is likely being used to obscure the 1253 authority for the sake of phishing attacks. 1255 4.2.5. http(s) References with Fragment Identifiers 1257 Fragment identifiers allow for indirect identification of a secondary 1258 resource, independent of the URI scheme, as defined in Section 3.5 of 1259 [URI]. Some protocol elements that refer to a URI allow inclusion of 1260 a fragment, while others do not. They are distinguished by use of 1261 the ABNF rule for elements where fragment is allowed; otherwise, a 1262 specific rule that excludes fragments is used. 1264 | *Note:* The fragment identifier component is not part of the 1265 | scheme definition for a URI scheme (see Section 4.3 of [URI]), 1266 | thus does not appear in the ABNF definitions for the "http" and 1267 | "https" URI schemes above. 1269 4.3. Authoritative Access 1271 Authoritative access refers to dereferencing a given identifier, for 1272 the sake of access to the identified resource, in a way that the 1273 client believes is authoritative (controlled by the resource owner). 1274 The process for determining whether access is granted is defined by 1275 the URI scheme and often uses data within the URI components, such as 1276 the authority component when the generic syntax is used. However, 1277 authoritative access is not limited to the identified mechanism. 1279 Section 4.3.1 defines the concept of an origin as an aid to such 1280 uses, and the subsequent subsections explain how to establish that a 1281 peer has the authority to represent an origin. 1283 See Section 17.1 for security considerations related to establishing 1284 authority. 1286 4.3.1. URI Origin 1288 The _origin_ for a given URI is the triple of scheme, host, and port 1289 after normalizing the scheme and host to lowercase and normalizing 1290 the port to remove any leading zeros. If port is elided from the 1291 URI, the default port for that scheme is used. For example, the URI 1293 https://Example.Com/happy.js 1295 would have the origin 1297 { "https", "example.com", "443" } 1299 which can also be described as the normalized URI prefix with port 1300 always present: 1302 https://example.com:443 1304 Each origin defines its own namespace and controls how identifiers 1305 within that namespace are mapped to resources. In turn, how the 1306 origin responds to valid requests, consistently over time, determines 1307 the semantics that users will associate with a URI, and the 1308 usefulness of those semantics is what ultimately transforms these 1309 mechanisms into a "resource" for users to reference and access in the 1310 future. 1312 Two origins are distinct if they differ in scheme, host, or port. 1313 Even when it can be verified that the same entity controls two 1314 distinct origins, the two namespaces under those origins are distinct 1315 unless explicitly aliased by a server authoritative for that origin. 1317 Origin is also used within HTML and related Web protocols, beyond the 1318 scope of this document, as described in [RFC6454]. 1320 4.3.2. http origins 1322 Although HTTP is independent of the transport protocol, the "http" 1323 scheme (Section 4.2.1) is specific to associating authority with 1324 whomever controls the origin server listening for TCP connections on 1325 the indicated port of whatever host is identified within the 1326 authority component. This is a very weak sense of authority because 1327 it depends on both client-specific name resolution mechanisms and 1328 communication that might not be secured from an on-path attacker. 1329 Nevertheless, it is a sufficient minimum for binding "http" 1330 identifiers to an origin server for consistent resolution within a 1331 trusted environment. 1333 If the host identifier is provided as an IP address, the origin 1334 server is the listener (if any) on the indicated TCP port at that IP 1335 address. If host is a registered name, the registered name is an 1336 indirect identifier for use with a name resolution service, such as 1337 DNS, to find an address for an appropriate origin server. 1339 When an "http" URI is used within a context that calls for access to 1340 the indicated resource, a client MAY attempt access by resolving the 1341 host identifier to an IP address, establishing a TCP connection to 1342 that address on the indicated port, and sending over that connection 1343 an HTTP request message containing a request target that matches the 1344 client's target URI (Section 7.1). 1346 If the server responds to such a request with a non-interim HTTP 1347 response message, as described in Section 15, then that response is 1348 considered an authoritative answer to the client's request. 1350 Note, however, that the above is not the only means for obtaining an 1351 authoritative response, nor does it imply that an authoritative 1352 response is always necessary (see [CACHING]). For example, the Alt- 1353 Svc header field [ALTSVC] allows an origin server to identify other 1354 services that are also authoritative for that origin. Access to 1355 "http" identified resources might also be provided by protocols 1356 outside the scope of this document. 1358 4.3.3. https origins 1360 The "https" scheme (Section 4.2.2) associates authority based on the 1361 ability of a server to use the private key corresponding to a 1362 certificate that the client considers to be trustworthy for the 1363 identified origin server. The client usually relies upon a chain of 1364 trust, conveyed from some prearranged or configured trust anchor, to 1365 deem a certificate trustworthy (Section 4.3.4). 1367 In HTTP/1.1 and earlier, a client will only attribute authority to a 1368 server when they are communicating over a successfully established 1369 and secured connection specifically to that URI origin's host. The 1370 connection establishment and certificate verification are used as 1371 proof of authority. 1373 In HTTP/2 and HTTP/3, a client will attribute authority to a server 1374 when they are communicating over a successfully established and 1375 secured connection if the URI origin's host matches any of the hosts 1376 present in the server's certificate and the client believes that it 1377 could open a connection to that host for that URI. In practice, a 1378 client will make a DNS query to check that the origin's host contains 1379 the same server IP address as the established connection. This 1380 restriction can be removed by the origin server sending an equivalent 1381 ORIGIN frame [RFC8336]. 1383 The request target's host and port value are passed within each HTTP 1384 request, identifying the origin and distinguishing it from other 1385 namespaces that might be controlled by the same server (Section 7.2). 1386 It is the origin's responsibility to ensure that any services 1387 provided with control over its certificate's private key are equally 1388 responsible for managing the corresponding "https" namespaces, or at 1389 least prepared to reject requests that appear to have been 1390 misdirected (Section 7.4). 1392 An origin server might be unwilling to process requests for certain 1393 target URIs even when they have the authority to do so. For example, 1394 when a host operates distinct services on different ports (e.g., 443 1395 and 8000), checking the target URI at the origin server is necessary 1396 (even after the connection has been secured) because a network 1397 attacker might cause connections for one port to be received at some 1398 other port. Failing to check the target URI might allow such an 1399 attacker to replace a response to one target URI (e.g., 1400 "https://example.com/foo") with a seemingly authoritative response 1401 from the other port (e.g., "https://example.com:8000/foo"). 1403 Note that the "https" scheme does not rely on TCP and the connected 1404 port number for associating authority, since both are outside the 1405 secured communication and thus cannot be trusted as definitive. 1406 Hence, the HTTP communication might take place over any channel that 1407 has been secured, as defined in Section 4.2.2, including protocols 1408 that don't use TCP. 1410 When an "https" URI is used within a context that calls for access to 1411 the indicated resource, a client MAY attempt access by resolving the 1412 host identifier to an IP address, establishing a TCP connection to 1413 that address on the indicated port, securing the connection end-to- 1414 end by successfully initiating TLS over TCP with confidentiality and 1415 integrity protection, and sending over that connection an HTTP 1416 request message containing a request target that matches the client's 1417 target URI (Section 7.1). 1419 If the server responds to such a request with a non-interim HTTP 1420 response message, as described in Section 15, then that response is 1421 considered an authoritative answer to the client's request. 1423 Note, however, that the above is not the only means for obtaining an 1424 authoritative response, nor does it imply that an authoritative 1425 response is always necessary (see [CACHING]). 1427 4.3.4. https certificate verification 1429 To establish a secured connection to dereference a URI, a client MUST 1430 verify that the service's identity is an acceptable match for the 1431 URI's origin server. Certificate verification is used to prevent 1432 server impersonation by an on-path attacker or by an attacker that 1433 controls name resolution. This process requires that a client be 1434 configured with a set of trust anchors. 1436 In general, a client MUST verify the service identity using the 1437 verification process defined in Section 6 of [RFC6125]. The client 1438 MUST construct a reference identity from the service's host: if the 1439 host is a literal IP address (Section 4.3.5), the reference identity 1440 is an IP-ID, otherwise the host is a name and the reference identity 1441 is a DNS-ID. 1443 A reference identity of type CN-ID MUST NOT be used by clients. As 1444 noted in Section 6.2.1 of [RFC6125] a reference identity of type CN- 1445 ID might be used by older clients. 1447 A client might be specially configured to accept an alternative form 1448 of server identity verification. For example, a client might be 1449 connecting to a server whose address and hostname are dynamic, with 1450 an expectation that the service will present a specific certificate 1451 (or a certificate matching some externally defined reference 1452 identity) rather than one matching the target URI's origin. 1454 In special cases, it might be appropriate for a client to simply 1455 ignore the server's identity, but it must be understood that this 1456 leaves a connection open to active attack. 1458 If the certificate is not valid for the target URI's origin, a user 1459 agent MUST either obtain confirmation from the user before proceeding 1460 (see Section 3.5) or terminate the connection with a bad certificate 1461 error. Automated clients MUST log the error to an appropriate audit 1462 log (if available) and SHOULD terminate the connection (with a bad 1463 certificate error). Automated clients MAY provide a configuration 1464 setting that disables this check, but MUST provide a setting which 1465 enables it. 1467 4.3.5. IP-ID reference identity 1469 A server that is identified using an IP address literal in the "host" 1470 field of an "https" URI has a reference identity of type IP-ID. An 1471 IP version 4 address uses the "IPv4address" ABNF rule and an IP 1472 version 6 address uses the "IP-literal" production with the 1473 "IPv6address" option; see Section 3.2.2 of [URI]. A reference 1474 identity of IP-ID contains the decoded bytes of the IP address. 1476 An IP version 4 address is 4 octets and an IP version 6 address is 16 1477 octets. Use of IP-ID is not defined for any other IP version. The 1478 iPAddress choice in the certificate subjectAltName extension does not 1479 explicitly include the IP version and so relies on the length of the 1480 address to distinguish versions; see Section 4.2.1.6 of [RFC5280]. 1482 A reference identity of type IP-ID matches if the address is 1483 identical to an iPAddress value of the subjectAltName extension of 1484 the certificate. 1486 5. Fields 1488 HTTP uses _fields_ to provide data in the form of extensible key/ 1489 value pairs with a registered key namespace. Fields are sent and 1490 received within the header and trailer sections of messages 1491 (Section 6). 1493 5.1. Field Names 1495 A field name labels the corresponding field value as having the 1496 semantics defined by that name. For example, the Date header field 1497 is defined in Section 6.6.1 as containing the origination timestamp 1498 for the message in which it appears. 1500 field-name = token 1502 Field names are case-insensitive and ought to be registered within 1503 the "Hypertext Transfer Protocol (HTTP) Field Name Registry"; see 1504 Section 16.3.1. 1506 The interpretation of a field does not change between minor versions 1507 of the same major HTTP version, though the default behavior of a 1508 recipient in the absence of such a field can change. Unless 1509 specified otherwise, fields are defined for all versions of HTTP. In 1510 particular, the Host and Connection fields ought to be recognized by 1511 all HTTP implementations whether or not they advertise conformance 1512 with HTTP/1.1. 1514 New fields can be introduced without changing the protocol version if 1515 their defined semantics allow them to be safely ignored by recipients 1516 that do not recognize them; see Section 16.3. 1518 A proxy MUST forward unrecognized header fields unless the field name 1519 is listed in the Connection header field (Section 7.6.1) or the proxy 1520 is specifically configured to block, or otherwise transform, such 1521 fields. Other recipients SHOULD ignore unrecognized header and 1522 trailer fields. Adhering to these requirements allows HTTP's 1523 functionality to be extended without updating or removing deployed 1524 intermediaries. 1526 5.2. Field Lines and Combined Field Value 1528 Field sections are composed of any number of _field lines_, each with 1529 a _field name_ (see Section 5.1) identifying the field, and a _field 1530 line value_ that conveys data for that instance of the field. 1532 When a field name is only present once in a section, the combined 1533 _field value_ for that field consists of the corresponding field line 1534 value. When a field name is repeated within a section, its combined 1535 field value consists of the list of corresponding field line values 1536 within that section, concatenated in order, with each field line 1537 value separated by a comma. 1539 For example, this section: 1541 Example-Field: Foo, Bar 1542 Example-Field: Baz 1544 contains two field lines, both with the field name "Example-Field". 1545 The first field line has a field line value of "Foo, Bar", while the 1546 second field line value is "Baz". The field value for "Example- 1547 Field" is the list "Foo, Bar, Baz". 1549 5.3. Field Order 1551 A recipient MAY combine multiple field lines within a field section 1552 that have the same field name into one field line, without changing 1553 the semantics of the message, by appending each subsequent field line 1554 value to the initial field line value in order, separated by a comma 1555 (",") and optional whitespace (OWS, defined in Section 5.6.3). For 1556 consistency, use comma SP. 1558 The order in which field lines with the same name are received is 1559 therefore significant to the interpretation of the field value; a 1560 proxy MUST NOT change the order of these field line values when 1561 forwarding a message. 1563 This means that, aside from the well-known exception noted below, a 1564 sender MUST NOT generate multiple field lines with the same name in a 1565 message (whether in the headers or trailers), or append a field line 1566 when a field line of the same name already exists in the message, 1567 unless that field's definition allows multiple field line values to 1568 be recombined as a comma-separated list [i.e., at least one 1569 alternative of the field's definition allows a comma-separated list, 1570 such as an ABNF rule of #(values) defined in Section 5.6.1]. 1572 | *Note:* In practice, the "Set-Cookie" header field ([COOKIE]) 1573 | often appears in a response message across multiple field lines 1574 | and does not use the list syntax, violating the above 1575 | requirements on multiple field lines with the same field name. 1576 | Since it cannot be combined into a single field value, 1577 | recipients ought to handle "Set-Cookie" as a special case while 1578 | processing fields. (See Appendix A.2.3 of [Kri2001] for 1579 | details.) 1581 The order in which field lines with differing field names are 1582 received in a section is not significant. However, it is good 1583 practice to send header fields that contain additional control data 1584 first, such as Host on requests and Date on responses, so that 1585 implementations can decide when not to handle a message as early as 1586 possible. 1588 A server MUST NOT apply a request to the target resource until it 1589 receives the entire request header section, since later header field 1590 lines might include conditionals, authentication credentials, or 1591 deliberately misleading duplicate header fields that could impact 1592 request processing. 1594 5.4. Field Limits 1596 HTTP does not place a predefined limit on the length of each field 1597 line, field value, or on the length of a header or trailer section as 1598 a whole, as described in Section 2. Various ad hoc limitations on 1599 individual lengths are found in practice, often depending on the 1600 specific field's semantics. 1602 A server that receives a request header field line, field value, or 1603 set of fields larger than it wishes to process MUST respond with an 1604 appropriate 4xx (Client Error) status code. Ignoring such header 1605 fields would increase the server's vulnerability to request smuggling 1606 attacks (Section 11.2 of [HTTP/1.1]). 1608 A client MAY discard or truncate received field lines that are larger 1609 than the client wishes to process if the field semantics are such 1610 that the dropped value(s) can be safely ignored without changing the 1611 message framing or response semantics. 1613 5.5. Field Values 1615 HTTP field values consist of a sequence of characters in a format 1616 defined by the field's grammar. Each field's grammar is usually 1617 defined using ABNF ([RFC5234]). 1619 field-value = *field-content 1620 field-content = field-vchar 1621 [ 1*( SP / HTAB / field-vchar ) field-vchar ] 1622 field-vchar = VCHAR / obs-text 1623 obs-text = %x80-FF 1625 A field value does not include leading or trailing whitespace. When 1626 a specific version of HTTP allows such whitespace to appear in a 1627 message, a field parsing implementation MUST exclude such whitespace 1628 prior to evaluating the field value. 1630 Field values are usually constrained to the range of US-ASCII 1631 characters [USASCII]. Fields needing a greater range of characters 1632 can use an encoding, such as the one defined in [RFC8187]. 1633 Historically, HTTP allowed field content with text in the ISO-8859-1 1634 charset [ISO-8859-1], supporting other charsets only through use of 1635 [RFC2047] encoding. Specifications for newly defined fields SHOULD 1636 limit their values to visible US-ASCII octets (VCHAR), SP, and HTAB. 1637 A recipient SHOULD treat other allowed octets in field content (i.e., 1638 obs-text) as opaque data. 1640 Field values containing CR, LF, or NUL characters are invalid and 1641 dangerous, due to the varying ways that implementations might parse 1642 and interpret those characters; a recipient of CR, LF, or NUL within 1643 a field value MUST either reject the message or replace each of those 1644 characters with SP before further processing or forwarding of that 1645 message. Field values containing other CTL characters are also 1646 invalid; however, recipients MAY retain such characters for the sake 1647 of robustness when they appear within a safe context (e.g., an 1648 application-specific quoted string that will not be processed by any 1649 downstream HTTP parser). 1651 Fields that only anticipate a single member as the field value are 1652 referred to as _singleton fields_. 1654 Fields that allow multiple members as the field value are referred to 1655 as _list-based fields_. The list operator extension of Section 5.6.1 1656 is used as a common notation for defining field values that can 1657 contain multiple members. 1659 Because commas (",") are used as the delimiter between members, they 1660 need to be treated with care if they are allowed as data within a 1661 member. This is true for both list-based and singleton fields, since 1662 a singleton field might be erroneously sent with multiple members and 1663 detecting such errors improves interoperability. Fields that expect 1664 to contain a comma within a member, such as within an HTTP-date or 1665 URI-reference element, ought to be defined with delimiters around 1666 that element to distinguish any comma within that data from potential 1667 list separators. 1669 For example, a textual date and a URI (either of which might contain 1670 a comma) could be safely carried in list-based field values like 1671 these: 1673 Example-URIs: "http://example.com/a.html,foo", 1674 "http://without-a-comma.example.com/" 1675 Example-Dates: "Sat, 04 May 1996", "Wed, 14 Sep 2005" 1677 Note that double-quote delimiters are almost always used with the 1678 quoted-string production (Section 5.6.4); using a different syntax 1679 inside double-quotes will likely cause unnecessary confusion. 1681 Many fields (such as Content-Type, defined in Section 8.3) use a 1682 common syntax for parameters that allows both unquoted (token) and 1683 quoted (quoted-string) syntax for a parameter value (Section 5.6.6). 1685 Use of common syntax allows recipients to reuse existing parser 1686 components. When allowing both forms, the meaning of a parameter 1687 value ought to be the same whether it was received as a token or a 1688 quoted string. 1690 | *Note:* For defining field value syntax, this specification 1691 | uses an ABNF rule named after the field name to define the 1692 | allowed grammar for that field's value (after said value has 1693 | been extracted from the underlying messaging syntax and 1694 | multiple instances combined into a list). 1696 5.6. Common Rules for Defining Field Values 1698 5.6.1. Lists (#rule ABNF Extension) 1700 A #rule extension to the ABNF rules of [RFC5234] is used to improve 1701 readability in the definitions of some list-based field values. 1703 A construct "#" is defined, similar to "*", for defining comma- 1704 delimited lists of elements. The full form is "#element" 1705 indicating at least and at most elements, each separated by a 1706 single comma (",") and optional whitespace (OWS, defined in 1707 Section 5.6.3). 1709 5.6.1.1. Sender Requirements 1711 In any production that uses the list construct, a sender MUST NOT 1712 generate empty list elements. In other words, a sender has to 1713 generate lists that satisfy the following syntax: 1715 1#element => element *( OWS "," OWS element ) 1717 and: 1719 #element => [ 1#element ] 1721 and for n >= 1 and m > 1: 1723 #element => element *( OWS "," OWS element ) 1725 Appendix A shows the collected ABNF for senders after the list 1726 constructs have been expanded. 1728 5.6.1.2. Recipient Requirements 1730 Empty elements do not contribute to the count of elements present. A 1731 recipient MUST parse and ignore a reasonable number of empty list 1732 elements: enough to handle common mistakes by senders that merge 1733 values, but not so much that they could be used as a denial-of- 1734 service mechanism. In other words, a recipient MUST accept lists 1735 that satisfy the following syntax: 1737 #element => [ element ] *( OWS "," OWS [ element ] ) 1739 Note that because of the potential presence of empty list elements, 1740 the RFC 5234 ABNF cannot enforce the cardinality of list elements, 1741 and consequently all cases are mapped as if there was no cardinality 1742 specified. 1744 For example, given these ABNF productions: 1746 example-list = 1#example-list-elmt 1747 example-list-elmt = token ; see Section 5.6.2 1749 Then the following are valid values for example-list (not including 1750 the double quotes, which are present for delimitation only): 1752 "foo,bar" 1753 "foo ,bar," 1754 "foo , ,bar,charlie" 1756 In contrast, the following values would be invalid, since at least 1757 one non-empty element is required by the example-list production: 1759 "" 1760 "," 1761 ", ," 1763 5.6.2. Tokens 1765 Tokens are short textual identifiers that do not include whitespace 1766 or delimiters. 1768 token = 1*tchar 1770 tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" 1771 / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" 1772 / DIGIT / ALPHA 1773 ; any VCHAR, except delimiters 1775 Many HTTP field values are defined using common syntax components, 1776 separated by whitespace or specific delimiting characters. 1777 Delimiters are chosen from the set of US-ASCII visual characters not 1778 allowed in a token (DQUOTE and "(),/:;<=>?@[\]{}"). 1780 5.6.3. Whitespace 1782 This specification uses three rules to denote the use of linear 1783 whitespace: OWS (optional whitespace), RWS (required whitespace), and 1784 BWS ("bad" whitespace). 1786 The OWS rule is used where zero or more linear whitespace octets 1787 might appear. For protocol elements where optional whitespace is 1788 preferred to improve readability, a sender SHOULD generate the 1789 optional whitespace as a single SP; otherwise, a sender SHOULD NOT 1790 generate optional whitespace except as needed to overwrite invalid or 1791 unwanted protocol elements during in-place message filtering. 1793 The RWS rule is used when at least one linear whitespace octet is 1794 required to separate field tokens. A sender SHOULD generate RWS as a 1795 single SP. 1797 OWS and RWS have the same semantics as a single SP. Any content 1798 known to be defined as OWS or RWS MAY be replaced with a single SP 1799 before interpreting it or forwarding the message downstream. 1801 The BWS rule is used where the grammar allows optional whitespace 1802 only for historical reasons. A sender MUST NOT generate BWS in 1803 messages. A recipient MUST parse for such bad whitespace and remove 1804 it before interpreting the protocol element. 1806 BWS has no semantics. Any content known to be defined as BWS MAY be 1807 removed before interpreting it or forwarding the message downstream. 1809 OWS = *( SP / HTAB ) 1810 ; optional whitespace 1811 RWS = 1*( SP / HTAB ) 1812 ; required whitespace 1813 BWS = OWS 1814 ; "bad" whitespace 1816 5.6.4. Quoted Strings 1818 A string of text is parsed as a single value if it is quoted using 1819 double-quote marks. 1821 quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE 1822 qdtext = HTAB / SP / %x21 / %x23-5B / %x5D-7E / obs-text 1824 The backslash octet ("\") can be used as a single-octet quoting 1825 mechanism within quoted-string and comment constructs. Recipients 1826 that process the value of a quoted-string MUST handle a quoted-pair 1827 as if it were replaced by the octet following the backslash. 1829 quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) 1831 A sender SHOULD NOT generate a quoted-pair in a quoted-string except 1832 where necessary to quote DQUOTE and backslash octets occurring within 1833 that string. A sender SHOULD NOT generate a quoted-pair in a comment 1834 except where necessary to quote parentheses ["(" and ")"] and 1835 backslash octets occurring within that comment. 1837 5.6.5. Comments 1839 Comments can be included in some HTTP fields by surrounding the 1840 comment text with parentheses. Comments are only allowed in fields 1841 containing "comment" as part of their field value definition. 1843 comment = "(" *( ctext / quoted-pair / comment ) ")" 1844 ctext = HTAB / SP / %x21-27 / %x2A-5B / %x5D-7E / obs-text 1846 5.6.6. Parameters 1848 Parameters are instances of name=value pairs; they are often used in 1849 field values as a common syntax for appending auxiliary information 1850 to an item. Each parameter is usually delimited by an immediately 1851 preceding semicolon. 1853 parameters = *( OWS ";" OWS [ parameter ] ) 1854 parameter = parameter-name "=" parameter-value 1855 parameter-name = token 1856 parameter-value = ( token / quoted-string ) 1858 Parameter names are case-insensitive. Parameter values might or 1859 might not be case-sensitive, depending on the semantics of the 1860 parameter name. Examples of parameters and some equivalent forms can 1861 be seen in media types (Section 8.3.1) and the Accept header field 1862 (Section 12.5.1). 1864 A parameter value that matches the token production can be 1865 transmitted either as a token or within a quoted-string. The quoted 1866 and unquoted values are equivalent. 1868 | *Note:* Parameters do not allow whitespace (not even "bad" 1869 | whitespace) around the "=" character. 1871 5.6.7. Date/Time Formats 1873 Prior to 1995, there were three different formats commonly used by 1874 servers to communicate timestamps. For compatibility with old 1875 implementations, all three are defined here. The preferred format is 1876 a fixed-length and single-zone subset of the date and time 1877 specification used by the Internet Message Format [RFC5322]. 1879 HTTP-date = IMF-fixdate / obs-date 1881 An example of the preferred format is 1883 Sun, 06 Nov 1994 08:49:37 GMT ; IMF-fixdate 1885 Examples of the two obsolete formats are 1887 Sunday, 06-Nov-94 08:49:37 GMT ; obsolete RFC 850 format 1888 Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format 1890 A recipient that parses a timestamp value in an HTTP field MUST 1891 accept all three HTTP-date formats. When a sender generates a field 1892 that contains one or more timestamps defined as HTTP-date, the sender 1893 MUST generate those timestamps in the IMF-fixdate format. 1895 An HTTP-date value represents time as an instance of Coordinated 1896 Universal Time (UTC). The first two formats indicate UTC by the 1897 three-letter abbreviation for Greenwich Mean Time, "GMT", a 1898 predecessor of the UTC name; values in the asctime format are assumed 1899 to be in UTC. 1901 A _clock_ is an implementation capable of providing a reasonable 1902 approximation of the current instant in UTC. A clock implementation 1903 ought to use NTP ([RFC5905]), or some similar protocol, to 1904 synchronize with UTC. 1906 Preferred format: 1908 IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT 1909 ; fixed length/zone/capitalization subset of the format 1910 ; see Section 3.3 of [RFC5322] 1912 day-name = %s"Mon" / %s"Tue" / %s"Wed" 1913 / %s"Thu" / %s"Fri" / %s"Sat" / %s"Sun" 1915 date1 = day SP month SP year 1916 ; e.g., 02 Jun 1982 1918 day = 2DIGIT 1919 month = %s"Jan" / %s"Feb" / %s"Mar" / %s"Apr" 1920 / %s"May" / %s"Jun" / %s"Jul" / %s"Aug" 1921 / %s"Sep" / %s"Oct" / %s"Nov" / %s"Dec" 1922 year = 4DIGIT 1924 GMT = %s"GMT" 1926 time-of-day = hour ":" minute ":" second 1927 ; 00:00:00 - 23:59:60 (leap second) 1929 hour = 2DIGIT 1930 minute = 2DIGIT 1931 second = 2DIGIT 1933 Obsolete formats: 1935 obs-date = rfc850-date / asctime-date 1937 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 1938 date2 = day "-" month "-" 2DIGIT 1939 ; e.g., 02-Jun-82 1941 day-name-l = %s"Monday" / %s"Tuesday" / %s"Wednesday" 1942 / %s"Thursday" / %s"Friday" / %s"Saturday" 1943 / %s"Sunday" 1945 asctime-date = day-name SP date3 SP time-of-day SP year 1946 date3 = month SP ( 2DIGIT / ( SP 1DIGIT )) 1947 ; e.g., Jun 2 1949 HTTP-date is case sensitive. Note that Section 4.2 of [CACHING] 1950 relaxes this for cache recipients. 1952 A sender MUST NOT generate additional whitespace in an HTTP-date 1953 beyond that specifically included as SP in the grammar. The 1954 semantics of day-name, day, month, year, and time-of-day are the same 1955 as those defined for the Internet Message Format constructs with the 1956 corresponding name ([RFC5322], Section 3.3). 1958 Recipients of a timestamp value in rfc850-date format, which uses a 1959 two-digit year, MUST interpret a timestamp that appears to be more 1960 than 50 years in the future as representing the most recent year in 1961 the past that had the same last two digits. 1963 Recipients of timestamp values are encouraged to be robust in parsing 1964 timestamps unless otherwise restricted by the field definition. For 1965 example, messages are occasionally forwarded over HTTP from a non- 1966 HTTP source that might generate any of the date and time 1967 specifications defined by the Internet Message Format. 1969 | *Note:* HTTP requirements for the date/time stamp format apply 1970 | only to their usage within the protocol stream. 1971 | Implementations are not required to use these formats for user 1972 | presentation, request logging, etc. 1974 6. Message Abstraction 1976 Each major version of HTTP defines its own syntax for communicating 1977 messages. This section defines an abstract data type for HTTP 1978 messages based on a generalization of those message characteristics, 1979 common structure, and capacity for conveying semantics. This 1980 abstraction is used to define requirements on senders and recipients 1981 that are independent of the HTTP version, such that a message in one 1982 version can be relayed through other versions without changing its 1983 meaning. 1985 A _message_ consists of control data to describe and route the 1986 message, a headers lookup table of key/value pairs for extending that 1987 control data and conveying additional information about the sender, 1988 message, content, or context, a potentially unbounded stream of 1989 content, and a trailers lookup table of key/value pairs for 1990 communicating information obtained while sending the content. 1992 Framing and control data is sent first, followed by a header section 1993 containing fields for the headers table. When a message includes 1994 content, the content is sent after the header section, potentially 1995 followed by a trailer section that might contain fields for the 1996 trailers table. 1998 Messages are expected to be processed as a stream, wherein the 1999 purpose of that stream and its continued processing is revealed while 2000 being read. Hence, control data describes what the recipient needs 2001 to know immediately, header fields describe what needs to be known 2002 before receiving content, the content (when present) presumably 2003 contains what the recipient wants or needs to fulfill the message 2004 semantics, and trailer fields provide optional metadata that was 2005 unknown prior to sending the content. 2007 Messages are intended to be _self-descriptive_: everything a 2008 recipient needs to know about the message can be determined by 2009 looking at the message itself, after decoding or reconstituting parts 2010 that have been compressed or elided in transit, without requiring an 2011 understanding of the sender's current application state (established 2012 via prior messages). However, a client MUST retain knowledge of the 2013 request when parsing, interpreting, or caching a corresponding 2014 response. For example, responses to the HEAD method look just like 2015 the beginning of a response to GET, but cannot be parsed in the same 2016 manner. 2018 Note that this message abstraction is a generalization across many 2019 versions of HTTP, including features that might not be found in some 2020 versions. For example, trailers were introduced within the HTTP/1.1 2021 chunked transfer coding as a trailer section after the content. An 2022 equivalent feature is present in HTTP/2 and HTTP/3 within the header 2023 block that terminates each stream. 2025 6.1. Framing and Completeness 2027 Message framing indicates how each message begins and ends, such that 2028 each message can be distinguished from other messages or noise on the 2029 same connection. Each major version of HTTP defines its own framing 2030 mechanism. 2032 HTTP/0.9 and early deployments of HTTP/1.0 used closure of the 2033 underlying connection to end a response. For backwards 2034 compatibility, this implicit framing is also allowed in HTTP/1.1. 2035 However, implicit framing can fail to distinguish an incomplete 2036 response if the connection closes early. For that reason, almost all 2037 modern implementations use explicit framing in the form of length- 2038 delimited sequences of message data. 2040 A message is considered _complete_ when all of the octets indicated 2041 by its framing are available. Note that, when no explicit framing is 2042 used, a response message that is ended by the underlying connection's 2043 close is considered complete even though it might be 2044 indistinguishable from an incomplete response, unless a transport- 2045 level error indicates that it is not complete. 2047 6.2. Control Data 2049 Messages start with control data that describe its primary purpose. 2050 Request message control data includes a request method (Section 9), 2051 request target (Section 7.1), and protocol version (Section 2.5). 2052 Response message control data includes a status code (Section 15), 2053 optional reason phrase, and protocol version. 2055 In HTTP/1.1 ([HTTP/1.1]) and earlier, control data is sent as the 2056 first line of a message. In HTTP/2 ([HTTP/2]) and HTTP/3 ([HTTP/3]), 2057 control data is sent as pseudo-header fields with a reserved name 2058 prefix (e.g., ":authority"). 2060 Every HTTP message has a protocol version. Depending on the version 2061 in use, it might be identified within the message explicitly or 2062 inferred by the connection over which the message is received. 2063 Recipients use that version information to determine limitations or 2064 potential for later communication with that sender. 2066 When a message is forwarded by an intermediary, the protocol version 2067 is updated to reflect the version used by that intermediary. The Via 2068 header field (Section 7.6.3) is used to communicate upstream protocol 2069 information within a forwarded message. 2071 A client SHOULD send a request version equal to the highest version 2072 to which the client is conformant and whose major version is no 2073 higher than the highest version supported by the server, if this is 2074 known. A client MUST NOT send a version to which it is not 2075 conformant. 2077 A client MAY send a lower request version if it is known that the 2078 server incorrectly implements the HTTP specification, but only after 2079 the client has attempted at least one normal request and determined 2080 from the response status code or header fields (e.g., Server) that 2081 the server improperly handles higher request versions. 2083 A server SHOULD send a response version equal to the highest version 2084 to which the server is conformant that has a major version less than 2085 or equal to the one received in the request. A server MUST NOT send 2086 a version to which it is not conformant. A server can send a 505 2087 (HTTP Version Not Supported) response if it wishes, for any reason, 2088 to refuse service of the client's major protocol version. 2090 A recipient that receives a message with a major version number that 2091 it implements and a minor version number higher than what it 2092 implements SHOULD process the message as if it were in the highest 2093 minor version within that major version to which the recipient is 2094 conformant. A recipient can assume that a message with a higher 2095 minor version, when sent to a recipient that has not yet indicated 2096 support for that higher version, is sufficiently backwards-compatible 2097 to be safely processed by any implementation of the same major 2098 version. 2100 6.3. Header Fields 2102 Fields (Section 5) that are sent/received before the content are 2103 referred to as "header fields" (or just "headers", colloquially). 2105 The _header section_ of a message consists of a sequence of header 2106 field lines. Each header field might modify or extend message 2107 semantics, describe the sender, define the content, or provide 2108 additional context. 2110 | *Note:* We refer to named fields specifically as a "header 2111 | field" when they are only allowed to be sent in the header 2112 | section. 2114 6.4. Content 2116 HTTP messages often transfer a complete or partial representation as 2117 the message _content_: a stream of octets sent after the header 2118 section, as delineated by the message framing. 2120 This abstract definition of content reflects the data after it has 2121 been extracted from the message framing. For example, an HTTP/1.1 2122 message body (Section 6 of [HTTP/1.1]) might consist of a stream of 2123 data encoded with the chunked transfer coding - a sequence of data 2124 chunks, one zero-length chunk, and a trailer section - whereas the 2125 content of that same message includes only the data stream after the 2126 transfer coding has been decoded; it does not include the chunk 2127 lengths, chunked framing syntax, nor the trailer fields 2128 (Section 6.5). 2130 | *Note:* Some field names have a "Content-" prefix. This is an 2131 | informal convention; while some of these fields refer to the 2132 | content of the message, as defined above, others are scoped to 2133 | the selected representation (Section 3.2). See the individual 2134 | field's definition to disambiguate. 2136 6.4.1. Content Semantics 2138 The purpose of content in a request is defined by the method 2139 semantics (Section 9). 2141 For example, a representation in the content of a PUT request 2142 (Section 9.3.4) represents the desired state of the target resource 2143 after the request is successfully applied, whereas a representation 2144 in the content of a POST request (Section 9.3.3) represents 2145 information to be processed by the target resource. 2147 In a response, the content's purpose is defined by the request 2148 method, response status code (Section 15), and response fields 2149 describing that content. For example, the content of a 200 (OK) 2150 response to GET (Section 9.3.1) represents the current state of the 2151 target resource, as observed at the time of the message origination 2152 date (Section 6.6.1), whereas the content of the same status code in 2153 a response to POST might represent either the processing result or 2154 the new state of the target resource after applying the processing. 2156 The content of a 206 (Partial Content) response to GET contains 2157 either a single part of the selected representation or a multipart 2158 message body containing multiple parts of that representation, as 2159 described in Section 15.3.7. 2161 Response messages with an error status code usually contain content 2162 that represents the error condition, such that the content describes 2163 the error state and what steps are suggested for resolving it. 2165 Responses to the HEAD request method (Section 9.3.2) never include 2166 content; the associated response header fields indicate only what 2167 their values would have been if the request method had been GET 2168 (Section 9.3.1). 2170 2xx (Successful) responses to a CONNECT request method 2171 (Section 9.3.6) switch the connection to tunnel mode instead of 2172 having content. 2174 All 1xx (Informational), 204 (No Content), and 304 (Not Modified) 2175 responses do not include content. 2177 All other responses do include content, although that content might 2178 be of zero length. 2180 6.4.2. Identifying Content 2182 When a complete or partial representation is transferred as message 2183 content, it is often desirable for the sender to supply, or the 2184 recipient to determine, an identifier for a resource corresponding to 2185 that specific representation. For example, a client making a GET 2186 request on a resource for "the current weather report" might want an 2187 identifier specific to the content returned (e.g., "weather report 2188 for Laguna Beach at 20210720T1711"). This can be useful for sharing 2189 or bookmarking content from resources that are expected to have 2190 changing representations over time. 2192 For a request message: 2194 * If the request has a Content-Location header field, then the 2195 sender asserts that the content is a representation of the 2196 resource identified by the Content-Location field value. However, 2197 such an assertion cannot be trusted unless it can be verified by 2198 other means (not defined by this specification). The information 2199 might still be useful for revision history links. 2201 * Otherwise, the content is unidentified by HTTP, but a more 2202 specific identifier might be supplied within the content itself. 2204 For a response message, the following rules are applied in order 2205 until a match is found: 2207 1. If the request method is HEAD or the response status code is 204 2208 (No Content) or 304 (Not Modified), there is no content in the 2209 response. 2211 2. If the request method is GET and the response status code is 200 2212 (OK), the content is a representation of the target resource 2213 (Section 7.1). 2215 3. If the request method is GET and the response status code is 203 2216 (Non-Authoritative Information), the content is a potentially 2217 modified or enhanced representation of the target resource as 2218 provided by an intermediary. 2220 4. If the request method is GET and the response status code is 206 2221 (Partial Content), the content is one or more parts of a 2222 representation of the target resource. 2224 5. If the response has a Content-Location header field and its field 2225 value is a reference to the same URI as the target URI, the 2226 content is a representation of the target resource. 2228 6. If the response has a Content-Location header field and its field 2229 value is a reference to a URI different from the target URI, then 2230 the sender asserts that the content is a representation of the 2231 resource identified by the Content-Location field value. 2232 However, such an assertion cannot be trusted unless it can be 2233 verified by other means (not defined by this specification). 2235 7. Otherwise, the content is unidentified by HTTP, but a more 2236 specific identifier might be supplied within the content itself. 2238 6.5. Trailer Fields 2240 Fields (Section 5) that are located within a _trailer section_ are 2241 referred to as "trailer fields" (or just "trailers", colloquially). 2242 Trailer fields can be useful for supplying message integrity checks, 2243 digital signatures, delivery metrics, or post-processing status 2244 information. 2246 Trailer fields ought to be processed and stored separately from the 2247 fields in the header section to avoid contradicting message semantics 2248 known at the time the header section was complete. The presence or 2249 absence of certain header fields might impact choices made for the 2250 routing or processing of the message as a whole before the trailers 2251 are received; those choices cannot be unmade by the later discovery 2252 of trailer fields. 2254 6.5.1. Limitations on use of Trailers 2256 A trailer section is only possible when supported by the version of 2257 HTTP in use and enabled by an explicit framing mechanism. For 2258 example, the chunked coding in HTTP/1.1 allows a trailer section to 2259 be sent after the content (Section 7.1.2 of [HTTP/1.1]). 2261 Many fields cannot be processed outside the header section because 2262 their evaluation is necessary prior to receiving the content, such as 2263 those that describe message framing, routing, authentication, request 2264 modifiers, response controls, or content format. A sender MUST NOT 2265 generate a trailer field unless the sender knows the corresponding 2266 header field name's definition permits the field to be sent in 2267 trailers. 2269 Trailer fields can be difficult to process by intermediaries that 2270 forward messages from one protocol version to another. If the entire 2271 message can be buffered in transit, some intermediaries could merge 2272 trailer fields into the header section (as appropriate) before it is 2273 forwarded. However, in most cases, the trailers are simply 2274 discarded. A recipient MUST NOT merge a trailer field into a header 2275 section unless the recipient understands the corresponding header 2276 field definition and that definition explicitly permits and defines 2277 how trailer field values can be safely merged. 2279 The presence of the keyword "trailers" in the TE header field 2280 (Section 10.1.4) of a request indicates that the client is willing to 2281 accept trailer fields, on behalf of itself and any downstream 2282 clients. For requests from an intermediary, this implies that all 2283 downstream clients are willing to accept trailer fields in the 2284 forwarded response. Note that the presence of "trailers" does not 2285 mean that the client(s) will process any particular trailer field in 2286 the response; only that the trailer section(s) will not be dropped by 2287 any of the clients. 2289 Because of the potential for trailer fields to be discarded in 2290 transit, a server SHOULD NOT generate trailer fields that it believes 2291 are necessary for the user agent to receive. 2293 6.5.2. Processing Trailer Fields 2295 The "Trailer" header field (Section 6.6.2) can be sent to indicate 2296 fields likely to be sent in the trailer section, which allows 2297 recipients to prepare for their receipt before processing the 2298 content. For example, this could be useful if a field name indicates 2299 that a dynamic checksum should be calculated as the content is 2300 received and then immediately checked upon receipt of the trailer 2301 field value. 2303 Like header fields, trailer fields with the same name are processed 2304 in the order received; multiple trailer field lines with the same 2305 name have the equivalent semantics as appending the multiple values 2306 as a list of members. Trailer fields that might be generated more 2307 than once during a message MUST be defined as a list-based field even 2308 if each member value is only processed once per field line received. 2310 At the end of a message, a recipient MAY treat the set of received 2311 trailer fields as a data structure of key/value pairs, similar to 2312 (but separate from) the header fields. Additional processing 2313 expectations, if any, can be defined within the field specification 2314 for a field intended for use in trailers. 2316 6.6. Message Metadata 2318 Fields that describe the message itself, such as when and how the 2319 message has been generated, can appear in both requests and 2320 responses. 2322 6.6.1. Date 2324 The "Date" header field represents the date and time at which the 2325 message was originated, having the same semantics as the Origination 2326 Date Field (orig-date) defined in Section 3.6.1 of [RFC5322]. The 2327 field value is an HTTP-date, as defined in Section 5.6.7. 2329 Date = HTTP-date 2331 An example is 2333 Date: Tue, 15 Nov 1994 08:12:31 GMT 2335 A sender that generates a Date header field SHOULD generate its field 2336 value as the best available approximation of the date and time of 2337 message generation. In theory, the date ought to represent the 2338 moment just before generating the message content. In practice, a 2339 sender can generate the date value at any time during message 2340 origination. 2342 An origin server with a clock (as defined in Section 5.6.7) MUST 2343 generate a Date header field in all 2xx (Successful), 3xx 2344 (Redirection), and 4xx (Client Error) responses, and MAY generate a 2345 Date header field in 1xx (Informational) and 5xx (Server Error) 2346 responses. 2348 An origin server without a clock MUST NOT generate a Date header 2349 field. 2351 A recipient with a clock that receives a response message without a 2352 Date header field MUST record the time it was received and append a 2353 corresponding Date header field to the message's header section if it 2354 is cached or forwarded downstream. 2356 A recipient with a clock that receives a response with an invalid 2357 Date header field value MAY replace that value with the time that 2358 response was received. 2360 A user agent MAY send a Date header field in a request, though 2361 generally will not do so unless it is believed to convey useful 2362 information to the server. For example, custom applications of HTTP 2363 might convey a Date if the server is expected to adjust its 2364 interpretation of the user's request based on differences between the 2365 user agent and server clocks. 2367 6.6.2. Trailer 2369 The "Trailer" header field provides a list of field names that the 2370 sender anticipates sending as trailer fields within that message. 2371 This allows a recipient to prepare for receipt of the indicated 2372 metadata before it starts processing the content. 2374 Trailer = #field-name 2376 For example, a sender might indicate that a signature will be 2377 computed as the content is being streamed and provide the final 2378 signature as a trailer field. This allows a recipient to perform the 2379 same check on the fly as it receives the content. 2381 A sender that intends to generate one or more trailer fields in a 2382 message SHOULD generate a Trailer header field in the header section 2383 of that message to indicate which fields might be present in the 2384 trailers. 2386 If an intermediary discards the trailer section in transit, the 2387 Trailer field could provide a hint of what metadata was lost, though 2388 there is no guarantee that a sender of Trailer will always follow 2389 through by sending the named fields. 2391 7. Routing HTTP Messages 2393 HTTP request message routing is determined by each client based on 2394 the target resource, the client's proxy configuration, and 2395 establishment or reuse of an inbound connection. The corresponding 2396 response routing follows the same connection chain back to the 2397 client. 2399 7.1. Determining the Target Resource 2401 Although HTTP is used in a wide variety of applications, most clients 2402 rely on the same resource identification mechanism and configuration 2403 techniques as general-purpose Web browsers. Even when communication 2404 options are hard-coded in a client's configuration, we can think of 2405 their combined effect as a URI reference (Section 4.1). 2407 A URI reference is resolved to its absolute form in order to obtain 2408 the _target URI_. The target URI excludes the reference's fragment 2409 component, if any, since fragment identifiers are reserved for 2410 client-side processing ([URI], Section 3.5). 2412 To perform an action on a _target resource_, the client sends a 2413 request message containing enough components of its parsed target URI 2414 to enable recipients to identify that same resource. For historical 2415 reasons, the parsed target URI components, collectively referred to 2416 as the _request target_, are sent within the message control data and 2417 the Host header field (Section 7.2). 2419 There are two unusual cases for which the request target components 2420 are in a method-specific form: 2422 * For CONNECT (Section 9.3.6), the request target is the host name 2423 and port number of the tunnel destination, separated by a colon. 2425 * For OPTIONS (Section 9.3.7), the request target can be a single 2426 asterisk ("*"). 2428 See the respective method definitions for details. These forms MUST 2429 NOT be used with other methods. 2431 Upon receipt of a client's request, a server reconstructs the target 2432 URI from the received components in accordance with their local 2433 configuration and incoming connection context. This reconstruction 2434 is specific to each major protocol version. For example, Section 3.3 2435 of [HTTP/1.1] defines how a server determines the target URI of an 2436 HTTP/1.1 request. 2438 | *Note:* Previous specifications defined the recomposed target 2439 | URI as a distinct concept, the _effective request URI_. 2441 7.2. Host and :authority 2443 The "Host" header field in a request provides the host and port 2444 information from the target URI, enabling the origin server to 2445 distinguish among resources while servicing requests for multiple 2446 host names. 2448 In HTTP/2 [HTTP/2] and HTTP/3 [HTTP/3], the Host header field is, in 2449 some cases, supplanted by the ":authority" pseudo-header field of a 2450 request's control data. 2452 Host = uri-host [ ":" port ] ; Section 4 2454 The target URI's authority information is critical for handling a 2455 request. A user agent MUST generate a Host header field in a request 2456 unless it sends that information as an ":authority" pseudo-header 2457 field. A user agent that sends Host SHOULD send it as the first 2458 field in the header section of a request. 2460 For example, a GET request to the origin server for 2461 would begin with: 2463 GET /pub/WWW/ HTTP/1.1 2464 Host: www.example.org 2466 Since the host and port information acts as an application-level 2467 routing mechanism, it is a frequent target for malware seeking to 2468 poison a shared cache or redirect a request to an unintended server. 2469 An interception proxy is particularly vulnerable if it relies on the 2470 host and port information for redirecting requests to internal 2471 servers, or for use as a cache key in a shared cache, without first 2472 verifying that the intercepted connection is targeting a valid IP 2473 address for that host. 2475 7.3. Routing Inbound Requests 2477 Once the target URI and its origin are determined, a client decides 2478 whether a network request is necessary to accomplish the desired 2479 semantics and, if so, where that request is to be directed. 2481 7.3.1. To a Cache 2483 If the client has a cache [CACHING] and the request can be satisfied 2484 by it, then the request is usually directed there first. 2486 7.3.2. To a Proxy 2488 If the request is not satisfied by a cache, then a typical client 2489 will check its configuration to determine whether a proxy is to be 2490 used to satisfy the request. Proxy configuration is implementation- 2491 dependent, but is often based on URI prefix matching, selective 2492 authority matching, or both, and the proxy itself is usually 2493 identified by an "http" or "https" URI. 2495 If an "http" or "https" proxy is applicable, the client connects 2496 inbound by establishing (or reusing) a connection to that proxy and 2497 then sending it an HTTP request message containing a request target 2498 that matches the client's target URI. 2500 7.3.3. To the Origin 2502 If no proxy is applicable, a typical client will invoke a handler 2503 routine (specific to the target URI's scheme) to obtain access to the 2504 identified resource. How that is accomplished is dependent on the 2505 target URI scheme and defined by its associated specification. 2507 Section 4.3.2 defines how to obtain access to an "http" resource by 2508 establishing (or reusing) an inbound connection to the identified 2509 origin server and then sending it an HTTP request message containing 2510 a request target that matches the client's target URI. 2512 Section 4.3.3 defines how to obtain access to an "https" resource by 2513 establishing (or reusing) an inbound secured connection to an origin 2514 server that is authoritative for the identified origin and then 2515 sending it an HTTP request message containing a request target that 2516 matches the client's target URI. 2518 7.4. Rejecting Misdirected Requests 2520 Once a request is received by a server and parsed sufficiently to 2521 determine its target URI, the server decides whether to process the 2522 request itself, forward the request to another server, redirect the 2523 client to a different resource, respond with an error, or drop the 2524 connection. This decision can be influenced by anything about the 2525 request or connection context, but is specifically directed at 2526 whether the server has been configured to process requests for that 2527 target URI and whether the connection context is appropriate for that 2528 request. 2530 For example, a request might have been misdirected, deliberately or 2531 accidentally, such that the information within a received Host header 2532 field differs from the connection's host or port. If the connection 2533 is from a trusted gateway, such inconsistency might be expected; 2534 otherwise, it might indicate an attempt to bypass security filters, 2535 trick the server into delivering non-public content, or poison a 2536 cache. See Section 17 for security considerations regarding message 2537 routing. 2539 Unless the connection is from a trusted gateway, an origin server 2540 MUST reject a request if any scheme-specific requirements for the 2541 target URI are not met. In particular, a request for an "https" 2542 resource MUST be rejected unless it has been received over a 2543 connection that has been secured via a certificate valid for that 2544 target URI's origin, as defined by Section 4.2.2. 2546 The 421 (Misdirected Request) status code in a response indicates 2547 that the origin server has rejected the request because it appears to 2548 have been misdirected (Section 15.5.20). 2550 7.5. Response Correlation 2552 A connection might be used for multiple request/response exchanges. 2553 The mechanism used to correlate between request and response messages 2554 is version dependent; some versions of HTTP use implicit ordering of 2555 messages, while others use an explicit identifier. 2557 All responses, regardless of the status code (including interim 2558 responses) can be sent at any time after a request is received, even 2559 if the request is not yet complete. A response can complete before 2560 its corresponding request is complete (Section 6.1). Likewise, 2561 clients are not expected to wait any specific amount of time for a 2562 response. Clients (including intermediaries) might abandon a request 2563 if the response is not forthcoming within a reasonable period of 2564 time. 2566 A client that receives a response while it is still sending the 2567 associated request SHOULD continue sending that request, unless it 2568 receives an explicit indication to the contrary (see, e.g., 2569 Section 9.5 of [HTTP/1.1] and Section 6.4 of [HTTP/2]). 2571 7.6. Message Forwarding 2573 As described in Section 3.7, intermediaries can serve a variety of 2574 roles in the processing of HTTP requests and responses. Some 2575 intermediaries are used to improve performance or availability. 2576 Others are used for access control or to filter content. Since an 2577 HTTP stream has characteristics similar to a pipe-and-filter 2578 architecture, there are no inherent limits to the extent an 2579 intermediary can enhance (or interfere) with either direction of the 2580 stream. 2582 Intermediaries are expected to forward messages even when protocol 2583 elements are not recognized (e.g., new methods, status codes, or 2584 field names), since that preserves extensibility for downstream 2585 recipients. 2587 An intermediary not acting as a tunnel MUST implement the Connection 2588 header field, as specified in Section 7.6.1, and exclude fields from 2589 being forwarded that are only intended for the incoming connection. 2591 An intermediary MUST NOT forward a message to itself unless it is 2592 protected from an infinite request loop. In general, an intermediary 2593 ought to recognize its own server names, including any aliases, local 2594 variations, or literal IP addresses, and respond to such requests 2595 directly. 2597 An HTTP message can be parsed as a stream for incremental processing 2598 or forwarding downstream. However, senders and recipients cannot 2599 rely on incremental delivery of partial messages, since some 2600 implementations will buffer or delay message forwarding for the sake 2601 of network efficiency, security checks, or content transformations. 2603 7.6.1. Connection 2605 The "Connection" header field allows the sender to list desired 2606 control options for the current connection. 2608 When a field aside from Connection is used to supply control 2609 information for or about the current connection, the sender MUST list 2610 the corresponding field name within the Connection header field. 2611 Note that some versions of HTTP prohibit the use of fields for such 2612 information, and therefore do not allow the Connection field. 2614 Intermediaries MUST parse a received Connection header field before a 2615 message is forwarded and, for each connection-option in this field, 2616 remove any header or trailer field(s) from the message with the same 2617 name as the connection-option, and then remove the Connection header 2618 field itself (or replace it with the intermediary's own connection 2619 options for the forwarded message). 2621 Hence, the Connection header field provides a declarative way of 2622 distinguishing fields that are only intended for the immediate 2623 recipient ("hop-by-hop") from those fields that are intended for all 2624 recipients on the chain ("end-to-end"), enabling the message to be 2625 self-descriptive and allowing future connection-specific extensions 2626 to be deployed without fear that they will be blindly forwarded by 2627 older intermediaries. 2629 Furthermore, intermediaries SHOULD remove or replace field(s) whose 2630 semantics are known to require removal before forwarding, whether or 2631 not they appear as a Connection option, after applying those fields' 2632 semantics. This includes but is not limited to: 2634 * Proxy-Connection (Appendix C.2.2 of [HTTP/1.1]) 2636 * Keep-Alive (Section 19.7.1 of [RFC2068]) 2638 * TE (Section 10.1.4) 2640 * Transfer-Encoding (Section 6.1 of [HTTP/1.1]) 2642 * Upgrade (Section 7.8) 2644 The Connection header field's value has the following grammar: 2646 Connection = #connection-option 2647 connection-option = token 2649 Connection options are case-insensitive. 2651 A sender MUST NOT send a connection option corresponding to a field 2652 that is intended for all recipients of the content. For example, 2653 Cache-Control is never appropriate as a connection option 2654 (Section 5.2 of [CACHING]). 2656 Connection options do not always correspond to a field present in the 2657 message, since a connection-specific field might not be needed if 2658 there are no parameters associated with a connection option. In 2659 contrast, a connection-specific field received without a 2660 corresponding connection option usually indicates that the field has 2661 been improperly forwarded by an intermediary and ought to be ignored 2662 by the recipient. 2664 When defining a new connection option that does not correspond to a 2665 field, specification authors ought to reserve the corresponding field 2666 name anyway in order to avoid later collisions. Such reserved field 2667 names are registered in the Hypertext Transfer Protocol (HTTP) Field 2668 Name Registry (Section 16.3.1). 2670 7.6.2. Max-Forwards 2672 The "Max-Forwards" header field provides a mechanism with the TRACE 2673 (Section 9.3.8) and OPTIONS (Section 9.3.7) request methods to limit 2674 the number of times that the request is forwarded by proxies. This 2675 can be useful when the client is attempting to trace a request that 2676 appears to be failing or looping mid-chain. 2678 Max-Forwards = 1*DIGIT 2680 The Max-Forwards value is a decimal integer indicating the remaining 2681 number of times this request message can be forwarded. 2683 Each intermediary that receives a TRACE or OPTIONS request containing 2684 a Max-Forwards header field MUST check and update its value prior to 2685 forwarding the request. If the received value is zero (0), the 2686 intermediary MUST NOT forward the request; instead, the intermediary 2687 MUST respond as the final recipient. If the received Max-Forwards 2688 value is greater than zero, the intermediary MUST generate an updated 2689 Max-Forwards field in the forwarded message with a field value that 2690 is the lesser of a) the received value decremented by one (1) or b) 2691 the recipient's maximum supported value for Max-Forwards. 2693 A recipient MAY ignore a Max-Forwards header field received with any 2694 other request methods. 2696 7.6.3. Via 2698 The "Via" header field indicates the presence of intermediate 2699 protocols and recipients between the user agent and the server (on 2700 requests) or between the origin server and the client (on responses), 2701 similar to the "Received" header field in email (Section 3.6.7 of 2702 [RFC5322]). Via can be used for tracking message forwards, avoiding 2703 request loops, and identifying the protocol capabilities of senders 2704 along the request/response chain. 2706 Via = #( received-protocol RWS received-by [ RWS comment ] ) 2708 received-protocol = [ protocol-name "/" ] protocol-version 2709 ; see Section 7.8 2710 received-by = pseudonym [ ":" port ] 2711 pseudonym = token 2713 Each member of the Via field value represents a proxy or gateway that 2714 has forwarded the message. Each intermediary appends its own 2715 information about how the message was received, such that the end 2716 result is ordered according to the sequence of forwarding recipients. 2718 A proxy MUST send an appropriate Via header field, as described 2719 below, in each message that it forwards. An HTTP-to-HTTP gateway 2720 MUST send an appropriate Via header field in each inbound request 2721 message and MAY send a Via header field in forwarded response 2722 messages. 2724 For each intermediary, the received-protocol indicates the protocol 2725 and protocol version used by the upstream sender of the message. 2726 Hence, the Via field value records the advertised protocol 2727 capabilities of the request/response chain such that they remain 2728 visible to downstream recipients; this can be useful for determining 2729 what backwards-incompatible features might be safe to use in 2730 response, or within a later request, as described in Section 2.5. 2731 For brevity, the protocol-name is omitted when the received protocol 2732 is HTTP. 2734 The received-by portion is normally the host and optional port number 2735 of a recipient server or client that subsequently forwarded the 2736 message. However, if the real host is considered to be sensitive 2737 information, a sender MAY replace it with a pseudonym. If a port is 2738 not provided, a recipient MAY interpret that as meaning it was 2739 received on the default port, if any, for the received-protocol. 2741 A sender MAY generate comments to identify the software of each 2742 recipient, analogous to the User-Agent and Server header fields. 2743 However, comments in Via are optional, and a recipient MAY remove 2744 them prior to forwarding the message. 2746 For example, a request message could be sent from an HTTP/1.0 user 2747 agent to an internal proxy code-named "fred", which uses HTTP/1.1 to 2748 forward the request to a public proxy at p.example.net, which 2749 completes the request by forwarding it to the origin server at 2750 www.example.com. The request received by www.example.com would then 2751 have the following Via header field: 2753 Via: 1.0 fred, 1.1 p.example.net 2755 An intermediary used as a portal through a network firewall SHOULD 2756 NOT forward the names and ports of hosts within the firewall region 2757 unless it is explicitly enabled to do so. If not enabled, such an 2758 intermediary SHOULD replace each received-by host of any host behind 2759 the firewall by an appropriate pseudonym for that host. 2761 An intermediary MAY combine an ordered subsequence of Via header 2762 field list members into a single member if the entries have identical 2763 received-protocol values. For example, 2765 Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy 2767 could be collapsed to 2769 Via: 1.0 ricky, 1.1 mertz, 1.0 lucy 2771 A sender SHOULD NOT combine multiple list members unless they are all 2772 under the same organizational control and the hosts have already been 2773 replaced by pseudonyms. A sender MUST NOT combine members that have 2774 different received-protocol values. 2776 7.7. Message Transformations 2778 Some intermediaries include features for transforming messages and 2779 their content. A proxy might, for example, convert between image 2780 formats in order to save cache space or to reduce the amount of 2781 traffic on a slow link. However, operational problems might occur 2782 when these transformations are applied to content intended for 2783 critical applications, such as medical imaging or scientific data 2784 analysis, particularly when integrity checks or digital signatures 2785 are used to ensure that the content received is identical to the 2786 original. 2788 An HTTP-to-HTTP proxy is called a _transforming proxy_ if it is 2789 designed or configured to modify messages in a semantically 2790 meaningful way (i.e., modifications, beyond those required by normal 2791 HTTP processing, that change the message in a way that would be 2792 significant to the original sender or potentially significant to 2793 downstream recipients). For example, a transforming proxy might be 2794 acting as a shared annotation server (modifying responses to include 2795 references to a local annotation database), a malware filter, a 2796 format transcoder, or a privacy filter. Such transformations are 2797 presumed to be desired by whichever client (or client organization) 2798 chose the proxy. 2800 If a proxy receives a target URI with a host name that is not a fully 2801 qualified domain name, it MAY add its own domain to the host name it 2802 received when forwarding the request. A proxy MUST NOT change the 2803 host name if the target URI contains a fully qualified domain name. 2805 A proxy MUST NOT modify the "absolute-path" and "query" parts of the 2806 received target URI when forwarding it to the next inbound server 2807 except as required by that forwarding protocol. For example, a proxy 2808 forwarding a request to an origin server via HTTP/1.1 will replace an 2809 empty path with "/" (Section 3.2.1 of [HTTP/1.1]) or "*" 2810 (Section 3.2.4 of [HTTP/1.1]), depending on the request method. 2812 A proxy MUST NOT transform the content (Section 6.4) of a message 2813 that contains a no-transform cache-control response directive 2814 (Section 5.2 of [CACHING]). Note that this does not include changes 2815 to the message body that do not affect the content, such as transfer 2816 codings (Section 7 of [HTTP/1.1]). 2818 A proxy MAY transform the content of a message that does not contain 2819 a no-transform cache-control directive. A proxy that transforms the 2820 content of a 200 (OK) response can inform downstream recipients that 2821 a transformation has been applied by changing the response status 2822 code to 203 (Non-Authoritative Information) (Section 15.3.4). 2824 A proxy SHOULD NOT modify header fields that provide information 2825 about the endpoints of the communication chain, the resource state, 2826 or the selected representation (other than the content) unless the 2827 field's definition specifically allows such modification or the 2828 modification is deemed necessary for privacy or security. 2830 7.8. Upgrade 2832 The "Upgrade" header field is intended to provide a simple mechanism 2833 for transitioning from HTTP/1.1 to some other protocol on the same 2834 connection. 2836 A client MAY send a list of protocol names in the Upgrade header 2837 field of a request to invite the server to switch to one or more of 2838 the named protocols, in order of descending preference, before 2839 sending the final response. A server MAY ignore a received Upgrade 2840 header field if it wishes to continue using the current protocol on 2841 that connection. Upgrade cannot be used to insist on a protocol 2842 change. 2844 Upgrade = #protocol 2846 protocol = protocol-name ["/" protocol-version] 2847 protocol-name = token 2848 protocol-version = token 2850 Although protocol names are registered with a preferred case, 2851 recipients SHOULD use case-insensitive comparison when matching each 2852 protocol-name to supported protocols. 2854 A server that sends a 101 (Switching Protocols) response MUST send an 2855 Upgrade header field to indicate the new protocol(s) to which the 2856 connection is being switched; if multiple protocol layers are being 2857 switched, the sender MUST list the protocols in layer-ascending 2858 order. A server MUST NOT switch to a protocol that was not indicated 2859 by the client in the corresponding request's Upgrade header field. A 2860 server MAY choose to ignore the order of preference indicated by the 2861 client and select the new protocol(s) based on other factors, such as 2862 the nature of the request or the current load on the server. 2864 A server that sends a 426 (Upgrade Required) response MUST send an 2865 Upgrade header field to indicate the acceptable protocols, in order 2866 of descending preference. 2868 A server MAY send an Upgrade header field in any other response to 2869 advertise that it implements support for upgrading to the listed 2870 protocols, in order of descending preference, when appropriate for a 2871 future request. 2873 The following is a hypothetical example sent by a client: 2875 GET /hello HTTP/1.1 2876 Host: www.example.com 2877 Connection: upgrade 2878 Upgrade: websocket, IRC/6.9, RTA/x11 2880 The capabilities and nature of the application-level communication 2881 after the protocol change is entirely dependent upon the new 2882 protocol(s) chosen. However, immediately after sending the 101 2883 (Switching Protocols) response, the server is expected to continue 2884 responding to the original request as if it had received its 2885 equivalent within the new protocol (i.e., the server still has an 2886 outstanding request to satisfy after the protocol has been changed, 2887 and is expected to do so without requiring the request to be 2888 repeated). 2890 For example, if the Upgrade header field is received in a GET request 2891 and the server decides to switch protocols, it first responds with a 2892 101 (Switching Protocols) message in HTTP/1.1 and then immediately 2893 follows that with the new protocol's equivalent of a response to a 2894 GET on the target resource. This allows a connection to be upgraded 2895 to protocols with the same semantics as HTTP without the latency cost 2896 of an additional round trip. A server MUST NOT switch protocols 2897 unless the received message semantics can be honored by the new 2898 protocol; an OPTIONS request can be honored by any protocol. 2900 The following is an example response to the above hypothetical 2901 request: 2903 HTTP/1.1 101 Switching Protocols 2904 Connection: upgrade 2905 Upgrade: websocket 2907 [... data stream switches to websocket with an appropriate response 2908 (as defined by new protocol) to the "GET /hello" request ...] 2910 A sender of Upgrade MUST also send an "Upgrade" connection option in 2911 the Connection header field (Section 7.6.1) to inform intermediaries 2912 not to forward this field. A server that receives an Upgrade header 2913 field in an HTTP/1.0 request MUST ignore that Upgrade field. 2915 A client cannot begin using an upgraded protocol on the connection 2916 until it has completely sent the request message (i.e., the client 2917 can't change the protocol it is sending in the middle of a message). 2918 If a server receives both an Upgrade and an Expect header field with 2919 the "100-continue" expectation (Section 10.1.1), the server MUST send 2920 a 100 (Continue) response before sending a 101 (Switching Protocols) 2921 response. 2923 The Upgrade header field only applies to switching protocols on top 2924 of the existing connection; it cannot be used to switch the 2925 underlying connection (transport) protocol, nor to switch the 2926 existing communication to a different connection. For those 2927 purposes, it is more appropriate to use a 3xx (Redirection) response 2928 (Section 15.4). 2930 This specification only defines the protocol name "HTTP" for use by 2931 the family of Hypertext Transfer Protocols, as defined by the HTTP 2932 version rules of Section 2.5 and future updates to this 2933 specification. Additional protocol names ought to be registered 2934 using the registration procedure defined in Section 16.7. 2936 8. Representation Data and Metadata 2938 8.1. Representation Data 2940 The representation data associated with an HTTP message is either 2941 provided as the content of the message or referred to by the message 2942 semantics and the target URI. The representation data is in a format 2943 and encoding defined by the representation metadata header fields. 2945 The data type of the representation data is determined via the header 2946 fields Content-Type and Content-Encoding. These define a two-layer, 2947 ordered encoding model: 2949 representation-data := Content-Encoding( Content-Type( data ) ) 2951 8.2. Representation Metadata 2953 Representation header fields provide metadata about the 2954 representation. When a message includes content, the representation 2955 header fields describe how to interpret that data. In a response to 2956 a HEAD request, the representation header fields describe the 2957 representation data that would have been enclosed in the content if 2958 the same request had been a GET. 2960 8.3. Content-Type 2962 The "Content-Type" header field indicates the media type of the 2963 associated representation: either the representation enclosed in the 2964 message content or the selected representation, as determined by the 2965 message semantics. The indicated media type defines both the data 2966 format and how that data is intended to be processed by a recipient, 2967 within the scope of the received message semantics, after any content 2968 codings indicated by Content-Encoding are decoded. 2970 Content-Type = media-type 2972 Media types are defined in Section 8.3.1. An example of the field is 2974 Content-Type: text/html; charset=ISO-8859-4 2975 A sender that generates a message containing content SHOULD generate 2976 a Content-Type header field in that message unless the intended media 2977 type of the enclosed representation is unknown to the sender. If a 2978 Content-Type header field is not present, the recipient MAY either 2979 assume a media type of "application/octet-stream" ([RFC2046], 2980 Section 4.5.1) or examine the data to determine its type. 2982 In practice, resource owners do not always properly configure their 2983 origin server to provide the correct Content-Type for a given 2984 representation. Some user agents examine the content and, in certain 2985 cases, override the received type (for example, see [Sniffing]). 2986 This "MIME sniffing" risks drawing incorrect conclusions about the 2987 data, which might expose the user to additional security risks (e.g., 2988 "privilege escalation"). Furthermore, distinct media types often 2989 share a common data format, differing only in how the data is 2990 intended to be processed, which is impossible to distinguish by 2991 inspecting the data alone. When sniffing is implemented, 2992 implementers are encouraged to provide a means for the user to 2993 disable it. 2995 Although Content-Type is defined as a singleton field, it is 2996 sometimes incorrectly generated multiple times, resulting in a 2997 combined field value that appears to be a list. Recipients often 2998 attempt to handle this error by using the last syntactically valid 2999 member of the list, leading to potential interoperability and 3000 security issues if different implementations have different error 3001 handling behaviors. 3003 8.3.1. Media Type 3005 HTTP uses media types [RFC2046] in the Content-Type (Section 8.3) and 3006 Accept (Section 12.5.1) header fields in order to provide open and 3007 extensible data typing and type negotiation. Media types define both 3008 a data format and various processing models: how to process that data 3009 in accordance with the message context. 3011 media-type = type "/" subtype parameters 3012 type = token 3013 subtype = token 3015 The type and subtype tokens are case-insensitive. 3017 The type/subtype MAY be followed by semicolon-delimited parameters 3018 (Section 5.6.6) in the form of name=value pairs. The presence or 3019 absence of a parameter might be significant to the processing of a 3020 media type, depending on its definition within the media type 3021 registry. Parameter values might or might not be case-sensitive, 3022 depending on the semantics of the parameter name. 3024 For example, the following media types are equivalent in describing 3025 HTML text data encoded in the UTF-8 character encoding scheme, but 3026 the first is preferred for consistency (the "charset" parameter value 3027 is defined as being case-insensitive in [RFC2046], Section 4.1.2): 3029 text/html;charset=utf-8 3030 Text/HTML;Charset="utf-8" 3031 text/html; charset="utf-8" 3032 text/html;charset=UTF-8 3034 Media types ought to be registered with IANA according to the 3035 procedures defined in [BCP13]. 3037 8.3.2. Charset 3039 HTTP uses _charset_ names to indicate or negotiate the character 3040 encoding scheme ([RFC6365], Section 1.3) of a textual representation. 3041 In the fields defined by this document, charset names appear either 3042 in parameters (Content-Type), or, for Accept-Encoding, in the form of 3043 a plain token. In both cases, charset names are matched case- 3044 insensitively. 3046 Charset names ought to be registered in the IANA "Character Sets" 3047 registry () 3048 according to the procedures defined in Section 2 of [RFC2978]. 3050 | *Note:* In theory, charset names are defined by the "mime- 3051 | charset" ABNF rule defined in Section 2.3 of [RFC2978] (as 3052 | corrected in [Err1912]). That rule allows two characters that 3053 | are not included in "token" ("{" and "}"), but no charset name 3054 | registered at the time of this writing includes braces (see 3055 | [Err5433]). 3057 8.3.3. Multipart Types 3059 MIME provides for a number of "multipart" types - encapsulations of 3060 one or more representations within a single message body. All 3061 multipart types share a common syntax, as defined in Section 5.1.1 of 3062 [RFC2046], and include a boundary parameter as part of the media type 3063 value. The message body is itself a protocol element; a sender MUST 3064 generate only CRLF to represent line breaks between body parts. 3066 HTTP message framing does not use the multipart boundary as an 3067 indicator of message body length, though it might be used by 3068 implementations that generate or process the content. For example, 3069 the "multipart/form-data" type is often used for carrying form data 3070 in a request, as described in [RFC7578], and the "multipart/ 3071 byteranges" type is defined by this specification for use in some 206 3072 (Partial Content) responses (see Section 15.3.7). 3074 8.4. Content-Encoding 3076 The "Content-Encoding" header field indicates what content codings 3077 have been applied to the representation, beyond those inherent in the 3078 media type, and thus what decoding mechanisms have to be applied in 3079 order to obtain data in the media type referenced by the Content-Type 3080 header field. Content-Encoding is primarily used to allow a 3081 representation's data to be compressed without losing the identity of 3082 its underlying media type. 3084 Content-Encoding = #content-coding 3086 An example of its use is 3088 Content-Encoding: gzip 3090 If one or more encodings have been applied to a representation, the 3091 sender that applied the encodings MUST generate a Content-Encoding 3092 header field that lists the content codings in the order in which 3093 they were applied. Note that the coding named "identity" is reserved 3094 for its special role in Accept-Encoding, and thus SHOULD NOT be 3095 included. 3097 Additional information about the encoding parameters can be provided 3098 by other header fields not defined by this specification. 3100 Unlike Transfer-Encoding (Section 6.1 of [HTTP/1.1]), the codings 3101 listed in Content-Encoding are a characteristic of the 3102 representation; the representation is defined in terms of the coded 3103 form, and all other metadata about the representation is about the 3104 coded form unless otherwise noted in the metadata definition. 3105 Typically, the representation is only decoded just prior to rendering 3106 or analogous usage. 3108 If the media type includes an inherent encoding, such as a data 3109 format that is always compressed, then that encoding would not be 3110 restated in Content-Encoding even if it happens to be the same 3111 algorithm as one of the content codings. Such a content coding would 3112 only be listed if, for some bizarre reason, it is applied a second 3113 time to form the representation. Likewise, an origin server might 3114 choose to publish the same data as multiple representations that 3115 differ only in whether the coding is defined as part of Content-Type 3116 or Content-Encoding, since some user agents will behave differently 3117 in their handling of each response (e.g., open a "Save as ..." dialog 3118 instead of automatic decompression and rendering of content). 3120 An origin server MAY respond with a status code of 415 (Unsupported 3121 Media Type) if a representation in the request message has a content 3122 coding that is not acceptable. 3124 8.4.1. Content Codings 3126 Content coding values indicate an encoding transformation that has 3127 been or can be applied to a representation. Content codings are 3128 primarily used to allow a representation to be compressed or 3129 otherwise usefully transformed without losing the identity of its 3130 underlying media type and without loss of information. Frequently, 3131 the representation is stored in coded form, transmitted directly, and 3132 only decoded by the final recipient. 3134 content-coding = token 3136 All content codings are case-insensitive and ought to be registered 3137 within the "HTTP Content Coding Registry", as described in 3138 Section 16.6 3140 Content-coding values are used in the Accept-Encoding 3141 (Section 12.5.3) and Content-Encoding (Section 8.4) header fields. 3143 8.4.1.1. Compress Coding 3145 The "compress" coding is an adaptive Lempel-Ziv-Welch (LZW) coding 3146 [Welch] that is commonly produced by the UNIX file compression 3147 program "compress". A recipient SHOULD consider "x-compress" to be 3148 equivalent to "compress". 3150 8.4.1.2. Deflate Coding 3152 The "deflate" coding is a "zlib" data format [RFC1950] containing a 3153 "deflate" compressed data stream [RFC1951] that uses a combination of 3154 the Lempel-Ziv (LZ77) compression algorithm and Huffman coding. 3156 | *Note:* Some non-conformant implementations send the "deflate" 3157 | compressed data without the zlib wrapper. 3159 8.4.1.3. Gzip Coding 3161 The "gzip" coding is an LZ77 coding with a 32-bit Cyclic Redundancy 3162 Check (CRC) that is commonly produced by the gzip file compression 3163 program [RFC1952]. A recipient SHOULD consider "x-gzip" to be 3164 equivalent to "gzip". 3166 8.5. Content-Language 3168 The "Content-Language" header field describes the natural language(s) 3169 of the intended audience for the representation. Note that this 3170 might not be equivalent to all the languages used within the 3171 representation. 3173 Content-Language = #language-tag 3175 Language tags are defined in Section 8.5.1. The primary purpose of 3176 Content-Language is to allow a user to identify and differentiate 3177 representations according to the users' own preferred language. 3178 Thus, if the content is intended only for a Danish-literate audience, 3179 the appropriate field is 3181 Content-Language: da 3183 If no Content-Language is specified, the default is that the content 3184 is intended for all language audiences. This might mean that the 3185 sender does not consider it to be specific to any natural language, 3186 or that the sender does not know for which language it is intended. 3188 Multiple languages MAY be listed for content that is intended for 3189 multiple audiences. For example, a rendition of the "Treaty of 3190 Waitangi", presented simultaneously in the original Maori and English 3191 versions, would call for 3193 Content-Language: mi, en 3195 However, just because multiple languages are present within a 3196 representation does not mean that it is intended for multiple 3197 linguistic audiences. An example would be a beginner's language 3198 primer, such as "A First Lesson in Latin", which is clearly intended 3199 to be used by an English-literate audience. In this case, the 3200 Content-Language would properly only include "en". 3202 Content-Language MAY be applied to any media type - it is not limited 3203 to textual documents. 3205 8.5.1. Language Tags 3207 A language tag, as defined in [RFC5646], identifies a natural 3208 language spoken, written, or otherwise conveyed by human beings for 3209 communication of information to other human beings. Computer 3210 languages are explicitly excluded. 3212 HTTP uses language tags within the Accept-Language and 3213 Content-Language header fields. Accept-Language uses the broader 3214 language-range production defined in Section 12.5.4, whereas 3215 Content-Language uses the language-tag production defined below. 3217 language-tag = 3219 A language tag is a sequence of one or more case-insensitive subtags, 3220 each separated by a hyphen character ("-", %x2D). In most cases, a 3221 language tag consists of a primary language subtag that identifies a 3222 broad family of related languages (e.g., "en" = English), which is 3223 optionally followed by a series of subtags that refine or narrow that 3224 language's range (e.g., "en-CA" = the variety of English as 3225 communicated in Canada). Whitespace is not allowed within a language 3226 tag. Example tags include: 3228 fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN 3230 See [RFC5646] for further information. 3232 8.6. Content-Length 3234 The "Content-Length" header field indicates the associated 3235 representation's data length as a decimal non-negative integer number 3236 of octets. When transferring a representation as content, Content- 3237 Length refers specifically to the amount of data enclosed so that it 3238 can be used to delimit framing (e.g., Section 6.2 of [HTTP/1.1]). In 3239 other cases, Content-Length indicates the selected representation's 3240 current length, which can be used by recipients to estimate transfer 3241 time or compare to previously stored representations. 3243 Content-Length = 1*DIGIT 3245 An example is 3247 Content-Length: 3495 3249 A user agent SHOULD send Content-Length in a request when the method 3250 defines a meaning for enclosed content and it is not sending 3251 Transfer-Encoding. For example, a user agent normally sends Content- 3252 Length in a POST request even when the value is 0 (indicating empty 3253 content). A user agent SHOULD NOT send a Content-Length header field 3254 when the request message does not contain content and the method 3255 semantics do not anticipate such data. 3257 A server MAY send a Content-Length header field in a response to a 3258 HEAD request (Section 9.3.2); a server MUST NOT send Content-Length 3259 in such a response unless its field value equals the decimal number 3260 of octets that would have been sent in the content of a response if 3261 the same request had used the GET method. 3263 A server MAY send a Content-Length header field in a 304 (Not 3264 Modified) response to a conditional GET request (Section 15.4.5); a 3265 server MUST NOT send Content-Length in such a response unless its 3266 field value equals the decimal number of octets that would have been 3267 sent in the content of a 200 (OK) response to the same request. 3269 A server MUST NOT send a Content-Length header field in any response 3270 with a status code of 1xx (Informational) or 204 (No Content). A 3271 server MUST NOT send a Content-Length header field in any 2xx 3272 (Successful) response to a CONNECT request (Section 9.3.6). 3274 Aside from the cases defined above, in the absence of Transfer- 3275 Encoding, an origin server SHOULD send a Content-Length header field 3276 when the content size is known prior to sending the complete header 3277 section. This will allow downstream recipients to measure transfer 3278 progress, know when a received message is complete, and potentially 3279 reuse the connection for additional requests. 3281 Any Content-Length field value greater than or equal to zero is 3282 valid. Since there is no predefined limit to the length of content, 3283 a recipient MUST anticipate potentially large decimal numerals and 3284 prevent parsing errors due to integer conversion overflows or 3285 precision loss due to integer conversion (Section 17.5). 3287 Because Content-Length is used for message delimitation in HTTP/1.1, 3288 its field value can impact how the message is parsed by downstream 3289 recipients even when the immediate connection is not using HTTP/1.1. 3290 If the message is forwarded by a downstream intermediary, a Content- 3291 Length field value that is inconsistent with the received message 3292 framing might cause a security failure due to request smuggling or 3293 response splitting. 3295 As a result, a sender MUST NOT forward a message with a Content- 3296 Length header field value that is known to be incorrect. 3298 Likewise, a sender MUST NOT forward a message with a Content-Length 3299 header field value that does not match the ABNF above, with one 3300 exception: A recipient of a Content-Length header field value 3301 consisting of the same decimal value repeated as a comma-separated 3302 list (e.g, "Content-Length: 42, 42"), MAY either reject the message 3303 as invalid or replace that invalid field value with a single instance 3304 of the decimal value, since this likely indicates that a duplicate 3305 was generated or combined by an upstream message processor. 3307 8.7. Content-Location 3309 The "Content-Location" header field references a URI that can be used 3310 as an identifier for a specific resource corresponding to the 3311 representation in this message's content. In other words, if one 3312 were to perform a GET request on this URI at the time of this 3313 message's generation, then a 200 (OK) response would contain the same 3314 representation that is enclosed as content in this message. 3316 Content-Location = absolute-URI / partial-URI 3318 The field value is either an absolute-URI or a partial-URI. In the 3319 latter case (Section 4), the referenced URI is relative to the target 3320 URI ([URI], Section 5). 3322 The Content-Location value is not a replacement for the target URI 3323 (Section 7.1). It is representation metadata. It has the same 3324 syntax and semantics as the header field of the same name defined for 3325 MIME body parts in Section 4 of [RFC2557]. However, its appearance 3326 in an HTTP message has some special implications for HTTP recipients. 3328 If Content-Location is included in a 2xx (Successful) response 3329 message and its value refers (after conversion to absolute form) to a 3330 URI that is the same as the target URI, then the recipient MAY 3331 consider the content to be a current representation of that resource 3332 at the time indicated by the message origination date. For a GET 3333 (Section 9.3.1) or HEAD (Section 9.3.2) request, this is the same as 3334 the default semantics when no Content-Location is provided by the 3335 server. For a state-changing request like PUT (Section 9.3.4) or 3336 POST (Section 9.3.3), it implies that the server's response contains 3337 the new representation of that resource, thereby distinguishing it 3338 from representations that might only report about the action (e.g., 3339 "It worked!"). This allows authoring applications to update their 3340 local copies without the need for a subsequent GET request. 3342 If Content-Location is included in a 2xx (Successful) response 3343 message and its field value refers to a URI that differs from the 3344 target URI, then the origin server claims that the URI is an 3345 identifier for a different resource corresponding to the enclosed 3346 representation. Such a claim can only be trusted if both identifiers 3347 share the same resource owner, which cannot be programmatically 3348 determined via HTTP. 3350 * For a response to a GET or HEAD request, this is an indication 3351 that the target URI refers to a resource that is subject to 3352 content negotiation and the Content-Location field value is a more 3353 specific identifier for the selected representation. 3355 * For a 201 (Created) response to a state-changing method, a 3356 Content-Location field value that is identical to the Location 3357 field value indicates that this content is a current 3358 representation of the newly created resource. 3360 * Otherwise, such a Content-Location indicates that this content is 3361 a representation reporting on the requested action's status and 3362 that the same report is available (for future access with GET) at 3363 the given URI. For example, a purchase transaction made via a 3364 POST request might include a receipt document as the content of 3365 the 200 (OK) response; the Content-Location field value provides 3366 an identifier for retrieving a copy of that same receipt in the 3367 future. 3369 A user agent that sends Content-Location in a request message is 3370 stating that its value refers to where the user agent originally 3371 obtained the content of the enclosed representation (prior to any 3372 modifications made by that user agent). In other words, the user 3373 agent is providing a back link to the source of the original 3374 representation. 3376 An origin server that receives a Content-Location field in a request 3377 message MUST treat the information as transitory request context 3378 rather than as metadata to be saved verbatim as part of the 3379 representation. An origin server MAY use that context to guide in 3380 processing the request or to save it for other uses, such as within 3381 source links or versioning metadata. However, an origin server MUST 3382 NOT use such context information to alter the request semantics. 3384 For example, if a client makes a PUT request on a negotiated resource 3385 and the origin server accepts that PUT (without redirection), then 3386 the new state of that resource is expected to be consistent with the 3387 one representation supplied in that PUT; the Content-Location cannot 3388 be used as a form of reverse content selection identifier to update 3389 only one of the negotiated representations. If the user agent had 3390 wanted the latter semantics, it would have applied the PUT directly 3391 to the Content-Location URI. 3393 8.8. Validator Fields 3395 Resource metadata is referred to as a _validator_ if it can be used 3396 within a precondition (Section 13.1) to make a conditional request 3397 (Section 13). Validator fields convey a current validator for the 3398 selected representation (Section 3.2). 3400 In responses to safe requests, validator fields describe the selected 3401 representation chosen by the origin server while handling the 3402 response. Note that, depending on the method and status code 3403 semantics, the selected representation for a given response is not 3404 necessarily the same as the representation enclosed as response 3405 content. 3407 In a successful response to a state-changing request, validator 3408 fields describe the new representation that has replaced the prior 3409 selected representation as a result of processing the request. 3411 For example, an ETag field in a 201 (Created) response communicates 3412 the entity-tag of the newly created resource's representation, so 3413 that the entity-tag can be used as a validator in later conditional 3414 requests to prevent the "lost update" problem. 3416 This specification defines two forms of metadata that are commonly 3417 used to observe resource state and test for preconditions: 3418 modification dates (Section 8.8.2) and opaque entity tags 3419 (Section 8.8.3). Additional metadata that reflects resource state 3420 has been defined by various extensions of HTTP, such as Web 3421 Distributed Authoring and Versioning [WEBDAV], that are beyond the 3422 scope of this specification. 3424 8.8.1. Weak versus Strong 3426 Validators come in two flavors: strong or weak. Weak validators are 3427 easy to generate but are far less useful for comparisons. Strong 3428 validators are ideal for comparisons but can be very difficult (and 3429 occasionally impossible) to generate efficiently. Rather than impose 3430 that all forms of resource adhere to the same strength of validator, 3431 HTTP exposes the type of validator in use and imposes restrictions on 3432 when weak validators can be used as preconditions. 3434 A _strong validator_ is representation metadata that changes value 3435 whenever a change occurs to the representation data that would be 3436 observable in the content of a 200 (OK) response to GET. 3438 A strong validator might change for reasons other than a change to 3439 the representation data, such as when a semantically significant part 3440 of the representation metadata is changed (e.g., Content-Type), but 3441 it is in the best interests of the origin server to only change the 3442 value when it is necessary to invalidate the stored responses held by 3443 remote caches and authoring tools. 3445 Cache entries might persist for arbitrarily long periods, regardless 3446 of expiration times. Thus, a cache might attempt to validate an 3447 entry using a validator that it obtained in the distant past. A 3448 strong validator is unique across all versions of all representations 3449 associated with a particular resource over time. However, there is 3450 no implication of uniqueness across representations of different 3451 resources (i.e., the same strong validator might be in use for 3452 representations of multiple resources at the same time and does not 3453 imply that those representations are equivalent). 3455 There are a variety of strong validators used in practice. The best 3456 are based on strict revision control, wherein each change to a 3457 representation always results in a unique node name and revision 3458 identifier being assigned before the representation is made 3459 accessible to GET. A collision-resistant hash function applied to 3460 the representation data is also sufficient if the data is available 3461 prior to the response header fields being sent and the digest does 3462 not need to be recalculated every time a validation request is 3463 received. However, if a resource has distinct representations that 3464 differ only in their metadata, such as might occur with content 3465 negotiation over media types that happen to share the same data 3466 format, then the origin server needs to incorporate additional 3467 information in the validator to distinguish those representations. 3469 In contrast, a _weak validator_ is representation metadata that might 3470 not change for every change to the representation data. This 3471 weakness might be due to limitations in how the value is calculated 3472 (e.g., clock resolution), an inability to ensure uniqueness for all 3473 possible representations of the resource, or a desire of the resource 3474 owner to group representations by some self-determined set of 3475 equivalency rather than unique sequences of data. 3477 An origin server SHOULD change a weak entity-tag whenever it 3478 considers prior representations to be unacceptable as a substitute 3479 for the current representation. In other words, a weak entity-tag 3480 ought to change whenever the origin server wants caches to invalidate 3481 old responses. 3483 For example, the representation of a weather report that changes in 3484 content every second, based on dynamic measurements, might be grouped 3485 into sets of equivalent representations (from the origin server's 3486 perspective) with the same weak validator in order to allow cached 3487 representations to be valid for a reasonable period of time (perhaps 3488 adjusted dynamically based on server load or weather quality). 3490 Likewise, a representation's modification time, if defined with only 3491 one-second resolution, might be a weak validator if it is possible 3492 for the representation to be modified twice during a single second 3493 and retrieved between those modifications. 3495 Likewise, a validator is weak if it is shared by two or more 3496 representations of a given resource at the same time, unless those 3497 representations have identical representation data. For example, if 3498 the origin server sends the same validator for a representation with 3499 a gzip content coding applied as it does for a representation with no 3500 content coding, then that validator is weak. However, two 3501 simultaneous representations might share the same strong validator if 3502 they differ only in the representation metadata, such as when two 3503 different media types are available for the same representation data. 3505 Strong validators are usable for all conditional requests, including 3506 cache validation, partial content ranges, and "lost update" 3507 avoidance. Weak validators are only usable when the client does not 3508 require exact equality with previously obtained representation data, 3509 such as when validating a cache entry or limiting a web traversal to 3510 recent changes. 3512 8.8.2. Last-Modified 3514 The "Last-Modified" header field in a response provides a timestamp 3515 indicating the date and time at which the origin server believes the 3516 selected representation was last modified, as determined at the 3517 conclusion of handling the request. 3519 Last-Modified = HTTP-date 3521 An example of its use is 3523 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 3525 8.8.2.1. Generation 3527 An origin server SHOULD send Last-Modified for any selected 3528 representation for which a last modification date can be reasonably 3529 and consistently determined, since its use in conditional requests 3530 and evaluating cache freshness ([CACHING]) can substantially reduce 3531 unnecessary transfers and significantly improve service availability 3532 and scalability. 3534 A representation is typically the sum of many parts behind the 3535 resource interface. The last-modified time would usually be the most 3536 recent time that any of those parts were changed. How that value is 3537 determined for any given resource is an implementation detail beyond 3538 the scope of this specification. 3540 An origin server SHOULD obtain the Last-Modified value of the 3541 representation as close as possible to the time that it generates the 3542 Date field value for its response. This allows a recipient to make 3543 an accurate assessment of the representation's modification time, 3544 especially if the representation changes near the time that the 3545 response is generated. 3547 An origin server with a clock (as defined in Section 5.6.7) MUST NOT 3548 generate a Last-Modified date that is later than the server's time of 3549 message origination (Date, Section 6.6.1). If the last modification 3550 time is derived from implementation-specific metadata that evaluates 3551 to some time in the future, according to the origin server's clock, 3552 then the origin server MUST replace that value with the message 3553 origination date. This prevents a future modification date from 3554 having an adverse impact on cache validation. 3556 An origin server without a clock MUST NOT generate a Last-Modified 3557 date for a response unless that date value was assigned to the 3558 resource by some other system (presumably one with a clock). 3560 8.8.2.2. Comparison 3562 A Last-Modified time, when used as a validator in a request, is 3563 implicitly weak unless it is possible to deduce that it is strong, 3564 using the following rules: 3566 * The validator is being compared by an origin server to the actual 3567 current validator for the representation and, 3569 * That origin server reliably knows that the associated 3570 representation did not change twice during the second covered by 3571 the presented validator; 3573 or 3575 * The validator is about to be used by a client in an 3576 If-Modified-Since, If-Unmodified-Since, or If-Range header field, 3577 because the client has a cache entry for the associated 3578 representation, and 3580 * That cache entry includes a Date value which is at least one 3581 second after the Last-Modified value and the client has reason to 3582 believe that they were generated by the same clock or that there 3583 is enough difference between the Last-Modified and Date values to 3584 make clock synchronization issues unlikely; 3586 or 3588 * The validator is being compared by an intermediate cache to the 3589 validator stored in its cache entry for the representation, and 3591 * That cache entry includes a Date value which is at least one 3592 second after the Last-Modified value and the cache has reason to 3593 believe that they were generated by the same clock or that there 3594 is enough difference between the Last-Modified and Date values to 3595 make clock synchronization issues unlikely. 3597 This method relies on the fact that if two different responses were 3598 sent by the origin server during the same second, but both had the 3599 same Last-Modified time, then at least one of those responses would 3600 have a Date value equal to its Last-Modified time. 3602 8.8.3. ETag 3604 The "ETag" field in a response provides the current entity-tag for 3605 the selected representation, as determined at the conclusion of 3606 handling the request. An entity-tag is an opaque validator for 3607 differentiating between multiple representations of the same 3608 resource, regardless of whether those multiple representations are 3609 due to resource state changes over time, content negotiation 3610 resulting in multiple representations being valid at the same time, 3611 or both. An entity-tag consists of an opaque quoted string, possibly 3612 prefixed by a weakness indicator. 3614 ETag = entity-tag 3616 entity-tag = [ weak ] opaque-tag 3617 weak = %s"W/" 3618 opaque-tag = DQUOTE *etagc DQUOTE 3619 etagc = %x21 / %x23-7E / obs-text 3620 ; VCHAR except double quotes, plus obs-text 3622 | *Note:* Previously, opaque-tag was defined to be a quoted- 3623 | string ([RFC2616], Section 3.11); thus, some recipients might 3624 | perform backslash unescaping. Servers therefore ought to avoid 3625 | backslash characters in entity tags. 3627 An entity-tag can be more reliable for validation than a modification 3628 date in situations where it is inconvenient to store modification 3629 dates, where the one-second resolution of HTTP date values is not 3630 sufficient, or where modification dates are not consistently 3631 maintained. 3633 Examples: 3635 ETag: "xyzzy" 3636 ETag: W/"xyzzy" 3637 ETag: "" 3639 An entity-tag can be either a weak or strong validator, with strong 3640 being the default. If an origin server provides an entity-tag for a 3641 representation and the generation of that entity-tag does not satisfy 3642 all of the characteristics of a strong validator (Section 8.8.1), 3643 then the origin server MUST mark the entity-tag as weak by prefixing 3644 its opaque value with "W/" (case-sensitive). 3646 A sender MAY send the Etag field in a trailer section (see 3647 Section 6.5). However, since trailers are often ignored, it is 3648 preferable to send Etag as a header field unless the entity-tag is 3649 generated while sending the content. 3651 8.8.3.1. Generation 3653 The principle behind entity-tags is that only the service author 3654 knows the implementation of a resource well enough to select the most 3655 accurate and efficient validation mechanism for that resource, and 3656 that any such mechanism can be mapped to a simple sequence of octets 3657 for easy comparison. Since the value is opaque, there is no need for 3658 the client to be aware of how each entity-tag is constructed. 3660 For example, a resource that has implementation-specific versioning 3661 applied to all changes might use an internal revision number, perhaps 3662 combined with a variance identifier for content negotiation, to 3663 accurately differentiate between representations. Other 3664 implementations might use a collision-resistant hash of 3665 representation content, a combination of various file attributes, or 3666 a modification timestamp that has sub-second resolution. 3668 An origin server SHOULD send an ETag for any selected representation 3669 for which detection of changes can be reasonably and consistently 3670 determined, since the entity-tag's use in conditional requests and 3671 evaluating cache freshness ([CACHING]) can substantially reduce 3672 unnecessary transfers and significantly improve service availability, 3673 scalability, and reliability. 3675 8.8.3.2. Comparison 3677 There are two entity-tag comparison functions, depending on whether 3678 or not the comparison context allows the use of weak validators: 3680 _Strong comparison_: two entity-tags are equivalent if both are not 3681 weak and their opaque-tags match character-by-character. 3683 _Weak comparison_: two entity-tags are equivalent if their opaque- 3684 tags match character-by-character, regardless of either or both 3685 being tagged as "weak". 3687 The example below shows the results for a set of entity-tag pairs and 3688 both the weak and strong comparison function results: 3690 +========+========+===================+=================+ 3691 | ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | 3692 +========+========+===================+=================+ 3693 | W/"1" | W/"1" | no match | match | 3694 +--------+--------+-------------------+-----------------+ 3695 | W/"1" | W/"2" | no match | no match | 3696 +--------+--------+-------------------+-----------------+ 3697 | W/"1" | "1" | no match | match | 3698 +--------+--------+-------------------+-----------------+ 3699 | "1" | "1" | match | match | 3700 +--------+--------+-------------------+-----------------+ 3702 Table 3 3704 8.8.3.3. Example: Entity-Tags Varying on Content-Negotiated Resources 3706 Consider a resource that is subject to content negotiation 3707 (Section 12), and where the representations sent in response to a GET 3708 request vary based on the Accept-Encoding request header field 3709 (Section 12.5.3): 3711 >> Request: 3713 GET /index HTTP/1.1 3714 Host: www.example.com 3715 Accept-Encoding: gzip 3717 In this case, the response might or might not use the gzip content 3718 coding. If it does not, the response might look like: 3720 >> Response: 3722 HTTP/1.1 200 OK 3723 Date: Fri, 26 Mar 2010 00:05:00 GMT 3724 ETag: "123-a" 3725 Content-Length: 70 3726 Vary: Accept-Encoding 3727 Content-Type: text/plain 3729 Hello World! 3730 Hello World! 3731 Hello World! 3732 Hello World! 3733 Hello World! 3735 An alternative representation that does use gzip content coding would 3736 be: 3738 >> Response: 3740 HTTP/1.1 200 OK 3741 Date: Fri, 26 Mar 2010 00:05:00 GMT 3742 ETag: "123-b" 3743 Content-Length: 43 3744 Vary: Accept-Encoding 3745 Content-Type: text/plain 3746 Content-Encoding: gzip 3748 ...binary data... 3750 | *Note:* Content codings are a property of the representation 3751 | data, so a strong entity-tag for a content-encoded 3752 | representation has to be distinct from the entity tag of an 3753 | unencoded representation to prevent potential conflicts during 3754 | cache updates and range requests. In contrast, transfer 3755 | codings (Section 7 of [HTTP/1.1]) apply only during message 3756 | transfer and do not result in distinct entity-tags. 3758 9. Methods 3760 9.1. Overview 3762 The request method token is the primary source of request semantics; 3763 it indicates the purpose for which the client has made this request 3764 and what is expected by the client as a successful result. 3766 The request method's semantics might be further specialized by the 3767 semantics of some header fields when present in a request if those 3768 additional semantics do not conflict with the method. For example, a 3769 client can send conditional request header fields (Section 13.1) to 3770 make the requested action conditional on the current state of the 3771 target resource. 3773 HTTP is designed to be usable as an interface to distributed object 3774 systems. The request method invokes an action to be applied to a 3775 target resource in much the same way that a remote method invocation 3776 can be sent to an identified object. 3778 method = token 3780 The method token is case-sensitive because it might be used as a 3781 gateway to object-based systems with case-sensitive method names. By 3782 convention, standardized methods are defined in all-uppercase US- 3783 ASCII letters. 3785 Unlike distributed objects, the standardized request methods in HTTP 3786 are not resource-specific, since uniform interfaces provide for 3787 better visibility and reuse in network-based systems [REST]. Once 3788 defined, a standardized method ought to have the same semantics when 3789 applied to any resource, though each resource determines for itself 3790 whether those semantics are implemented or allowed. 3792 This specification defines a number of standardized methods that are 3793 commonly used in HTTP, as outlined by the following table. 3795 +=========+============================================+=======+ 3796 | Method | Description | Ref. | 3797 +=========+============================================+=======+ 3798 | GET | Transfer a current representation of the | 9.3.1 | 3799 | | target resource. | | 3800 +---------+--------------------------------------------+-------+ 3801 | HEAD | Same as GET, but do not transfer the | 9.3.2 | 3802 | | response content. | | 3803 +---------+--------------------------------------------+-------+ 3804 | POST | Perform resource-specific processing on | 9.3.3 | 3805 | | the request content. | | 3806 +---------+--------------------------------------------+-------+ 3807 | PUT | Replace all current representations of the | 9.3.4 | 3808 | | target resource with the request content. | | 3809 +---------+--------------------------------------------+-------+ 3810 | DELETE | Remove all current representations of the | 9.3.5 | 3811 | | target resource. | | 3812 +---------+--------------------------------------------+-------+ 3813 | CONNECT | Establish a tunnel to the server | 9.3.6 | 3814 | | identified by the target resource. | | 3815 +---------+--------------------------------------------+-------+ 3816 | OPTIONS | Describe the communication options for the | 9.3.7 | 3817 | | target resource. | | 3818 +---------+--------------------------------------------+-------+ 3819 | TRACE | Perform a message loop-back test along the | 9.3.8 | 3820 | | path to the target resource. | | 3821 +---------+--------------------------------------------+-------+ 3823 Table 4 3825 All general-purpose servers MUST support the methods GET and HEAD. 3826 All other methods are OPTIONAL. 3828 The set of methods allowed by a target resource can be listed in an 3829 Allow header field (Section 10.2.1). However, the set of allowed 3830 methods can change dynamically. An origin server that receives a 3831 request method that is unrecognized or not implemented SHOULD respond 3832 with the 501 (Not Implemented) status code. An origin server that 3833 receives a request method that is recognized and implemented, but not 3834 allowed for the target resource, SHOULD respond with the 405 (Method 3835 Not Allowed) status code. 3837 Additional methods, outside the scope of this specification, have 3838 been specified for use in HTTP. All such methods ought to be 3839 registered within the "Hypertext Transfer Protocol (HTTP) Method 3840 Registry", as described in Section 16.1. 3842 9.2. Common Method Properties 3844 9.2.1. Safe Methods 3846 Request methods are considered _safe_ if their defined semantics are 3847 essentially read-only; i.e., the client does not request, and does 3848 not expect, any state change on the origin server as a result of 3849 applying a safe method to a target resource. Likewise, reasonable 3850 use of a safe method is not expected to cause any harm, loss of 3851 property, or unusual burden on the origin server. 3853 This definition of safe methods does not prevent an implementation 3854 from including behavior that is potentially harmful, that is not 3855 entirely read-only, or that causes side effects while invoking a safe 3856 method. What is important, however, is that the client did not 3857 request that additional behavior and cannot be held accountable for 3858 it. For example, most servers append request information to access 3859 log files at the completion of every response, regardless of the 3860 method, and that is considered safe even though the log storage might 3861 become full and cause the server to fail. Likewise, a safe request 3862 initiated by selecting an advertisement on the Web will often have 3863 the side effect of charging an advertising account. 3865 Of the request methods defined by this specification, the GET, HEAD, 3866 OPTIONS, and TRACE methods are defined to be safe. 3868 The purpose of distinguishing between safe and unsafe methods is to 3869 allow automated retrieval processes (spiders) and cache performance 3870 optimization (pre-fetching) to work without fear of causing harm. In 3871 addition, it allows a user agent to apply appropriate constraints on 3872 the automated use of unsafe methods when processing potentially 3873 untrusted content. 3875 A user agent SHOULD distinguish between safe and unsafe methods when 3876 presenting potential actions to a user, such that the user can be 3877 made aware of an unsafe action before it is requested. 3879 When a resource is constructed such that parameters within the target 3880 URI have the effect of selecting an action, it is the resource 3881 owner's responsibility to ensure that the action is consistent with 3882 the request method semantics. For example, it is common for Web- 3883 based content editing software to use actions within query 3884 parameters, such as "page?do=delete". If the purpose of such a 3885 resource is to perform an unsafe action, then the resource owner MUST 3886 disable or disallow that action when it is accessed using a safe 3887 request method. Failure to do so will result in unfortunate side 3888 effects when automated processes perform a GET on every URI reference 3889 for the sake of link maintenance, pre-fetching, building a search 3890 index, etc. 3892 9.2.2. Idempotent Methods 3894 A request method is considered _idempotent_ if the intended effect on 3895 the server of multiple identical requests with that method is the 3896 same as the effect for a single such request. Of the request methods 3897 defined by this specification, PUT, DELETE, and safe request methods 3898 are idempotent. 3900 Like the definition of safe, the idempotent property only applies to 3901 what has been requested by the user; a server is free to log each 3902 request separately, retain a revision control history, or implement 3903 other non-idempotent side effects for each idempotent request. 3905 Idempotent methods are distinguished because the request can be 3906 repeated automatically if a communication failure occurs before the 3907 client is able to read the server's response. For example, if a 3908 client sends a PUT request and the underlying connection is closed 3909 before any response is received, then the client can establish a new 3910 connection and retry the idempotent request. It knows that repeating 3911 the request will have the same intended effect, even if the original 3912 request succeeded, though the response might differ. 3914 A client SHOULD NOT automatically retry a request with a non- 3915 idempotent method unless it has some means to know that the request 3916 semantics are actually idempotent, regardless of the method, or some 3917 means to detect that the original request was never applied. 3919 For example, a user agent can repeat a POST request automatically if 3920 it knows (through design or configuration) that the request is safe 3921 for that resource. Likewise, a user agent designed specifically to 3922 operate on a version control repository might be able to recover from 3923 partial failure conditions by checking the target resource 3924 revision(s) after a failed connection, reverting or fixing any 3925 changes that were partially applied, and then automatically retrying 3926 the requests that failed. 3928 Some clients take a riskier approach and attempt to guess when an 3929 automatic retry is possible. For example, a client might 3930 automatically retry a POST request if the underlying transport 3931 connection closed before any part of a response is received, 3932 particularly if an idle persistent connection was used. 3934 A proxy MUST NOT automatically retry non-idempotent requests. A 3935 client SHOULD NOT automatically retry a failed automatic retry. 3937 9.2.3. Methods and Caching 3939 For a cache to store and use a response, the associated method needs 3940 to explicitly allow caching, and detail under what conditions a 3941 response can be used to satisfy subsequent requests; a method 3942 definition which does not do so cannot be cached. For additional 3943 requirements see [CACHING]. 3945 This specification defines caching semantics for GET, HEAD, and POST, 3946 although the overwhelming majority of cache implementations only 3947 support GET and HEAD. 3949 9.3. Method Definitions 3951 9.3.1. GET 3953 The GET method requests transfer of a current selected representation 3954 for the target resource. A successful response reflects the quality 3955 of "sameness" identified by the target URI (Section 1.2.2 of [URI]). 3956 Hence, retrieving identifiable information via HTTP is usually 3957 performed by making a GET request on an identifier associated with 3958 the potential for providing that information in a 200 (OK) response. 3960 GET is the primary mechanism of information retrieval and the focus 3961 of almost all performance optimizations. Applications that produce a 3962 URI for each important resource can benefit from those optimizations 3963 while enabling their reuse by other applications, creating a network 3964 effect that promotes further expansion of the Web. 3966 It is tempting to think of resource identifiers as remote file system 3967 pathnames and of representations as being a copy of the contents of 3968 such files. In fact, that is how many resources are implemented (see 3969 Section 17.3 for related security considerations). However, there 3970 are no such limitations in practice. 3972 The HTTP interface for a resource is just as likely to be implemented 3973 as a tree of content objects, a programmatic view on various database 3974 records, or a gateway to other information systems. Even when the 3975 URI mapping mechanism is tied to a file system, an origin server 3976 might be configured to execute the files with the request as input 3977 and send the output as the representation rather than transfer the 3978 files directly. Regardless, only the origin server needs to know how 3979 each resource identifier corresponds to an implementation and how 3980 that implementation manages to select and send a current 3981 representation of the target resource. 3983 A client can alter the semantics of GET to be a "range request", 3984 requesting transfer of only some part(s) of the selected 3985 representation, by sending a Range header field in the request 3986 (Section 14.2). 3988 Although request message framing is independent of the method used, 3989 content received in a GET request has no generally defined semantics, 3990 cannot alter the meaning or target of the request, and might lead 3991 some implementations to reject the request and close the connection 3992 because of its potential as a request smuggling attack (Section 11.2 3993 of [HTTP/1.1]). A client SHOULD NOT generate content in a GET 3994 request unless it is made directly to an origin server that has 3995 previously indicated, in or out of band, that such a request has a 3996 purpose and will be adequately supported. An origin server SHOULD 3997 NOT rely on private agreements to receive content, since participants 3998 in HTTP communication are often unaware of intermediaries along the 3999 request chain. 4001 The response to a GET request is cacheable; a cache MAY use it to 4002 satisfy subsequent GET and HEAD requests unless otherwise indicated 4003 by the Cache-Control header field (Section 5.2 of [CACHING]). 4005 When information retrieval is performed with a mechanism that 4006 constructs a target URI from user-provided information, such as the 4007 query fields of a form using GET, potentially sensitive data might be 4008 provided that would not be appropriate for disclosure within a URI 4009 (see Section 17.9). In some cases, the data can be filtered or 4010 transformed such that it would not reveal such information. In 4011 others, particularly when there is no benefit from caching a 4012 response, using the POST method (Section 9.3.3) instead of GET can 4013 transmit such information in the request content rather than within 4014 the target URI. 4016 9.3.2. HEAD 4018 The HEAD method is identical to GET except that the server MUST NOT 4019 send content in the response. HEAD is used to obtain metadata about 4020 the selected representation without transferring its representation 4021 data, often for the sake of testing hypertext links or finding recent 4022 modifications. 4024 The server SHOULD send the same header fields in response to a HEAD 4025 request as it would have sent if the request method had been GET. 4026 However, a server MAY omit header fields for which a value is 4027 determined only while generating the content. For example, some 4028 servers buffer a dynamic response to GET until a minimum amount of 4029 data is generated so that they can more efficiently delimit small 4030 responses or make late decisions with regard to content selection. 4031 Such a response to GET might contain Content-Length and Vary fields, 4032 for example, that are not generated within a HEAD response. These 4033 minor inconsistencies are considered preferable to generating and 4034 discarding the content for a HEAD request, since HEAD is usually 4035 requested for the sake of efficiency. 4037 Although request message framing is independent of the method used, 4038 content received in a HEAD request has no generally defined 4039 semantics, cannot alter the meaning or target of the request, and 4040 might lead some implementations to reject the request and close the 4041 connection because of its potential as a request smuggling attack 4042 (Section 11.2 of [HTTP/1.1]). A client SHOULD NOT generate content 4043 in a HEAD request unless it is made directly to an origin server that 4044 has previously indicated, in or out of band, that such a request has 4045 a purpose and will be adequately supported. An origin server SHOULD 4046 NOT rely on private agreements to receive content, since participants 4047 in HTTP communication are often unaware of intermediaries along the 4048 request chain. 4050 The response to a HEAD request is cacheable; a cache MAY use it to 4051 satisfy subsequent HEAD requests unless otherwise indicated by the 4052 Cache-Control header field (Section 5.2 of [CACHING]). A HEAD 4053 response might also affect previously cached responses to GET; see 4054 Section 4.3.5 of [CACHING]. 4056 9.3.3. POST 4058 The POST method requests that the target resource process the 4059 representation enclosed in the request according to the resource's 4060 own specific semantics. For example, POST is used for the following 4061 functions (among others): 4063 * Providing a block of data, such as the fields entered into an HTML 4064 form, to a data-handling process; 4066 * Posting a message to a bulletin board, newsgroup, mailing list, 4067 blog, or similar group of articles; 4069 * Creating a new resource that has yet to be identified by the 4070 origin server; and 4072 * Appending data to a resource's existing representation(s). 4074 An origin server indicates response semantics by choosing an 4075 appropriate status code depending on the result of processing the 4076 POST request; almost all of the status codes defined by this 4077 specification could be received in a response to POST (the exceptions 4078 being 206 (Partial Content), 304 (Not Modified), and 416 (Range Not 4079 Satisfiable)). 4081 If one or more resources has been created on the origin server as a 4082 result of successfully processing a POST request, the origin server 4083 SHOULD send a 201 (Created) response containing a Location header 4084 field that provides an identifier for the primary resource created 4085 (Section 10.2.2) and a representation that describes the status of 4086 the request while referring to the new resource(s). 4088 Responses to POST requests are only cacheable when they include 4089 explicit freshness information (see Section 4.2.1 of [CACHING]) and a 4090 Content-Location header field that has the same value as the POST's 4091 target URI (Section 8.7). A cached POST response can be reused to 4092 satisfy a later GET or HEAD request, but not a POST request, since 4093 POST is required to be written through to the origin server, because 4094 it is unsafe; see Section 4 of [CACHING]. 4096 If the result of processing a POST would be equivalent to a 4097 representation of an existing resource, an origin server MAY redirect 4098 the user agent to that resource by sending a 303 (See Other) response 4099 with the existing resource's identifier in the Location field. This 4100 has the benefits of providing the user agent a resource identifier 4101 and transferring the representation via a method more amenable to 4102 shared caching, though at the cost of an extra request if the user 4103 agent does not already have the representation cached. 4105 9.3.4. PUT 4107 The PUT method requests that the state of the target resource be 4108 created or replaced with the state defined by the representation 4109 enclosed in the request message content. A successful PUT of a given 4110 representation would suggest that a subsequent GET on that same 4111 target resource will result in an equivalent representation being 4112 sent in a 200 (OK) response. However, there is no guarantee that 4113 such a state change will be observable, since the target resource 4114 might be acted upon by other user agents in parallel, or might be 4115 subject to dynamic processing by the origin server, before any 4116 subsequent GET is received. A successful response only implies that 4117 the user agent's intent was achieved at the time of its processing by 4118 the origin server. 4120 If the target resource does not have a current representation and the 4121 PUT successfully creates one, then the origin server MUST inform the 4122 user agent by sending a 201 (Created) response. If the target 4123 resource does have a current representation and that representation 4124 is successfully modified in accordance with the state of the enclosed 4125 representation, then the origin server MUST send either a 200 (OK) or 4126 a 204 (No Content) response to indicate successful completion of the 4127 request. 4129 An origin server SHOULD verify that the PUT representation is 4130 consistent with its configured constraints for the target resource. 4131 For example, if an origin server determines a resource's 4132 representation metadata based on the URI, then the origin server 4133 needs to ensure that the content received in a successful PUT request 4134 is consistent with that metadata. When a PUT representation is 4135 inconsistent with the target resource, the origin server SHOULD 4136 either make them consistent, by transforming the representation or 4137 changing the resource configuration, or respond with an appropriate 4138 error message containing sufficient information to explain why the 4139 representation is unsuitable. The 409 (Conflict) or 415 (Unsupported 4140 Media Type) status codes are suggested, with the latter being 4141 specific to constraints on Content-Type values. 4143 For example, if the target resource is configured to always have a 4144 Content-Type of "text/html" and the representation being PUT has a 4145 Content-Type of "image/jpeg", the origin server ought to do one of: 4147 a. reconfigure the target resource to reflect the new media type; 4149 b. transform the PUT representation to a format consistent with that 4150 of the resource before saving it as the new resource state; or, 4152 c. reject the request with a 415 (Unsupported Media Type) response 4153 indicating that the target resource is limited to "text/html", 4154 perhaps including a link to a different resource that would be a 4155 suitable target for the new representation. 4157 HTTP does not define exactly how a PUT method affects the state of an 4158 origin server beyond what can be expressed by the intent of the user 4159 agent request and the semantics of the origin server response. It 4160 does not define what a resource might be, in any sense of that word, 4161 beyond the interface provided via HTTP. It does not define how 4162 resource state is "stored", nor how such storage might change as a 4163 result of a change in resource state, nor how the origin server 4164 translates resource state into representations. Generally speaking, 4165 all implementation details behind the resource interface are 4166 intentionally hidden by the server. 4168 This extends to how header and trailer fields are stored; while 4169 common header fields like Content-Type will typically be stored and 4170 returned upon subsequent GET requests, header and trailer field 4171 handling is specific to the resource that received the request. As a 4172 result, an origin server SHOULD ignore unrecognized header and 4173 trailer fields received in a PUT request (i.e., not save them as part 4174 of the resource state). 4176 An origin server MUST NOT send a validator field (Section 8.8), such 4177 as an ETag or Last-Modified field, in a successful response to PUT 4178 unless the request's representation data was saved without any 4179 transformation applied to the content (i.e., the resource's new 4180 representation data is identical to the content received in the PUT 4181 request) and the validator field value reflects the new 4182 representation. This requirement allows a user agent to know when 4183 the representation it sent (and retains in memory) is the result of 4184 the PUT, and thus doesn't need to be retrieved again from the origin 4185 server. The new validator(s) received in the response can be used 4186 for future conditional requests in order to prevent accidental 4187 overwrites (Section 13.1). 4189 The fundamental difference between the POST and PUT methods is 4190 highlighted by the different intent for the enclosed representation. 4191 The target resource in a POST request is intended to handle the 4192 enclosed representation according to the resource's own semantics, 4193 whereas the enclosed representation in a PUT request is defined as 4194 replacing the state of the target resource. Hence, the intent of PUT 4195 is idempotent and visible to intermediaries, even though the exact 4196 effect is only known by the origin server. 4198 Proper interpretation of a PUT request presumes that the user agent 4199 knows which target resource is desired. A service that selects a 4200 proper URI on behalf of the client, after receiving a state-changing 4201 request, SHOULD be implemented using the POST method rather than PUT. 4202 If the origin server will not make the requested PUT state change to 4203 the target resource and instead wishes to have it applied to a 4204 different resource, such as when the resource has been moved to a 4205 different URI, then the origin server MUST send an appropriate 3xx 4206 (Redirection) response; the user agent MAY then make its own decision 4207 regarding whether or not to redirect the request. 4209 A PUT request applied to the target resource can have side effects on 4210 other resources. For example, an article might have a URI for 4211 identifying "the current version" (a resource) that is separate from 4212 the URIs identifying each particular version (different resources 4213 that at one point shared the same state as the current version 4214 resource). A successful PUT request on "the current version" URI 4215 might therefore create a new version resource in addition to changing 4216 the state of the target resource, and might also cause links to be 4217 added between the related resources. 4219 Some origin servers support use of the Content-Range header field 4220 (Section 14.4) as a request modifier to perform a partial PUT, as 4221 described in Section 14.5. 4223 Responses to the PUT method are not cacheable. If a successful PUT 4224 request passes through a cache that has one or more stored responses 4225 for the target URI, those stored responses will be invalidated (see 4226 Section 4.4 of [CACHING]). 4228 9.3.5. DELETE 4230 The DELETE method requests that the origin server remove the 4231 association between the target resource and its current 4232 functionality. In effect, this method is similar to the "rm" command 4233 in UNIX: it expresses a deletion operation on the URI mapping of the 4234 origin server rather than an expectation that the previously 4235 associated information be deleted. 4237 If the target resource has one or more current representations, they 4238 might or might not be destroyed by the origin server, and the 4239 associated storage might or might not be reclaimed, depending 4240 entirely on the nature of the resource and its implementation by the 4241 origin server (which are beyond the scope of this specification). 4242 Likewise, other implementation aspects of a resource might need to be 4243 deactivated or archived as a result of a DELETE, such as database or 4244 gateway connections. In general, it is assumed that the origin 4245 server will only allow DELETE on resources for which it has a 4246 prescribed mechanism for accomplishing the deletion. 4248 Relatively few resources allow the DELETE method - its primary use is 4249 for remote authoring environments, where the user has some direction 4250 regarding its effect. For example, a resource that was previously 4251 created using a PUT request, or identified via the Location header 4252 field after a 201 (Created) response to a POST request, might allow a 4253 corresponding DELETE request to undo those actions. Similarly, 4254 custom user agent implementations that implement an authoring 4255 function, such as revision control clients using HTTP for remote 4256 operations, might use DELETE based on an assumption that the server's 4257 URI space has been crafted to correspond to a version repository. 4259 If a DELETE method is successfully applied, the origin server SHOULD 4260 send 4262 * a 202 (Accepted) status code if the action will likely succeed but 4263 has not yet been enacted, 4265 * a 204 (No Content) status code if the action has been enacted and 4266 no further information is to be supplied, or 4268 * a 200 (OK) status code if the action has been enacted and the 4269 response message includes a representation describing the status. 4271 Although request message framing is independent of the method used, 4272 content received in a DELETE request has no generally defined 4273 semantics, cannot alter the meaning or target of the request, and 4274 might lead some implementations to reject the request and close the 4275 connection because of its potential as a request smuggling attack 4276 (Section 11.2 of [HTTP/1.1]). A client SHOULD NOT generate content 4277 in a DELETE request unless it is made directly to an origin server 4278 that has previously indicated, in or out of band, that such a request 4279 has a purpose and will be adequately supported. An origin server 4280 SHOULD NOT rely on private agreements to receive content, since 4281 participants in HTTP communication are often unaware of 4282 intermediaries along the request chain. 4284 Responses to the DELETE method are not cacheable. If a successful 4285 DELETE request passes through a cache that has one or more stored 4286 responses for the target URI, those stored responses will be 4287 invalidated (see Section 4.4 of [CACHING]). 4289 9.3.6. CONNECT 4291 The CONNECT method requests that the recipient establish a tunnel to 4292 the destination origin server identified by the request target and, 4293 if successful, thereafter restrict its behavior to blind forwarding 4294 of data, in both directions, until the tunnel is closed. Tunnels are 4295 commonly used to create an end-to-end virtual connection, through one 4296 or more proxies, which can then be secured using TLS (Transport Layer 4297 Security, [TLS13]). 4299 CONNECT uses a special form of request target, unique to this method, 4300 consisting of only the host and port number of the tunnel 4301 destination, separated by a colon. There is no default port; a 4302 client MUST send the port number even if the CONNECT request is based 4303 on a URI reference that contains an authority component with an 4304 elided port (Section 4.1). For example, 4306 CONNECT server.example.com:80 HTTP/1.1 4307 Host: server.example.com 4309 A server MUST reject a CONNECT request that targets an empty or 4310 invalid port number, typically by responding with a 400 (Bad Request) 4311 status code. 4313 Because CONNECT changes the request/response nature of an HTTP 4314 connection, specific HTTP versions might have different ways of 4315 mapping its semantics into the protocol's wire format. 4317 CONNECT is intended for use in requests to a proxy. The recipient 4318 can establish a tunnel either by directly connecting to the server 4319 identified by the request target or, if configured to use another 4320 proxy, by forwarding the CONNECT request to the next inbound proxy. 4321 An origin server MAY accept a CONNECT request, but most origin 4322 servers do not implement CONNECT. 4324 Any 2xx (Successful) response indicates that the sender (and all 4325 inbound proxies) will switch to tunnel mode immediately after the 4326 response header section; data received after that header section is 4327 from the server identified by the request target. Any response other 4328 than a successful response indicates that the tunnel has not yet been 4329 formed. 4331 A tunnel is closed when a tunnel intermediary detects that either 4332 side has closed its connection: the intermediary MUST attempt to send 4333 any outstanding data that came from the closed side to the other 4334 side, close both connections, and then discard any remaining data 4335 left undelivered. 4337 Proxy authentication might be used to establish the authority to 4338 create a tunnel. For example, 4340 CONNECT server.example.com:443 HTTP/1.1 4341 Host: server.example.com:443 4342 Proxy-Authorization: basic aGVsbG86d29ybGQ= 4344 There are significant risks in establishing a tunnel to arbitrary 4345 servers, particularly when the destination is a well-known or 4346 reserved TCP port that is not intended for Web traffic. For example, 4347 a CONNECT to "example.com:25" would suggest that the proxy connect to 4348 the reserved port for SMTP traffic; if allowed, that could trick the 4349 proxy into relaying spam email. Proxies that support CONNECT SHOULD 4350 restrict its use to a limited set of known ports or a configurable 4351 list of safe request targets. 4353 A server MUST NOT send any Transfer-Encoding or Content-Length header 4354 fields in a 2xx (Successful) response to CONNECT. A client MUST 4355 ignore any Content-Length or Transfer-Encoding header fields received 4356 in a successful response to CONNECT. 4358 A CONNECT request message does not have content. The interpretation 4359 of data sent after the header section of the CONNECT request message 4360 is specific to the version of HTTP in use. 4362 Responses to the CONNECT method are not cacheable. 4364 9.3.7. OPTIONS 4366 The OPTIONS method requests information about the communication 4367 options available for the target resource, at either the origin 4368 server or an intervening intermediary. This method allows a client 4369 to determine the options and/or requirements associated with a 4370 resource, or the capabilities of a server, without implying a 4371 resource action. 4373 An OPTIONS request with an asterisk ("*") as the request target 4374 (Section 7.1) applies to the server in general rather than to a 4375 specific resource. Since a server's communication options typically 4376 depend on the resource, the "*" request is only useful as a "ping" or 4377 "no-op" type of method; it does nothing beyond allowing the client to 4378 test the capabilities of the server. For example, this can be used 4379 to test a proxy for HTTP/1.1 conformance (or lack thereof). 4381 If the request target is not an asterisk, the OPTIONS request applies 4382 to the options that are available when communicating with the target 4383 resource. 4385 A server generating a successful response to OPTIONS SHOULD send any 4386 header that might indicate optional features implemented by the 4387 server and applicable to the target resource (e.g., Allow), including 4388 potential extensions not defined by this specification. The response 4389 content, if any, might also describe the communication options in a 4390 machine or human-readable representation. A standard format for such 4391 a representation is not defined by this specification, but might be 4392 defined by future extensions to HTTP. 4394 A client MAY send a Max-Forwards header field in an OPTIONS request 4395 to target a specific recipient in the request chain (see 4396 Section 7.6.2). A proxy MUST NOT generate a Max-Forwards header 4397 field while forwarding a request unless that request was received 4398 with a Max-Forwards field. 4400 A client that generates an OPTIONS request containing content MUST 4401 send a valid Content-Type header field describing the representation 4402 media type. Note that this specification does not define any use for 4403 such content. 4405 Responses to the OPTIONS method are not cacheable. 4407 9.3.8. TRACE 4409 The TRACE method requests a remote, application-level loop-back of 4410 the request message. The final recipient of the request SHOULD 4411 reflect the message received, excluding some fields described below, 4412 back to the client as the content of a 200 (OK) response. The 4413 "message/http" (Section 10.1 of [HTTP/1.1]) format is one way to do 4414 so. The final recipient is either the origin server or the first 4415 server to receive a Max-Forwards value of zero (0) in the request 4416 (Section 7.6.2). 4418 A client MUST NOT generate fields in a TRACE request containing 4419 sensitive data that might be disclosed by the response. For example, 4420 it would be foolish for a user agent to send stored user credentials 4421 (Section 11) or cookies [COOKIE] in a TRACE request. The final 4422 recipient of the request SHOULD exclude any request fields that are 4423 likely to contain sensitive data when that recipient generates the 4424 response content. 4426 TRACE allows the client to see what is being received at the other 4427 end of the request chain and use that data for testing or diagnostic 4428 information. The value of the Via header field (Section 7.6.3) is of 4429 particular interest, since it acts as a trace of the request chain. 4430 Use of the Max-Forwards header field allows the client to limit the 4431 length of the request chain, which is useful for testing a chain of 4432 proxies forwarding messages in an infinite loop. 4434 A client MUST NOT send content in a TRACE request. 4436 Responses to the TRACE method are not cacheable. 4438 10. Message Context 4440 10.1. Request Context Fields 4442 The request header fields below provide additional information about 4443 the request context, including information about the user, user 4444 agent, and resource behind the request. 4446 10.1.1. Expect 4448 The "Expect" header field in a request indicates a certain set of 4449 behaviors (expectations) that need to be supported by the server in 4450 order to properly handle this request. 4452 Expect = #expectation 4453 expectation = token [ "=" ( token / quoted-string ) parameters ] 4455 The Expect field value is case-insensitive. 4457 The only expectation defined by this specification is "100-continue" 4458 (with no defined parameters). 4460 A server that receives an Expect field value containing a member 4461 other than 100-continue MAY respond with a 417 (Expectation Failed) 4462 status code to indicate that the unexpected expectation cannot be 4463 met. 4465 A _100-continue_ expectation informs recipients that the client is 4466 about to send (presumably large) content in this request and wishes 4467 to receive a 100 (Continue) interim response if the method, target 4468 URI, and header fields are not sufficient to cause an immediate 4469 success, redirect, or error response. This allows the client to wait 4470 for an indication that it is worthwhile to send the content before 4471 actually doing so, which can improve efficiency when the data is huge 4472 or when the client anticipates that an error is likely (e.g., when 4473 sending a state-changing method, for the first time, without 4474 previously verified authentication credentials). 4476 For example, a request that begins with 4477 PUT /somewhere/fun HTTP/1.1 4478 Host: origin.example.com 4479 Content-Type: video/h264 4480 Content-Length: 1234567890987 4481 Expect: 100-continue 4483 allows the origin server to immediately respond with an error 4484 message, such as 401 (Unauthorized) or 405 (Method Not Allowed), 4485 before the client starts filling the pipes with an unnecessary data 4486 transfer. 4488 Requirements for clients: 4490 * A client MUST NOT generate a 100-continue expectation in a request 4491 that does not include content. 4493 * A client that will wait for a 100 (Continue) response before 4494 sending the request content MUST send an Expect header field 4495 containing a 100-continue expectation. 4497 * A client that sends a 100-continue expectation is not required to 4498 wait for any specific length of time; such a client MAY proceed to 4499 send the content even if it has not yet received a response. 4500 Furthermore, since 100 (Continue) responses cannot be sent through 4501 an HTTP/1.0 intermediary, such a client SHOULD NOT wait for an 4502 indefinite period before sending the content. 4504 * A client that receives a 417 (Expectation Failed) status code in 4505 response to a request containing a 100-continue expectation SHOULD 4506 repeat that request without a 100-continue expectation, since the 4507 417 response merely indicates that the response chain does not 4508 support expectations (e.g., it passes through an HTTP/1.0 server). 4510 Requirements for servers: 4512 * A server that receives a 100-continue expectation in an HTTP/1.0 4513 request MUST ignore that expectation. 4515 * A server MAY omit sending a 100 (Continue) response if it has 4516 already received some or all of the content for the corresponding 4517 request, or if the framing indicates that there is no content. 4519 * A server that sends a 100 (Continue) response MUST ultimately send 4520 a final status code, once it receives and processes the request 4521 content, unless the connection is closed prematurely. 4523 * A server that responds with a final status code before reading the 4524 entire request content SHOULD indicate whether it intends to close 4525 the connection (e.g., see Section 9.6 of [HTTP/1.1]) or continue 4526 reading the request content. 4528 An origin server MUST, upon receiving an HTTP/1.1 (or later) request 4529 that has a method, target URI, and complete header section that 4530 contains a 100-continue expectation and an indication that request 4531 content will follow, either send an immediate response with a final 4532 status code, if that status can be determined by examining just the 4533 method, target URI, and header fields, or send an immediate 100 4534 (Continue) response to encourage the client to send the request 4535 content. The origin server MUST NOT wait for the content before 4536 sending the 100 (Continue) response. 4538 A proxy MUST, upon receiving an HTTP/1.1 (or later) request that has 4539 a method, target URI, and complete header section that contains a 4540 100-continue expectation and indicates a request content will follow, 4541 either send an immediate response with a final status code, if that 4542 status can be determined by examining just the method, target URI, 4543 and header fields, or begin forwarding the request toward the origin 4544 server by sending a corresponding request-line and header section to 4545 the next inbound server. If the proxy believes (from configuration 4546 or past interaction) that the next inbound server only supports 4547 HTTP/1.0, the proxy MAY generate an immediate 100 (Continue) response 4548 to encourage the client to begin sending the content. 4550 10.1.2. From 4552 The "From" header field contains an Internet email address for a 4553 human user who controls the requesting user agent. The address ought 4554 to be machine-usable, as defined by "mailbox" in Section 3.4 of 4555 [RFC5322]: 4557 From = mailbox 4559 mailbox = 4561 An example is: 4563 From: webmaster@example.org 4565 The From header field is rarely sent by non-robotic user agents. A 4566 user agent SHOULD NOT send a From header field without explicit 4567 configuration by the user, since that might conflict with the user's 4568 privacy interests or their site's security policy. 4570 A robotic user agent SHOULD send a valid From header field so that 4571 the person responsible for running the robot can be contacted if 4572 problems occur on servers, such as if the robot is sending excessive, 4573 unwanted, or invalid requests. 4575 A server SHOULD NOT use the From header field for access control or 4576 authentication, since its value is expected to be visible to anyone 4577 receiving or observing the request and is often recorded within 4578 logfiles and error reports without any expectation of privacy. 4580 10.1.3. Referer 4582 The "Referer" [sic] header field allows the user agent to specify a 4583 URI reference for the resource from which the target URI was obtained 4584 (i.e., the "referrer", though the field name is misspelled). A user 4585 agent MUST NOT include the fragment and userinfo components of the 4586 URI reference [URI], if any, when generating the Referer field value. 4588 Referer = absolute-URI / partial-URI 4590 The field value is either an absolute-URI or a partial-URI. In the 4591 latter case (Section 4), the referenced URI is relative to the target 4592 URI ([URI], Section 5). 4594 The Referer header field allows servers to generate back-links to 4595 other resources for simple analytics, logging, optimized caching, 4596 etc. It also allows obsolete or mistyped links to be found for 4597 maintenance. Some servers use the Referer header field as a means of 4598 denying links from other sites (so-called "deep linking") or 4599 restricting cross-site request forgery (CSRF), but not all requests 4600 contain it. 4602 Example: 4604 Referer: http://www.example.org/hypertext/Overview.html 4606 If the target URI was obtained from a source that does not have its 4607 own URI (e.g., input from the user keyboard, or an entry within the 4608 user's bookmarks/favorites), the user agent MUST either exclude the 4609 Referer header field or send it with a value of "about:blank". 4611 The Referer header field value need not convey the full URI of the 4612 referring resource; a user agent MAY truncate parts other than the 4613 referring origin. 4615 The Referer header field has the potential to reveal information 4616 about the request context or browsing history of the user, which is a 4617 privacy concern if the referring resource's identifier reveals 4618 personal information (such as an account name) or a resource that is 4619 supposed to be confidential (such as behind a firewall or internal to 4620 a secured service). Most general-purpose user agents do not send the 4621 Referer header field when the referring resource is a local "file" or 4622 "data" URI. A user agent SHOULD NOT send a Referer header field if 4623 the referring resource was accessed with a secure protocol and the 4624 request target has an origin differing from that of the referring 4625 resource, unless the referring resource explicitly allows Referer to 4626 be sent. A user agent MUST NOT send a Referer header field in an 4627 unsecured HTTP request if the referring resource was accessed with a 4628 secure protocol. See Section 17.9 for additional security 4629 considerations. 4631 Some intermediaries have been known to indiscriminately remove 4632 Referer header fields from outgoing requests. This has the 4633 unfortunate side effect of interfering with protection against CSRF 4634 attacks, which can be far more harmful to their users. 4635 Intermediaries and user agent extensions that wish to limit 4636 information disclosure in Referer ought to restrict their changes to 4637 specific edits, such as replacing internal domain names with 4638 pseudonyms or truncating the query and/or path components. An 4639 intermediary SHOULD NOT modify or delete the Referer header field 4640 when the field value shares the same scheme and host as the target 4641 URI. 4643 10.1.4. TE 4645 The "TE" header field describes capabilities of the client with 4646 regard to transfer encodings and trailer sections. 4648 A TE field with a "trailers" member sent in a request indicates that 4649 the client will not discard trailer fields, as described in 4650 Section 6.5. 4652 TE is also used within HTTP/1.1 to advise servers about what transfer 4653 codings the client is able to accept in a response. As of 4654 publication, only HTTP/1.1 uses transfer codings (see Section 7 of 4655 [HTTP/1.1]). 4657 The TE field value is a list of members, with each member (aside from 4658 "trailers") consisting of a transfer coding name token with an 4659 optional weight indicating the client's relative preference for that 4660 transfer coding (Section 12.4.2) and optional parameters for that 4661 transfer coding. 4663 TE = #t-codings 4664 t-codings = "trailers" / ( transfer-coding [ weight ] ) 4665 transfer-coding = token *( OWS ";" OWS transfer-parameter ) 4666 transfer-parameter = token BWS "=" BWS ( token / quoted-string ) 4668 A sender of TE MUST also send a "TE" connection option within the 4669 Connection header field (Section 7.6.1) to inform intermediaries not 4670 to forward this field. 4672 10.1.5. User-Agent 4674 The "User-Agent" header field contains information about the user 4675 agent originating the request, which is often used by servers to help 4676 identify the scope of reported interoperability problems, to work 4677 around or tailor responses to avoid particular user agent 4678 limitations, and for analytics regarding browser or operating system 4679 use. A user agent SHOULD send a User-Agent header field in each 4680 request unless specifically configured not to do so. 4682 User-Agent = product *( RWS ( product / comment ) ) 4684 The User-Agent field value consists of one or more product 4685 identifiers, each followed by zero or more comments (Section 5.6.5), 4686 which together identify the user agent software and its significant 4687 subproducts. By convention, the product identifiers are listed in 4688 decreasing order of their significance for identifying the user agent 4689 software. Each product identifier consists of a name and optional 4690 version. 4692 product = token ["/" product-version] 4693 product-version = token 4695 A sender SHOULD limit generated product identifiers to what is 4696 necessary to identify the product; a sender MUST NOT generate 4697 advertising or other nonessential information within the product 4698 identifier. A sender SHOULD NOT generate information in 4699 product-version that is not a version identifier (i.e., successive 4700 versions of the same product name ought to differ only in the 4701 product-version portion of the product identifier). 4703 Example: 4705 User-Agent: CERN-LineMode/2.15 libwww/2.17b3 4706 A user agent SHOULD NOT generate a User-Agent header field containing 4707 needlessly fine-grained detail and SHOULD limit the addition of 4708 subproducts by third parties. Overly long and detailed User-Agent 4709 field values increase request latency and the risk of a user being 4710 identified against their wishes ("fingerprinting"). 4712 Likewise, implementations are encouraged not to use the product 4713 tokens of other implementations in order to declare compatibility 4714 with them, as this circumvents the purpose of the field. If a user 4715 agent masquerades as a different user agent, recipients can assume 4716 that the user intentionally desires to see responses tailored for 4717 that identified user agent, even if they might not work as well for 4718 the actual user agent being used. 4720 10.2. Response Context Fields 4722 The response header fields below provide additional information about 4723 the response, beyond what is implied by the status code, including 4724 information about the server, about the target resource, or about 4725 related resources. 4727 10.2.1. Allow 4729 The "Allow" header field lists the set of methods advertised as 4730 supported by the target resource. The purpose of this field is 4731 strictly to inform the recipient of valid request methods associated 4732 with the resource. 4734 Allow = #method 4736 Example of use: 4738 Allow: GET, HEAD, PUT 4740 The actual set of allowed methods is defined by the origin server at 4741 the time of each request. An origin server MUST generate an Allow 4742 header field in a 405 (Method Not Allowed) response and MAY do so in 4743 any other response. An empty Allow field value indicates that the 4744 resource allows no methods, which might occur in a 405 response if 4745 the resource has been temporarily disabled by configuration. 4747 A proxy MUST NOT modify the Allow header field - it does not need to 4748 understand all of the indicated methods in order to handle them 4749 according to the generic message handling rules. 4751 10.2.2. Location 4753 The "Location" header field is used in some responses to refer to a 4754 specific resource in relation to the response. The type of 4755 relationship is defined by the combination of request method and 4756 status code semantics. 4758 Location = URI-reference 4760 The field value consists of a single URI-reference. When it has the 4761 form of a relative reference ([URI], Section 4.2), the final value is 4762 computed by resolving it against the target URI ([URI], Section 5). 4764 For 201 (Created) responses, the Location value refers to the primary 4765 resource created by the request. For 3xx (Redirection) responses, 4766 the Location value refers to the preferred target resource for 4767 automatically redirecting the request. 4769 If the Location value provided in a 3xx (Redirection) response does 4770 not have a fragment component, a user agent MUST process the 4771 redirection as if the value inherits the fragment component of the 4772 URI reference used to generate the target URI (i.e., the redirection 4773 inherits the original reference's fragment, if any). 4775 For example, a GET request generated for the URI reference 4776 "http://www.example.org/~tim" might result in a 303 (See Other) 4777 response containing the header field: 4779 Location: /People.html#tim 4781 which suggests that the user agent redirect to 4782 "http://www.example.org/People.html#tim" 4784 Likewise, a GET request generated for the URI reference 4785 "http://www.example.org/index.html#larry" might result in a 301 4786 (Moved Permanently) response containing the header field: 4788 Location: http://www.example.net/index.html 4790 which suggests that the user agent redirect to 4791 "http://www.example.net/index.html#larry", preserving the original 4792 fragment identifier. 4794 There are circumstances in which a fragment identifier in a Location 4795 value would not be appropriate. For example, the Location header 4796 field in a 201 (Created) response is supposed to provide a URI that 4797 is specific to the created resource. 4799 | *Note:* Some recipients attempt to recover from Location header 4800 | fields that are not valid URI references. This specification 4801 | does not mandate or define such processing, but does allow it 4802 | for the sake of robustness. A Location field value cannot 4803 | allow a list of members because the comma list separator is a 4804 | valid data character within a URI-reference. If an invalid 4805 | message is sent with multiple Location field lines, a recipient 4806 | along the path might combine those field lines into one value. 4807 | Recovery of a valid Location field value from that situation is 4808 | difficult and not interoperable across implementations. 4810 | *Note:* The Content-Location header field (Section 8.7) differs 4811 | from Location in that the Content-Location refers to the most 4812 | specific resource corresponding to the enclosed representation. 4813 | It is therefore possible for a response to contain both the 4814 | Location and Content-Location header fields. 4816 10.2.3. Retry-After 4818 Servers send the "Retry-After" header field to indicate how long the 4819 user agent ought to wait before making a follow-up request. When 4820 sent with a 503 (Service Unavailable) response, Retry-After indicates 4821 how long the service is expected to be unavailable to the client. 4822 When sent with any 3xx (Redirection) response, Retry-After indicates 4823 the minimum time that the user agent is asked to wait before issuing 4824 the redirected request. 4826 The Retry-After field value can be either an HTTP-date or a number of 4827 seconds to delay after receiving the response. 4829 Retry-After = HTTP-date / delay-seconds 4831 A delay-seconds value is a non-negative decimal integer, representing 4832 time in seconds. 4834 delay-seconds = 1*DIGIT 4836 Two examples of its use are 4838 Retry-After: Fri, 31 Dec 1999 23:59:59 GMT 4839 Retry-After: 120 4841 In the latter example, the delay is 2 minutes. 4843 10.2.4. Server 4845 The "Server" header field contains information about the software 4846 used by the origin server to handle the request, which is often used 4847 by clients to help identify the scope of reported interoperability 4848 problems, to work around or tailor requests to avoid particular 4849 server limitations, and for analytics regarding server or operating 4850 system use. An origin server MAY generate a Server header field in 4851 its responses. 4853 Server = product *( RWS ( product / comment ) ) 4855 The Server header field value consists of one or more product 4856 identifiers, each followed by zero or more comments (Section 5.6.5), 4857 which together identify the origin server software and its 4858 significant subproducts. By convention, the product identifiers are 4859 listed in decreasing order of their significance for identifying the 4860 origin server software. Each product identifier consists of a name 4861 and optional version, as defined in Section 10.1.5. 4863 Example: 4865 Server: CERN/3.0 libwww/2.17 4867 An origin server SHOULD NOT generate a Server header field containing 4868 needlessly fine-grained detail and SHOULD limit the addition of 4869 subproducts by third parties. Overly long and detailed Server field 4870 values increase response latency and potentially reveal internal 4871 implementation details that might make it (slightly) easier for 4872 attackers to find and exploit known security holes. 4874 11. HTTP Authentication 4876 11.1. Authentication Scheme 4878 HTTP provides a general framework for access control and 4879 authentication, via an extensible set of challenge-response 4880 authentication schemes, which can be used by a server to challenge a 4881 client request and by a client to provide authentication information. 4882 It uses a case-insensitive token to identify the authentication 4883 scheme 4885 auth-scheme = token 4887 Aside from the general framework, this document does not specify any 4888 authentication schemes. New and existing authentication schemes are 4889 specified independently and ought to be registered within the 4890 "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry". 4891 For example, the "basic" and "digest" authentication schemes are 4892 defined by RFC 7617 and RFC 7616, respectively. 4894 11.2. Authentication Parameters 4896 The authentication scheme is followed by additional information 4897 necessary for achieving authentication via that scheme as either a 4898 comma-separated list of parameters or a single sequence of characters 4899 capable of holding base64-encoded information. 4901 token68 = 1*( ALPHA / DIGIT / 4902 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 4904 The token68 syntax allows the 66 unreserved URI characters ([URI]), 4905 plus a few others, so that it can hold a base64, base64url (URL and 4906 filename safe alphabet), base32, or base16 (hex) encoding, with or 4907 without padding, but excluding whitespace ([RFC4648]). 4909 Authentication parameters are name=value pairs, where the name token 4910 is matched case-insensitively and each parameter name MUST only occur 4911 once per challenge. 4913 auth-param = token BWS "=" BWS ( token / quoted-string ) 4915 Parameter values can be expressed either as "token" or as "quoted- 4916 string" (Section 5.6). Authentication scheme definitions need to 4917 accept both notations, both for senders and recipients, to allow 4918 recipients to use generic parsing components regardless of the 4919 authentication scheme. 4921 For backwards compatibility, authentication scheme definitions can 4922 restrict the format for senders to one of the two variants. This can 4923 be important when it is known that deployed implementations will fail 4924 when encountering one of the two formats. 4926 11.3. Challenge and Response 4928 A 401 (Unauthorized) response message is used by an origin server to 4929 challenge the authorization of a user agent, including a 4930 WWW-Authenticate header field containing at least one challenge 4931 applicable to the requested resource. 4933 A 407 (Proxy Authentication Required) response message is used by a 4934 proxy to challenge the authorization of a client, including a 4935 Proxy-Authenticate header field containing at least one challenge 4936 applicable to the proxy for the requested resource. 4938 challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ] 4940 | *Note:* Many clients fail to parse a challenge that contains an 4941 | unknown scheme. A workaround for this problem is to list well- 4942 | supported schemes (such as "basic") first. 4944 A user agent that wishes to authenticate itself with an origin server 4945 - usually, but not necessarily, after receiving a 401 (Unauthorized) 4946 - can do so by including an Authorization header field with the 4947 request. 4949 A client that wishes to authenticate itself with a proxy - usually, 4950 but not necessarily, after receiving a 407 (Proxy Authentication 4951 Required) - can do so by including a Proxy-Authorization header field 4952 with the request. 4954 11.4. Credentials 4956 Both the Authorization field value and the Proxy-Authorization field 4957 value contain the client's credentials for the realm of the resource 4958 being requested, based upon a challenge received in a response 4959 (possibly at some point in the past). When creating their values, 4960 the user agent ought to do so by selecting the challenge with what it 4961 considers to be the most secure auth-scheme that it understands, 4962 obtaining credentials from the user as appropriate. Transmission of 4963 credentials within header field values implies significant security 4964 considerations regarding the confidentiality of the underlying 4965 connection, as described in Section 17.16.1. 4967 credentials = auth-scheme [ 1*SP ( token68 / #auth-param ) ] 4969 Upon receipt of a request for a protected resource that omits 4970 credentials, contains invalid credentials (e.g., a bad password) or 4971 partial credentials (e.g., when the authentication scheme requires 4972 more than one round trip), an origin server SHOULD send a 401 4973 (Unauthorized) response that contains a WWW-Authenticate header field 4974 with at least one (possibly new) challenge applicable to the 4975 requested resource. 4977 Likewise, upon receipt of a request that omits proxy credentials or 4978 contains invalid or partial proxy credentials, a proxy that requires 4979 authentication SHOULD generate a 407 (Proxy Authentication Required) 4980 response that contains a Proxy-Authenticate header field with at 4981 least one (possibly new) challenge applicable to the proxy. 4983 A server that receives valid credentials that are not adequate to 4984 gain access ought to respond with the 403 (Forbidden) status code 4985 (Section 15.5.4). 4987 HTTP does not restrict applications to this simple challenge-response 4988 framework for access authentication. Additional mechanisms can be 4989 used, such as authentication at the transport level or via message 4990 encapsulation, and with additional header fields specifying 4991 authentication information. However, such additional mechanisms are 4992 not defined by this specification. 4994 Note that various custom mechanisms for user authentication use the 4995 Set-Cookie and Cookie header fields, defined in [COOKIE], for passing 4996 tokens related to authentication. 4998 11.5. Establishing a Protection Space (Realm) 5000 The _realm_ authentication parameter is reserved for use by 5001 authentication schemes that wish to indicate a scope of protection. 5003 A _protection space_ is defined by the origin (see Section 4.3.1) of 5004 the server being accessed, in combination with the realm value if 5005 present. These realms allow the protected resources on a server to 5006 be partitioned into a set of protection spaces, each with its own 5007 authentication scheme and/or authorization database. The realm value 5008 is a string, generally assigned by the origin server, that can have 5009 additional semantics specific to the authentication scheme. Note 5010 that a response can have multiple challenges with the same auth- 5011 scheme but with different realms. 5013 The protection space determines the domain over which credentials can 5014 be automatically applied. If a prior request has been authorized, 5015 the user agent MAY reuse the same credentials for all other requests 5016 within that protection space for a period of time determined by the 5017 authentication scheme, parameters, and/or user preferences (such as a 5018 configurable inactivity timeout). 5020 The extent of a protection space, and therefore the requests to which 5021 credentials might be automatically applied, is not necessarily known 5022 to clients without additional information. An authentication scheme 5023 might define parameters that describe the extent of a protection 5024 space. Unless specifically allowed by the authentication scheme, a 5025 single protection space cannot extend outside the scope of its 5026 server. 5028 For historical reasons, a sender MUST only generate the quoted-string 5029 syntax. Recipients might have to support both token and quoted- 5030 string syntax for maximum interoperability with existing clients that 5031 have been accepting both notations for a long time. 5033 11.6. Authenticating Users to Origin Servers 5035 11.6.1. WWW-Authenticate 5037 The "WWW-Authenticate" response header field indicates the 5038 authentication scheme(s) and parameters applicable to the target 5039 resource. 5041 WWW-Authenticate = #challenge 5043 A server generating a 401 (Unauthorized) response MUST send a WWW- 5044 Authenticate header field containing at least one challenge. A 5045 server MAY generate a WWW-Authenticate header field in other response 5046 messages to indicate that supplying credentials (or different 5047 credentials) might affect the response. 5049 A proxy forwarding a response MUST NOT modify any WWW-Authenticate 5050 header fields in that response. 5052 User agents are advised to take special care in parsing the field 5053 value, as it might contain more than one challenge, and each 5054 challenge can contain a comma-separated list of authentication 5055 parameters. Furthermore, the header field itself can occur multiple 5056 times. 5058 For instance: 5060 WWW-Authenticate: Basic realm="simple", Newauth realm="apps", 5061 type=1, title="Login to \"apps\"" 5063 This header field contains two challenges; one for the "Basic" scheme 5064 with a realm value of "simple", and another for the "Newauth" scheme 5065 with a realm value of "apps", and two additional parameters "type" 5066 and "title". 5068 Some user agents do not recognise this form, however. As a result, 5069 sending a WWW-Authenticate field value with more than one member on 5070 the same field line might not be interoperable. 5072 | *Note:* The challenge grammar production uses the list syntax 5073 | as well. Therefore, a sequence of comma, whitespace, and comma 5074 | can be considered either as applying to the preceding 5075 | challenge, or to be an empty entry in the list of challenges. 5076 | In practice, this ambiguity does not affect the semantics of 5077 | the header field value and thus is harmless. 5079 11.6.2. Authorization 5081 The "Authorization" header field allows a user agent to authenticate 5082 itself with an origin server - usually, but not necessarily, after 5083 receiving a 401 (Unauthorized) response. Its value consists of 5084 credentials containing the authentication information of the user 5085 agent for the realm of the resource being requested. 5087 Authorization = credentials 5089 If a request is authenticated and a realm specified, the same 5090 credentials are presumed to be valid for all other requests within 5091 this realm (assuming that the authentication scheme itself does not 5092 require otherwise, such as credentials that vary according to a 5093 challenge value or using synchronized clocks). 5095 A proxy forwarding a request MUST NOT modify any Authorization header 5096 fields in that request. See Section 3.5 of [CACHING] for details of 5097 and requirements pertaining to handling of the Authorization header 5098 field by HTTP caches. 5100 11.6.3. Authentication-Info 5102 HTTP authentication schemes can use the Authentication-Info response 5103 field to communicate information after the client's authentication 5104 credentials have been accepted. This information can include a 5105 finalization message from the server (e.g., it can contain the server 5106 authentication). 5108 The field value is a list of parameters (name/value pairs), using the 5109 "auth-param" syntax defined in Section 11.3. This specification only 5110 describes the generic format; authentication schemes using 5111 Authentication-Info will define the individual parameters. The 5112 "Digest" Authentication Scheme, for instance, defines multiple 5113 parameters in Section 3.5 of [RFC7616]. 5115 Authentication-Info = #auth-param 5117 The Authentication-Info field can be used in any HTTP response, 5118 independently of request method and status code. Its semantics are 5119 defined by the authentication scheme indicated by the Authorization 5120 header field (Section 11.6.2) of the corresponding request. 5122 A proxy forwarding a response is not allowed to modify the field 5123 value in any way. 5125 Authentication-Info can be sent as a trailer field (Section 6.5) when 5126 the authentication scheme explicitly allows this. 5128 11.7. Authenticating Clients to Proxies 5130 11.7.1. Proxy-Authenticate 5132 The "Proxy-Authenticate" header field consists of at least one 5133 challenge that indicates the authentication scheme(s) and parameters 5134 applicable to the proxy for this request. A proxy MUST send at least 5135 one Proxy-Authenticate header field in each 407 (Proxy Authentication 5136 Required) response that it generates. 5138 Proxy-Authenticate = #challenge 5140 Unlike WWW-Authenticate, the Proxy-Authenticate header field applies 5141 only to the next outbound client on the response chain. This is 5142 because only the client that chose a given proxy is likely to have 5143 the credentials necessary for authentication. However, when multiple 5144 proxies are used within the same administrative domain, such as 5145 office and regional caching proxies within a large corporate network, 5146 it is common for credentials to be generated by the user agent and 5147 passed through the hierarchy until consumed. Hence, in such a 5148 configuration, it will appear as if Proxy-Authenticate is being 5149 forwarded because each proxy will send the same challenge set. 5151 Note that the parsing considerations for WWW-Authenticate apply to 5152 this header field as well; see Section 11.6.1 for details. 5154 11.7.2. Proxy-Authorization 5156 The "Proxy-Authorization" header field allows the client to identify 5157 itself (or its user) to a proxy that requires authentication. Its 5158 value consists of credentials containing the authentication 5159 information of the client for the proxy and/or realm of the resource 5160 being requested. 5162 Proxy-Authorization = credentials 5164 Unlike Authorization, the Proxy-Authorization header field applies 5165 only to the next inbound proxy that demanded authentication using the 5166 Proxy-Authenticate header field. When multiple proxies are used in a 5167 chain, the Proxy-Authorization header field is consumed by the first 5168 inbound proxy that was expecting to receive credentials. A proxy MAY 5169 relay the credentials from the client request to the next proxy if 5170 that is the mechanism by which the proxies cooperatively authenticate 5171 a given request. 5173 11.7.3. Proxy-Authentication-Info 5175 The Proxy-Authentication-Info response header field is equivalent to 5176 Authentication-Info, except that it applies to proxy authentication 5177 (Section 11.3) and its semantics are defined by the authentication 5178 scheme indicated by the Proxy-Authorization header field 5179 (Section 11.7.2) of the corresponding request: 5181 Proxy-Authentication-Info = #auth-param 5183 However, unlike Authentication-Info, the Proxy-Authentication-Info 5184 header field applies only to the next outbound client on the response 5185 chain. This is because only the client that chose a given proxy is 5186 likely to have the credentials necessary for authentication. 5187 However, when multiple proxies are used within the same 5188 administrative domain, such as office and regional caching proxies 5189 within a large corporate network, it is common for credentials to be 5190 generated by the user agent and passed through the hierarchy until 5191 consumed. Hence, in such a configuration, it will appear as if 5192 Proxy-Authentication-Info is being forwarded because each proxy will 5193 send the same field value. 5195 Proxy-Authentication-Info can be sent as a trailer field 5196 (Section 6.5) when the authentication scheme explicitly allows this. 5198 12. Content Negotiation 5200 When responses convey content, whether indicating a success or an 5201 error, the origin server often has different ways of representing 5202 that information; for example, in different formats, languages, or 5203 encodings. Likewise, different users or user agents might have 5204 differing capabilities, characteristics, or preferences that could 5205 influence which representation, among those available, would be best 5206 to deliver. For this reason, HTTP provides mechanisms for content 5207 negotiation. 5209 This specification defines three patterns of content negotiation that 5210 can be made visible within the protocol: "proactive" negotiation, 5211 where the server selects the representation based upon the user 5212 agent's stated preferences, "reactive" negotiation, where the server 5213 provides a list of representations for the user agent to choose from, 5214 and "request content" negotiation, where the user agent selects the 5215 representation for a future request based upon the server's stated 5216 preferences in past responses. 5218 Other patterns of content negotiation include "conditional content", 5219 where the representation consists of multiple parts that are 5220 selectively rendered based on user agent parameters, "active 5221 content", where the representation contains a script that makes 5222 additional (more specific) requests based on the user agent 5223 characteristics, and "Transparent Content Negotiation" ([RFC2295]), 5224 where content selection is performed by an intermediary. These 5225 patterns are not mutually exclusive, and each has trade-offs in 5226 applicability and practicality. 5228 Note that, in all cases, HTTP is not aware of the resource semantics. 5229 The consistency with which an origin server responds to requests, 5230 over time and over the varying dimensions of content negotiation, and 5231 thus the "sameness" of a resource's observed representations over 5232 time, is determined entirely by whatever entity or algorithm selects 5233 or generates those responses. 5235 12.1. Proactive Negotiation 5237 When content negotiation preferences are sent by the user agent in a 5238 request to encourage an algorithm located at the server to select the 5239 preferred representation, it is called _proactive negotiation_ 5240 (a.k.a., _server-driven negotiation_). Selection is based on the 5241 available representations for a response (the dimensions over which 5242 it might vary, such as language, content coding, etc.) compared to 5243 various information supplied in the request, including both the 5244 explicit negotiation header fields below and implicit 5245 characteristics, such as the client's network address or parts of the 5246 User-Agent field. 5248 Proactive negotiation is advantageous when the algorithm for 5249 selecting from among the available representations is difficult to 5250 describe to a user agent, or when the server desires to send its 5251 "best guess" to the user agent along with the first response (when 5252 that "best guess" is good enough for the user, this avoids the round 5253 trip delay of a subsequent request). In order to improve the 5254 server's guess, a user agent MAY send request header fields that 5255 describe its preferences. 5257 Proactive negotiation has serious disadvantages: 5259 * It is impossible for the server to accurately determine what might 5260 be "best" for any given user, since that would require complete 5261 knowledge of both the capabilities of the user agent and the 5262 intended use for the response (e.g., does the user want to view it 5263 on screen or print it on paper?); 5265 * Having the user agent describe its capabilities in every request 5266 can be both very inefficient (given that only a small percentage 5267 of responses have multiple representations) and a potential risk 5268 to the user's privacy; 5270 * It complicates the implementation of an origin server and the 5271 algorithms for generating responses to a request; and, 5273 * It limits the reusability of responses for shared caching. 5275 A user agent cannot rely on proactive negotiation preferences being 5276 consistently honored, since the origin server might not implement 5277 proactive negotiation for the requested resource or might decide that 5278 sending a response that doesn't conform to the user agent's 5279 preferences is better than sending a 406 (Not Acceptable) response. 5281 A Vary header field (Section 12.5.5) is often sent in a response 5282 subject to proactive negotiation to indicate what parts of the 5283 request information were used in the selection algorithm. 5285 The request header fields Accept, Accept-Charset, Accept-Encoding, 5286 and Accept-Language are defined below for a user agent to engage in 5287 proactive negotiation of the response content. The preferences sent 5288 in these fields apply to any content in the response, including 5289 representations of the target resource, representations of error or 5290 processing status, and potentially even the miscellaneous text 5291 strings that might appear within the protocol. 5293 12.2. Reactive Negotiation 5295 With _reactive negotiation_ (a.k.a., _agent-driven negotiation_), 5296 selection of content (regardless of the status code) is performed by 5297 the user agent after receiving an initial response. The mechanism 5298 for reactive negotiation might be as simple as a list of references 5299 to alternative representations. 5301 If the user agent is not satisfied by the initial response content, 5302 it can perform a GET request on one or more of the alternative 5303 resources to obtain a different representation. Selection of such 5304 alternatives might be performed automatically (by the user agent) or 5305 manually (e.g., by the user selecting from a hypertext menu). 5307 A server might choose not to send an initial representation, other 5308 than the list of alternatives, and thereby indicate that reactive 5309 negotiation by the user agent is preferred. For example, the 5310 alternatives listed in responses with the 300 (Multiple Choices) and 5311 406 (Not Acceptable) status codes include information about available 5312 representations so that the user or user agent can react by making a 5313 selection. 5315 Reactive negotiation is advantageous when the response would vary 5316 over commonly used dimensions (such as type, language, or encoding), 5317 when the origin server is unable to determine a user agent's 5318 capabilities from examining the request, and generally when public 5319 caches are used to distribute server load and reduce network usage. 5321 Reactive negotiation suffers from the disadvantages of transmitting a 5322 list of alternatives to the user agent, which degrades user-perceived 5323 latency if transmitted in the header section, and needing a second 5324 request to obtain an alternate representation. Furthermore, this 5325 specification does not define a mechanism for supporting automatic 5326 selection, though it does not prevent such a mechanism from being 5327 developed as an extension. 5329 12.3. Request Content Negotiation 5331 When content negotiation preferences are sent in a server's response, 5332 the listed preferences are called _request content negotiation_ 5333 because they intend to influence selection of an appropriate content 5334 for subsequent requests to that resource. For example, the Accept 5335 (Section 12.5.1) and Accept-Encoding (Section 12.5.3) header fields 5336 can be sent in a response to indicate preferred media types and 5337 content codings for subsequent requests to that resource. 5339 Similarly, Section 3.1 of [RFC5789] defines the "Accept-Patch" 5340 response header field which allows discovery of which content types 5341 are accepted in PATCH requests. 5343 12.4. Content Negotiation Field Features 5345 12.4.1. Absence 5347 For each of the content negotiation fields, a request that does not 5348 contain the field implies that the sender has no preference on that 5349 dimension of negotiation. 5351 If a content negotiation header field is present in a request and 5352 none of the available representations for the response can be 5353 considered acceptable according to it, the origin server can either 5354 honor the header field by sending a 406 (Not Acceptable) response or 5355 disregard the header field by treating the response as if it is not 5356 subject to content negotiation for that request header field. This 5357 does not imply, however, that the client will be able to use the 5358 representation. 5360 | *Note:* A user agent sending these header fields makes it 5361 | easier for a server to identify an individual by virtue of the 5362 | user agent's request characteristics (Section 17.13). 5364 12.4.2. Quality Values 5366 The content negotiation fields defined by this specification use a 5367 common parameter, named "q" (case-insensitive), to assign a relative 5368 "weight" to the preference for that associated kind of content. This 5369 weight is referred to as a "quality value" (or "qvalue") because the 5370 same parameter name is often used within server configurations to 5371 assign a weight to the relative quality of the various 5372 representations that can be selected for a resource. 5374 The weight is normalized to a real number in the range 0 through 1, 5375 where 0.001 is the least preferred and 1 is the most preferred; a 5376 value of 0 means "not acceptable". If no "q" parameter is present, 5377 the default weight is 1. 5379 weight = OWS ";" OWS "q=" qvalue 5380 qvalue = ( "0" [ "." 0*3DIGIT ] ) 5381 / ( "1" [ "." 0*3("0") ] ) 5383 A sender of qvalue MUST NOT generate more than three digits after the 5384 decimal point. User configuration of these values ought to be 5385 limited in the same fashion. 5387 12.4.3. Wildcard Values 5389 Most of these header fields, where indicated, define a wildcard value 5390 ("*") to select unspecified values. If no wildcard is present, 5391 values that are not explicitly mentioned in the field are considered 5392 unacceptable. Within Vary, the wildcard value means that the 5393 variance is unlimited. 5395 | *Note:* In practice, using wildcards in content negotiation has 5396 | limited practical value, because it is seldom useful to say, 5397 | for example, "I prefer image/* more or less than (some other 5398 | specific value)". Clients can explicitly request a 406 (Not 5399 | Acceptable) response if a more preferred format is not 5400 | available by sending Accept: */*;q=0, but they still need to be 5401 | able to handle a different response, since the server is 5402 | allowed to ignore their preference. 5404 12.5. Content Negotiation Fields 5406 12.5.1. Accept 5408 The "Accept" header field can be used by user agents to specify their 5409 preferences regarding response media types. For example, Accept 5410 header fields can be used to indicate that the request is 5411 specifically limited to a small set of desired types, as in the case 5412 of a request for an in-line image. 5414 When sent by a server in a response, Accept provides information 5415 about what content types are preferred in the content of a subsequent 5416 request to the same resource. 5418 Accept = #( media-range [ weight ] ) 5420 media-range = ( "*/*" 5421 / ( type "/" "*" ) 5422 / ( type "/" subtype ) 5423 ) parameters 5425 The asterisk "*" character is used to group media types into ranges, 5426 with "*/*" indicating all media types and "type/*" indicating all 5427 subtypes of that type. The media-range can include media type 5428 parameters that are applicable to that range. 5430 Each media-range might be followed by optional applicable media type 5431 parameters (e.g., charset), followed by an optional "q" parameter for 5432 indicating a relative weight (Section 12.4.2). 5434 Previous specifications allowed additional extension parameters to 5435 appear after the weight parameter. The accept extension grammar 5436 (accept-params, accept-ext) has been removed because it had a 5437 complicated definition, was not being used in practice, and is more 5438 easily deployed through new header fields. Senders using weights 5439 SHOULD send "q" last (after all media-range parameters). Recipients 5440 SHOULD process any parameter named "q" as weight, regardless of 5441 parameter ordering. 5443 | *Note:* Use of the "q" parameter name to control content 5444 | negotiation is due to historical practice. Although this 5445 | prevents any media type parameter named "q" from being used 5446 | with a media range, such an event is believed to be unlikely 5447 | given the lack of any "q" parameters in the IANA media type 5448 | registry and the rare usage of any media type parameters in 5449 | Accept. Future media types are discouraged from registering 5450 | any parameter named "q". 5452 The example 5454 Accept: audio/*; q=0.2, audio/basic 5456 is interpreted as "I prefer audio/basic, but send me any audio type 5457 if it is the best available after an 80% markdown in quality". 5459 A more elaborate example is 5461 Accept: text/plain; q=0.5, text/html, 5462 text/x-dvi; q=0.8, text/x-c 5464 Verbally, this would be interpreted as "text/html and text/x-c are 5465 the equally preferred media types, but if they do not exist, then 5466 send the text/x-dvi representation, and if that does not exist, send 5467 the text/plain representation". 5469 Media ranges can be overridden by more specific media ranges or 5470 specific media types. If more than one media range applies to a 5471 given type, the most specific reference has precedence. For example, 5473 Accept: text/*, text/plain, text/plain;format=flowed, */* 5475 have the following precedence: 5477 1. text/plain;format=flowed 5479 2. text/plain 5481 3. text/* 5483 4. */* 5485 The media type quality factor associated with a given type is 5486 determined by finding the media range with the highest precedence 5487 that matches the type. For example, 5489 Accept: text/*;q=0.3, text/plain;q=0.7, text/plain;format=flowed, 5490 text/plain;format=fixed;q=0.4, */*;q=0.5 5492 would cause the following values to be associated: 5494 +==========================+===============+ 5495 | Media Type | Quality Value | 5496 +==========================+===============+ 5497 | text/plain;format=flowed | 1 | 5498 +--------------------------+---------------+ 5499 | text/plain | 0.7 | 5500 +--------------------------+---------------+ 5501 | text/html | 0.3 | 5502 +--------------------------+---------------+ 5503 | image/jpeg | 0.5 | 5504 +--------------------------+---------------+ 5505 | text/plain;format=fixed | 0.4 | 5506 +--------------------------+---------------+ 5507 | text/html;level=3 | 0.7 | 5508 +--------------------------+---------------+ 5510 Table 5 5512 | *Note:* A user agent might be provided with a default set of 5513 | quality values for certain media ranges. However, unless the 5514 | user agent is a closed system that cannot interact with other 5515 | rendering agents, this default set ought to be configurable by 5516 | the user. 5518 12.5.2. Accept-Charset 5520 The "Accept-Charset" header field can be sent by a user agent to 5521 indicate its preferences for charsets in textual response content. 5522 For example, this field allows user agents capable of understanding 5523 more comprehensive or special-purpose charsets to signal that 5524 capability to an origin server that is capable of representing 5525 information in those charsets. 5527 Accept-Charset = #( ( token / "*" ) [ weight ] ) 5529 Charset names are defined in Section 8.3.2. A user agent MAY 5530 associate a quality value with each charset to indicate the user's 5531 relative preference for that charset, as defined in Section 12.4.2. 5532 An example is 5534 Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 5536 The special value "*", if present in the Accept-Charset header field, 5537 matches every charset that is not mentioned elsewhere in the field. 5539 | *Note:* Accept-Charset is deprecated because UTF-8 has become 5540 | nearly ubiquitous and sending a detailed list of user-preferred 5541 | charsets wastes bandwidth, increases latency, and makes passive 5542 | fingerprinting far too easy (Section 17.13). Most general- 5543 | purpose user agents do not send Accept-Charset, unless 5544 | specifically configured to do so. 5546 12.5.3. Accept-Encoding 5548 The "Accept-Encoding" header field can be used to indicate 5549 preferences regarding the use of content codings (Section 8.4.1). 5551 When sent by a user agent in a request, Accept-Encoding indicates the 5552 content codings acceptable in a response. 5554 When sent by a server in a response, Accept-Encoding provides 5555 information about what content codings are preferred in the content 5556 of a subsequent request to the same resource. 5558 An "identity" token is used as a synonym for "no encoding" in order 5559 to communicate when no encoding is preferred. 5561 Accept-Encoding = #( codings [ weight ] ) 5562 codings = content-coding / "identity" / "*" 5564 Each codings value MAY be given an associated quality value (weight) 5565 representing the preference for that encoding, as defined in 5566 Section 12.4.2. The asterisk "*" symbol in an Accept-Encoding field 5567 matches any available content coding not explicitly listed in the 5568 field. 5570 Examples: 5572 Accept-Encoding: compress, gzip 5573 Accept-Encoding: 5574 Accept-Encoding: * 5575 Accept-Encoding: compress;q=0.5, gzip;q=1.0 5576 Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 5578 A server tests whether a content coding for a given representation is 5579 acceptable using these rules: 5581 1. If no Accept-Encoding header field is in the request, any content 5582 coding is considered acceptable by the user agent. 5584 2. If the representation has no content coding, then it is 5585 acceptable by default unless specifically excluded by the Accept- 5586 Encoding header field stating either "identity;q=0" or "*;q=0" 5587 without a more specific entry for "identity". 5589 3. If the representation's content coding is one of the content 5590 codings listed in the Accept-Encoding field value, then it is 5591 acceptable unless it is accompanied by a qvalue of 0. (As 5592 defined in Section 12.4.2, a qvalue of 0 means "not acceptable".) 5594 A representation could be encoded with multiple content codings. 5595 However, most content codings are alternative ways to accomplish the 5596 same purpose (e.g., data compression). When selecting between 5597 multiple content codings that have the same purpose, the acceptable 5598 content coding with the highest non-zero qvalue is preferred. 5600 An Accept-Encoding header field with a field value that is empty 5601 implies that the user agent does not want any content coding in 5602 response. If an Accept-Encoding header field is present in a request 5603 and none of the available representations for the response have a 5604 content coding that is listed as acceptable, the origin server SHOULD 5605 send a response without any content coding. 5607 When the Accept-Encoding header field is present in a response, it 5608 indicates what content codings the resource was willing to accept in 5609 the associated request. The field value is evaluated the same way as 5610 in a request. 5612 Note that this information is specific to the associated request; the 5613 set of supported encodings might be different for other resources on 5614 the same server and could change over time or depend on other aspects 5615 of the request (such as the request method). 5617 Servers that fail a request due to an unsupported content coding 5618 ought to respond with a 415 (Unsupported Media Type) status and 5619 include an Accept-Encoding header field in that response, allowing 5620 clients to distinguish between issues related to content codings and 5621 media types. In order to avoid confusion with issues related to 5622 media types, servers that fail a request with a 415 status for 5623 reasons unrelated to content codings MUST NOT include the Accept- 5624 Encoding header field. 5626 The most common use of Accept-Encoding is in responses with a 415 5627 (Unsupported Media Type) status code, in response to optimistic use 5628 of a content coding by clients. However, the header field can also 5629 be used to indicate to clients that content codings are supported, to 5630 optimize future interactions. For example, a resource might include 5631 it in a 2xx (Successful) response when the request content was big 5632 enough to justify use of a compression coding but the client failed 5633 do so. 5635 12.5.4. Accept-Language 5637 The "Accept-Language" header field can be used by user agents to 5638 indicate the set of natural languages that are preferred in the 5639 response. Language tags are defined in Section 8.5.1. 5641 Accept-Language = #( language-range [ weight ] ) 5642 language-range = 5643 5645 Each language-range can be given an associated quality value 5646 representing an estimate of the user's preference for the languages 5647 specified by that range, as defined in Section 12.4.2. For example, 5649 Accept-Language: da, en-gb;q=0.8, en;q=0.7 5651 would mean: "I prefer Danish, but will accept British English and 5652 other types of English". 5654 Note that some recipients treat the order in which language tags are 5655 listed as an indication of descending priority, particularly for tags 5656 that are assigned equal quality values (no value is the same as q=1). 5657 However, this behavior cannot be relied upon. For consistency and to 5658 maximize interoperability, many user agents assign each language tag 5659 a unique quality value while also listing them in order of decreasing 5660 quality. Additional discussion of language priority lists can be 5661 found in Section 2.3 of [RFC4647]. 5663 For matching, Section 3 of [RFC4647] defines several matching 5664 schemes. Implementations can offer the most appropriate matching 5665 scheme for their requirements. The "Basic Filtering" scheme 5666 ([RFC4647], Section 3.3.1) is identical to the matching scheme that 5667 was previously defined for HTTP in Section 14.4 of [RFC2616]. 5669 It might be contrary to the privacy expectations of the user to send 5670 an Accept-Language header field with the complete linguistic 5671 preferences of the user in every request (Section 17.13). 5673 Since intelligibility is highly dependent on the individual user, 5674 user agents need to allow user control over the linguistic preference 5675 (either through configuration of the user agent itself or by 5676 defaulting to a user controllable system setting). A user agent that 5677 does not provide such control to the user MUST NOT send an Accept- 5678 Language header field. 5680 | *Note:* User agents ought to provide guidance to users when 5681 | setting a preference, since users are rarely familiar with the 5682 | details of language matching as described above. For example, 5683 | users might assume that on selecting "en-gb", they will be 5684 | served any kind of English document if British English is not 5685 | available. A user agent might suggest, in such a case, to add 5686 | "en" to the list for better matching behavior. 5688 12.5.5. Vary 5690 The "Vary" header field in a response describes what parts of a 5691 request message, aside from the method and target URI, might have 5692 influenced the origin server's process for selecting the content of 5693 this response. 5695 Vary = #( "*" / field-name ) 5697 A Vary field value is either the wildcard member "*" or a list of 5698 request field names, known as the selecting header fields, that might 5699 have had a role in selecting the representation for this response. 5700 Potential selecting header fields are not limited to fields defined 5701 by this specification. 5703 A list containing the member "*" signals that other aspects of the 5704 request might have played a role in selecting the response 5705 representation, possibly including aspects outside the message syntax 5706 (e.g., the client's network address). A recipient will not be able 5707 to determine whether this response is appropriate for a later request 5708 without forwarding the request to the origin server. A proxy MUST 5709 NOT generate "*" in a Vary field value. 5711 For example, a response that contains 5713 Vary: accept-encoding, accept-language 5715 indicates that the origin server might have used the request's 5716 Accept-Encoding and Accept-Language header fields (or lack thereof) 5717 as determining factors while choosing the content for this response. 5719 A Vary field containing a list of field names has two purposes: 5721 1. To inform cache recipients that they MUST NOT use this response 5722 to satisfy a later request unless the later request has the same 5723 values for the listed header fields as the original request 5724 (Section 4.1 of [CACHING]) or reuse of the response has been 5725 validated by the origin server. In other words, Vary expands the 5726 cache key required to match a new request to the stored cache 5727 entry. 5729 2. To inform user agent recipients that this response was subject to 5730 content negotiation (Section 12) and a different representation 5731 might be sent in a subsequent request if other values are 5732 provided in the listed header fields (proactive negotiation). 5734 An origin server SHOULD generate a Vary header field on a cacheable 5735 response when it wishes that response to be selectively reused for 5736 subsequent requests. Generally, that is the case when the response 5737 content has been tailored to better fit the preferences expressed by 5738 those selecting header fields, such as when an origin server has 5739 selected the response's language based on the request's 5740 Accept-Language header field. 5742 Vary might be elided when an origin server considers variance in 5743 content selection to be less significant than Vary's performance 5744 impact on caching, particularly when reuse is already limited by 5745 Cache-Control response directives (Section 5.2 of [CACHING]). 5747 There is no need to send the Authorization field name in Vary because 5748 reuse of that response for a different user is prohibited by the 5749 field definition (Section 11.6.2). Likewise, if the response content 5750 has been selected or influenced by network region but the origin 5751 server wants the cached response to be reused even if recipients move 5752 from one region to another, then there is no need for the origin 5753 server to indicate such variance in Vary. 5755 13. Conditional Requests 5757 A conditional request is an HTTP request with one or more request 5758 header fields that indicate a precondition to be tested before 5759 applying the request method to the target resource. Section 13.2 5760 defines when to evaluate preconditions and their order of precedence 5761 when more than one precondition is present. 5763 Conditional GET requests are the most efficient mechanism for HTTP 5764 cache updates [CACHING]. Conditionals can also be applied to state- 5765 changing methods, such as PUT and DELETE, to prevent the "lost 5766 update" problem: one client accidentally overwriting the work of 5767 another client that has been acting in parallel. 5769 13.1. Preconditions 5771 Preconditions are usually defined with respect to a state of the 5772 target resource as a whole (its current value set) or the state as 5773 observed in a previously obtained representation (one value in that 5774 set). If a resource has multiple current representations, each with 5775 its own observable state, a precondition will assume that the mapping 5776 of each request to a selected representation (Section 3.2) is 5777 consistent over time. Regardless, if the mapping is inconsistent or 5778 the server is unable to select an appropriate representation, then no 5779 harm will result when the precondition evaluates to false. 5781 Each precondition defined below consists of a comparison between a 5782 set of validators obtained from prior representations of the target 5783 resource to the current state of validators for the selected 5784 representation (Section 8.8). Hence, these preconditions evaluate 5785 whether the state of the target resource has changed since a given 5786 state known by the client. The effect of such an evaluation depends 5787 on the method semantics and choice of conditional, as defined in 5788 Section 13.2. 5790 Other preconditions, defined by other specifications as extension 5791 fields, might place conditions on all recipients, on the state of the 5792 target resource in general, or on a group of resources. For 5793 instance, the "If" header field in WebDAV can make a request 5794 conditional on various aspects of multiple resources, such as locks, 5795 if the recipient understands and implements that field ([WEBDAV], 5796 Section 10.4). 5798 Extensibility of preconditions is only possible when the precondition 5799 can be safely ignored if unknown (like If-Modified-Since), when 5800 deployment can be assumed for a given use case, or when 5801 implementation is signaled by some other property of the target 5802 resource. This encourages a focus on mutually agreed deployment of 5803 common standards. 5805 13.1.1. If-Match 5807 The "If-Match" header field makes the request method conditional on 5808 the recipient origin server either having at least one current 5809 representation of the target resource, when the field value is "*", 5810 or having a current representation of the target resource that has an 5811 entity-tag matching a member of the list of entity-tags provided in 5812 the field value. 5814 An origin server MUST use the strong comparison function when 5815 comparing entity-tags for If-Match (Section 8.8.3.2), since the 5816 client intends this precondition to prevent the method from being 5817 applied if there have been any changes to the representation data. 5819 If-Match = "*" / #entity-tag 5821 Examples: 5823 If-Match: "xyzzy" 5824 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 5825 If-Match: * 5827 If-Match is most often used with state-changing methods (e.g., POST, 5828 PUT, DELETE) to prevent accidental overwrites when multiple user 5829 agents might be acting in parallel on the same resource (i.e., to 5830 prevent the "lost update" problem). In general, it can be used with 5831 any method that involves the selection or modification of a 5832 representation to abort the request if the selected representation's 5833 current entity-tag is not a member within the If-Match field value. 5835 When an origin server receives a request that selects a 5836 representation and that request includes an If-Match header field, 5837 the origin server MUST evaluate the If-Match condition as per 5838 Section 13.2 prior to performing the method. 5840 To evaluate a received If-Match header field: 5842 1. If the field value is "*", the condition is true if the origin 5843 server has a current representation for the target resource. 5845 2. If the field value is a list of entity-tags, the condition is 5846 true if any of the listed tags match the entity-tag of the 5847 selected representation. 5849 3. Otherwise, the condition is false. 5851 An origin server that evaluates an If-Match condition MUST NOT 5852 perform the requested method if the condition evaluates to false. 5853 Instead, the origin server MAY indicate that the conditional request 5854 failed by responding with a 412 (Precondition Failed) status code. 5855 Alternatively, if the request is a state-changing operation that 5856 appears to have already been applied to the selected representation, 5857 the origin server MAY respond with a 2xx (Successful) status code 5858 (i.e., the change requested by the user agent has already succeeded, 5859 but the user agent might not be aware of it, perhaps because the 5860 prior response was lost or an equivalent change was made by some 5861 other user agent). 5863 Allowing an origin server to send a success response when a change 5864 request appears to have already been applied is more efficient for 5865 many authoring use cases, but comes with some risk if multiple user 5866 agents are making change requests that are very similar but not 5867 cooperative. For example, multiple user agents writing to a common 5868 resource as a semaphore (e.g., a non-atomic increment) are likely to 5869 collide and potentially lose important state transitions. For those 5870 kinds of resources, an origin server is better off being stringent in 5871 sending 412 for every failed precondition on an unsafe method. In 5872 other cases, excluding the ETag field from a success response might 5873 encourage the user agent to perform a GET as its next request to 5874 eliminate confusion about the resource's current state. 5876 A client MAY send an If-Match header field in a GET request to 5877 indicate that it would prefer a 412 (Precondition Failed) response if 5878 the selected representation does not match. However, this is only 5879 useful in range requests (Section 14), for completing a previously 5880 received partial representation, when there is no desire for a new 5881 representation. If-Range (Section 13.1.5) is better suited for range 5882 requests when the client prefers to receive a new representation. 5884 A cache or intermediary MAY ignore If-Match because its 5885 interoperability features are only necessary for an origin server. 5887 Note that an If-Match header field with a list value containing "*" 5888 and other values (including other instances of "*") is syntactically 5889 invalid (therefore not allowed to be generated) and furthermore is 5890 unlikely to be interoperable. 5892 13.1.2. If-None-Match 5894 The "If-None-Match" header field makes the request method conditional 5895 on a recipient cache or origin server either not having any current 5896 representation of the target resource, when the field value is "*", 5897 or having a selected representation with an entity-tag that does not 5898 match any of those listed in the field value. 5900 A recipient MUST use the weak comparison function when comparing 5901 entity-tags for If-None-Match (Section 8.8.3.2), since weak entity- 5902 tags can be used for cache validation even if there have been changes 5903 to the representation data. 5905 If-None-Match = "*" / #entity-tag 5907 Examples: 5909 If-None-Match: "xyzzy" 5910 If-None-Match: W/"xyzzy" 5911 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 5912 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 5913 If-None-Match: * 5915 If-None-Match is primarily used in conditional GET requests to enable 5916 efficient updates of cached information with a minimum amount of 5917 transaction overhead. When a client desires to update one or more 5918 stored responses that have entity-tags, the client SHOULD generate an 5919 If-None-Match header field containing a list of those entity-tags 5920 when making a GET request; this allows recipient servers to send a 5921 304 (Not Modified) response to indicate when one of those stored 5922 responses matches the selected representation. 5924 If-None-Match can also be used with a value of "*" to prevent an 5925 unsafe request method (e.g., PUT) from inadvertently modifying an 5926 existing representation of the target resource when the client 5927 believes that the resource does not have a current representation 5928 (Section 9.2.1). This is a variation on the "lost update" problem 5929 that might arise if more than one client attempts to create an 5930 initial representation for the target resource. 5932 When an origin server receives a request that selects a 5933 representation and that request includes an If-None-Match header 5934 field, the origin server MUST evaluate the If-None-Match condition as 5935 per Section 13.2 prior to performing the method. 5937 To evaluate a received If-None-Match header field: 5939 1. If the field value is "*", the condition is false if the origin 5940 server has a current representation for the target resource. 5942 2. If the field value is a list of entity-tags, the condition is 5943 false if one of the listed tags matches the entity-tag of the 5944 selected representation. 5946 3. Otherwise, the condition is true. 5948 An origin server that evaluates an If-None-Match condition MUST NOT 5949 perform the requested method if the condition evaluates to false; 5950 instead, the origin server MUST respond with either a) the 304 (Not 5951 Modified) status code if the request method is GET or HEAD or b) the 5952 412 (Precondition Failed) status code for all other request methods. 5954 Requirements on cache handling of a received If-None-Match header 5955 field are defined in Section 4.3.2 of [CACHING]. 5957 Note that an If-None-Match header field with a list value containing 5958 "*" and other values (including other instances of "*") is 5959 syntactically invalid (therefore not allowed to be generated) and 5960 furthermore is unlikely to be interoperable. 5962 13.1.3. If-Modified-Since 5964 The "If-Modified-Since" header field makes a GET or HEAD request 5965 method conditional on the selected representation's modification date 5966 being more recent than the date provided in the field value. 5967 Transfer of the selected representation's data is avoided if that 5968 data has not changed. 5970 If-Modified-Since = HTTP-date 5972 An example of the field is: 5974 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 5976 A recipient MUST ignore If-Modified-Since if the request contains an 5977 If-None-Match header field; the condition in If-None-Match is 5978 considered to be a more accurate replacement for the condition in If- 5979 Modified-Since, and the two are only combined for the sake of 5980 interoperating with older intermediaries that might not implement 5981 If-None-Match. 5983 A recipient MUST ignore the If-Modified-Since header field if the 5984 received field value is not a valid HTTP-date, the field value has 5985 more than one member, or if the request method is neither GET nor 5986 HEAD. 5988 A recipient MUST ignore the If-Modified-Since header field if the 5989 resource does not have a modification date available. 5991 A recipient MUST interpret an If-Modified-Since field value's 5992 timestamp in terms of the origin server's clock. 5994 If-Modified-Since is typically used for two distinct purposes: 1) to 5995 allow efficient updates of a cached representation that does not have 5996 an entity-tag and 2) to limit the scope of a web traversal to 5997 resources that have recently changed. 5999 When used for cache updates, a cache will typically use the value of 6000 the cached message's Last-Modified header field to generate the field 6001 value of If-Modified-Since. This behavior is most interoperable for 6002 cases where clocks are poorly synchronized or when the server has 6003 chosen to only honor exact timestamp matches (due to a problem with 6004 Last-Modified dates that appear to go "back in time" when the origin 6005 server's clock is corrected or a representation is restored from an 6006 archived backup). However, caches occasionally generate the field 6007 value based on other data, such as the Date header field of the 6008 cached message or the clock time at which the message was received, 6009 particularly when the cached message does not contain a Last-Modified 6010 header field. 6012 When used for limiting the scope of retrieval to a recent time 6013 window, a user agent will generate an If-Modified-Since field value 6014 based on either its own clock or a Date header field received from 6015 the server in a prior response. Origin servers that choose an exact 6016 timestamp match based on the selected representation's Last-Modified 6017 header field will not be able to help the user agent limit its data 6018 transfers to only those changed during the specified window. 6020 When an origin server receives a request that selects a 6021 representation and that request includes an If-Modified-Since header 6022 field without an If-None-Match header field, the origin server SHOULD 6023 evaluate the If-Modified-Since condition as per Section 13.2 prior to 6024 performing the method. 6026 To evaluate a received If-Modified-Since header field: 6028 1. If the selected representation's last modification date is 6029 earlier or equal to the date provided in the field value, the 6030 condition is false. 6032 2. Otherwise, the condition is true. 6034 An origin server that evaluates an If-Modified-Since condition SHOULD 6035 NOT perform the requested method if the condition evaluates to false; 6036 instead, the origin server SHOULD generate a 304 (Not Modified) 6037 response, including only those metadata that are useful for 6038 identifying or updating a previously cached response. 6040 Requirements on cache handling of a received If-Modified-Since header 6041 field are defined in Section 4.3.2 of [CACHING]. 6043 13.1.4. If-Unmodified-Since 6045 The "If-Unmodified-Since" header field makes the request method 6046 conditional on the selected representation's last modification date 6047 being earlier than or equal to the date provided in the field value. 6048 This field accomplishes the same purpose as If-Match for cases where 6049 the user agent does not have an entity-tag for the representation. 6051 If-Unmodified-Since = HTTP-date 6053 An example of the field is: 6055 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 6057 A recipient MUST ignore If-Unmodified-Since if the request contains 6058 an If-Match header field; the condition in If-Match is considered to 6059 be a more accurate replacement for the condition in If-Unmodified- 6060 Since, and the two are only combined for the sake of interoperating 6061 with older intermediaries that might not implement If-Match. 6063 A recipient MUST ignore the If-Unmodified-Since header field if the 6064 received field value is not a valid HTTP-date (including when the 6065 field value appears to be a list of dates). 6067 A recipient MUST ignore the If-Unmodified-Since header field if the 6068 resource does not have a modification date available. 6070 A recipient MUST interpret an If-Unmodified-Since field value's 6071 timestamp in terms of the origin server's clock. 6073 If-Unmodified-Since is most often used with state-changing methods 6074 (e.g., POST, PUT, DELETE) to prevent accidental overwrites when 6075 multiple user agents might be acting in parallel on a resource that 6076 does not supply entity-tags with its representations (i.e., to 6077 prevent the "lost update" problem). In general, it can be used with 6078 any method that involves the selection or modification of a 6079 representation to abort the request if the selected representation's 6080 last modification date has changed since the date provided in the If- 6081 Unmodified-Since field value. 6083 When an origin server receives a request that selects a 6084 representation and that request includes an If-Unmodified-Since 6085 header field without an If-Match header field, the origin server MUST 6086 evaluate the If-Unmodified-Since condition as per Section 13.2 prior 6087 to performing the method. 6089 To evaluate a received If-Unmodified-Since header field: 6091 1. If the selected representation's last modification date is 6092 earlier than or equal to the date provided in the field value, 6093 the condition is true. 6095 2. Otherwise, the condition is false. 6097 An origin server that evaluates an If-Unmodified-Since condition MUST 6098 NOT perform the requested method if the condition evaluates to false. 6099 Instead, the origin server MAY indicate that the conditional request 6100 failed by responding with a 412 (Precondition Failed) status code. 6101 Alternatively, if the request is a state-changing operation that 6102 appears to have already been applied to the selected representation, 6103 the origin server MAY respond with a 2xx (Successful) status code 6104 (i.e., the change requested by the user agent has already succeeded, 6105 but the user agent might not be aware of it, perhaps because the 6106 prior response was lost or an equivalent change was made by some 6107 other user agent). 6109 Allowing an origin server to send a success response when a change 6110 request appears to have already been applied is more efficient for 6111 many authoring use cases, but comes with some risk if multiple user 6112 agents are making change requests that are very similar but not 6113 cooperative. In those cases, an origin server is better off being 6114 stringent in sending 412 for every failed precondition on an unsafe 6115 method. 6117 A client MAY send an If-Unmodified-Since header field in a GET 6118 request to indicate that it would prefer a 412 (Precondition Failed) 6119 response if the selected representation has been modified. However, 6120 this is only useful in range requests (Section 14), for completing a 6121 previously received partial representation, when there is no desire 6122 for a new representation. If-Range (Section 13.1.5) is better suited 6123 for range requests when the client prefers to receive a new 6124 representation. 6126 A cache or intermediary MAY ignore If-Unmodified-Since because its 6127 interoperability features are only necessary for an origin server. 6129 13.1.5. If-Range 6131 The "If-Range" header field provides a special conditional request 6132 mechanism that is similar to the If-Match and If-Unmodified-Since 6133 header fields but that instructs the recipient to ignore the Range 6134 header field if the validator doesn't match, resulting in transfer of 6135 the new selected representation instead of a 412 (Precondition 6136 Failed) response. 6138 If a client has a partial copy of a representation and wishes to have 6139 an up-to-date copy of the entire representation, it could use the 6140 Range header field with a conditional GET (using either or both of 6141 If-Unmodified-Since and If-Match.) However, if the precondition 6142 fails because the representation has been modified, the client would 6143 then have to make a second request to obtain the entire current 6144 representation. 6146 The "If-Range" header field allows a client to "short-circuit" the 6147 second request. Informally, its meaning is as follows: if the 6148 representation is unchanged, send me the part(s) that I am requesting 6149 in Range; otherwise, send me the entire representation. 6151 If-Range = entity-tag / HTTP-date 6153 A valid entity-tag can be distinguished from a valid HTTP-date by 6154 examining the first three characters for a DQUOTE. 6156 A client MUST NOT generate an If-Range header field in a request that 6157 does not contain a Range header field. A server MUST ignore an If- 6158 Range header field received in a request that does not contain a 6159 Range header field. An origin server MUST ignore an If-Range header 6160 field received in a request for a target resource that does not 6161 support Range requests. 6163 A client MUST NOT generate an If-Range header field containing an 6164 entity-tag that is marked as weak. A client MUST NOT generate an If- 6165 Range header field containing an HTTP-date unless the client has no 6166 entity-tag for the corresponding representation and the date is a 6167 strong validator in the sense defined by Section 8.8.2.2. 6169 A server that receives an If-Range header field on a Range request 6170 MUST evaluate the condition as per Section 13.2 prior to performing 6171 the method. 6173 To evaluate a received If-Range header field containing an HTTP-date: 6175 1. If the HTTP-date validator provided is not a strong validator in 6176 the sense defined by Section 8.8.2.2, the condition is false. 6178 2. If the HTTP-date validator provided exactly matches the 6179 Last-Modified field value for the selected representation, the 6180 condition is true. 6182 3. Otherwise, the condition is false. 6184 To evaluate a received If-Range header field containing an 6185 entity-tag: 6187 1. If the entity-tag validator provided exactly matches the ETag 6188 field value for the selected representation using the strong 6189 comparison function (Section 8.8.3.2), the condition is true. 6191 2. Otherwise, the condition is false. 6193 A recipient of an If-Range header field MUST ignore the Range header 6194 field if the If-Range condition evaluates to false. Otherwise, the 6195 recipient SHOULD process the Range header field as requested. 6197 Note that the If-Range comparison is by exact match, including when 6198 the validator is an HTTP-date, and so differs from the "earlier than 6199 or equal to" comparison used when evaluating an If-Unmodified-Since 6200 conditional. 6202 13.2. Evaluation of Preconditions 6204 13.2.1. When to Evaluate 6206 Except when excluded below, a recipient cache or origin server MUST 6207 evaluate received request preconditions after it has successfully 6208 performed its normal request checks and just before it would process 6209 the request content (if any) or perform the action associated with 6210 the request method. A server MUST ignore all received preconditions 6211 if its response to the same request without those conditions, prior 6212 to processing the request content, would have been a status code 6213 other than a 2xx (Successful) or 412 (Precondition Failed). In other 6214 words, redirects and failures that can be detected before significant 6215 processing occurs take precedence over the evaluation of 6216 preconditions. 6218 A server that is not the origin server for the target resource and 6219 cannot act as a cache for requests on the target resource MUST NOT 6220 evaluate the conditional request header fields defined by this 6221 specification, and it MUST forward them if the request is forwarded, 6222 since the generating client intends that they be evaluated by a 6223 server that can provide a current representation. Likewise, a server 6224 MUST ignore the conditional request header fields defined by this 6225 specification when received with a request method that does not 6226 involve the selection or modification of a selected representation, 6227 such as CONNECT, OPTIONS, or TRACE. 6229 Note that protocol extensions can modify the conditions under which 6230 preconditions are evaluated or the consequences of their evaluation. 6231 For example, the "immutable" cache directive (defined by [RFC8246]) 6232 instructs caches to forgo forwarding conditional requests when they 6233 hold a fresh response. 6235 Although conditional request header fields are defined as being 6236 usable with the HEAD method (to keep HEAD's semantics consistent with 6237 those of GET), there is no point in sending a conditional HEAD 6238 because a successful response is around the same size as a 304 (Not 6239 Modified) response and more useful than a 412 (Precondition Failed) 6240 response. 6242 13.2.2. Precedence of Preconditions 6244 When more than one conditional request header field is present in a 6245 request, the order in which the fields are evaluated becomes 6246 important. In practice, the fields defined in this document are 6247 consistently implemented in a single, logical order, since "lost 6248 update" preconditions have more strict requirements than cache 6249 validation, a validated cache is more efficient than a partial 6250 response, and entity tags are presumed to be more accurate than date 6251 validators. 6253 A recipient cache or origin server MUST evaluate the request 6254 preconditions defined by this specification in the following order: 6256 1. When recipient is the origin server and If-Match is present, 6257 evaluate the If-Match precondition: 6259 * if true, continue to step 3 6261 * if false, respond 412 (Precondition Failed) unless it can be 6262 determined that the state-changing request has already 6263 succeeded (see Section 13.1.1) 6265 2. When recipient is the origin server, If-Match is not present, and 6266 If-Unmodified-Since is present, evaluate the If-Unmodified-Since 6267 precondition: 6269 * if true, continue to step 3 6271 * if false, respond 412 (Precondition Failed) unless it can be 6272 determined that the state-changing request has already 6273 succeeded (see Section 13.1.4) 6275 3. When If-None-Match is present, evaluate the If-None-Match 6276 precondition: 6278 * if true, continue to step 5 6280 * if false for GET/HEAD, respond 304 (Not Modified) 6282 * if false for other methods, respond 412 (Precondition Failed) 6284 4. When the method is GET or HEAD, If-None-Match is not present, and 6285 If-Modified-Since is present, evaluate the If-Modified-Since 6286 precondition: 6288 * if true, continue to step 5 6290 * if false, respond 304 (Not Modified) 6292 5. When the method is GET and both Range and If-Range are present, 6293 evaluate the If-Range precondition: 6295 * if true and the Range is applicable to the selected 6296 representation, respond 206 (Partial Content) 6298 * otherwise, ignore the Range header field and respond 200 (OK) 6300 6. Otherwise, 6302 * perform the requested method and respond according to its 6303 success or failure. 6305 Any extension to HTTP that defines additional conditional request 6306 header fields ought to define the order for evaluating such fields in 6307 relation to those defined in this document and other conditionals 6308 that might be found in practice. 6310 14. Range Requests 6312 Clients often encounter interrupted data transfers as a result of 6313 canceled requests or dropped connections. When a client has stored a 6314 partial representation, it is desirable to request the remainder of 6315 that representation in a subsequent request rather than transfer the 6316 entire representation. Likewise, devices with limited local storage 6317 might benefit from being able to request only a subset of a larger 6318 representation, such as a single page of a very large document, or 6319 the dimensions of an embedded image. 6321 Range requests are an OPTIONAL feature of HTTP, designed so that 6322 recipients not implementing this feature (or not supporting it for 6323 the target resource) can respond as if it is a normal GET request 6324 without impacting interoperability. Partial responses are indicated 6325 by a distinct status code to not be mistaken for full responses by 6326 caches that might not implement the feature. 6328 14.1. Range Units 6330 Representation data can be partitioned into subranges when there are 6331 addressable structural units inherent to that data's content coding 6332 or media type. For example, octet (a.k.a., byte) boundaries are a 6333 structural unit common to all representation data, allowing 6334 partitions of the data to be identified as a range of bytes at some 6335 offset from the start or end of that data. 6337 This general notion of a _range unit_ is used in the Accept-Ranges 6338 (Section 14.3) response header field to advertise support for range 6339 requests, the Range (Section 14.2) request header field to delineate 6340 the parts of a representation that are requested, and the 6341 Content-Range (Section 14.4) header field to describe which part of a 6342 representation is being transferred. 6344 range-unit = token 6346 All range unit names are case-insensitive and ought to be registered 6347 within the "HTTP Range Unit Registry", as defined in Section 16.5.1. 6349 Range units are intended to be extensible, as described in 6350 Section 16.5. 6352 14.1.1. Range Specifiers 6354 Ranges are expressed in terms of a range unit paired with a set of 6355 range specifiers. The range unit name determines what kinds of 6356 range-spec are applicable to its own specifiers. Hence, the 6357 following grammar is generic: each range unit is expected to specify 6358 requirements on when int-range, suffix-range, and other-range are 6359 allowed. 6361 A range request can specify a single range or a set of ranges within 6362 a single representation. 6364 ranges-specifier = range-unit "=" range-set 6365 range-set = 1#range-spec 6366 range-spec = int-range 6367 / suffix-range 6368 / other-range 6370 An int-range is a range expressed as two non-negative integers or as 6371 one non-negative integer through to the end of the representation 6372 data. The range unit specifies what the integers mean (e.g., they 6373 might indicate unit offsets from the beginning, inclusive numbered 6374 parts, etc.). 6376 int-range = first-pos "-" [ last-pos ] 6377 first-pos = 1*DIGIT 6378 last-pos = 1*DIGIT 6380 An int-range is invalid if the last-pos value is present and less 6381 than the first-pos. 6383 A suffix-range is a range expressed as a suffix of the representation 6384 data with the provided non-negative integer maximum length (in range 6385 units). In other words, the last N units of the representation data. 6387 suffix-range = "-" suffix-length 6388 suffix-length = 1*DIGIT 6390 To provide for extensibility, the other-range rule is a mostly 6391 unconstrained grammar that allows application-specific or future 6392 range units to define additional range specifiers. 6394 other-range = 1*( %x21-2B / %x2D-7E ) 6395 ; 1*(VCHAR excluding comma) 6397 14.1.2. Byte Ranges 6399 The "bytes" range unit is used to express subranges of a 6400 representation data's octet sequence. Each byte range is expressed 6401 as an integer range at some offset, relative to either the beginning 6402 (int-range) or end (suffix-range) of the representation data. Byte 6403 ranges do not use the other-range specifier. 6405 The first-pos value in a bytes int-range gives the offset of the 6406 first byte in a range. The last-pos value gives the offset of the 6407 last byte in the range; that is, the byte positions specified are 6408 inclusive. Byte offsets start at zero. 6410 If the representation data has a content coding applied, each byte 6411 range is calculated with respect to the encoded sequence of bytes, 6412 not the sequence of underlying bytes that would be obtained after 6413 decoding. 6415 Examples of bytes range specifiers: 6417 * The first 500 bytes (byte offsets 0-499, inclusive): 6419 bytes=0-499 6421 * The second 500 bytes (byte offsets 500-999, inclusive): 6423 bytes=500-999 6425 A client can limit the number of bytes requested without knowing the 6426 size of the selected representation. If the last-pos value is 6427 absent, or if the value is greater than or equal to the current 6428 length of the representation data, the byte range is interpreted as 6429 the remainder of the representation (i.e., the server replaces the 6430 value of last-pos with a value that is one less than the current 6431 length of the selected representation). 6433 A client can request the last N bytes (N > 0) of the selected 6434 representation using a suffix-range. If the selected representation 6435 is shorter than the specified suffix-length, the entire 6436 representation is used. 6438 Additional examples, assuming a representation of length 10000: 6440 * The final 500 bytes (byte offsets 9500-9999, inclusive): 6442 bytes=-500 6444 Or: 6446 bytes=9500- 6448 * The first and last bytes only (bytes 0 and 9999): 6450 bytes=0-0,-1 6452 * The first, middle, and last 1000 bytes: 6454 bytes= 0-999, 4500-5499, -1000 6456 * Other valid (but not canonical) specifications of the second 500 6457 bytes (byte offsets 500-999, inclusive): 6459 bytes=500-600,601-999 6460 bytes=500-700,601-999 6462 If a valid bytes range-set includes at least one range-spec with a 6463 first-pos that is less than the current length of the representation, 6464 or at least one suffix-range with a non-zero suffix-length, then the 6465 bytes range-set is satisfiable. Otherwise, the bytes range-set is 6466 unsatisfiable. 6468 If the selected representation has zero length, the only satisfiable 6469 form of range-spec is a suffix-range with a non-zero suffix-length. 6471 In the byte-range syntax, first-pos, last-pos, and suffix-length are 6472 expressed as decimal number of octets. Since there is no predefined 6473 limit to the length of content, recipients MUST anticipate 6474 potentially large decimal numerals and prevent parsing errors due to 6475 integer conversion overflows. 6477 14.2. Range 6479 The "Range" header field on a GET request modifies the method 6480 semantics to request transfer of only one or more subranges of the 6481 selected representation data (Section 8.1), rather than the entire 6482 selected representation. 6484 Range = ranges-specifier 6486 A server MAY ignore the Range header field. However, origin servers 6487 and intermediate caches ought to support byte ranges when possible, 6488 since they support efficient recovery from partially failed transfers 6489 and partial retrieval of large representations. 6491 A server MUST ignore a Range header field received with a request 6492 method which is unrecognized or for which range handling is not 6493 defined. For this specification, GET is the only method for which 6494 range handling is defined. 6496 An origin server MUST ignore a Range header field that contains a 6497 range unit it does not understand. A proxy MAY discard a Range 6498 header field that contains a range unit it does not understand. 6500 A server that supports range requests MAY ignore or reject a Range 6501 header field that consists of more than two overlapping ranges, or a 6502 set of many small ranges that are not listed in ascending order, 6503 since both are indications of either a broken client or a deliberate 6504 denial-of-service attack (Section 17.15). A client SHOULD NOT 6505 request multiple ranges that are inherently less efficient to process 6506 and transfer than a single range that encompasses the same data. 6508 A server that supports range requests MAY ignore a Range header field 6509 when the selected representation has no content (i.e., the selected 6510 representation's data is of zero length). 6512 A client that is requesting multiple ranges SHOULD list those ranges 6513 in ascending order (the order in which they would typically be 6514 received in a complete representation) unless there is a specific 6515 need to request a later part earlier. For example, a user agent 6516 processing a large representation with an internal catalog of parts 6517 might need to request later parts first, particularly if the 6518 representation consists of pages stored in reverse order and the user 6519 agent wishes to transfer one page at a time. 6521 The Range header field is evaluated after evaluating the precondition 6522 header fields defined in Section 13.1, and only if the result in 6523 absence of the Range header field would be a 200 (OK) response. In 6524 other words, Range is ignored when a conditional GET would result in 6525 a 304 (Not Modified) response. 6527 The If-Range header field (Section 13.1.5) can be used as a 6528 precondition to applying the Range header field. 6530 If all of the preconditions are true, the server supports the Range 6531 header field for the target resource, and the specified range(s) are 6532 valid and satisfiable (as defined in Section 14.1.2), the server 6533 SHOULD send a 206 (Partial Content) response with a content 6534 containing one or more partial representations that correspond to the 6535 satisfiable ranges requested. 6537 The above does not imply that a server will send all requested 6538 ranges. In some cases, it may only be possible (or efficient) to 6539 send a portion of the requested ranges first, while expecting the 6540 client to re-request the remaining portions later if they are still 6541 desired (see Section 15.3.7). 6543 If all of the preconditions are true, the server supports the Range 6544 header field for the target resource, and the specified range(s) are 6545 invalid or unsatisfiable, the server SHOULD send a 416 (Range Not 6546 Satisfiable) response. 6548 14.3. Accept-Ranges 6550 The "Accept-Ranges" field in a response indicates whether an upstream 6551 server supports range requests for the target resource. 6553 Accept-Ranges = acceptable-ranges 6554 acceptable-ranges = 1#range-unit 6556 For example, a server that supports byte-range requests 6557 (Section 14.1.2) can send the field 6559 Accept-Ranges: bytes 6560 to indicate that it supports byte range requests for that target 6561 resource, thereby encouraging its use by the client for future 6562 partial requests on the same request path. Range units are defined 6563 in Section 14.1. 6565 A client MAY generate range requests regardless of having received an 6566 Accept-Ranges field. The information only provides advice for the 6567 sake of improving performance and reducing unnecessary network 6568 transfers. 6570 Conversely, a client MUST NOT assume that receiving an Accept-Ranges 6571 field means that future range requests will return partial responses. 6572 The content might change, the server might only support range 6573 requests at certain times or under certain conditions, or a different 6574 intermediary might process the next request. 6576 A server that does not support any kind of range request for the 6577 target resource MAY send 6579 Accept-Ranges: none 6581 to advise the client not to attempt a range request on the same 6582 request path. The range unit "none" is reserved for this purpose. 6584 The Accept-Ranges field MAY be sent in a trailer section, but is 6585 preferred to be sent as a header field because the information is 6586 particularly useful for restarting large information transfers that 6587 have failed in mid-content (before the trailer section is received). 6589 14.4. Content-Range 6591 The "Content-Range" header field is sent in a single part 206 6592 (Partial Content) response to indicate the partial range of the 6593 selected representation enclosed as the message content, sent in each 6594 part of a multipart 206 response to indicate the range enclosed 6595 within each body part, and sent in 416 (Range Not Satisfiable) 6596 responses to provide information about the selected representation. 6598 Content-Range = range-unit SP 6599 ( range-resp / unsatisfied-range ) 6601 range-resp = incl-range "/" ( complete-length / "*" ) 6602 incl-range = first-pos "-" last-pos 6603 unsatisfied-range = "*/" complete-length 6605 complete-length = 1*DIGIT 6607 If a 206 (Partial Content) response contains a Content-Range header 6608 field with a range unit (Section 14.1) that the recipient does not 6609 understand, the recipient MUST NOT attempt to recombine it with a 6610 stored representation. A proxy that receives such a message SHOULD 6611 forward it downstream. 6613 Content-Range might also be sent as a request modifier to request a 6614 partial PUT, as described in Section 14.5, based on private 6615 agreements between client and origin server. A server MUST ignore a 6616 Content-Range header field received in a request with a method for 6617 which Content-Range support is not defined. 6619 For byte ranges, a sender SHOULD indicate the complete length of the 6620 representation from which the range has been extracted, unless the 6621 complete length is unknown or difficult to determine. An asterisk 6622 character ("*") in place of the complete-length indicates that the 6623 representation length was unknown when the header field was 6624 generated. 6626 The following example illustrates when the complete length of the 6627 selected representation is known by the sender to be 1234 bytes: 6629 Content-Range: bytes 42-1233/1234 6631 and this second example illustrates when the complete length is 6632 unknown: 6634 Content-Range: bytes 42-1233/* 6636 A Content-Range field value is invalid if it contains a range-resp 6637 that has a last-pos value less than its first-pos value, or a 6638 complete-length value less than or equal to its last-pos value. The 6639 recipient of an invalid Content-Range MUST NOT attempt to recombine 6640 the received content with a stored representation. 6642 A server generating a 416 (Range Not Satisfiable) response to a byte- 6643 range request SHOULD send a Content-Range header field with an 6644 unsatisfied-range value, as in the following example: 6646 Content-Range: bytes */1234 6648 The complete-length in a 416 response indicates the current length of 6649 the selected representation. 6651 The Content-Range header field has no meaning for status codes that 6652 do not explicitly describe its semantic. For this specification, 6653 only the 206 (Partial Content) and 416 (Range Not Satisfiable) status 6654 codes describe a meaning for Content-Range. 6656 The following are examples of Content-Range values in which the 6657 selected representation contains a total of 1234 bytes: 6659 * The first 500 bytes: 6661 Content-Range: bytes 0-499/1234 6663 * The second 500 bytes: 6665 Content-Range: bytes 500-999/1234 6667 * All except for the first 500 bytes: 6669 Content-Range: bytes 500-1233/1234 6671 * The last 500 bytes: 6673 Content-Range: bytes 734-1233/1234 6675 14.5. Partial PUT 6677 Some origin servers support PUT of a partial representation when the 6678 user agent sends a Content-Range header field (Section 14.4) in the 6679 request, though such support is inconsistent and depends on private 6680 agreements with user agents. In general, it requests that the state 6681 of the target resource be partly replaced with the enclosed content 6682 at an offset and length indicated by the Content-Range value, where 6683 the offset is relative to the current selected representation. 6685 An origin server SHOULD respond with a 400 (Bad Request) status code 6686 if it receives Content-Range on a PUT for a target resource that does 6687 not support partial PUT requests. 6689 Partial PUT is not backwards compatible with the original definition 6690 of PUT. It may result in the content being written as a complete 6691 replacement for the current representation. 6693 Partial resource updates are also possible by targeting a separately 6694 identified resource with state that overlaps or extends a portion of 6695 the larger resource, or by using a different method that has been 6696 specifically defined for partial updates (for example, the PATCH 6697 method defined in [RFC5789]). 6699 14.6. Media Type multipart/byteranges 6701 When a 206 (Partial Content) response message includes the content of 6702 multiple ranges, they are transmitted as body parts in a multipart 6703 message body ([RFC2046], Section 5.1) with the media type of 6704 "multipart/byteranges". 6706 The multipart/byteranges media type includes one or more body parts, 6707 each with its own Content-Type and Content-Range fields. The 6708 required boundary parameter specifies the boundary string used to 6709 separate each body part. 6711 Implementation Notes: 6713 1. Additional CRLFs might precede the first boundary string in the 6714 body. 6716 2. Although [RFC2046] permits the boundary string to be quoted, some 6717 existing implementations handle a quoted boundary string 6718 incorrectly. 6720 3. A number of clients and servers were coded to an early draft of 6721 the byteranges specification that used a media type of multipart/ 6722 x-byteranges , which is almost (but not quite) compatible with 6723 this type. 6725 Despite the name, the "multipart/byteranges" media type is not 6726 limited to byte ranges. The following example uses an "exampleunit" 6727 range unit: 6729 HTTP/1.1 206 Partial Content 6730 Date: Tue, 14 Nov 1995 06:25:24 GMT 6731 Last-Modified: Tue, 14 July 04:58:08 GMT 6732 Content-Length: 2331785 6733 Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 6735 --THIS_STRING_SEPARATES 6736 Content-Type: video/example 6737 Content-Range: exampleunit 1.2-4.3/25 6739 ...the first range... 6740 --THIS_STRING_SEPARATES 6741 Content-Type: video/example 6742 Content-Range: exampleunit 11.2-14.3/25 6744 ...the second range 6745 --THIS_STRING_SEPARATES-- 6746 The following information serves as the registration form for the 6747 multipart/byteranges media type. 6749 Type name: multipart 6751 Subtype name: byteranges 6753 Required parameters: boundary 6755 Optional parameters: N/A 6757 Encoding considerations: only "7bit", "8bit", or "binary" are 6758 permitted 6760 Security considerations: see Section 17 6762 Interoperability considerations: N/A 6764 Published specification: This specification (see Section 14.6). 6766 Applications that use this media type: HTTP components supporting 6767 multiple ranges in a single request. 6769 Fragment identifier considerations: N/A 6771 Additional information: Deprecated alias names for this type: N/A 6773 Magic number(s): N/A 6775 File extension(s): N/A 6777 Macintosh file type code(s): N/A 6779 Person and email address to contact for further information: See Aut 6780 hors' Addresses section. 6782 Intended usage: COMMON 6784 Restrictions on usage: N/A 6786 Author: See Authors' Addresses section. 6788 Change controller: IESG 6790 15. Status Codes 6792 The status code of a response is a three-digit integer code that 6793 describes the result of the request and the semantics of the 6794 response, including whether the request was successful and what 6795 content is enclosed (if any). All valid status codes are within the 6796 range of 100 to 599, inclusive. 6798 The first digit of the status code defines the class of response. 6799 The last two digits do not have any categorization role. There are 6800 five values for the first digit: 6802 * 1xx (Informational): The request was received, continuing process 6804 * 2xx (Successful): The request was successfully received, 6805 understood, and accepted 6807 * 3xx (Redirection): Further action needs to be taken in order to 6808 complete the request 6810 * 4xx (Client Error): The request contains bad syntax or cannot be 6811 fulfilled 6813 * 5xx (Server Error): The server failed to fulfill an apparently 6814 valid request 6816 HTTP status codes are extensible. A client is not required to 6817 understand the meaning of all registered status codes, though such 6818 understanding is obviously desirable. However, a client MUST 6819 understand the class of any status code, as indicated by the first 6820 digit, and treat an unrecognized status code as being equivalent to 6821 the x00 status code of that class. 6823 For example, if a client receives an unrecognized status code of 471, 6824 it can see from the first digit that there was something wrong with 6825 its request and treat the response as if it had received a 400 (Bad 6826 Request) status code. The response message will usually contain a 6827 representation that explains the status. 6829 Values outside the range 100..599 are invalid. Implementations often 6830 use three-digit integer values outside of that range (i.e., 600..999) 6831 for internal communication of non-HTTP status (e.g., library errors). 6832 A client that receives a response with an invalid status code SHOULD 6833 process the response as if it had a 5xx (Server Error) status code. 6835 A single request can have multiple associated responses: zero or more 6836 _interim_ (non-final) responses with status codes in the 6837 "informational" (1xx) range, followed by exactly one _final_ response 6838 with a status code in one of the other ranges. 6840 15.1. Overview of Status Codes 6842 The status codes listed below are defined in this specification. The 6843 reason phrases listed here are only recommendations - they can be 6844 replaced by local equivalents or left out altogether without 6845 affecting the protocol. 6847 Responses with status codes that are defined as heuristically 6848 cacheable (e.g., 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 6849 414, and 501 in this specification) can be reused by a cache with 6850 heuristic expiration unless otherwise indicated by the method 6851 definition or explicit cache controls [CACHING]; all other status 6852 codes are not heuristically cacheable. 6854 Additional status codes, outside the scope of this specification, 6855 have been specified for use in HTTP. All such status codes ought to 6856 be registered within the "Hypertext Transfer Protocol (HTTP) Status 6857 Code Registry", as described in Section 16.2. 6859 15.2. Informational 1xx 6861 The _1xx (Informational)_ class of status code indicates an interim 6862 response for communicating connection status or request progress 6863 prior to completing the requested action and sending a final 6864 response. Since HTTP/1.0 did not define any 1xx status codes, a 6865 server MUST NOT send a 1xx response to an HTTP/1.0 client. 6867 A 1xx response is terminated by the end of the header section; it 6868 cannot contain content or trailers. 6870 A client MUST be able to parse one or more 1xx responses received 6871 prior to a final response, even if the client does not expect one. A 6872 user agent MAY ignore unexpected 1xx responses. 6874 A proxy MUST forward 1xx responses unless the proxy itself requested 6875 the generation of the 1xx response. For example, if a proxy adds an 6876 "Expect: 100-continue" header field when it forwards a request, then 6877 it need not forward the corresponding 100 (Continue) response(s). 6879 15.2.1. 100 Continue 6881 The _100 (Continue)_ status code indicates that the initial part of a 6882 request has been received and has not yet been rejected by the 6883 server. The server intends to send a final response after the 6884 request has been fully received and acted upon. 6886 When the request contains an Expect header field that includes a 6887 100-continue expectation, the 100 response indicates that the server 6888 wishes to receive the request content, as described in 6889 Section 10.1.1. The client ought to continue sending the request and 6890 discard the 100 response. 6892 If the request did not contain an Expect header field containing the 6893 100-continue expectation, the client can simply discard this interim 6894 response. 6896 15.2.2. 101 Switching Protocols 6898 The _101 (Switching Protocols)_ status code indicates that the server 6899 understands and is willing to comply with the client's request, via 6900 the Upgrade header field (Section 7.8), for a change in the 6901 application protocol being used on this connection. The server MUST 6902 generate an Upgrade header field in the response that indicates which 6903 protocol(s) will be in effect after this response. 6905 It is assumed that the server will only agree to switch protocols 6906 when it is advantageous to do so. For example, switching to a newer 6907 version of HTTP might be advantageous over older versions, and 6908 switching to a real-time, synchronous protocol might be advantageous 6909 when delivering resources that use such features. 6911 15.3. Successful 2xx 6913 The _2xx (Successful)_ class of status code indicates that the 6914 client's request was successfully received, understood, and accepted. 6916 15.3.1. 200 OK 6918 The _200 (OK)_ status code indicates that the request has succeeded. 6919 The content sent in a 200 response depends on the request method. 6920 For the methods defined by this specification, the intended meaning 6921 of the content can be summarized as: 6923 +================+============================================+ 6924 | request method | response content is a representation of | 6925 +================+============================================+ 6926 | GET | the target resource | 6927 +----------------+--------------------------------------------+ 6928 | HEAD | the target resource, like GET, but without | 6929 | | transferring the representation data | 6930 +----------------+--------------------------------------------+ 6931 | POST | the status of, or results obtained from, | 6932 | | the action | 6933 +----------------+--------------------------------------------+ 6934 | PUT, DELETE | the status of the action | 6935 +----------------+--------------------------------------------+ 6936 | OPTIONS | communication options for the target | 6937 | | resource | 6938 +----------------+--------------------------------------------+ 6939 | TRACE | the request message as received by the | 6940 | | server returning the trace | 6941 +----------------+--------------------------------------------+ 6943 Table 6 6945 Aside from responses to CONNECT, a 200 response is expected to 6946 contain message content unless the message framing explicitly 6947 indicates that the content has zero length. If some aspect of the 6948 request indicates a preference for no content upon success, the 6949 origin server ought to send a _204 (No Content)_ response instead. 6950 For CONNECT, there is no content because the successful result is a 6951 tunnel, which begins immediately after the 200 response header 6952 section. 6954 A 200 response is heuristically cacheable; i.e., unless otherwise 6955 indicated by the method definition or explicit cache controls (see 6956 Section 4.2.2 of [CACHING]). 6958 In 200 responses to GET or HEAD, an origin server SHOULD send any 6959 available validator fields (Section 8.8) for the selected 6960 representation, with both a strong entity-tag and a Last-Modified 6961 date being preferred. 6963 In 200 responses to state-changing methods, any validator fields 6964 (Section 8.8) sent in the response convey the current validators for 6965 the new representation formed as a result of successfully applying 6966 the request semantics. Note that the PUT method (Section 9.3.4) has 6967 additional requirements that might preclude sending such validators. 6969 15.3.2. 201 Created 6971 The _201 (Created)_ status code indicates that the request has been 6972 fulfilled and has resulted in one or more new resources being 6973 created. The primary resource created by the request is identified 6974 by either a Location header field in the response or, if no Location 6975 header field is received, by the target URI. 6977 The 201 response content typically describes and links to the 6978 resource(s) created. Any validator fields (Section 8.8) sent in the 6979 response convey the current validators for a new representation 6980 created by the request. Note that the PUT method (Section 9.3.4) has 6981 additional requirements that might preclude sending such validators. 6983 15.3.3. 202 Accepted 6985 The _202 (Accepted)_ status code indicates that the request has been 6986 accepted for processing, but the processing has not been completed. 6987 The request might or might not eventually be acted upon, as it might 6988 be disallowed when processing actually takes place. There is no 6989 facility in HTTP for re-sending a status code from an asynchronous 6990 operation. 6992 The 202 response is intentionally noncommittal. Its purpose is to 6993 allow a server to accept a request for some other process (perhaps a 6994 batch-oriented process that is only run once per day) without 6995 requiring that the user agent's connection to the server persist 6996 until the process is completed. The representation sent with this 6997 response ought to describe the request's current status and point to 6998 (or embed) a status monitor that can provide the user with an 6999 estimate of when the request will be fulfilled. 7001 15.3.4. 203 Non-Authoritative Information 7003 The _203 (Non-Authoritative Information)_ status code indicates that 7004 the request was successful but the enclosed content has been modified 7005 from that of the origin server's 200 (OK) response by a transforming 7006 proxy (Section 7.7). This status code allows the proxy to notify 7007 recipients when a transformation has been applied, since that 7008 knowledge might impact later decisions regarding the content. For 7009 example, future cache validation requests for the content might only 7010 be applicable along the same request path (through the same proxies). 7012 A 203 response is heuristically cacheable; i.e., unless otherwise 7013 indicated by the method definition or explicit cache controls (see 7014 Section 4.2.2 of [CACHING]). 7016 15.3.5. 204 No Content 7018 The _204 (No Content)_ status code indicates that the server has 7019 successfully fulfilled the request and that there is no additional 7020 content to send in the response content. Metadata in the response 7021 header fields refer to the target resource and its selected 7022 representation after the requested action was applied. 7024 For example, if a 204 status code is received in response to a PUT 7025 request and the response contains an ETag field, then the PUT was 7026 successful and the ETag field value contains the entity-tag for the 7027 new representation of that target resource. 7029 The 204 response allows a server to indicate that the action has been 7030 successfully applied to the target resource, while implying that the 7031 user agent does not need to traverse away from its current "document 7032 view" (if any). The server assumes that the user agent will provide 7033 some indication of the success to its user, in accord with its own 7034 interface, and apply any new or updated metadata in the response to 7035 its active representation. 7037 For example, a 204 status code is commonly used with document editing 7038 interfaces corresponding to a "save" action, such that the document 7039 being saved remains available to the user for editing. It is also 7040 frequently used with interfaces that expect automated data transfers 7041 to be prevalent, such as within distributed version control systems. 7043 A 204 response is terminated by the end of the header section; it 7044 cannot contain content or trailers. 7046 A 204 response is heuristically cacheable; i.e., unless otherwise 7047 indicated by the method definition or explicit cache controls (see 7048 Section 4.2.2 of [CACHING]). 7050 15.3.6. 205 Reset Content 7052 The _205 (Reset Content)_ status code indicates that the server has 7053 fulfilled the request and desires that the user agent reset the 7054 "document view", which caused the request to be sent, to its original 7055 state as received from the origin server. 7057 This response is intended to support a common data entry use case 7058 where the user receives content that supports data entry (a form, 7059 notepad, canvas, etc.), enters or manipulates data in that space, 7060 causes the entered data to be submitted in a request, and then the 7061 data entry mechanism is reset for the next entry so that the user can 7062 easily initiate another input action. 7064 Since the 205 status code implies that no additional content will be 7065 provided, a server MUST NOT generate content in a 205 response. 7067 15.3.7. 206 Partial Content 7069 The _206 (Partial Content)_ status code indicates that the server is 7070 successfully fulfilling a range request for the target resource by 7071 transferring one or more parts of the selected representation. 7073 A server that supports range requests (Section 14) will usually 7074 attempt to satisfy all of the requested ranges, since sending less 7075 data will likely result in another client request for the remainder. 7076 However, a server might want to send only a subset of the data 7077 requested for reasons of its own, such as temporary unavailability, 7078 cache efficiency, load balancing, etc. Since a 206 response is self- 7079 descriptive, the client can still understand a response that only 7080 partially satisfies its range request. 7082 A client MUST inspect a 206 response's Content-Type and Content-Range 7083 field(s) to determine what parts are enclosed and whether additional 7084 requests are needed. 7086 A server that generates a 206 response MUST generate the following 7087 header fields, in addition to those required in the subsections 7088 below, if the field would have been sent in a 200 (OK) response to 7089 the same request: Date, Cache-Control, ETag, Expires, 7090 Content-Location, and Vary. 7092 A Content-Length header field present in a 206 response indicates the 7093 number of octets in the content of this message, which is usually not 7094 the complete length of the selected representation. Each 7095 Content-Range header field includes information about the selected 7096 representation's complete length. 7098 A sender that generates a 206 response to a request with an If-Range 7099 header field SHOULD NOT generate other representation header fields 7100 beyond those required, because the client already has a prior 7101 response containing those header fields. Otherwise, a sender MUST 7102 generate all of the representation header fields that would have been 7103 sent in a 200 (OK) response to the same request. 7105 A 206 response is heuristically cacheable; i.e., unless otherwise 7106 indicated by explicit cache controls (see Section 4.2.2 of 7107 [CACHING]). 7109 15.3.7.1. Single Part 7111 If a single part is being transferred, the server generating the 206 7112 response MUST generate a Content-Range header field, describing what 7113 range of the selected representation is enclosed, and a content 7114 consisting of the range. For example: 7116 HTTP/1.1 206 Partial Content 7117 Date: Wed, 15 Nov 1995 06:25:24 GMT 7118 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 7119 Content-Range: bytes 21010-47021/47022 7120 Content-Length: 26012 7121 Content-Type: image/gif 7123 ... 26012 bytes of partial image data ... 7125 15.3.7.2. Multiple Parts 7127 If multiple parts are being transferred, the server generating the 7128 206 response MUST generate "multipart/byteranges" content, as defined 7129 in Section 14.6, and a Content-Type header field containing the 7130 multipart/byteranges media type and its required boundary parameter. 7131 To avoid confusion with single-part responses, a server MUST NOT 7132 generate a Content-Range header field in the HTTP header section of a 7133 multiple part response (this field will be sent in each part 7134 instead). 7136 Within the header area of each body part in the multipart content, 7137 the server MUST generate a Content-Range header field corresponding 7138 to the range being enclosed in that body part. If the selected 7139 representation would have had a Content-Type header field in a 200 7140 (OK) response, the server SHOULD generate that same Content-Type 7141 header field in the header area of each body part. For example: 7143 HTTP/1.1 206 Partial Content 7144 Date: Wed, 15 Nov 1995 06:25:24 GMT 7145 Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT 7146 Content-Length: 1741 7147 Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES 7149 --THIS_STRING_SEPARATES 7150 Content-Type: application/pdf 7151 Content-Range: bytes 500-999/8000 7153 ...the first range... 7154 --THIS_STRING_SEPARATES 7155 Content-Type: application/pdf 7156 Content-Range: bytes 7000-7999/8000 7158 ...the second range 7159 --THIS_STRING_SEPARATES-- 7161 When multiple ranges are requested, a server MAY coalesce any of the 7162 ranges that overlap, or that are separated by a gap that is smaller 7163 than the overhead of sending multiple parts, regardless of the order 7164 in which the corresponding range-spec appeared in the received Range 7165 header field. Since the typical overhead between each part of a 7166 multipart/byteranges is around 80 bytes, depending on the selected 7167 representation's media type and the chosen boundary parameter length, 7168 it can be less efficient to transfer many small disjoint parts than 7169 it is to transfer the entire selected representation. 7171 A server MUST NOT generate a multipart response to a request for a 7172 single range, since a client that does not request multiple parts 7173 might not support multipart responses. However, a server MAY 7174 generate a multipart/byteranges response with only a single body part 7175 if multiple ranges were requested and only one range was found to be 7176 satisfiable or only one range remained after coalescing. A client 7177 that cannot process a multipart/byteranges response MUST NOT generate 7178 a request that asks for multiple ranges. 7180 A server that generates a multipart response SHOULD send the parts in 7181 the same order that the corresponding range-spec appeared in the 7182 received Range header field, excluding those ranges that were deemed 7183 unsatisfiable or that were coalesced into other ranges. A client 7184 that receives a multipart response MUST inspect the Content-Range 7185 header field present in each body part in order to determine which 7186 range is contained in that body part; a client cannot rely on 7187 receiving the same ranges that it requested, nor the same order that 7188 it requested. 7190 15.3.7.3. Combining Parts 7192 A response might transfer only a subrange of a representation if the 7193 connection closed prematurely or if the request used one or more 7194 Range specifications. After several such transfers, a client might 7195 have received several ranges of the same representation. These 7196 ranges can only be safely combined if they all have in common the 7197 same strong validator (Section 8.8.1). 7199 A client that has received multiple partial responses to GET requests 7200 on a target resource MAY combine those responses into a larger 7201 continuous range if they share the same strong validator. 7203 If the most recent response is an incomplete 200 (OK) response, then 7204 the header fields of that response are used for any combined response 7205 and replace those of the matching stored responses. 7207 If the most recent response is a 206 (Partial Content) response and 7208 at least one of the matching stored responses is a 200 (OK), then the 7209 combined response header fields consist of the most recent 200 7210 response's header fields. If all of the matching stored responses 7211 are 206 responses, then the stored response with the most recent 7212 header fields is used as the source of header fields for the combined 7213 response, except that the client MUST use other header fields 7214 provided in the new response, aside from Content-Range, to replace 7215 all instances of the corresponding header fields in the stored 7216 response. 7218 The combined response content consists of the union of partial 7219 content ranges within the new response and all of the matching stored 7220 responses. If the union consists of the entire range of the 7221 representation, then the client MUST process the combined response as 7222 if it were a complete 200 (OK) response, including a Content-Length 7223 header field that reflects the complete length. Otherwise, the 7224 client MUST process the set of continuous ranges as one of the 7225 following: an incomplete 200 (OK) response if the combined response 7226 is a prefix of the representation, a single 206 (Partial Content) 7227 response containing multipart/byteranges content, or multiple 206 7228 (Partial Content) responses, each with one continuous range that is 7229 indicated by a Content-Range header field. 7231 15.4. Redirection 3xx 7233 The _3xx (Redirection)_ class of status code indicates that further 7234 action needs to be taken by the user agent in order to fulfill the 7235 request. There are several types of redirects: 7237 1. Redirects that indicate this resource might be available at a 7238 different URI, as provided by the Location header field, as in 7239 the status codes 301 (Moved Permanently), 302 (Found), 307 7240 (Temporary Redirect), and 308 (Permanent Redirect). 7242 2. Redirection that offers a choice among matching resources capable 7243 of representing this resource, as in the 300 (Multiple Choices) 7244 status code. 7246 3. Redirection to a different resource, identified by the Location 7247 header field, that can represent an indirect response to the 7248 request, as in the 303 (See Other) status code. 7250 4. Redirection to a previously stored result, as in the 304 (Not 7251 Modified) status code. 7253 | *Note:* In HTTP/1.0, the status codes 301 (Moved Permanently) 7254 | and 302 (Found) were originally defined as method-preserving 7255 | ([HTTP/1.0], Section 9.3) to match their implementation at 7256 | CERN; 303 (See Other) was defined for a redirection that 7257 | changed its method to GET. However, early user agents split on 7258 | whether to redirect POST requests as POST (according to then- 7259 | current specification) or as GET (the safer alternative when 7260 | redirected to a different site). Prevailing practice 7261 | eventually converged on changing the method to GET. 307 7262 | (Temporary Redirect) and 308 (Permanent Redirect) [RFC7538] 7263 | were later added to unambiguously indicate method-preserving 7264 | redirects, and 301/302 have been adjusted to allow a POST 7265 | request to be redirected as GET. 7267 If a Location header field (Section 10.2.2) is provided, the user 7268 agent MAY automatically redirect its request to the URI referenced by 7269 the Location field value, even if the specific status code is not 7270 understood. Automatic redirection needs to be done with care for 7271 methods not known to be safe, as defined in Section 9.2.1, since the 7272 user might not wish to redirect an unsafe request. 7274 When automatically following a redirected request, the user agent 7275 SHOULD resend the original request message with the following 7276 modifications: 7278 1. Replace the target URI with the URI referenced by the redirection 7279 response's Location header field value after resolving it 7280 relative to the original request's target URI. 7282 2. Remove header fields that were automatically generated by the 7283 implementation, replacing them with updated values as appropriate 7284 to the new request. This includes: 7286 1. Connection-specific header fields (see Section 7.6.1), 7288 2. Header fields specific to the client's proxy configuration, 7289 including (but not limited to) Proxy-Authorization, 7291 3. Origin-specific header fields (if any), including (but not 7292 limited to) Host, 7294 4. Validating header fields that were added by the 7295 implementation's cache (e.g., If-None-Match, 7296 If-Modified-Since), 7298 5. Resource-specific header fields, including (but not limited 7299 to) Referer, Origin, Authorization, and Cookie. 7301 3. Consider removing header fields that were not automatically 7302 generated by the implementation (i.e., those present in the 7303 request because they were added by the calling context) where 7304 there are security implications; this includes but is not limited 7305 to Authorization and Cookie. 7307 4. Change the request method according to the redirecting status 7308 code's semantics, if applicable. 7310 5. If the request method has been changed to GET or HEAD, remove 7311 content-specific header fields, including (but not limited to) 7312 Content-Encoding, Content-Language, Content-Location, 7313 Content-Type, Content-Length, Digest, Last-Modified. 7315 A client SHOULD detect and intervene in cyclical redirections (i.e., 7316 "infinite" redirection loops). 7318 | *Note:* An earlier version of this specification recommended a 7319 | maximum of five redirections ([RFC2068], Section 10.3). 7320 | Content developers need to be aware that some clients might 7321 | implement such a fixed limitation. 7323 15.4.1. 300 Multiple Choices 7325 The _300 (Multiple Choices)_ status code indicates that the target 7326 resource has more than one representation, each with its own more 7327 specific identifier, and information about the alternatives is being 7328 provided so that the user (or user agent) can select a preferred 7329 representation by redirecting its request to one or more of those 7330 identifiers. In other words, the server desires that the user agent 7331 engage in reactive negotiation to select the most appropriate 7332 representation(s) for its needs (Section 12). 7334 If the server has a preferred choice, the server SHOULD generate a 7335 Location header field containing a preferred choice's URI reference. 7336 The user agent MAY use the Location field value for automatic 7337 redirection. 7339 For request methods other than HEAD, the server SHOULD generate 7340 content in the 300 response containing a list of representation 7341 metadata and URI reference(s) from which the user or user agent can 7342 choose the one most preferred. The user agent MAY make a selection 7343 from that list automatically if it understands the provided media 7344 type. A specific format for automatic selection is not defined by 7345 this specification because HTTP tries to remain orthogonal to the 7346 definition of its content. In practice, the representation is 7347 provided in some easily parsed format believed to be acceptable to 7348 the user agent, as determined by shared design or content 7349 negotiation, or in some commonly accepted hypertext format. 7351 A 300 response is heuristically cacheable; i.e., unless otherwise 7352 indicated by the method definition or explicit cache controls (see 7353 Section 4.2.2 of [CACHING]). 7355 | *Note:* The original proposal for the 300 status code defined 7356 | the URI header field as providing a list of alternative 7357 | representations, such that it would be usable for 200, 300, and 7358 | 406 responses and be transferred in responses to the HEAD 7359 | method. However, lack of deployment and disagreement over 7360 | syntax led to both URI and Alternates (a subsequent proposal) 7361 | being dropped from this specification. It is possible to 7362 | communicate the list as a Link header field value [RFC8288] 7363 | whose members have a relationship of "alternate", though 7364 | deployment is a chicken-and-egg problem. 7366 15.4.2. 301 Moved Permanently 7368 The _301 (Moved Permanently)_ status code indicates that the target 7369 resource has been assigned a new permanent URI and any future 7370 references to this resource ought to use one of the enclosed URIs. 7371 Clients with link-editing capabilities ought to automatically re-link 7372 references to the target URI to one or more of the new references 7373 sent by the server, where possible. 7375 The server SHOULD generate a Location header field in the response 7376 containing a preferred URI reference for the new permanent URI. The 7377 user agent MAY use the Location field value for automatic 7378 redirection. The server's response content usually contains a short 7379 hypertext note with a hyperlink to the new URI(s). 7381 | *Note:* For historical reasons, a user agent MAY change the 7382 | request method from POST to GET for the subsequent request. If 7383 | this behavior is undesired, the 308 (Permanent Redirect) status 7384 | code can be used instead. 7386 A 301 response is heuristically cacheable; i.e., unless otherwise 7387 indicated by the method definition or explicit cache controls (see 7388 Section 4.2.2 of [CACHING]). 7390 15.4.3. 302 Found 7392 The _302 (Found)_ status code indicates that the target resource 7393 resides temporarily under a different URI. Since the redirection 7394 might be altered on occasion, the client ought to continue to use the 7395 target URI for future requests. 7397 The server SHOULD generate a Location header field in the response 7398 containing a URI reference for the different URI. The user agent MAY 7399 use the Location field value for automatic redirection. The server's 7400 response content usually contains a short hypertext note with a 7401 hyperlink to the different URI(s). 7403 | *Note:* For historical reasons, a user agent MAY change the 7404 | request method from POST to GET for the subsequent request. If 7405 | this behavior is undesired, the 307 (Temporary Redirect) status 7406 | code can be used instead. 7408 15.4.4. 303 See Other 7410 The _303 (See Other)_ status code indicates that the server is 7411 redirecting the user agent to a different resource, as indicated by a 7412 URI in the Location header field, which is intended to provide an 7413 indirect response to the original request. A user agent can perform 7414 a retrieval request targeting that URI (a GET or HEAD request if 7415 using HTTP), which might also be redirected, and present the eventual 7416 result as an answer to the original request. Note that the new URI 7417 in the Location header field is not considered equivalent to the 7418 target URI. 7420 This status code is applicable to any HTTP method. It is primarily 7421 used to allow the output of a POST action to redirect the user agent 7422 to a different resource, since doing so provides the information 7423 corresponding to the POST response as a resource that can be 7424 separately identified, bookmarked, and cached. 7426 A 303 response to a GET request indicates that the origin server does 7427 not have a representation of the target resource that can be 7428 transferred by the server over HTTP. However, the Location field 7429 value refers to a resource that is descriptive of the target 7430 resource, such that making a retrieval request on that other resource 7431 might result in a representation that is useful to recipients without 7432 implying that it represents the original target resource. Note that 7433 answers to the questions of what can be represented, what 7434 representations are adequate, and what might be a useful description 7435 are outside the scope of HTTP. 7437 Except for responses to a HEAD request, the representation of a 303 7438 response ought to contain a short hypertext note with a hyperlink to 7439 the same URI reference provided in the Location header field. 7441 15.4.5. 304 Not Modified 7443 The _304 (Not Modified)_ status code indicates that a conditional GET 7444 or HEAD request has been received and would have resulted in a 200 7445 (OK) response if it were not for the fact that the condition 7446 evaluated to false. In other words, there is no need for the server 7447 to transfer a representation of the target resource because the 7448 request indicates that the client, which made the request 7449 conditional, already has a valid representation; the server is 7450 therefore redirecting the client to make use of that stored 7451 representation as if it were the content of a 200 (OK) response. 7453 The server generating a 304 response MUST generate any of the 7454 following header fields that would have been sent in a 200 (OK) 7455 response to the same request: Cache-Control, Content-Location, Date, 7456 ETag, Expires, and Vary. 7458 Since the goal of a 304 response is to minimize information transfer 7459 when the recipient already has one or more cached representations, a 7460 sender SHOULD NOT generate representation metadata other than the 7461 above listed fields unless said metadata exists for the purpose of 7462 guiding cache updates (e.g., Last-Modified might be useful if the 7463 response does not have an ETag field). 7465 Requirements on a cache that receives a 304 response are defined in 7466 Section 4.3.4 of [CACHING]. If the conditional request originated 7467 with an outbound client, such as a user agent with its own cache 7468 sending a conditional GET to a shared proxy, then the proxy SHOULD 7469 forward the 304 response to that client. 7471 A 304 response is terminated by the end of the header section; it 7472 cannot contain content or trailers. 7474 15.4.6. 305 Use Proxy 7476 The _305 (Use Proxy)_ status code was defined in a previous version 7477 of this specification and is now deprecated (Appendix B of 7478 [RFC7231]). 7480 15.4.7. 306 (Unused) 7482 The 306 status code was defined in a previous version of this 7483 specification, is no longer used, and the code is reserved. 7485 15.4.8. 307 Temporary Redirect 7487 The _307 (Temporary Redirect)_ status code indicates that the target 7488 resource resides temporarily under a different URI and the user agent 7489 MUST NOT change the request method if it performs an automatic 7490 redirection to that URI. Since the redirection can change over time, 7491 the client ought to continue using the original target URI for future 7492 requests. 7494 The server SHOULD generate a Location header field in the response 7495 containing a URI reference for the different URI. The user agent MAY 7496 use the Location field value for automatic redirection. The server's 7497 response content usually contains a short hypertext note with a 7498 hyperlink to the different URI(s). 7500 15.4.9. 308 Permanent Redirect 7502 The _308 (Permanent Redirect)_ status code indicates that the target 7503 resource has been assigned a new permanent URI and any future 7504 references to this resource ought to use one of the enclosed URIs. 7505 Clients with link editing capabilities ought to automatically re-link 7506 references to the target URI to one or more of the new references 7507 sent by the server, where possible. 7509 The server SHOULD generate a Location header field in the response 7510 containing a preferred URI reference for the new permanent URI. The 7511 user agent MAY use the Location field value for automatic 7512 redirection. The server's response content usually contains a short 7513 hypertext note with a hyperlink to the new URI(s). 7515 A 308 response is heuristically cacheable; i.e., unless otherwise 7516 indicated by the method definition or explicit cache controls (see 7517 Section 4.2.2 of [CACHING]). 7519 | *Note:* This status code is much younger (June 2014) than its 7520 | sibling codes, and thus might not be recognized everywhere. 7521 | See Section 4 of [RFC7538] for deployment considerations. 7523 15.5. Client Error 4xx 7525 The _4xx (Client Error)_ class of status code indicates that the 7526 client seems to have erred. Except when responding to a HEAD 7527 request, the server SHOULD send a representation containing an 7528 explanation of the error situation, and whether it is a temporary or 7529 permanent condition. These status codes are applicable to any 7530 request method. User agents SHOULD display any included 7531 representation to the user. 7533 15.5.1. 400 Bad Request 7535 The _400 (Bad Request)_ status code indicates that the server cannot 7536 or will not process the request due to something that is perceived to 7537 be a client error (e.g., malformed request syntax, invalid request 7538 message framing, or deceptive request routing). 7540 15.5.2. 401 Unauthorized 7542 The _401 (Unauthorized)_ status code indicates that the request has 7543 not been applied because it lacks valid authentication credentials 7544 for the target resource. The server generating a 401 response MUST 7545 send a WWW-Authenticate header field (Section 11.6.1) containing at 7546 least one challenge applicable to the target resource. 7548 If the request included authentication credentials, then the 401 7549 response indicates that authorization has been refused for those 7550 credentials. The user agent MAY repeat the request with a new or 7551 replaced Authorization header field (Section 11.6.2). If the 401 7552 response contains the same challenge as the prior response, and the 7553 user agent has already attempted authentication at least once, then 7554 the user agent SHOULD present the enclosed representation to the 7555 user, since it usually contains relevant diagnostic information. 7557 15.5.3. 402 Payment Required 7559 The _402 (Payment Required)_ status code is reserved for future use. 7561 15.5.4. 403 Forbidden 7563 The _403 (Forbidden)_ status code indicates that the server 7564 understood the request but refuses to fulfill it. A server that 7565 wishes to make public why the request has been forbidden can describe 7566 that reason in the response content (if any). 7568 If authentication credentials were provided in the request, the 7569 server considers them insufficient to grant access. The client 7570 SHOULD NOT automatically repeat the request with the same 7571 credentials. The client MAY repeat the request with new or different 7572 credentials. However, a request might be forbidden for reasons 7573 unrelated to the credentials. 7575 An origin server that wishes to "hide" the current existence of a 7576 forbidden target resource MAY instead respond with a status code of 7577 404 (Not Found). 7579 15.5.5. 404 Not Found 7581 The _404 (Not Found)_ status code indicates that the origin server 7582 did not find a current representation for the target resource or is 7583 not willing to disclose that one exists. A 404 status code does not 7584 indicate whether this lack of representation is temporary or 7585 permanent; the 410 (Gone) status code is preferred over 404 if the 7586 origin server knows, presumably through some configurable means, that 7587 the condition is likely to be permanent. 7589 A 404 response is heuristically cacheable; i.e., unless otherwise 7590 indicated by the method definition or explicit cache controls (see 7591 Section 4.2.2 of [CACHING]). 7593 15.5.6. 405 Method Not Allowed 7595 The _405 (Method Not Allowed)_ status code indicates that the method 7596 received in the request-line is known by the origin server but not 7597 supported by the target resource. The origin server MUST generate an 7598 Allow header field in a 405 response containing a list of the target 7599 resource's currently supported methods. 7601 A 405 response is heuristically cacheable; i.e., unless otherwise 7602 indicated by the method definition or explicit cache controls (see 7603 Section 4.2.2 of [CACHING]). 7605 15.5.7. 406 Not Acceptable 7607 The _406 (Not Acceptable)_ status code indicates that the target 7608 resource does not have a current representation that would be 7609 acceptable to the user agent, according to the proactive negotiation 7610 header fields received in the request (Section 12.1), and the server 7611 is unwilling to supply a default representation. 7613 The server SHOULD generate content containing a list of available 7614 representation characteristics and corresponding resource identifiers 7615 from which the user or user agent can choose the one most 7616 appropriate. A user agent MAY automatically select the most 7617 appropriate choice from that list. However, this specification does 7618 not define any standard for such automatic selection, as described in 7619 Section 15.4.1. 7621 15.5.8. 407 Proxy Authentication Required 7623 The _407 (Proxy Authentication Required)_ status code is similar to 7624 401 (Unauthorized), but it indicates that the client needs to 7625 authenticate itself in order to use a proxy for this request. The 7626 proxy MUST send a Proxy-Authenticate header field (Section 11.7.1) 7627 containing a challenge applicable to that proxy for the request. The 7628 client MAY repeat the request with a new or replaced 7629 Proxy-Authorization header field (Section 11.7.2). 7631 15.5.9. 408 Request Timeout 7633 The _408 (Request Timeout)_ status code indicates that the server did 7634 not receive a complete request message within the time that it was 7635 prepared to wait. 7637 If the client has an outstanding request in transit, it MAY repeat 7638 that request. If the current connection is not usable (e.g., as it 7639 would be in HTTP/1.1, because request delimitation is lost), a new 7640 connection will be used. 7642 15.5.10. 409 Conflict 7644 The _409 (Conflict)_ status code indicates that the request could not 7645 be completed due to a conflict with the current state of the target 7646 resource. This code is used in situations where the user might be 7647 able to resolve the conflict and resubmit the request. The server 7648 SHOULD generate content that includes enough information for a user 7649 to recognize the source of the conflict. 7651 Conflicts are most likely to occur in response to a PUT request. For 7652 example, if versioning were being used and the representation being 7653 PUT included changes to a resource that conflict with those made by 7654 an earlier (third-party) request, the origin server might use a 409 7655 response to indicate that it can't complete the request. In this 7656 case, the response representation would likely contain information 7657 useful for merging the differences based on the revision history. 7659 15.5.11. 410 Gone 7661 The _410 (Gone)_ status code indicates that access to the target 7662 resource is no longer available at the origin server and that this 7663 condition is likely to be permanent. If the origin server does not 7664 know, or has no facility to determine, whether or not the condition 7665 is permanent, the status code 404 (Not Found) ought to be used 7666 instead. 7668 The 410 response is primarily intended to assist the task of web 7669 maintenance by notifying the recipient that the resource is 7670 intentionally unavailable and that the server owners desire that 7671 remote links to that resource be removed. Such an event is common 7672 for limited-time, promotional services and for resources belonging to 7673 individuals no longer associated with the origin server's site. It 7674 is not necessary to mark all permanently unavailable resources as 7675 "gone" or to keep the mark for any length of time - that is left to 7676 the discretion of the server owner. 7678 A 410 response is heuristically cacheable; i.e., unless otherwise 7679 indicated by the method definition or explicit cache controls (see 7680 Section 4.2.2 of [CACHING]). 7682 15.5.12. 411 Length Required 7684 The _411 (Length Required)_ status code indicates that the server 7685 refuses to accept the request without a defined Content-Length 7686 (Section 8.6). The client MAY repeat the request if it adds a valid 7687 Content-Length header field containing the length of the request 7688 content. 7690 15.5.13. 412 Precondition Failed 7692 The _412 (Precondition Failed)_ status code indicates that one or 7693 more conditions given in the request header fields evaluated to false 7694 when tested on the server (Section 13). This response status code 7695 allows the client to place preconditions on the current resource 7696 state (its current representations and metadata) and, thus, prevent 7697 the request method from being applied if the target resource is in an 7698 unexpected state. 7700 15.5.14. 413 Content Too Large 7702 The _413 (Content Too Large)_ status code indicates that the server 7703 is refusing to process a request because the request content is 7704 larger than the server is willing or able to process. The server MAY 7705 terminate the request, if the protocol version in use allows it; 7706 otherwise, the server MAY close the connection. 7708 If the condition is temporary, the server SHOULD generate a 7709 Retry-After header field to indicate that it is temporary and after 7710 what time the client MAY try again. 7712 15.5.15. 414 URI Too Long 7714 The _414 (URI Too Long)_ status code indicates that the server is 7715 refusing to service the request because the target URI is longer than 7716 the server is willing to interpret. This rare condition is only 7717 likely to occur when a client has improperly converted a POST request 7718 to a GET request with long query information, when the client has 7719 descended into a "black hole" of redirection (e.g., a redirected URI 7720 prefix that points to a suffix of itself) or when the server is under 7721 attack by a client attempting to exploit potential security holes. 7723 A 414 response is heuristically cacheable; i.e., unless otherwise 7724 indicated by the method definition or explicit cache controls (see 7725 Section 4.2.2 of [CACHING]). 7727 15.5.16. 415 Unsupported Media Type 7729 The _415 (Unsupported Media Type)_ status code indicates that the 7730 origin server is refusing to service the request because the content 7731 is in a format not supported by this method on the target resource. 7733 The format problem might be due to the request's indicated 7734 Content-Type or Content-Encoding, or as a result of inspecting the 7735 data directly. 7737 If the problem was caused by an unsupported content coding, the 7738 Accept-Encoding response header field (Section 12.5.3) ought to be 7739 used to indicate what (if any) content codings would have been 7740 accepted in the request. 7742 On the other hand, if the cause was an unsupported media type, the 7743 Accept response header field (Section 12.5.1) can be used to indicate 7744 what media types would have been accepted in the request. 7746 15.5.17. 416 Range Not Satisfiable 7748 The _416 (Range Not Satisfiable)_ status code indicates that the set 7749 of ranges in the request's Range header field (Section 14.2) has been 7750 rejected either because none of the requested ranges are satisfiable 7751 or because the client has requested an excessive number of small or 7752 overlapping ranges (a potential denial of service attack). 7754 Each range unit defines what is required for its own range sets to be 7755 satisfiable. For example, Section 14.1.2 defines what makes a bytes 7756 range set satisfiable. 7758 A server that generates a 416 response to a byte-range request SHOULD 7759 generate a Content-Range header field specifying the current length 7760 of the selected representation (Section 14.4). 7762 For example: 7764 HTTP/1.1 416 Range Not Satisfiable 7765 Date: Fri, 20 Jan 2012 15:41:54 GMT 7766 Content-Range: bytes */47022 7768 | *Note:* Because servers are free to ignore Range, many 7769 | implementations will respond with the entire selected 7770 | representation in a 200 (OK) response. That is partly because 7771 | most clients are prepared to receive a 200 (OK) to complete the 7772 | task (albeit less efficiently) and partly because clients might 7773 | not stop making an invalid range request until they have 7774 | received a complete representation. Thus, clients cannot 7775 | depend on receiving a 416 (Range Not Satisfiable) response even 7776 | when it is most appropriate. 7778 15.5.18. 417 Expectation Failed 7780 The _417 (Expectation Failed)_ status code indicates that the 7781 expectation given in the request's Expect header field 7782 (Section 10.1.1) could not be met by at least one of the inbound 7783 servers. 7785 15.5.19. 418 (Unused) 7787 [RFC2324] was an April 1 RFC that lampooned the various ways HTTP was 7788 abused; one such abuse was the definition of an application-specific 7789 418 status code. In the intervening years, this status code has been 7790 widely implemented as an "Easter Egg", and therefore is effectively 7791 consumed by this use. 7793 Therefore, the 418 status code is reserved in the IANA HTTP Status 7794 Code Registry. This indicates that the status code cannot be 7795 assigned to other applications currently. If future circumstances 7796 require its use (e.g., exhaustion of 4NN status codes), it can be re- 7797 assigned to another use. 7799 15.5.20. 421 Misdirected Request 7801 The 421 (Misdirected Request) status code indicates that the request 7802 was directed at a server that is unable or unwilling to produce an 7803 authoritative response for the target URI. An origin server (or 7804 gateway acting on behalf of the origin server) sends 421 to reject a 7805 target URI that does not match an origin for which the server has 7806 been configured (Section 4.3.1) or does not match the connection 7807 context over which the request was received (Section 7.4). 7809 A client that receives a 421 (Misdirected Request) response MAY retry 7810 the request, whether or not the request method is idempotent, over a 7811 different connection, such as a fresh connection specific to the 7812 target resource's origin, or via an alternative service [ALTSVC]. 7814 A proxy MUST NOT generate a 421 response. 7816 15.5.21. 422 Unprocessable Content 7818 The 422 (Unprocessable Content) status code indicates that the server 7819 understands the content type of the request content (hence a 415 7820 (Unsupported Media Type) status code is inappropriate), and the 7821 syntax of the request content is correct, but was unable to process 7822 the contained instructions. For example, this status code can be 7823 sent if an XML request content contains well-formed (i.e., 7824 syntactically correct), but semantically erroneous XML instructions. 7826 15.5.22. 426 Upgrade Required 7828 The _426 (Upgrade Required)_ status code indicates that the server 7829 refuses to perform the request using the current protocol but might 7830 be willing to do so after the client upgrades to a different 7831 protocol. The server MUST send an Upgrade header field in a 426 7832 response to indicate the required protocol(s) (Section 7.8). 7834 Example: 7836 HTTP/1.1 426 Upgrade Required 7837 Upgrade: HTTP/3.0 7838 Connection: Upgrade 7839 Content-Length: 53 7840 Content-Type: text/plain 7842 This service requires use of the HTTP/3.0 protocol. 7844 15.6. Server Error 5xx 7846 The _5xx (Server Error)_ class of status code indicates that the 7847 server is aware that it has erred or is incapable of performing the 7848 requested method. Except when responding to a HEAD request, the 7849 server SHOULD send a representation containing an explanation of the 7850 error situation, and whether it is a temporary or permanent 7851 condition. A user agent SHOULD display any included representation 7852 to the user. These response codes are applicable to any request 7853 method. 7855 15.6.1. 500 Internal Server Error 7857 The _500 (Internal Server Error)_ status code indicates that the 7858 server encountered an unexpected condition that prevented it from 7859 fulfilling the request. 7861 15.6.2. 501 Not Implemented 7863 The _501 (Not Implemented)_ status code indicates that the server 7864 does not support the functionality required to fulfill the request. 7865 This is the appropriate response when the server does not recognize 7866 the request method and is not capable of supporting it for any 7867 resource. 7869 A 501 response is heuristically cacheable; i.e., unless otherwise 7870 indicated by the method definition or explicit cache controls (see 7871 Section 4.2.2 of [CACHING]). 7873 15.6.3. 502 Bad Gateway 7875 The _502 (Bad Gateway)_ status code indicates that the server, while 7876 acting as a gateway or proxy, received an invalid response from an 7877 inbound server it accessed while attempting to fulfill the request. 7879 15.6.4. 503 Service Unavailable 7881 The _503 (Service Unavailable)_ status code indicates that the server 7882 is currently unable to handle the request due to a temporary overload 7883 or scheduled maintenance, which will likely be alleviated after some 7884 delay. The server MAY send a Retry-After header field 7885 (Section 10.2.3) to suggest an appropriate amount of time for the 7886 client to wait before retrying the request. 7888 | *Note:* The existence of the 503 status code does not imply 7889 | that a server has to use it when becoming overloaded. Some 7890 | servers might simply refuse the connection. 7892 15.6.5. 504 Gateway Timeout 7894 The _504 (Gateway Timeout)_ status code indicates that the server, 7895 while acting as a gateway or proxy, did not receive a timely response 7896 from an upstream server it needed to access in order to complete the 7897 request. 7899 15.6.6. 505 HTTP Version Not Supported 7901 The _505 (HTTP Version Not Supported)_ status code indicates that the 7902 server does not support, or refuses to support, the major version of 7903 HTTP that was used in the request message. The server is indicating 7904 that it is unable or unwilling to complete the request using the same 7905 major version as the client, as described in Section 2.5, other than 7906 with this error message. The server SHOULD generate a representation 7907 for the 505 response that describes why that version is not supported 7908 and what other protocols are supported by that server. 7910 16. Extending HTTP 7912 HTTP defines a number of generic extension points that can be used to 7913 introduce capabilities to the protocol without introducing a new 7914 version, including methods, status codes, field names, and further 7915 extensibility points within defined fields, such as authentication 7916 schemes and cache-directives (see Cache-Control extensions in 7917 Section 5.2.3 of [CACHING]). Because the semantics of HTTP are not 7918 versioned, these extension points are persistent; the version of the 7919 protocol in use does not affect their semantics. 7921 Version-independent extensions are discouraged from depending on or 7922 interacting with the specific version of the protocol in use. When 7923 this is unavoidable, careful consideration needs to be given to how 7924 the extension can interoperate across versions. 7926 Additionally, specific versions of HTTP might have their own 7927 extensibility points, such as transfer-codings in HTTP/1.1 7928 (Section 6.1 of [HTTP/1.1]) and HTTP/2 ([HTTP/2]) SETTINGS or frame 7929 types. These extension points are specific to the version of the 7930 protocol they occur within. 7932 Version-specific extensions cannot override or modify the semantics 7933 of a version-independent mechanism or extension point (like a method 7934 or header field) without explicitly being allowed by that protocol 7935 element. For example, the CONNECT method (Section 9.3.6) allows 7936 this. 7938 These guidelines assure that the protocol operates correctly and 7939 predictably, even when parts of the path implement different versions 7940 of HTTP. 7942 16.1. Method Extensibility 7944 16.1.1. Method Registry 7946 The "Hypertext Transfer Protocol (HTTP) Method Registry", maintained 7947 by IANA at , registers 7948 method names. 7950 HTTP method registrations MUST include the following fields: 7952 * Method Name (see Section 9) 7954 * Safe ("yes" or "no", see Section 9.2.1) 7956 * Idempotent ("yes" or "no", see Section 9.2.2) 7958 * Pointer to specification text 7960 Values to be added to this namespace require IETF Review (see 7961 [RFC8126], Section 4.8). 7963 16.1.2. Considerations for New Methods 7965 Standardized methods are generic; that is, they are potentially 7966 applicable to any resource, not just one particular media type, kind 7967 of resource, or application. As such, it is preferred that new 7968 methods be registered in a document that isn't specific to a single 7969 application or data format, since orthogonal technologies deserve 7970 orthogonal specification. 7972 Since message parsing (Section 6) needs to be independent of method 7973 semantics (aside from responses to HEAD), definitions of new methods 7974 cannot change the parsing algorithm or prohibit the presence of 7975 content on either the request or the response message. Definitions 7976 of new methods can specify that only a zero-length content is allowed 7977 by requiring a Content-Length header field with a value of "0". 7979 Likewise, new methods cannot use the special host:port and asterisk 7980 forms of request target that are allowed for CONNECT and OPTIONS, 7981 respectively (Section 7.1). A full URI in absolute form is needed 7982 for the target URI, which means either the request target needs to be 7983 sent in absolute form or the target URI will be reconstructed from 7984 the request context in the same way it is for other methods. 7986 A new method definition needs to indicate whether it is safe 7987 (Section 9.2.1), idempotent (Section 9.2.2), cacheable 7988 (Section 9.2.3), what semantics are to be associated with the request 7989 content (if any), and what refinements the method makes to header 7990 field or status code semantics. If the new method is cacheable, its 7991 definition ought to describe how, and under what conditions, a cache 7992 can store a response and use it to satisfy a subsequent request. The 7993 new method ought to describe whether it can be made conditional 7994 (Section 13.1) and, if so, how a server responds when the condition 7995 is false. Likewise, if the new method might have some use for 7996 partial response semantics (Section 14.2), it ought to document this, 7997 too. 7999 | *Note:* Avoid defining a method name that starts with "M-", 8000 | since that prefix might be misinterpreted as having the 8001 | semantics assigned to it by [RFC2774]. 8003 16.2. Status Code Extensibility 8005 16.2.1. Status Code Registry 8007 The "Hypertext Transfer Protocol (HTTP) Status Code Registry", 8008 maintained by IANA at , registers status code numbers. 8011 A registration MUST include the following fields: 8013 * Status Code (3 digits) 8015 * Short Description 8017 * Pointer to specification text 8019 Values to be added to the HTTP status code namespace require IETF 8020 Review (see [RFC8126], Section 4.8). 8022 16.2.2. Considerations for New Status Codes 8024 When it is necessary to express semantics for a response that are not 8025 defined by current status codes, a new status code can be registered. 8026 Status codes are generic; they are potentially applicable to any 8027 resource, not just one particular media type, kind of resource, or 8028 application of HTTP. As such, it is preferred that new status codes 8029 be registered in a document that isn't specific to a single 8030 application. 8032 New status codes are required to fall under one of the categories 8033 defined in Section 15. To allow existing parsers to process the 8034 response message, new status codes cannot disallow content, although 8035 they can mandate a zero-length content. 8037 Proposals for new status codes that are not yet widely deployed ought 8038 to avoid allocating a specific number for the code until there is 8039 clear consensus that it will be registered; instead, early drafts can 8040 use a notation such as "4NN", or "3N0" .. "3N9", to indicate the 8041 class of the proposed status code(s) without consuming a number 8042 prematurely. 8044 The definition of a new status code ought to explain the request 8045 conditions that would cause a response containing that status code 8046 (e.g., combinations of request header fields and/or method(s)) along 8047 with any dependencies on response header fields (e.g., what fields 8048 are required, what fields can modify the semantics, and what field 8049 semantics are further refined when used with the new status code). 8051 By default, a status code applies only to the request corresponding 8052 to the response it occurs within. If a status code applies to a 8053 larger scope of applicability - for example, all requests to the 8054 resource in question, or all requests to a server - this must be 8055 explicitly specified. When doing so, it should be noted that not all 8056 clients can be expected to consistently apply a larger scope, because 8057 they might not understand the new status code. 8059 The definition of a new final status code ought to specify whether or 8060 not it is heuristically cacheable. Note that all final status codes 8061 can be cached if the response they occur in has explicit freshness 8062 information; however, those status codes that are defined as being 8063 heuristically cacheable are allowed to be cached without explicit 8064 freshness information. Likewise, the definition of a status code can 8065 place constraints upon cache behavior, if the 'must-understand' cache 8066 directive is used. See [CACHING] for more information. 8068 Finally, the definition of a new status code ought to indicate 8069 whether the content has any implied association with an identified 8070 resource (Section 6.4.2). 8072 16.3. Field Extensibility 8074 HTTP's most widely used extensibility point is the definition of new 8075 header and trailer fields. 8077 New fields can be defined such that, when they are understood by a 8078 recipient, they override or enhance the interpretation of previously 8079 defined fields, define preconditions on request evaluation, or refine 8080 the meaning of responses. 8082 However, defining a field doesn't guarantee its deployment or 8083 recognition by recipients. Most fields are designed with the 8084 expectation that a recipient can safely ignore (but forward 8085 downstream) any field not recognized. In other cases, the sender's 8086 ability to understand a given field might be indicated by its prior 8087 communication, perhaps in the protocol version or fields that it sent 8088 in prior messages, or its use of a specific media type. Likewise, 8089 direct inspection of support might be possible through an OPTIONS 8090 request or by interacting with a defined well-known URI [RFC8615] if 8091 such inspection is defined along with the field being introduced. 8093 16.3.1. Field Name Registry 8095 The "Hypertext Transfer Protocol (HTTP) Field Name Registry" defines 8096 the namespace for HTTP field names. 8098 Any party can request registration of an HTTP field. See 8099 Section 16.3.2 for considerations to take into account when creating 8100 a new HTTP field. 8102 The "Hypertext Transfer Protocol (HTTP) Field Name Registry" is 8103 located at . 8104 Registration requests can be made by following the instructions 8105 located there or by sending an email to the "ietf-http-wg@w3.org" 8106 mailing list. 8108 Field names are registered on the advice of a Designated Expert 8109 (appointed by the IESG or their delegate). Fields with the status 8110 'permanent' are Specification Required ([RFC8126], Section 4.6). 8112 Registration requests consist of the following information: 8114 Field name: 8115 The requested field name. It MUST conform to the field-name 8116 syntax defined in Section 5.1, and SHOULD be restricted to just 8117 letters, digits, and hyphen ('-') characters, with the first 8118 character being a letter. 8120 Status: 8121 "permanent" or "provisional". 8123 Specification document(s): 8124 Reference to the document that specifies the field, preferably 8125 including a URI that can be used to retrieve a copy of the 8126 document. Optional but encouraged for provisional registrations. 8127 An indication of the relevant section(s) can also be included, but 8128 is not required. 8130 And, optionally: 8132 Comments: Additional information, such as about reserved entries. 8134 The Expert(s) can define additional fields to be collected in the 8135 registry, in consultation with the community. 8137 Standards-defined names have a status of "permanent". Other names 8138 can also be registered as permanent, if the Expert(s) find that they 8139 are in use, in consultation with the community. Other names should 8140 be registered as "provisional". 8142 Provisional entries can be removed by the Expert(s) if - in 8143 consultation with the community - the Expert(s) find that they are 8144 not in use. The Experts can change a provisional entry's status to 8145 permanent at any time. 8147 Note that names can be registered by third parties (including the 8148 Expert(s)), if the Expert(s) determines that an unregistered name is 8149 widely deployed and not likely to be registered in a timely manner 8150 otherwise. 8152 16.3.2. Considerations for New Fields 8154 HTTP header and trailer fields are a widely-used extension point for 8155 the protocol. While they can be used in an ad hoc fashion, fields 8156 that are intended for wider use need to be carefully documented to 8157 ensure interoperability. 8159 In particular, authors of specifications defining new fields are 8160 advised to consider and, where appropriate, document the following 8161 aspects: 8163 * Under what conditions the field can be used; e.g., only in 8164 responses or requests, in all messages, only on responses to a 8165 particular request method, etc. 8167 * Whether the field semantics are further refined by their context, 8168 such as their use with certain request methods or status codes. 8170 * The scope of applicability for the information conveyed. By 8171 default, fields apply only to the message they are associated 8172 with, but some response fields are designed to apply to all 8173 representations of a resource, the resource itself, or an even 8174 broader scope. Specifications that expand the scope of a response 8175 field will need to carefully consider issues such as content 8176 negotiation, the time period of applicability, and (in some cases) 8177 multi-tenant server deployments. 8179 * Under what conditions intermediaries are allowed to insert, 8180 delete, or modify the field's value. 8182 * If the field is allowable in trailers; by default, it will not be 8183 (see Section 6.5.1). 8185 * Whether it is appropriate or even required to list the field name 8186 in the Connection header field (i.e., if the field is to be hop- 8187 by-hop; see Section 7.6.1). 8189 * Whether the field introduces any additional security 8190 considerations, such as disclosure of privacy-related data. 8192 Request header fields have additional considerations that need to be 8193 documented if the default behaviour is not appropriate: 8195 * If it is appropriate to list the field name in a Vary response 8196 header field (e.g., when the request header field is used by an 8197 origin server's content selection algorithm; see Section 12.5.5). 8199 * If the field is intended to be stored when received in a PUT 8200 request (see Section 9.3.4). 8202 * If the field ought to be removed when automatically redirecting a 8203 request, due to security concerns (see Section 15.4). 8205 16.3.2.1. Considerations for New Field Names 8207 Authors of specifications defining new fields are advised to choose a 8208 short but descriptive field name. Short names avoid needless data 8209 transmission; descriptive names avoid confusion and "squatting" on 8210 names that might have broader uses. 8212 To that end, limited-use fields (such as a header confined to a 8213 single application or use case) are encouraged to use a name that 8214 includes that use (or an abbreviation) as a prefix; for example, if 8215 the Foo Application needs a Description field, it might use "Foo- 8216 Desc"; "Description" is too generic, and "Foo-Description" is 8217 needlessly long. 8219 While the field-name syntax is defined to allow any token character, 8220 in practice some implementations place limits on the characters they 8221 accept in field-names. To be interoperable, new field names SHOULD 8222 constrain themselves to alphanumeric characters, "-", and ".", and 8223 SHOULD begin with a letter. For example, the underscore ("_") 8224 character can be problematic when passed through non-HTTP gateway 8225 interfaces (see Section 17.10). 8227 Field names ought not be prefixed with "X-"; see [BCP178] for further 8228 information. 8230 Other prefixes are sometimes used in HTTP field names; for example, 8231 "Accept-" is used in many content negotiation headers, and "Content-" 8232 is used as explained in Section 6.4. These prefixes are only an aid 8233 to recognizing the purpose of a field, and do not trigger automatic 8234 processing. 8236 16.3.2.2. Considerations for New Field Values 8238 A major task in the definition of a new HTTP field is the 8239 specification of the field value syntax: what senders should 8240 generate, and how recipients should infer semantics from what is 8241 received. 8243 Authors are encouraged (but not required) to use either the ABNF 8244 rules in this specification or those in [RFC8941] to define the 8245 syntax of new field values. 8247 Authors are advised to carefully consider how the combination of 8248 multiple field lines will impact them (see Section 5.3). Because 8249 senders might erroneously send multiple values, and both 8250 intermediaries and HTTP libraries can perform combination 8251 automatically, this applies to all field values - even when only a 8252 single value is anticipated. 8254 Therefore, authors are advised to delimit or encode values that 8255 contain commas (e.g., with the quoted-string rule of Section 5.6.4, 8256 the String data type of [RFC8941], or a field-specific encoding). 8257 This ensures that commas within field data are not confused with the 8258 commas that delimit a list value. 8260 For example, the Content-Type field value only allows commas inside 8261 quoted strings, which can be reliably parsed even when multiple 8262 values are present. The Location field value provides a counter- 8263 example that should not be emulated: because URIs can include commas, 8264 it is not possible to reliably distinguish between a single value 8265 that includes a comma from two values. 8267 Authors of fields with a singleton value (see Section 5.5) are 8268 additionally advised to document how to treat messages where the 8269 multiple members are present (a sensible default would be to ignore 8270 the field, but this might not always be the right choice). 8272 16.4. Authentication Scheme Extensibility 8274 16.4.1. Authentication Scheme Registry 8276 The "Hypertext Transfer Protocol (HTTP) Authentication Scheme 8277 Registry" defines the namespace for the authentication schemes in 8278 challenges and credentials. It is maintained at 8279 . 8281 Registrations MUST include the following fields: 8283 * Authentication Scheme Name 8285 * Pointer to specification text 8287 * Notes (optional) 8289 Values to be added to this namespace require IETF Review (see 8290 [RFC8126], Section 4.8). 8292 16.4.2. Considerations for New Authentication Schemes 8294 There are certain aspects of the HTTP Authentication framework that 8295 put constraints on how new authentication schemes can work: 8297 * HTTP authentication is presumed to be stateless: all of the 8298 information necessary to authenticate a request MUST be provided 8299 in the request, rather than be dependent on the server remembering 8300 prior requests. Authentication based on, or bound to, the 8301 underlying connection is outside the scope of this specification 8302 and inherently flawed unless steps are taken to ensure that the 8303 connection cannot be used by any party other than the 8304 authenticated user (see Section 3.3). 8306 * The authentication parameter "realm" is reserved for defining 8307 protection spaces as described in Section 11.5. New schemes MUST 8308 NOT use it in a way incompatible with that definition. 8310 * The "token68" notation was introduced for compatibility with 8311 existing authentication schemes and can only be used once per 8312 challenge or credential. Thus, new schemes ought to use the auth- 8313 param syntax instead, because otherwise future extensions will be 8314 impossible. 8316 * The parsing of challenges and credentials is defined by this 8317 specification and cannot be modified by new authentication 8318 schemes. When the auth-param syntax is used, all parameters ought 8319 to support both token and quoted-string syntax, and syntactical 8320 constraints ought to be defined on the field value after parsing 8321 (i.e., quoted-string processing). This is necessary so that 8322 recipients can use a generic parser that applies to all 8323 authentication schemes. 8325 *Note:* The fact that the value syntax for the "realm" parameter 8326 is restricted to quoted-string was a bad design choice not to be 8327 repeated for new parameters. 8329 * Definitions of new schemes ought to define the treatment of 8330 unknown extension parameters. In general, a "must-ignore" rule is 8331 preferable to a "must-understand" rule, because otherwise it will 8332 be hard to introduce new parameters in the presence of legacy 8333 recipients. Furthermore, it's good to describe the policy for 8334 defining new parameters (such as "update the specification" or 8335 "use this registry"). 8337 * Authentication schemes need to document whether they are usable in 8338 origin-server authentication (i.e., using WWW-Authenticate), and/ 8339 or proxy authentication (i.e., using Proxy-Authenticate). 8341 * The credentials carried in an Authorization header field are 8342 specific to the user agent and, therefore, have the same effect on 8343 HTTP caches as the "private" Cache-Control response directive 8344 (Section 5.2.2.7 of [CACHING]), within the scope of the request in 8345 which they appear. 8347 Therefore, new authentication schemes that choose not to carry 8348 credentials in the Authorization header field (e.g., using a newly 8349 defined header field) will need to explicitly disallow caching, by 8350 mandating the use of Cache-Control response directives (e.g., 8351 "private"). 8353 * Schemes using Authentication-Info, Proxy-Authentication-Info, or 8354 any other authentication related response header field need to 8355 consider and document the related security considerations (see 8356 Section 17.16.4). 8358 16.5. Range Unit Extensibility 8359 16.5.1. Range Unit Registry 8361 The "HTTP Range Unit Registry" defines the namespace for the range 8362 unit names and refers to their corresponding specifications. It is 8363 maintained at . 8365 Registration of an HTTP Range Unit MUST include the following fields: 8367 * Name 8369 * Description 8371 * Pointer to specification text 8373 Values to be added to this namespace require IETF Review (see 8374 [RFC8126], Section 4.8). 8376 16.5.2. Considerations for New Range Units 8378 Other range units, such as format-specific boundaries like pages, 8379 sections, records, rows, or time, are potentially usable in HTTP for 8380 application-specific purposes, but are not commonly used in practice. 8381 Implementors of alternative range units ought to consider how they 8382 would work with content codings and general-purpose intermediaries. 8384 16.6. Content Coding Extensibility 8386 16.6.1. Content Coding Registry 8388 The "HTTP Content Coding Registry", maintained by IANA at 8389 , registers 8390 content-coding names. 8392 Content coding registrations MUST include the following fields: 8394 * Name 8396 * Description 8398 * Pointer to specification text 8400 Names of content codings MUST NOT overlap with names of transfer 8401 codings (as per the "HTTP Transfer Coding registry", located at 8402 ), unless the 8403 encoding transformation is identical (as is the case for the 8404 compression codings defined in Section 8.4.1). 8406 Values to be added to this namespace require IETF Review (see 8407 Section 4.8 of [RFC8126]) and MUST conform to the purpose of content 8408 coding defined in Section 8.4.1. 8410 16.6.2. Considerations for New Content Codings 8412 New content codings ought to be self-descriptive whenever possible, 8413 with optional parameters discoverable within the coding format 8414 itself, rather than rely on external metadata that might be lost 8415 during transit. 8417 16.7. Upgrade Token Registry 8419 The "Hypertext Transfer Protocol (HTTP) Upgrade Token Registry" 8420 defines the namespace for protocol-name tokens used to identify 8421 protocols in the Upgrade header field. The registry is maintained at 8422 . 8424 Each registered protocol name is associated with contact information 8425 and an optional set of specifications that details how the connection 8426 will be processed after it has been upgraded. 8428 Registrations happen on a "First Come First Served" basis (see 8429 Section 4.4 of [RFC8126]) and are subject to the following rules: 8431 1. A protocol-name token, once registered, stays registered forever. 8433 2. A protocol-name token is case-insensitive and registered with the 8434 preferred case to be generated by senders. 8436 3. The registration MUST name a responsible party for the 8437 registration. 8439 4. The registration MUST name a point of contact. 8441 5. The registration MAY name a set of specifications associated with 8442 that token. Such specifications need not be publicly available. 8444 6. The registration SHOULD name a set of expected "protocol-version" 8445 tokens associated with that token at the time of registration. 8447 7. The responsible party MAY change the registration at any time. 8448 The IANA will keep a record of all such changes, and make them 8449 available upon request. 8451 8. The IESG MAY reassign responsibility for a protocol token. This 8452 will normally only be used in the case when a responsible party 8453 cannot be contacted. 8455 17. Security Considerations 8457 This section is meant to inform developers, information providers, 8458 and users of known security concerns relevant to HTTP semantics and 8459 its use for transferring information over the Internet. 8460 Considerations related to caching are discussed in Section 7 of 8461 [CACHING] and considerations related to HTTP/1.1 message syntax and 8462 parsing are discussed in Section 11 of [HTTP/1.1]. 8464 The list of considerations below is not exhaustive. Most security 8465 concerns related to HTTP semantics are about securing server-side 8466 applications (code behind the HTTP interface), securing user agent 8467 processing of content received via HTTP, or secure use of the 8468 Internet in general, rather than security of the protocol. Various 8469 organizations maintain topical information and links to current 8470 research on Web application security (e.g., [OWASP]). 8472 17.1. Establishing Authority 8474 HTTP relies on the notion of an _authoritative response_: a response 8475 that has been determined by (or at the direction of) the origin 8476 server identified within the target URI to be the most appropriate 8477 response for that request given the state of the target resource at 8478 the time of response message origination. 8480 When a registered name is used in the authority component, the "http" 8481 URI scheme (Section 4.2.1) relies on the user's local name resolution 8482 service to determine where it can find authoritative responses. This 8483 means that any attack on a user's network host table, cached names, 8484 or name resolution libraries becomes an avenue for attack on 8485 establishing authority for "http" URIs. Likewise, the user's choice 8486 of server for Domain Name Service (DNS), and the hierarchy of servers 8487 from which it obtains resolution results, could impact the 8488 authenticity of address mappings; DNS Security Extensions (DNSSEC, 8489 [RFC4033]) are one way to improve authenticity, as are the various 8490 mechanisms for making DNS requests over more secure transfer 8491 protocols. 8493 Furthermore, after an IP address is obtained, establishing authority 8494 for an "http" URI is vulnerable to attacks on Internet Protocol 8495 routing. 8497 The "https" scheme (Section 4.2.2) is intended to prevent (or at 8498 least reveal) many of these potential attacks on establishing 8499 authority, provided that the negotiated connection is secured and the 8500 client properly verifies that the communicating server's identity 8501 matches the target URI's authority component (Section 4.3.4). 8502 Correctly implementing such verification can be difficult (see 8503 [Georgiev]). 8505 Authority for a given origin server can be delegated through protocol 8506 extensions; for example, [ALTSVC]. Likewise, the set of servers for 8507 which a connection is considered authoritative can be changed with a 8508 protocol extension like [RFC8336]. 8510 Providing a response from a non-authoritative source, such as a 8511 shared proxy cache, is often useful to improve performance and 8512 availability, but only to the extent that the source can be trusted 8513 or the distrusted response can be safely used. 8515 Unfortunately, communicating authority to users can be difficult. 8516 For example, _phishing_ is an attack on the user's perception of 8517 authority, where that perception can be misled by presenting similar 8518 branding in hypertext, possibly aided by userinfo obfuscating the 8519 authority component (see Section 4.2.1). User agents can reduce the 8520 impact of phishing attacks by enabling users to easily inspect a 8521 target URI prior to making an action, by prominently distinguishing 8522 (or rejecting) userinfo when present, and by not sending stored 8523 credentials and cookies when the referring document is from an 8524 unknown or untrusted source. 8526 17.2. Risks of Intermediaries 8528 HTTP intermediaries are inherently situated for on-path attacks. 8529 Compromise of the systems on which the intermediaries run can result 8530 in serious security and privacy problems. Intermediaries might have 8531 access to security-related information, personal information about 8532 individual users and organizations, and proprietary information 8533 belonging to users and content providers. A compromised 8534 intermediary, or an intermediary implemented or configured without 8535 regard to security and privacy considerations, might be used in the 8536 commission of a wide range of potential attacks. 8538 Intermediaries that contain a shared cache are especially vulnerable 8539 to cache poisoning attacks, as described in Section 7 of [CACHING]. 8541 Implementers need to consider the privacy and security implications 8542 of their design and coding decisions, and of the configuration 8543 options they provide to operators (especially the default 8544 configuration). 8546 Intermediaries are no more trustworthy than the people and policies 8547 under which they operate; HTTP cannot solve this problem. 8549 17.3. Attacks Based on File and Path Names 8551 Origin servers frequently make use of their local file system to 8552 manage the mapping from target URI to resource representations. Most 8553 file systems are not designed to protect against malicious file or 8554 path names. Therefore, an origin server needs to avoid accessing 8555 names that have a special significance to the system when mapping the 8556 target resource to files, folders, or directories. 8558 For example, UNIX, Microsoft Windows, and other operating systems use 8559 ".." as a path component to indicate a directory level above the 8560 current one, and they use specially named paths or file names to send 8561 data to system devices. Similar naming conventions might exist 8562 within other types of storage systems. Likewise, local storage 8563 systems have an annoying tendency to prefer user-friendliness over 8564 security when handling invalid or unexpected characters, 8565 recomposition of decomposed characters, and case-normalization of 8566 case-insensitive names. 8568 Attacks based on such special names tend to focus on either denial- 8569 of-service (e.g., telling the server to read from a COM port) or 8570 disclosure of configuration and source files that are not meant to be 8571 served. 8573 17.4. Attacks Based on Command, Code, or Query Injection 8575 Origin servers often use parameters within the URI as a means of 8576 identifying system services, selecting database entries, or choosing 8577 a data source. However, data received in a request cannot be 8578 trusted. An attacker could construct any of the request data 8579 elements (method, target URI, header fields, or content) to contain 8580 data that might be misinterpreted as a command, code, or query when 8581 passed through a command invocation, language interpreter, or 8582 database interface. 8584 For example, SQL injection is a common attack wherein additional 8585 query language is inserted within some part of the target URI or 8586 header fields (e.g., Host, Referer, etc.). If the received data is 8587 used directly within a SELECT statement, the query language might be 8588 interpreted as a database command instead of a simple string value. 8589 This type of implementation vulnerability is extremely common, in 8590 spite of being easy to prevent. 8592 In general, resource implementations ought to avoid use of request 8593 data in contexts that are processed or interpreted as instructions. 8594 Parameters ought to be compared to fixed strings and acted upon as a 8595 result of that comparison, rather than passed through an interface 8596 that is not prepared for untrusted data. Received data that isn't 8597 based on fixed parameters ought to be carefully filtered or encoded 8598 to avoid being misinterpreted. 8600 Similar considerations apply to request data when it is stored and 8601 later processed, such as within log files, monitoring tools, or when 8602 included within a data format that allows embedded scripts. 8604 17.5. Attacks via Protocol Element Length 8606 Because HTTP uses mostly textual, character-delimited fields, parsers 8607 are often vulnerable to attacks based on sending very long (or very 8608 slow) streams of data, particularly where an implementation is 8609 expecting a protocol element with no predefined length (Section 2.3). 8611 To promote interoperability, specific recommendations are made for 8612 minimum size limits on fields (Section 5.4). These are minimum 8613 recommendations, chosen to be supportable even by implementations 8614 with limited resources; it is expected that most implementations will 8615 choose substantially higher limits. 8617 A server can reject a message that has a target URI that is too long 8618 (Section 15.5.15) or request content that is too large 8619 (Section 15.5.14). Additional status codes related to capacity 8620 limits have been defined by extensions to HTTP [RFC6585]. 8622 Recipients ought to carefully limit the extent to which they process 8623 other protocol elements, including (but not limited to) request 8624 methods, response status phrases, field names, numeric values, and 8625 chunk lengths. Failure to limit such processing can result in 8626 arbitrary code execution due to buffer or arithmetic overflows, and 8627 increased vulnerability to denial-of-service attacks. 8629 17.6. Attacks using Shared-dictionary Compression 8631 Some attacks on encrypted protocols use the differences in size 8632 created by dynamic compression to reveal confidential information; 8633 for example, [BREACH]. These attacks rely on creating a redundancy 8634 between attacker-controlled content and the confidential information, 8635 such that a dynamic compression algorithm using the same dictionary 8636 for both content will compress more efficiently when the attacker- 8637 controlled content matches parts of the confidential content. 8639 HTTP messages can be compressed in a number of ways, including using 8640 TLS compression, content codings, transfer codings, and other 8641 extension or version-specific mechanisms. 8643 The most effective mitigation for this risk is to disable compression 8644 on sensitive data, or to strictly separate sensitive data from 8645 attacker-controlled data so that they cannot share the same 8646 compression dictionary. With careful design, a compression scheme 8647 can be designed in a way that is not considered exploitable in 8648 limited use cases, such as HPACK ([HPACK]). 8650 17.7. Disclosure of Personal Information 8652 Clients are often privy to large amounts of personal information, 8653 including both information provided by the user to interact with 8654 resources (e.g., the user's name, location, mail address, passwords, 8655 encryption keys, etc.) and information about the user's browsing 8656 activity over time (e.g., history, bookmarks, etc.). Implementations 8657 need to prevent unintentional disclosure of personal information. 8659 17.8. Privacy of Server Log Information 8661 A server is in the position to save personal data about a user's 8662 requests over time, which might identify their reading patterns or 8663 subjects of interest. In particular, log information gathered at an 8664 intermediary often contains a history of user agent interaction, 8665 across a multitude of sites, that can be traced to individual users. 8667 HTTP log information is confidential in nature; its handling is often 8668 constrained by laws and regulations. Log information needs to be 8669 securely stored and appropriate guidelines followed for its analysis. 8670 Anonymization of personal information within individual entries 8671 helps, but it is generally not sufficient to prevent real log traces 8672 from being re-identified based on correlation with other access 8673 characteristics. As such, access traces that are keyed to a specific 8674 client are unsafe to publish even if the key is pseudonymous. 8676 To minimize the risk of theft or accidental publication, log 8677 information ought to be purged of personally identifiable 8678 information, including user identifiers, IP addresses, and user- 8679 provided query parameters, as soon as that information is no longer 8680 necessary to support operational needs for security, auditing, or 8681 fraud control. 8683 17.9. Disclosure of Sensitive Information in URIs 8685 URIs are intended to be shared, not secured, even when they identify 8686 secure resources. URIs are often shown on displays, added to 8687 templates when a page is printed, and stored in a variety of 8688 unprotected bookmark lists. Many servers, proxies, and user agents 8689 log or display the target URI in places where it might be visible to 8690 third parties. It is therefore unwise to include information within 8691 a URI that is sensitive, personally identifiable, or a risk to 8692 disclose. 8694 When an application uses client-side mechanisms to construct a target 8695 URI out of user-provided information, such as the query fields of a 8696 form using GET, potentially sensitive data might be provided that 8697 would not be appropriate for disclosure within a URI. POST is often 8698 preferred in such cases because it usually doesn't construct a URI; 8699 instead, POST of a form transmits the potentially sensitive data in 8700 the request content. However, this hinders caching and uses an 8701 unsafe method for what would otherwise be a safe request. 8702 Alternative workarounds include transforming the user-provided data 8703 prior to constructing the URI, or filtering the data to only include 8704 common values that are not sensitive. Likewise, redirecting the 8705 result of a query to a different (server-generated) URI can remove 8706 potentially sensitive data from later links and provide a cacheable 8707 response for later reuse. 8709 Since the Referer header field tells a target site about the context 8710 that resulted in a request, it has the potential to reveal 8711 information about the user's immediate browsing history and any 8712 personal information that might be found in the referring resource's 8713 URI. Limitations on the Referer header field are described in 8714 Section 10.1.3 to address some of its security considerations. 8716 17.10. Application Handling of Field Names 8718 Servers often use non-HTTP gateway interfaces and frameworks to 8719 process a received request and produce content for the response. For 8720 historical reasons, such interfaces often pass received field names 8721 as external variable names, using a name mapping suitable for 8722 environment variables. 8724 For example, the Common Gateway Interface (CGI) mapping of protocol- 8725 specific meta-variables, defined by Section 4.1.18 of [RFC3875], is 8726 applied to received header fields that do not correspond to one of 8727 CGI's standard variables; the mapping consists of prepending "HTTP_" 8728 to each name and changing all instances of hyphen ("-") to underscore 8729 ("_"). This same mapping has been inherited by many other 8730 application frameworks in order to simplify moving applications from 8731 one platform to the next. 8733 In CGI, a received Content-Length field would be passed as the meta- 8734 variable "CONTENT_LENGTH" with a string value matching the received 8735 field's value. In contrast, a received "Content_Length" header field 8736 would be passed as the protocol-specific meta-variable 8737 "HTTP_CONTENT_LENGTH", which might lead to some confusion if an 8738 application mistakenly reads the protocol-specific meta-variable 8739 instead of the default one. (This historical practice is why 8740 Section 16.3.2.1 discourages the creation of new field names that 8741 contain an underscore.) 8743 Unfortunately, mapping field names to different interface names can 8744 lead to security vulnerabilities if the mapping is incomplete or 8745 ambiguous. For example, if an attacker were to send a field named 8746 "Transfer_Encoding", a naive interface might map that to the same 8747 variable name as the "Transfer-Encoding" field, resulting in a 8748 potential request smuggling vulnerability (Section 11.2 of 8749 [HTTP/1.1]). 8751 To mitigate the associated risks, implementations that perform such 8752 mappings are advised to make the mapping unambiguous and complete for 8753 the full range of potential octets received as a name (including 8754 those that are discouraged or forbidden by the HTTP grammar). For 8755 example, a field with an unusual name character might result in the 8756 request being blocked, the specific field being removed, or the name 8757 being passed with a different prefix to distinguish it from other 8758 fields. 8760 17.11. Disclosure of Fragment after Redirects 8762 Although fragment identifiers used within URI references are not sent 8763 in requests, implementers ought to be aware that they will be visible 8764 to the user agent and any extensions or scripts running as a result 8765 of the response. In particular, when a redirect occurs and the 8766 original request's fragment identifier is inherited by the new 8767 reference in Location (Section 10.2.2), this might have the effect of 8768 disclosing one site's fragment to another site. If the first site 8769 uses personal information in fragments, it ought to ensure that 8770 redirects to other sites include a (possibly empty) fragment 8771 component in order to block that inheritance. 8773 17.12. Disclosure of Product Information 8775 The User-Agent (Section 10.1.5), Via (Section 7.6.3), and Server 8776 (Section 10.2.4) header fields often reveal information about the 8777 respective sender's software systems. In theory, this can make it 8778 easier for an attacker to exploit known security holes; in practice, 8779 attackers tend to try all potential holes regardless of the apparent 8780 software versions being used. 8782 Proxies that serve as a portal through a network firewall ought to 8783 take special precautions regarding the transfer of header information 8784 that might identify hosts behind the firewall. The Via header field 8785 allows intermediaries to replace sensitive machine names with 8786 pseudonyms. 8788 17.13. Browser Fingerprinting 8790 Browser fingerprinting is a set of techniques for identifying a 8791 specific user agent over time through its unique set of 8792 characteristics. These characteristics might include information 8793 related to how it uses the underlying transport protocol, feature 8794 capabilities, and scripting environment, though of particular 8795 interest here is the set of unique characteristics that might be 8796 communicated via HTTP. Fingerprinting is considered a privacy 8797 concern because it enables tracking of a user agent's behavior over 8798 time ([Bujlow]) without the corresponding controls that the user 8799 might have over other forms of data collection (e.g., cookies). Many 8800 general-purpose user agents (i.e., Web browsers) have taken steps to 8801 reduce their fingerprints. 8803 There are a number of request header fields that might reveal 8804 information to servers that is sufficiently unique to enable 8805 fingerprinting. The From header field is the most obvious, though it 8806 is expected that From will only be sent when self-identification is 8807 desired by the user. Likewise, Cookie header fields are deliberately 8808 designed to enable re-identification, so fingerprinting concerns only 8809 apply to situations where cookies are disabled or restricted by the 8810 user agent's configuration. 8812 The User-Agent header field might contain enough information to 8813 uniquely identify a specific device, usually when combined with other 8814 characteristics, particularly if the user agent sends excessive 8815 details about the user's system or extensions. However, the source 8816 of unique information that is least expected by users is proactive 8817 negotiation (Section 12.1), including the Accept, Accept-Charset, 8818 Accept-Encoding, and Accept-Language header fields. 8820 In addition to the fingerprinting concern, detailed use of the 8821 Accept-Language header field can reveal information the user might 8822 consider to be of a private nature. For example, understanding a 8823 given language set might be strongly correlated to membership in a 8824 particular ethnic group. An approach that limits such loss of 8825 privacy would be for a user agent to omit the sending of Accept- 8826 Language except for sites that have been explicitly permitted, 8827 perhaps via interaction after detecting a Vary header field that 8828 indicates language negotiation might be useful. 8830 In environments where proxies are used to enhance privacy, user 8831 agents ought to be conservative in sending proactive negotiation 8832 header fields. General-purpose user agents that provide a high 8833 degree of header field configurability ought to inform users about 8834 the loss of privacy that might result if too much detail is provided. 8835 As an extreme privacy measure, proxies could filter the proactive 8836 negotiation header fields in relayed requests. 8838 17.14. Validator Retention 8840 The validators defined by this specification are not intended to 8841 ensure the validity of a representation, guard against malicious 8842 changes, or detect on-path attacks. At best, they enable more 8843 efficient cache updates and optimistic concurrent writes when all 8844 participants are behaving nicely. At worst, the conditions will fail 8845 and the client will receive a response that is no more harmful than 8846 an HTTP exchange without conditional requests. 8848 An entity-tag can be abused in ways that create privacy risks. For 8849 example, a site might deliberately construct a semantically invalid 8850 entity-tag that is unique to the user or user agent, send it in a 8851 cacheable response with a long freshness time, and then read that 8852 entity-tag in later conditional requests as a means of re-identifying 8853 that user or user agent. Such an identifying tag would become a 8854 persistent identifier for as long as the user agent retained the 8855 original cache entry. User agents that cache representations ought 8856 to ensure that the cache is cleared or replaced whenever the user 8857 performs privacy-maintaining actions, such as clearing stored cookies 8858 or changing to a private browsing mode. 8860 17.15. Denial-of-Service Attacks Using Range 8862 Unconstrained multiple range requests are susceptible to denial-of- 8863 service attacks because the effort required to request many 8864 overlapping ranges of the same data is tiny compared to the time, 8865 memory, and bandwidth consumed by attempting to serve the requested 8866 data in many parts. Servers ought to ignore, coalesce, or reject 8867 egregious range requests, such as requests for more than two 8868 overlapping ranges or for many small ranges in a single set, 8869 particularly when the ranges are requested out of order for no 8870 apparent reason. Multipart range requests are not designed to 8871 support random access. 8873 17.16. Authentication Considerations 8875 Everything about the topic of HTTP authentication is a security 8876 consideration, so the list of considerations below is not exhaustive. 8877 Furthermore, it is limited to security considerations regarding the 8878 authentication framework, in general, rather than discussing all of 8879 the potential considerations for specific authentication schemes 8880 (which ought to be documented in the specifications that define those 8881 schemes). Various organizations maintain topical information and 8882 links to current research on Web application security (e.g., 8883 [OWASP]), including common pitfalls for implementing and using the 8884 authentication schemes found in practice. 8886 17.16.1. Confidentiality of Credentials 8888 The HTTP authentication framework does not define a single mechanism 8889 for maintaining the confidentiality of credentials; instead, each 8890 authentication scheme defines how the credentials are encoded prior 8891 to transmission. While this provides flexibility for the development 8892 of future authentication schemes, it is inadequate for the protection 8893 of existing schemes that provide no confidentiality on their own, or 8894 that do not sufficiently protect against replay attacks. 8895 Furthermore, if the server expects credentials that are specific to 8896 each individual user, the exchange of those credentials will have the 8897 effect of identifying that user even if the content within 8898 credentials remains confidential. 8900 HTTP depends on the security properties of the underlying transport- 8901 or session-level connection to provide confidential transmission of 8902 fields. Services that depend on individual user authentication 8903 require a secured connection prior to exchanging credentials 8904 (Section 4.2.2). 8906 17.16.2. Credentials and Idle Clients 8908 Existing HTTP clients and user agents typically retain authentication 8909 information indefinitely. HTTP does not provide a mechanism for the 8910 origin server to direct clients to discard these cached credentials, 8911 since the protocol has no awareness of how credentials are obtained 8912 or managed by the user agent. The mechanisms for expiring or 8913 revoking credentials can be specified as part of an authentication 8914 scheme definition. 8916 Circumstances under which credential caching can interfere with the 8917 application's security model include but are not limited to: 8919 * Clients that have been idle for an extended period, following 8920 which the server might wish to cause the client to re-prompt the 8921 user for credentials. 8923 * Applications that include a session termination indication (such 8924 as a "logout" or "commit" button on a page) after which the server 8925 side of the application "knows" that there is no further reason 8926 for the client to retain the credentials. 8928 User agents that cache credentials are encouraged to provide a 8929 readily accessible mechanism for discarding cached credentials under 8930 user control. 8932 17.16.3. Protection Spaces 8934 Authentication schemes that solely rely on the "realm" mechanism for 8935 establishing a protection space will expose credentials to all 8936 resources on an origin server. Clients that have successfully made 8937 authenticated requests with a resource can use the same 8938 authentication credentials for other resources on the same origin 8939 server. This makes it possible for a different resource to harvest 8940 authentication credentials for other resources. 8942 This is of particular concern when an origin server hosts resources 8943 for multiple parties under the same origin (Section 11.5). Possible 8944 mitigation strategies include restricting direct access to 8945 authentication credentials (i.e., not making the content of the 8946 Authorization request header field available), and separating 8947 protection spaces by using a different host name (or port number) for 8948 each party. 8950 17.16.4. Additional Response Fields 8952 Adding information to responses that are sent over an unencrypted 8953 channel can affect security and privacy. The presence of the 8954 Authentication-Info and Proxy-Authentication-Info header fields alone 8955 indicates that HTTP authentication is in use. Additional information 8956 could be exposed by the contents of the authentication-scheme 8957 specific parameters; this will have to be considered in the 8958 definitions of these schemes. 8960 18. IANA Considerations 8962 The change controller for the following registrations is: "IETF 8963 (iesg@ietf.org) - Internet Engineering Task Force". 8965 18.1. URI Scheme Registration 8967 Please update the registry of URI Schemes [BCP35] at 8968 with the permanent 8969 schemes listed in the table in Section 4.2. 8971 18.2. Method Registration 8973 Please update the "Hypertext Transfer Protocol (HTTP) Method 8974 Registry" at with the 8975 registration procedure of Section 16.1.1 and the method names 8976 summarized in the following table. 8978 +=========+======+============+=======+ 8979 | Method | Safe | Idempotent | Ref. | 8980 +=========+======+============+=======+ 8981 | CONNECT | no | no | 9.3.6 | 8982 +---------+------+------------+-------+ 8983 | DELETE | no | yes | 9.3.5 | 8984 +---------+------+------------+-------+ 8985 | GET | yes | yes | 9.3.1 | 8986 +---------+------+------------+-------+ 8987 | HEAD | yes | yes | 9.3.2 | 8988 +---------+------+------------+-------+ 8989 | OPTIONS | yes | yes | 9.3.7 | 8990 +---------+------+------------+-------+ 8991 | POST | no | no | 9.3.3 | 8992 +---------+------+------------+-------+ 8993 | PUT | no | yes | 9.3.4 | 8994 +---------+------+------------+-------+ 8995 | TRACE | yes | yes | 9.3.8 | 8996 +---------+------+------------+-------+ 8997 | * | no | no | 18.2 | 8998 +---------+------+------------+-------+ 9000 Table 7 9002 The method name "*" is reserved, since using "*" as a method name 9003 would conflict with its usage as a wildcard in some fields (e.g., 9004 "Access-Control-Request-Method"). 9006 18.3. Status Code Registration 9008 Please update the "Hypertext Transfer Protocol (HTTP) Status Code 9009 Registry" at 9010 with the registration procedure of Section 16.2.1 and the status code 9011 values summarized in the following table. 9013 +=======+===============================+=========+ 9014 | Value | Description | Ref. | 9015 +=======+===============================+=========+ 9016 | 100 | Continue | 15.2.1 | 9017 +-------+-------------------------------+---------+ 9018 | 101 | Switching Protocols | 15.2.2 | 9019 +-------+-------------------------------+---------+ 9020 | 200 | OK | 15.3.1 | 9021 +-------+-------------------------------+---------+ 9022 | 201 | Created | 15.3.2 | 9023 +-------+-------------------------------+---------+ 9024 | 202 | Accepted | 15.3.3 | 9025 +-------+-------------------------------+---------+ 9026 | 203 | Non-Authoritative Information | 15.3.4 | 9027 +-------+-------------------------------+---------+ 9028 | 204 | No Content | 15.3.5 | 9029 +-------+-------------------------------+---------+ 9030 | 205 | Reset Content | 15.3.6 | 9031 +-------+-------------------------------+---------+ 9032 | 206 | Partial Content | 15.3.7 | 9033 +-------+-------------------------------+---------+ 9034 | 300 | Multiple Choices | 15.4.1 | 9035 +-------+-------------------------------+---------+ 9036 | 301 | Moved Permanently | 15.4.2 | 9037 +-------+-------------------------------+---------+ 9038 | 302 | Found | 15.4.3 | 9039 +-------+-------------------------------+---------+ 9040 | 303 | See Other | 15.4.4 | 9041 +-------+-------------------------------+---------+ 9042 | 304 | Not Modified | 15.4.5 | 9043 +-------+-------------------------------+---------+ 9044 | 305 | Use Proxy | 15.4.6 | 9045 +-------+-------------------------------+---------+ 9046 | 306 | (Unused) | 15.4.7 | 9047 +-------+-------------------------------+---------+ 9048 | 307 | Temporary Redirect | 15.4.8 | 9049 +-------+-------------------------------+---------+ 9050 | 308 | Permanent Redirect | 15.4.9 | 9051 +-------+-------------------------------+---------+ 9052 | 400 | Bad Request | 15.5.1 | 9053 +-------+-------------------------------+---------+ 9054 | 401 | Unauthorized | 15.5.2 | 9055 +-------+-------------------------------+---------+ 9056 | 402 | Payment Required | 15.5.3 | 9057 +-------+-------------------------------+---------+ 9058 | 403 | Forbidden | 15.5.4 | 9059 +-------+-------------------------------+---------+ 9060 | 404 | Not Found | 15.5.5 | 9061 +-------+-------------------------------+---------+ 9062 | 405 | Method Not Allowed | 15.5.6 | 9063 +-------+-------------------------------+---------+ 9064 | 406 | Not Acceptable | 15.5.7 | 9065 +-------+-------------------------------+---------+ 9066 | 407 | Proxy Authentication Required | 15.5.8 | 9067 +-------+-------------------------------+---------+ 9068 | 408 | Request Timeout | 15.5.9 | 9069 +-------+-------------------------------+---------+ 9070 | 409 | Conflict | 15.5.10 | 9071 +-------+-------------------------------+---------+ 9072 | 410 | Gone | 15.5.11 | 9073 +-------+-------------------------------+---------+ 9074 | 411 | Length Required | 15.5.12 | 9075 +-------+-------------------------------+---------+ 9076 | 412 | Precondition Failed | 15.5.13 | 9077 +-------+-------------------------------+---------+ 9078 | 413 | Content Too Large | 15.5.14 | 9079 +-------+-------------------------------+---------+ 9080 | 414 | URI Too Long | 15.5.15 | 9081 +-------+-------------------------------+---------+ 9082 | 415 | Unsupported Media Type | 15.5.16 | 9083 +-------+-------------------------------+---------+ 9084 | 416 | Range Not Satisfiable | 15.5.17 | 9085 +-------+-------------------------------+---------+ 9086 | 417 | Expectation Failed | 15.5.18 | 9087 +-------+-------------------------------+---------+ 9088 | 418 | (Unused) | 15.5.19 | 9089 +-------+-------------------------------+---------+ 9090 | 421 | Misdirected Request | 15.5.20 | 9091 +-------+-------------------------------+---------+ 9092 | 422 | Unprocessable Content | 15.5.21 | 9093 +-------+-------------------------------+---------+ 9094 | 426 | Upgrade Required | 15.5.22 | 9095 +-------+-------------------------------+---------+ 9096 | 500 | Internal Server Error | 15.6.1 | 9097 +-------+-------------------------------+---------+ 9098 | 501 | Not Implemented | 15.6.2 | 9099 +-------+-------------------------------+---------+ 9100 | 502 | Bad Gateway | 15.6.3 | 9101 +-------+-------------------------------+---------+ 9102 | 503 | Service Unavailable | 15.6.4 | 9103 +-------+-------------------------------+---------+ 9104 | 504 | Gateway Timeout | 15.6.5 | 9105 +-------+-------------------------------+---------+ 9106 | 505 | HTTP Version Not Supported | 15.6.6 | 9107 +-------+-------------------------------+---------+ 9108 Table 8 9110 18.4. Field Name Registration 9112 This specification updates the HTTP related aspects of the existing 9113 registration procedures for message header fields defined in 9114 [RFC3864]. It defines both a new registration procedure and moves 9115 HTTP field definitions into a separate registry. 9117 Please create a new registry as outlined in Section 16.3.1. 9119 After creating the registry, all entries in the Permanent and 9120 Provisional Message Header Registries with the protocol 'http' are to 9121 be moved to it, with the following changes applied: 9123 1. The 'Applicable Protocol' field is to be omitted. 9125 2. Entries with a status of 'standard', 'experimental', 'reserved', 9126 or 'informational' are to have a status of 'permanent'. 9128 3. Provisional entries without a status are to have a status of 9129 'provisional'. 9131 4. Permanent entries without a status (after confirmation that the 9132 registration document did not define one) will have a status of 9133 'provisional'. The Expert(s) can choose to update their status 9134 if there is evidence that another is more appropriate. 9136 Please annotate the Permanent and Provisional Message Header 9137 registries to indicate that HTTP field name registrations have moved, 9138 with an appropriate link. 9140 After that is complete, please update the new registry with the field 9141 names listed in the following table. 9143 +===========================+============+========+============+ 9144 | Field Name | Status | Ref. | Comments | 9145 +===========================+============+========+============+ 9146 | Accept | standard | 12.5.1 | | 9147 +---------------------------+------------+--------+------------+ 9148 | Accept-Charset | deprecated | 12.5.2 | | 9149 +---------------------------+------------+--------+------------+ 9150 | Accept-Encoding | standard | 12.5.3 | | 9151 +---------------------------+------------+--------+------------+ 9152 | Accept-Language | standard | 12.5.4 | | 9153 +---------------------------+------------+--------+------------+ 9154 | Accept-Ranges | standard | 14.3 | | 9155 +---------------------------+------------+--------+------------+ 9156 | Allow | standard | 10.2.1 | | 9157 +---------------------------+------------+--------+------------+ 9158 | Authentication-Info | standard | 11.6.3 | | 9159 +---------------------------+------------+--------+------------+ 9160 | Authorization | standard | 11.6.2 | | 9161 +---------------------------+------------+--------+------------+ 9162 | Connection | standard | 7.6.1 | | 9163 +---------------------------+------------+--------+------------+ 9164 | Content-Encoding | standard | 8.4 | | 9165 +---------------------------+------------+--------+------------+ 9166 | Content-Language | standard | 8.5 | | 9167 +---------------------------+------------+--------+------------+ 9168 | Content-Length | standard | 8.6 | | 9169 +---------------------------+------------+--------+------------+ 9170 | Content-Location | standard | 8.7 | | 9171 +---------------------------+------------+--------+------------+ 9172 | Content-Range | standard | 14.4 | | 9173 +---------------------------+------------+--------+------------+ 9174 | Content-Type | standard | 8.3 | | 9175 +---------------------------+------------+--------+------------+ 9176 | Date | standard | 6.6.1 | | 9177 +---------------------------+------------+--------+------------+ 9178 | ETag | standard | 8.8.3 | | 9179 +---------------------------+------------+--------+------------+ 9180 | Expect | standard | 10.1.1 | | 9181 +---------------------------+------------+--------+------------+ 9182 | From | standard | 10.1.2 | | 9183 +---------------------------+------------+--------+------------+ 9184 | Host | standard | 7.2 | | 9185 +---------------------------+------------+--------+------------+ 9186 | If-Match | standard | 13.1.1 | | 9187 +---------------------------+------------+--------+------------+ 9188 | If-Modified-Since | standard | 13.1.3 | | 9189 +---------------------------+------------+--------+------------+ 9190 | If-None-Match | standard | 13.1.2 | | 9191 +---------------------------+------------+--------+------------+ 9192 | If-Range | standard | 13.1.5 | | 9193 +---------------------------+------------+--------+------------+ 9194 | If-Unmodified-Since | standard | 13.1.4 | | 9195 +---------------------------+------------+--------+------------+ 9196 | Last-Modified | standard | 8.8.2 | | 9197 +---------------------------+------------+--------+------------+ 9198 | Location | standard | 10.2.2 | | 9199 +---------------------------+------------+--------+------------+ 9200 | Max-Forwards | standard | 7.6.2 | | 9201 +---------------------------+------------+--------+------------+ 9202 | Proxy-Authenticate | standard | 11.7.1 | | 9203 +---------------------------+------------+--------+------------+ 9204 | Proxy-Authentication-Info | standard | 11.7.3 | | 9205 +---------------------------+------------+--------+------------+ 9206 | Proxy-Authorization | standard | 11.7.2 | | 9207 +---------------------------+------------+--------+------------+ 9208 | Range | standard | 14.2 | | 9209 +---------------------------+------------+--------+------------+ 9210 | Referer | standard | 10.1.3 | | 9211 +---------------------------+------------+--------+------------+ 9212 | Retry-After | standard | 10.2.3 | | 9213 +---------------------------+------------+--------+------------+ 9214 | Server | standard | 10.2.4 | | 9215 +---------------------------+------------+--------+------------+ 9216 | TE | standard | 10.1.4 | | 9217 +---------------------------+------------+--------+------------+ 9218 | Trailer | standard | 6.6.2 | | 9219 +---------------------------+------------+--------+------------+ 9220 | Upgrade | standard | 7.8 | | 9221 +---------------------------+------------+--------+------------+ 9222 | User-Agent | standard | 10.1.5 | | 9223 +---------------------------+------------+--------+------------+ 9224 | Vary | standard | 12.5.5 | | 9225 +---------------------------+------------+--------+------------+ 9226 | Via | standard | 7.6.3 | | 9227 +---------------------------+------------+--------+------------+ 9228 | WWW-Authenticate | standard | 11.6.1 | | 9229 +---------------------------+------------+--------+------------+ 9230 | * | standard | 12.5.5 | (reserved) | 9231 +---------------------------+------------+--------+------------+ 9233 Table 9 9235 The field name "*" is reserved, since using that name as an HTTP 9236 header field might conflict with its special semantics in the Vary 9237 header field (Section 12.5.5). 9239 Finally, please update the "Content-MD5" entry in the new registry to 9240 have a status of 'obsoleted' with references to Section 14.15 of 9241 [RFC2616] (for the definition of the header field) and Appendix B of 9242 [RFC7231] (which removed the field definition from the updated 9243 specification). 9245 18.5. Authentication Scheme Registration 9247 Please update the "Hypertext Transfer Protocol (HTTP) Authentication 9248 Scheme Registry" at with the registration procedure of Section 16.4.1. No 9250 authentication schemes are defined in this document. 9252 18.6. Content Coding Registration 9254 Please update the "HTTP Content Coding Registry" at 9255 with the 9256 registration procedure of Section 16.6.1 and the content coding names 9257 summarized in the table below. 9259 +============+===========================================+=========+ 9260 | Name | Description | Ref. | 9261 +============+===========================================+=========+ 9262 | compress | UNIX "compress" data format [Welch] | 8.4.1.1 | 9263 +------------+-------------------------------------------+---------+ 9264 | deflate | "deflate" compressed data ([RFC1951]) | 8.4.1.2 | 9265 | | inside the "zlib" data format ([RFC1950]) | | 9266 +------------+-------------------------------------------+---------+ 9267 | gzip | GZIP file format [RFC1952] | 8.4.1.3 | 9268 +------------+-------------------------------------------+---------+ 9269 | identity | Reserved | 12.5.3 | 9270 +------------+-------------------------------------------+---------+ 9271 | x-compress | Deprecated (alias for compress) | 8.4.1.1 | 9272 +------------+-------------------------------------------+---------+ 9273 | x-gzip | Deprecated (alias for gzip) | 8.4.1.3 | 9274 +------------+-------------------------------------------+---------+ 9276 Table 10 9278 18.7. Range Unit Registration 9280 Please update the "HTTP Range Unit Registry" at 9281 with the 9282 registration procedure of Section 16.5.1 and the range unit names 9283 summarized in the table below. 9285 +=================+==================================+========+ 9286 | Range Unit Name | Description | Ref. | 9287 +=================+==================================+========+ 9288 | bytes | a range of octets | 14.1.2 | 9289 +-----------------+----------------------------------+--------+ 9290 | none | reserved as keyword to indicate | 14.3 | 9291 | | range requests are not supported | | 9292 +-----------------+----------------------------------+--------+ 9294 Table 11 9296 18.8. Media Type Registration 9298 Please update the "Media Types" registry at 9299 with the registration 9300 information in Section 14.6 for the media type "multipart/ 9301 byteranges". 9303 18.9. Port Registration 9305 Please update the "Service Name and Transport Protocol Port Number" 9306 registry at for the services on ports 80 and 443 that use UDP or TCP 9308 to: 9310 1. use this document as "Reference", and 9312 2. when currently unspecified, set "Assignee" to "IESG" and 9313 "Contact" to "IETF_Chair". 9315 18.10. Upgrade Token Registration 9317 Please update the "Hypertext Transfer Protocol (HTTP) Upgrade Token 9318 Registry" at 9319 with the registration procedure of Section 16.7 and the upgrade token 9320 names summarized in the following table. 9322 +======+===================+=========================+======+ 9323 | Name | Description | Expected Version Tokens | Ref. | 9324 +======+===================+=========================+======+ 9325 | HTTP | Hypertext | any DIGIT.DIGIT (e.g, | 2.5 | 9326 | | Transfer Protocol | "2.0") | | 9327 +------+-------------------+-------------------------+------+ 9329 Table 12 9331 19. References 9333 19.1. Normative References 9335 [CACHING] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 9336 Ed., "HTTP Caching", Work in Progress, Internet-Draft, 9337 draft-ietf-httpbis-cache-18, 18 August 2021, 9338 . 9341 [RFC1950] Deutsch, L.P. and J-L. Gailly, "ZLIB Compressed Data 9342 Format Specification version 3.3", RFC 1950, 9343 DOI 10.17487/RFC1950, May 1996, 9344 . 9346 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 9347 version 1.3", RFC 1951, DOI 10.17487/RFC1951, May 1996, 9348 . 9350 [RFC1952] Deutsch, P., Gailly, J-L., Adler, M., Deutsch, L.P., and 9351 G. Randers-Pehrson, "GZIP file format specification 9352 version 4.3", RFC 1952, DOI 10.17487/RFC1952, May 1996, 9353 . 9355 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 9356 Extensions (MIME) Part Two: Media Types", RFC 2046, 9357 DOI 10.17487/RFC2046, November 1996, 9358 . 9360 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 9361 Requirement Levels", BCP 14, RFC 2119, 9362 DOI 10.17487/RFC2119, March 1997, 9363 . 9365 [RFC4647] Phillips, A., Ed. and M. Davis, Ed., "Matching of Language 9366 Tags", BCP 47, RFC 4647, DOI 10.17487/RFC4647, September 9367 2006, . 9369 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 9370 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 9371 . 9373 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 9374 Specifications: ABNF", STD 68, RFC 5234, 9375 DOI 10.17487/RFC5234, January 2008, 9376 . 9378 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 9379 Housley, R., and W. Polk, "Internet X.509 Public Key 9380 Infrastructure Certificate and Certificate Revocation List 9381 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 9382 . 9384 [RFC5322] Resnick, P., "Internet Message Format", RFC 5322, 9385 DOI 10.17487/RFC5322, October 2008, 9386 . 9388 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 9389 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 9390 September 2009, . 9392 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 9393 Verification of Domain-Based Application Service Identity 9394 within Internet Public Key Infrastructure Using X.509 9395 (PKIX) Certificates in the Context of Transport Layer 9396 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 9397 2011, . 9399 [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in 9400 Internationalization in the IETF", BCP 166, RFC 6365, 9401 DOI 10.17487/RFC6365, September 2011, 9402 . 9404 [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", 9405 RFC 7405, DOI 10.17487/RFC7405, December 2014, 9406 . 9408 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 9409 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 9410 May 2017, . 9412 [TCP] Postel, J., "Transmission Control Protocol", STD 7, 9413 RFC 793, DOI 10.17487/RFC0793, September 1981, 9414 . 9416 [TLS13] Rescorla, E., "The Transport Layer Security (TLS) Protocol 9417 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 9418 . 9420 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 9421 Resource Identifier (URI): Generic Syntax", STD 66, 9422 RFC 3986, DOI 10.17487/RFC3986, January 2005, 9423 . 9425 [USASCII] American National Standards Institute, "Coded Character 9426 Set -- 7-bit American Standard Code for Information 9427 Interchange", ANSI X3.4, 1986. 9429 [Welch] Welch, T. A., "A Technique for High-Performance Data 9430 Compression", IEEE Computer 17(6), 9431 DOI 10.1109/MC.1984.1659158, June 1984, 9432 . 9434 19.2. Informative References 9436 [ALTSVC] Nottingham, M., McManus, P., and J. Reschke, "HTTP 9437 Alternative Services", RFC 7838, DOI 10.17487/RFC7838, 9438 April 2016, . 9440 [BCP13] Freed, N., Klensin, J., and T. Hansen, "Media Type 9441 Specifications and Registration Procedures", BCP 13, 9442 RFC 6838, January 2013, 9443 . 9445 [BCP178] Saint-Andre, P., Crocker, D., and M. Nottingham, 9446 "Deprecating the "X-" Prefix and Similar Constructs in 9447 Application Protocols", BCP 178, RFC 6648, June 2012, 9448 . 9450 [BCP35] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 9451 and Registration Procedures for URI Schemes", BCP 35, 9452 RFC 7595, June 2015, 9453 . 9455 [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving the 9456 CRIME Attack", July 2013, 9457 . 9460 [Bujlow] Bujlow, T., Carela-Espanol, V., Sole-Pareta, J., and P. 9461 Barlet-Ros, "A Survey on Web Tracking: Mechanisms, 9462 Implications, and Defenses", 9463 DOI 10.1109/JPROC.2016.2637878, Proceedings of the 9464 IEEE 105(8), August 2017, 9465 . 9467 [COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265, 9468 DOI 10.17487/RFC6265, April 2011, 9469 . 9471 [Err1912] RFC Errata, Erratum ID 1912, RFC 2978, 9472 . 9474 [Err5433] RFC Errata, Erratum ID 5433, RFC 2978, 9475 . 9477 [Georgiev] Georgiev, M., Iyengar, S., Jana, S., Anubhai, R., Boneh, 9478 D., and V. Shmatikov, "The Most Dangerous Code in the 9479 World: Validating SSL Certificates in Non-browser 9480 Software", In Proceedings of the 2012 ACM Conference on 9481 Computer and Communications Security (CCS '12), pp. 38-49, 9482 DOI 10.1145/2382196.2382204, October 2012, 9483 . 9485 [HPACK] Peon, R. and H. Ruellan, "HPACK: Header Compression for 9486 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 9487 . 9489 [HTTP/1.0] Berners-Lee, T., Fielding, R.T., and H.F. Nielsen, 9490 "Hypertext Transfer Protocol -- HTTP/1.0", RFC 1945, 9491 DOI 10.17487/RFC1945, May 1996, 9492 . 9494 [HTTP/1.1] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 9495 Ed., "HTTP/1.1", Work in Progress, Internet-Draft, draft- 9496 ietf-httpbis-messaging-18, 18 August 2021, 9497 . 9500 [HTTP/2] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 9501 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 9502 DOI 10.17487/RFC7540, May 2015, 9503 . 9505 [HTTP/3] Bishop, M., "Hypertext Transfer Protocol Version 3 9506 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 9507 quic-http-34, 2 February 2021, 9508 . 9511 [ISO-8859-1] 9512 International Organization for Standardization, 9513 "Information technology -- 8-bit single-byte coded graphic 9514 character sets -- Part 1: Latin alphabet No. 1", ISO/ 9515 IEC 8859-1:1998, 1998. 9517 [Kri2001] Kristol, D., "HTTP Cookies: Standards, Privacy, and 9518 Politics", ACM Transactions on Internet Technology 1(2), 9519 November 2001, . 9521 [OWASP] van der Stock, A., Ed., "A Guide to Building Secure Web 9522 Applications and Web Services", The Open Web Application 9523 Security Project (OWASP) 2.0.1, 27 July 2005, 9524 . 9526 [REST] Fielding, R.T., "Architectural Styles and the Design of 9527 Network-based Software Architectures", Doctoral 9528 Dissertation, University of California, Irvine, September 9529 2000, . 9531 [RFC1919] Chatel, M., "Classical versus Transparent IP Proxies", 9532 RFC 1919, DOI 10.17487/RFC1919, March 1996, 9533 . 9535 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 9536 Part Three: Message Header Extensions for Non-ASCII Text", 9537 RFC 2047, DOI 10.17487/RFC2047, November 1996, 9538 . 9540 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T. 9541 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", 9542 RFC 2068, DOI 10.17487/RFC2068, January 1997, 9543 . 9545 [RFC2145] Mogul, J.C., Fielding, R.T., Gettys, J., and H.F. Nielsen, 9546 "Use and Interpretation of HTTP Version Numbers", 9547 RFC 2145, DOI 10.17487/RFC2145, May 1997, 9548 . 9550 [RFC2295] Holtman, K. and A.H. Mutz, "Transparent Content 9551 Negotiation in HTTP", RFC 2295, DOI 10.17487/RFC2295, 9552 March 1998, . 9554 [RFC2324] Masinter, L., "Hyper Text Coffee Pot Control Protocol 9555 (HTCPCP/1.0)", RFC 2324, DOI 10.17487/RFC2324, 1 April 9556 1998, . 9558 [RFC2557] Palme, F., Hopmann, A., Shelness, N., and E. Stefferud, 9559 "MIME Encapsulation of Aggregate Documents, such as HTML 9560 (MHTML)", RFC 2557, DOI 10.17487/RFC2557, March 1999, 9561 . 9563 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 9564 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 9565 Transfer Protocol -- HTTP/1.1", RFC 2616, 9566 DOI 10.17487/RFC2616, June 1999, 9567 . 9569 [RFC2617] Franks, J., Hallam-Baker, P.M., Hostetler, J.L., Lawrence, 9570 S.D., Leach, P.J., Luotonen, A., and L. Stewart, "HTTP 9571 Authentication: Basic and Digest Access Authentication", 9572 RFC 2617, DOI 10.17487/RFC2617, June 1999, 9573 . 9575 [RFC2774] Frystyk, H., Leach, P., and S. Lawrence, "An HTTP 9576 Extension Framework", RFC 2774, DOI 10.17487/RFC2774, 9577 February 2000, . 9579 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 9580 DOI 10.17487/RFC2818, May 2000, 9581 . 9583 [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration 9584 Procedures", BCP 19, RFC 2978, DOI 10.17487/RFC2978, 9585 October 2000, . 9587 [RFC3040] Cooper, I., Melve, I., and G. Tomlinson, "Internet Web 9588 Replication and Caching Taxonomy", RFC 3040, 9589 DOI 10.17487/RFC3040, January 2001, 9590 . 9592 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 9593 Procedures for Message Header Fields", BCP 90, RFC 3864, 9594 DOI 10.17487/RFC3864, September 2004, 9595 . 9597 [RFC3875] Robinson, D. and K. Coar, "The Common Gateway Interface 9598 (CGI) Version 1.1", RFC 3875, DOI 10.17487/RFC3875, 9599 October 2004, . 9601 [RFC4033] Arends, R., Austein, R., Larson, M., Massey, D., and S. 9602 Rose, "DNS Security Introduction and Requirements", 9603 RFC 4033, DOI 10.17487/RFC4033, March 2005, 9604 . 9606 [RFC4559] Jaganathan, K., Zhu, L., and J. Brezak, "SPNEGO-based 9607 Kerberos and NTLM HTTP Authentication in Microsoft 9608 Windows", RFC 4559, DOI 10.17487/RFC4559, June 2006, 9609 . 9611 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 9612 RFC 5789, DOI 10.17487/RFC5789, March 2010, 9613 . 9615 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 9616 "Network Time Protocol Version 4: Protocol and Algorithms 9617 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 9618 . 9620 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 9621 DOI 10.17487/RFC6454, December 2011, 9622 . 9624 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 9625 Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, 9626 . 9628 [RFC7230] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9629 Transfer Protocol (HTTP/1.1): Message Syntax and Routing", 9630 RFC 7230, DOI 10.17487/RFC7230, June 2014, 9631 . 9633 [RFC7231] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9634 Transfer Protocol (HTTP/1.1): Semantics and Content", 9635 RFC 7231, DOI 10.17487/RFC7231, June 2014, 9636 . 9638 [RFC7232] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9639 Transfer Protocol (HTTP/1.1): Conditional Requests", 9640 RFC 7232, DOI 10.17487/RFC7232, June 2014, 9641 . 9643 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. F. Reschke, Ed., 9644 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 9645 RFC 7233, DOI 10.17487/RFC7233, June 2014, 9646 . 9648 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. F. Reschke, 9649 Ed., "Hypertext Transfer Protocol (HTTP): Caching", 9650 RFC 7234, DOI 10.17487/RFC7234, June 2014, 9651 . 9653 [RFC7235] Fielding, R., Ed. and J. F. Reschke, Ed., "Hypertext 9654 Transfer Protocol (HTTP/1.1): Authentication", RFC 7235, 9655 DOI 10.17487/RFC7235, June 2014, 9656 . 9658 [RFC7538] Reschke, J. F., "The Hypertext Transfer Protocol Status 9659 Code 308 (Permanent Redirect)", RFC 7538, 9660 DOI 10.17487/RFC7538, April 2015, 9661 . 9663 [RFC7578] Masinter, L., "Returning Values from Forms: multipart/ 9664 form-data", RFC 7578, DOI 10.17487/RFC7578, July 2015, 9665 . 9667 [RFC7615] Reschke, J. F., "HTTP Authentication-Info and Proxy- 9668 Authentication-Info Response Header Fields", RFC 7615, 9669 DOI 10.17487/RFC7615, September 2015, 9670 . 9672 [RFC7616] Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP 9673 Digest Access Authentication", RFC 7616, 9674 DOI 10.17487/RFC7616, September 2015, 9675 . 9677 [RFC7617] Reschke, J. F., "The 'Basic' HTTP Authentication Scheme", 9678 RFC 7617, DOI 10.17487/RFC7617, September 2015, 9679 . 9681 [RFC7694] Reschke, J. F., "Hypertext Transfer Protocol (HTTP) 9682 Client-Initiated Content-Encoding", RFC 7694, 9683 DOI 10.17487/RFC7694, November 2015, 9684 . 9686 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 9687 Writing an IANA Considerations Section in RFCs", BCP 26, 9688 RFC 8126, DOI 10.17487/RFC8126, June 2017, 9689 . 9691 [RFC8187] Reschke, J. F., "Indicating Character Encoding and 9692 Language for HTTP Header Field Parameters", RFC 8187, 9693 DOI 10.17487/RFC8187, September 2017, 9694 . 9696 [RFC8246] McManus, P., "HTTP Immutable Responses", RFC 8246, 9697 DOI 10.17487/RFC8246, September 2017, 9698 . 9700 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 9701 DOI 10.17487/RFC8288, October 2017, 9702 . 9704 [RFC8336] Nottingham, M. and E. Nygren, "The ORIGIN HTTP/2 Frame", 9705 RFC 8336, DOI 10.17487/RFC8336, March 2018, 9706 . 9708 [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers 9709 (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, 9710 . 9712 [RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for 9713 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 9714 . 9716 [Sniffing] WHATWG, "MIME Sniffing", 9717 . 9719 [WEBDAV] Dusseault, L.M., Ed., "HTTP Extensions for Web Distributed 9720 Authoring and Versioning (WebDAV)", RFC 4918, 9721 DOI 10.17487/RFC4918, June 2007, 9722 . 9724 Appendix A. Collected ABNF 9726 In the collected ABNF below, list rules are expanded as per 9727 Section 5.6.1.1. 9729 Accept = [ ( media-range [ weight ] ) *( OWS "," OWS ( media-range [ 9730 weight ] ) ) ] 9731 Accept-Charset = [ ( ( token / "*" ) [ weight ] ) *( OWS "," OWS ( ( 9732 token / "*" ) [ weight ] ) ) ] 9733 Accept-Encoding = [ ( codings [ weight ] ) *( OWS "," OWS ( codings [ 9734 weight ] ) ) ] 9735 Accept-Language = [ ( language-range [ weight ] ) *( OWS "," OWS ( 9736 language-range [ weight ] ) ) ] 9737 Accept-Ranges = acceptable-ranges 9738 Allow = [ method *( OWS "," OWS method ) ] 9739 Authentication-Info = [ auth-param *( OWS "," OWS auth-param ) ] 9740 Authorization = credentials 9742 BWS = OWS 9744 Connection = [ connection-option *( OWS "," OWS connection-option ) 9745 ] 9746 Content-Encoding = [ content-coding *( OWS "," OWS content-coding ) 9747 ] 9748 Content-Language = [ language-tag *( OWS "," OWS language-tag ) ] 9749 Content-Length = 1*DIGIT 9750 Content-Location = absolute-URI / partial-URI 9751 Content-Range = range-unit SP ( range-resp / unsatisfied-range ) 9752 Content-Type = media-type 9754 Date = HTTP-date 9756 ETag = entity-tag 9757 Expect = [ expectation *( OWS "," OWS expectation ) ] 9759 From = mailbox 9761 GMT = %x47.4D.54 ; GMT 9763 HTTP-date = IMF-fixdate / obs-date 9764 Host = uri-host [ ":" port ] 9766 IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT 9767 If-Match = "*" / [ entity-tag *( OWS "," OWS entity-tag ) ] 9768 If-Modified-Since = HTTP-date 9769 If-None-Match = "*" / [ entity-tag *( OWS "," OWS entity-tag ) ] 9770 If-Range = entity-tag / HTTP-date 9771 If-Unmodified-Since = HTTP-date 9772 Last-Modified = HTTP-date 9773 Location = URI-reference 9775 Max-Forwards = 1*DIGIT 9777 OWS = *( SP / HTAB ) 9779 Proxy-Authenticate = [ challenge *( OWS "," OWS challenge ) ] 9780 Proxy-Authentication-Info = [ auth-param *( OWS "," OWS auth-param ) 9781 ] 9782 Proxy-Authorization = credentials 9784 RWS = 1*( SP / HTAB ) 9785 Range = ranges-specifier 9786 Referer = absolute-URI / partial-URI 9787 Retry-After = HTTP-date / delay-seconds 9789 Server = product *( RWS ( product / comment ) ) 9791 TE = [ t-codings *( OWS "," OWS t-codings ) ] 9792 Trailer = [ field-name *( OWS "," OWS field-name ) ] 9794 URI-reference = 9795 Upgrade = [ protocol *( OWS "," OWS protocol ) ] 9796 User-Agent = product *( RWS ( product / comment ) ) 9798 Vary = [ ( "*" / field-name ) *( OWS "," OWS ( "*" / field-name ) ) 9799 ] 9800 Via = [ ( received-protocol RWS received-by [ RWS comment ] ) *( OWS 9801 "," OWS ( received-protocol RWS received-by [ RWS comment ] ) ) ] 9803 WWW-Authenticate = [ challenge *( OWS "," OWS challenge ) ] 9805 absolute-URI = 9806 absolute-path = 1*( "/" segment ) 9807 acceptable-ranges = range-unit *( OWS "," OWS range-unit ) 9808 asctime-date = day-name SP date3 SP time-of-day SP year 9809 auth-param = token BWS "=" BWS ( token / quoted-string ) 9810 auth-scheme = token 9811 authority = 9813 challenge = auth-scheme [ 1*SP ( token68 / [ auth-param *( OWS "," 9814 OWS auth-param ) ] ) ] 9815 codings = content-coding / "identity" / "*" 9816 comment = "(" *( ctext / quoted-pair / comment ) ")" 9817 complete-length = 1*DIGIT 9818 connection-option = token 9819 content-coding = token 9820 credentials = auth-scheme [ 1*SP ( token68 / [ auth-param *( OWS "," 9821 OWS auth-param ) ] ) ] 9822 ctext = HTAB / SP / %x21-27 ; '!'-''' 9823 / %x2A-5B ; '*'-'[' 9824 / %x5D-7E ; ']'-'~' 9825 / obs-text 9827 date1 = day SP month SP year 9828 date2 = day "-" month "-" 2DIGIT 9829 date3 = month SP ( 2DIGIT / ( SP DIGIT ) ) 9830 day = 2DIGIT 9831 day-name = %x4D.6F.6E ; Mon 9832 / %x54.75.65 ; Tue 9833 / %x57.65.64 ; Wed 9834 / %x54.68.75 ; Thu 9835 / %x46.72.69 ; Fri 9836 / %x53.61.74 ; Sat 9837 / %x53.75.6E ; Sun 9838 day-name-l = %x4D.6F.6E.64.61.79 ; Monday 9839 / %x54.75.65.73.64.61.79 ; Tuesday 9840 / %x57.65.64.6E.65.73.64.61.79 ; Wednesday 9841 / %x54.68.75.72.73.64.61.79 ; Thursday 9842 / %x46.72.69.64.61.79 ; Friday 9843 / %x53.61.74.75.72.64.61.79 ; Saturday 9844 / %x53.75.6E.64.61.79 ; Sunday 9845 delay-seconds = 1*DIGIT 9847 entity-tag = [ weak ] opaque-tag 9848 etagc = "!" / %x23-7E ; '#'-'~' 9849 / obs-text 9850 expectation = token [ "=" ( token / quoted-string ) parameters ] 9852 field-content = field-vchar [ 1*( SP / HTAB / field-vchar ) 9853 field-vchar ] 9854 field-name = token 9855 field-value = *field-content 9856 field-vchar = VCHAR / obs-text 9857 first-pos = 1*DIGIT 9859 hour = 2DIGIT 9860 http-URI = "http://" authority path-abempty [ "?" query ] 9861 https-URI = "https://" authority path-abempty [ "?" query ] 9863 incl-range = first-pos "-" last-pos 9864 int-range = first-pos "-" [ last-pos ] 9866 language-range = 9867 language-tag = 9868 last-pos = 1*DIGIT 9870 mailbox = 9871 media-range = ( "*/*" / ( type "/*" ) / ( type "/" subtype ) ) 9872 parameters 9873 media-type = type "/" subtype parameters 9874 method = token 9875 minute = 2DIGIT 9876 month = %x4A.61.6E ; Jan 9877 / %x46.65.62 ; Feb 9878 / %x4D.61.72 ; Mar 9879 / %x41.70.72 ; Apr 9880 / %x4D.61.79 ; May 9881 / %x4A.75.6E ; Jun 9882 / %x4A.75.6C ; Jul 9883 / %x41.75.67 ; Aug 9884 / %x53.65.70 ; Sep 9885 / %x4F.63.74 ; Oct 9886 / %x4E.6F.76 ; Nov 9887 / %x44.65.63 ; Dec 9889 obs-date = rfc850-date / asctime-date 9890 obs-text = %x80-FF 9891 opaque-tag = DQUOTE *etagc DQUOTE 9892 other-range = 1*( %x21-2B ; '!'-'+' 9893 / %x2D-7E ; '-'-'~' 9894 ) 9896 parameter = parameter-name "=" parameter-value 9897 parameter-name = token 9898 parameter-value = ( token / quoted-string ) 9899 parameters = *( OWS ";" OWS [ parameter ] ) 9900 partial-URI = relative-part [ "?" query ] 9901 path-abempty = 9902 port = 9903 product = token [ "/" product-version ] 9904 product-version = token 9905 protocol = protocol-name [ "/" protocol-version ] 9906 protocol-name = token 9907 protocol-version = token 9908 pseudonym = token 9910 qdtext = HTAB / SP / "!" / %x23-5B ; '#'-'[' 9911 / %x5D-7E ; ']'-'~' 9912 / obs-text 9913 query = 9914 quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text ) 9915 quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE 9916 qvalue = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] ) 9918 range-resp = incl-range "/" ( complete-length / "*" ) 9919 range-set = range-spec *( OWS "," OWS range-spec ) 9920 range-spec = int-range / suffix-range / other-range 9921 range-unit = token 9922 ranges-specifier = range-unit "=" range-set 9923 received-by = pseudonym [ ":" port ] 9924 received-protocol = [ protocol-name "/" ] protocol-version 9925 relative-part = 9926 rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT 9928 second = 2DIGIT 9929 segment = 9930 subtype = token 9931 suffix-length = 1*DIGIT 9932 suffix-range = "-" suffix-length 9934 t-codings = "trailers" / ( transfer-coding [ weight ] ) 9935 tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / 9936 "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA 9937 time-of-day = hour ":" minute ":" second 9938 token = 1*tchar 9939 token68 = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" ) 9940 *"=" 9941 transfer-coding = token *( OWS ";" OWS transfer-parameter ) 9942 transfer-parameter = token BWS "=" BWS ( token / quoted-string ) 9943 type = token 9945 unsatisfied-range = "*/" complete-length 9946 uri-host = 9948 weak = %x57.2F ; W/ 9949 weight = OWS ";" OWS "q=" qvalue 9951 year = 4DIGIT 9953 Appendix B. Changes from previous RFCs 9955 B.1. Changes from RFC 2818 9957 None. 9959 B.2. Changes from RFC 7230 9961 The sections introducing HTTP's design goals, history, architecture, 9962 conformance criteria, protocol versioning, URIs, message routing, and 9963 header fields have been moved here. 9965 The requirement on semantic conformance has been replaced with 9966 permission to ignore/workaround implementation-specific failures. 9967 (Section 2.2) 9969 The description of an origin and authoritative access to origin 9970 servers has been extended for both "http" and "https" URIs to account 9971 for alternative services and secured connections that are not 9972 necessarily based on TCP. (Section 4.2.1, Section 4.2.2, 9973 Section 4.3.1, Section 7.3.3) 9975 Explicit requirements have been added to check the target URI 9976 scheme's semantics and reject requests that don't meet any associated 9977 requirements. (Section 7.4) 9979 Parameters in media type, media range, and expectation can be empty 9980 via one or more trailing semicolons. (Section 5.6.6) 9982 "Field value" now refers to the value after multiple field lines are 9983 combined with commas - by far the most common use. To refer to a 9984 single header line's value, use "field line value". (Section 6.3) 9986 Trailer field semantics now transcend the specifics of chunked 9987 encoding. Use of trailer fields has been further limited to only 9988 allow generation as a trailer field when the sender knows the field 9989 defines that usage and to only allow merging into the header section 9990 if the recipient knows the corresponding field definition permits and 9991 defines how to merge. In all other cases, implementations are 9992 encouraged to either store the trailer fields separately or discard 9993 them instead of merging. (Section 6.5.1) 9995 Made the priority of the absolute form of the request URI over the 9996 Host header by origin servers explicit, to align with proxy handling. 9997 (Section 7.2) 9999 The grammar definition for the Via field's "received-by" was expanded 10000 in 7230 due to changes in the URI grammar for host [URI] that are not 10001 desirable for Via. For simplicity, we have removed uri-host from the 10002 received-by production because it can be encompassed by the existing 10003 grammar for pseudonym. In particular, this change removed comma from 10004 the allowed set of charaters for a host name in received-by. 10005 (Section 7.6.3) 10007 B.3. Changes from RFC 7231 10009 Minimum URI lengths to be supported by implementations are now 10010 recommended. (Section 3.1) 10011 Clarified that CR and NUL in field values are to be rejected or 10012 mapped to SP and that leading and trailing whitespace need to be 10013 stripped from field values before they are consumed. (Section 5.5) 10015 Parameters in media type, media range, and expectation can be empty 10016 via one or more trailing semicolons. (Section 5.6.6) 10018 An abstract data type for HTTP messages has been introduced to define 10019 the components of a message and their semantics as an abstraction 10020 across multiple HTTP versions, rather than in terms of the specific 10021 syntax form of HTTP/1.1 in [HTTP/1.1], and reflect the contents after 10022 the message is parsed. This makes it easier to distinguish between 10023 requirements on the content (what is conveyed) versus requirements on 10024 the messaging syntax (how it is conveyed) and avoids baking 10025 limitations of early protocol versions into the future of HTTP. 10026 (Section 6) 10028 The terms "payload" and "payload body" have been replaced with 10029 "content", to better align with its usage elsewhere (e.g., in field 10030 names) and to avoid confusion with frame payloads in HTTP/2 and 10031 HTTP/3. (Section 6.4) 10033 The term "effective request URI" has been replaced with "target URI". 10034 (Section 7.1) 10036 Restrictions on client retries have been loosened, to reflect 10037 implementation behavior. (Section 9.2.2) 10039 Clarified that request bodies on GET, HEAD, and DELETE are not 10040 interoperable. (Section 9.3.1, Section 9.3.2, Section 9.3.5) 10042 Allowed use of the Content-Range header field (Section 14.4) as a 10043 request modifier on PUT. (Section 9.3.4) 10045 Removed a superfluous requirement about setting Content-Length from 10046 the description of the OPTIONS method. (Section 9.3.7) 10048 Removed normative requirement to use the "message/http" media type in 10049 TRACE responses. (Section 9.3.8) 10051 Restore list-based grammar for Expect for compatibility with RFC 10052 2616. (Section 10.1.1) 10054 Allow Accept and Accept-Encoding in response messages; the latter was 10055 introduced by [RFC7694]. (Section 12.3) 10056 "Accept Parameters" (accept-params and accept-ext ABNF production) 10057 have been removed from the definition of the Accept field. 10058 (Section 12.5.1) 10060 The "Accept-Charset" field now is deprecated. (Section 12.5.2) 10062 The semantics of "*" in the Vary header field when other values are 10063 present was clarified. (Section 12.5.5) 10065 Range units are compared in a case insensitive fashion. 10066 (Section 14.1) 10068 Use of "Accept-Ranges" is not restricted to origin servers. 10069 (Section 14.3) 10071 The process of creating a redirected request has been clarified. 10072 (Section 15.4) 10074 Added status code 308 (previously defined in [RFC7538]) so that it's 10075 defined closer to status codes 301, 302, and 307. (Section 15.4.9) 10077 Added status code 421 (previously defined in Section 9.1.2 of 10078 [HTTP/2]) because of its general applicability. 421 is no longer 10079 defined as heuristically cacheable, since the response is specific to 10080 the connection (not the target resource). (Section 15.5.20) 10082 Added status code 422 (previously defined in Section 11.2 of 10083 [WEBDAV]) because of its general applicability. (Section 15.5.21) 10085 B.4. Changes from RFC 7232 10087 Previous revisions of HTTP imposed an arbitrary 60-second limit on 10088 the determination of whether Last-Modified was a strong validator to 10089 guard against the possibility that the Date and Last-Modified values 10090 are generated from different clocks or at somewhat different times 10091 during the preparation of the response. This specification has 10092 relaxed that to allow reasonable discretion. (Section 8.8.2.2) 10094 Removed edge case requirement on If-Match and If-Unmodified-Since 10095 that a validator not be sent in a 2xx response when validation fails 10096 and the server decides that the same change request has already been 10097 applied. (Section 13.1.1 and Section 13.1.4) 10099 Clarified that If-Unmodified-Since doesn't apply to a resource 10100 without a concept of modification time. (Section 13.1.4) 10101 Preconditions can now be evaluated before the request content is 10102 processed rather than waiting until the response would otherwise be 10103 successful. (Section 13.2) 10105 B.5. Changes from RFC 7233 10107 Refactored the range-unit and ranges-specifier grammars to simplify 10108 and reduce artificial distinctions between bytes and other 10109 (extension) range units, removing the overlapping grammar of other- 10110 range-unit by defining range units generically as a token and placing 10111 extensions within the scope of a range-spec (other-range). This 10112 disambiguates the role of list syntax (commas) in all range sets, 10113 including extension range units, for indicating a range-set of more 10114 than one range. Moving the extension grammar into range specifiers 10115 also allows protocol specific to byte ranges to be specified 10116 separately. 10118 It is now possible to define Range handling on extension methods. 10119 (Section 14.2) 10121 Described use of the Content-Range header field (Section 14.4) as a 10122 request modifier to perform a partial PUT. (Section 14.5) 10124 B.6. Changes from RFC 7235 10126 None. 10128 B.7. Changes from RFC 7538 10130 None. 10132 B.8. Changes from RFC 7615 10134 None. 10136 B.9. Changes from RFC 7694 10138 This specification includes the extension defined in [RFC7694], but 10139 leaves out examples and deployment considerations. 10141 Appendix C. Change Log 10143 This section is to be removed before publishing as an RFC. 10145 C.1. Between RFC723x and draft 00 10147 The changes were purely editorial: 10149 * Change boilerplate and abstract to indicate the "draft" status, 10150 and update references to ancestor specifications. 10152 * Remove version "1.1" from document title, indicating that this 10153 specification applies to all HTTP versions. 10155 * Adjust historical notes. 10157 * Update links to sibling specifications. 10159 * Replace sections listing changes from RFC 2616 by new empty 10160 sections referring to RFC 723x. 10162 * Remove acknowledgements specific to RFC 723x. 10164 * Move "Acknowledgements" to the very end and make them unnumbered. 10166 C.2. Since draft-ietf-httpbis-semantics-00 10168 The changes in this draft are editorial, with respect to HTTP as a 10169 whole, to merge core HTTP semantics into this document: 10171 * Merged introduction, architecture, conformance, and ABNF 10172 extensions from RFC 7230 (Messaging). 10174 * Rearranged architecture to extract conformance, http(s) schemes, 10175 and protocol versioning into a separate major section. 10177 * Moved discussion of MIME differences to [HTTP/1.1] since that is 10178 primarily concerned with transforming 1.1 messages. 10180 * Merged entire content of RFC 7232 (Conditional Requests). 10182 * Merged entire content of RFC 7233 (Range Requests). 10184 * Merged entire content of RFC 7235 (Auth Framework). 10186 * Moved all extensibility tips, registration procedures, and 10187 registry tables from the IANA considerations to normative 10188 sections, reducing the IANA considerations to just instructions 10189 that will be removed prior to publication as an RFC. 10191 C.3. Since draft-ietf-httpbis-semantics-01 10193 * Improve [Welch] citation () 10196 * Remove HTTP/1.1-ism about Range Requests 10197 () 10199 * Cite RFC 8126 instead of RFC 5226 () 10202 * Cite RFC 7538 instead of RFC 7238 () 10205 * Cite RFC 8288 instead of RFC 5988 () 10208 * Cite RFC 8187 instead of RFC 5987 () 10211 * Cite RFC 7578 instead of RFC 2388 () 10214 * Cite RFC 7595 instead of RFC 4395 () 10217 * improve ABNF readability for qdtext (, ) 10220 * Clarify "resource" vs "representation" in definition of status 10221 code 416 (, 10222 ) 10224 * Resolved erratum 4072, no change needed here 10225 (, 10226 ) 10228 * Clarify DELETE status code suggestions 10229 (, 10230 ) 10232 * In Section 14.4, fix ABNF for "other-range-resp" to use VCHAR 10233 instead of CHAR (, 10234 ) 10236 * Resolved erratum 5162, no change needed here 10237 (, 10238 ) 10240 * Replace "response code" with "response status code" and "status- 10241 code" (the ABNF production name from the HTTP/1.1 message format) 10242 by "status code" (, 10243 ) 10245 * Added a missing word in Section 15.4 (, ) 10248 * In Section 5.6.1, fixed an example that had trailing whitespace 10249 where it shouldn't (, ) 10252 * In Section 15.3.7, remove words that were potentially misleading 10253 with respect to the relation to the requested ranges 10254 (, 10255 ) 10257 C.4. Since draft-ietf-httpbis-semantics-02 10259 * Included (Proxy-)Auth-Info header field definition from RFC 7615 10260 () 10262 * In Section 9.3.3, clarify POST caching 10263 () 10265 * Add Section 15.5.19 to reserve the 418 status code 10266 () 10268 * In Section 3.4 and Section 10.1.1, clarified when a response can 10269 be sent () 10271 * In Section 8.3.2, explain the difference between the "token" 10272 production, the RFC 2978 ABNF for charset names, and the actual 10273 registration practice (, ) 10276 * In Section 3.1, removed the fragment component in the URI scheme 10277 definitions as per Section 4.3 of [URI], furthermore moved 10278 fragment discussion into a separate section 10279 (, 10280 , ) 10283 * In Section 2.5, add language about minor HTTP version number 10284 defaulting () 10286 * Added Section 15.5.21 for status code 422, previously defined in 10287 Section 11.2 of [WEBDAV] () 10290 * In Section 15.5.17, fixed prose about byte range comparison 10291 (, 10292 ) 10294 * In Section 3.4, explain that request/response correlation is 10295 version specific () 10298 C.5. Since draft-ietf-httpbis-semantics-03 10300 * In Section 15.4.9, include status code 308 from RFC 7538 10301 () 10303 * In Section 8.3.1, clarify that the charset parameter value is 10304 case-insensitive due to the definition in RFC 2046 10305 () 10307 * Define a separate registry for HTTP header field names 10308 () 10310 * In Section 12.1, refactor and clarify description of wildcard 10311 ("*") handling () 10313 * Deprecate Accept-Charset () 10316 * In Section 13.2, mention Cache-Control: immutable 10317 () 10319 * In Section 5.3, clarify when header field combination is allowed 10320 () 10322 * In Section 18.4, instruct IANA to mark Content-MD5 as obsolete 10323 () 10325 * Use RFC 7405 ABNF notation for case-sensitive string constants 10326 () 10328 * Rework Section 3.4 to be more version-independent 10329 () 10331 * In Section 9.3.5, clarify that DELETE needs to be successful to 10332 invalidate cache (, ) 10335 C.6. Since draft-ietf-httpbis-semantics-04 10337 * In Section 5.5, fix field-content ABNF 10338 (, 10339 ) 10341 * Move Section 5.6.6 into its own section 10342 () 10344 * In Section 8.3, reference MIME Sniffing 10345 () 10347 * In Section 5.6.1, simplify the #rule mapping for recipients 10348 (, 10349 ) 10351 * In Section 9.3.7, remove misleading text about "extension" of HTTP 10352 is needed to define method content () 10355 * Fix editorial issue in Section 3.2 () 10358 * In Section 15.5.21, rephrase language not to use "entity" anymore, 10359 and also avoid lowercase "may" () 10362 * Move discussion of retries from [HTTP/1.1] into Section 9.2.2 10363 () 10365 C.7. Since draft-ietf-httpbis-semantics-05 10367 * Moved transport-independent part of the description of trailers 10368 into Section 6.5 () 10370 * Loosen requirements on retries based upon implementation behavior 10371 () 10373 * In Section 18.9, update IANA port registry for TCP/UDP on ports 80 10374 and 443 () 10376 * In Section 16.3.2.2, revise guidelines for new header field names 10377 () 10379 * In Section 9.2.3, remove concept of "cacheable methods" in favor 10380 of prose (, 10381 ) 10383 * In Section 17.1, mention that the concept of authority can be 10384 modified by protocol extensions () 10387 * Create new subsection on content in Section 6.4, taken from 10388 portions of message body () 10391 * Moved definition of "Whitespace" into new container "Generic 10392 Syntax" () 10394 * In Section 3.1, recommend minimum URI size support for 10395 implementations () 10397 * In Section 14.1, refactored the range-unit and ranges-specifier 10398 grammars (, 10399 ) 10401 * In Section 9.3.1, caution against a request content more strongly 10402 () 10404 * Reorganized text in Section 16.3.2.2 () 10407 * In Section 15.5.4, replace "authorize" with "fulfill" 10408 () 10410 * In Section 9.3.7, removed a misleading statement about Content- 10411 Length (, 10412 ) 10414 * In Section 17.1, add text from RFC 2818 10415 () 10417 * Changed "cacheable by default" to "heuristically cacheable" 10418 throughout () 10420 C.8. Since draft-ietf-httpbis-semantics-06 10422 * In Section 7.6.3, simplify received-by grammar (and disallow comma 10423 character) () 10425 * In Section 5.1, give guidance on interoperable field names 10426 () 10428 * In Section 5.6.3, define the semantics and possible replacement of 10429 whitespace when it is known to occur (, ) 10432 * In Section 6.3, introduce field terminology and distinguish 10433 between field line values and field values; use terminology 10434 consistently throughout () 10437 * Moved #rule definition into Section 5.5 and whitespace into 10438 Section 2.1 () 10440 * In Section 14.1, explicitly call out range unit names as case- 10441 insensitive, and encourage registration 10442 () 10444 * In Section 8.4.1, explicitly call out content codings as case- 10445 insensitive, and encourage registration 10446 () 10448 * In Section 5.1, explicitly call out field names as case- 10449 insensitive () 10451 * In Section 17.13, cite [Bujlow] () 10454 * In Section 15, formally define "final" and "interim" status codes 10455 () 10457 * In Section 9.3.5, caution against a request content more strongly 10458 () 10460 * In Section 8.8.3, note that Etag can be used in trailers 10461 () 10463 * In Section 18.4, consider reserved fields as well 10464 () 10466 * In Section 4.2.4, be more correct about what was deprecated by RFC 10467 3986 (, 10468 ) 10470 * In Section 5.3, recommend comma SP when combining field lines 10471 () 10473 * In Section 7.2, make explicit requirements on origin server to use 10474 authority from absolute-form when available 10475 () 10477 * In Section 4.2.1, Section 4.2.2, Section 4.3.1, and Section 7.3.3, 10478 refactored schemes to define origin and authoritative access to an 10479 origin server for both "http" and "https" URIs to account for 10480 alternative services and secured connections that are not 10481 necessarily based on TCP () 10484 * In Section 2.2, reference RFC 8174 as well 10485 () 10487 C.9. Since draft-ietf-httpbis-semantics-07 10489 * In Section 14.2, explicitly reference the definition of 10490 representation data as including any content codings 10491 () 10493 * Move TE: trailers from [HTTP/1.1] into Section 6.5.1 10494 () 10496 * In Section 8.6, adjust requirements for handling multiple content- 10497 length values () 10499 * In Section 13.1.1 and Section 13.1.2, clarified condition 10500 evaluation () 10502 * In Section 5.5, remove concept of obs-fold, as that is 10503 HTTP/1-specific () 10505 * In Section 12, introduce the concept of request content 10506 negotiation (Section 12.3) and define for Accept-Encoding 10507 () 10509 * In Section 15.3.6, Section 15.5.9, and Section 15.5.14, remove 10510 HTTP/1-specific, connection-related requirements 10511 () 10513 * In Section 9.3.6, correct language about what is forwarded 10514 () 10516 * Throughout, replace "effective request URI", "request-target" and 10517 similar with "target URI" () 10520 * In Section 16.3.2.2 and Section 16.2.2, describe how extensions 10521 should consider scope of applicability 10522 () 10524 * In Section 3.4, don't rely on the HTTP/1.1 Messaging specification 10525 to define "message" () 10528 * In Section 8.7 and Section 10.1.3, note that URL resolution is 10529 necessary () 10531 * In Section 3.2, explicitly reference 206 as one of the status 10532 codes that provide representation data 10533 () 10535 * In Section 13.1.4, refine requirements so that they don't apply to 10536 resources without a concept of modification time 10537 () 10539 * In Section 11.7.1, specify the scope as a request, not a target 10540 resource () 10542 * In Section 3.4, introduce concept of "complete" messages 10543 () 10545 * In Section 7.1, Section 9.3.6, and Section 9.3.7, refine use of 10546 "request target" () 10549 * Throughout, remove "status-line" and "request-line", as these are 10550 HTTP/1.1-specific () 10553 C.10. Since draft-ietf-httpbis-semantics-08 10555 * In Section 15.5.17, remove duplicate definition of what makes a 10556 range satisfiable and refer instead to each range unit's 10557 definition () 10559 * In Section 14.1.2 and Section 14.2, clarify that a selected 10560 representation of zero length can only be satisfiable as a suffix 10561 range and that a server can still ignore Range for that case 10562 () 10564 * In Section 12.5.1 and Section 15.5.16, allow "Accept" as response 10565 field () 10567 * Appendix A now uses the sender variant of the "#" list expansion 10568 () 10570 * In Section 12.5.5, make the field list-based even when "*" is 10571 present () 10573 * In Section 16.3.1, add optional "Comments" entry 10574 () 10576 * In Section 18.4, reserve "*" as field name 10577 () 10579 * In Section 18.2, reserve "*" as method name 10580 () 10582 * In Section 13.1.1 and Section 13.1.2, state that multiple "*" is 10583 unlikely to be interoperable () 10586 * In Section 12.5.1, avoid use of obsolete media type parameter on 10587 text/html (, 10588 ) 10590 * Rephrase prose in Section 3.4 to become version-agnostic 10591 () 10593 * In Section 5.5, instruct recipients how to deal with control 10594 characters in field values () 10597 * In Section 5.5, update note about field ABNF 10598 () 10600 * Add Section 16 about Extending and Versioning HTTP 10601 () 10603 * In Section 15.1, include status 308 in list of heuristically 10604 cacheable status codes () 10607 * In Section 8.4, make it clearer that "identity" is not to be 10608 included () 10610 C.11. Since draft-ietf-httpbis-semantics-09 10612 * Switch to xml2rfc v3 mode for draft generation 10613 () 10615 C.12. Since draft-ietf-httpbis-semantics-10 10617 * In Section 17.6, mention compression attacks 10618 () 10620 * In Section 16.6.1, advise to make new content codings self- 10621 descriptive () 10623 * In Section 5.6.6, introduced the "parameters" ABNF rule, allowing 10624 empty parameters and trailing semicolons within media type, media 10625 range, and expectation () 10628 * In Section 15.4, explain how to create a redirected request 10629 () 10631 * In Section 8.3, defined error handling for multiple members 10632 () 10634 * In Section 1, revise the introduction and introduce HTTP/2 and 10635 HTTP/3 () 10637 * In Section 8.6, added a definition for Content-Length that 10638 encompasses its various roles in describing message content or 10639 selected representation length; in Section 15.3.7, noted that 10640 Content-Length counts only the message content (not the selected 10641 representation) and that the representation length is in each 10642 Content-Range () 10644 * Noted that "WWW-Authenticate" with more than one value on a line 10645 is sometimes not interoperable [HTTP/1.1] 10646 () 10648 * In Section 13.1.1 and Section 13.1.4, removed requirement that a 10649 validator not be sent in a 2xx response when validation fails and 10650 the server decides that the same change request has already been 10651 applied () 10653 * Moved requirements specific to HTTP/1.1 from Section 7.2 to 10654 [HTTP/1.1] () 10656 * In Section 5.5, introduce the terms "singleton field" and "list- 10657 based field" (also - in various places - discuss what to do when a 10658 singleton field is received as a list) 10659 () 10661 * In Section 10.1.1, change the ABNF back to be a list of 10662 expectations, as defined in RFC 2616 () 10665 * In Section 6.6.2 (Trailer), Section 7.6.3 (Via), Section 7.8 10666 (Upgrade), Section 7.6.1 (Connection), Section 8.4 10667 (Content-Encoding), Section 8.5 (Content-Language), Section 10.1.1 10668 (Expect), Section 13.1.1 (If-Match), Section 13.1.2 10669 (If-None-Match), Section 12.5.2 (Accept-Charset), Section 12.5.4 10670 (Accept-Language), Section 12.5.5 (Vary), Section 11.6.1 10671 (WWW-Authenticate), and Section 11.7.1 (Proxy-Authenticate), 10672 adjust ABNF to allow empty lists () 10675 * In Section 9.3.1 and Section 17.9, provide a more nuanced 10676 explanation of sensitive data in GET-based forms and describe 10677 workarounds () 10679 * In Section 13.2, allow preconditions to be evaluated before the 10680 request content (if any) is processed () 10683 * In Section 6.3 and Section 6.5.2, allow for trailer fields in 10684 multiple trailer sections, depending on the HTTP version and 10685 framing in use, with processing being iterative as each section is 10686 received () 10688 * Moved definitions of "TE" and "Upgrade" from [HTTP/1.1] 10689 () 10691 * Moved 1.1-specific discussion of TLS to Messaging and rewrote 10692 Section 4.3.4 to refer to RFC6125 () 10695 * Moved definition of "Connection" from [HTTP/1.1] 10696 () 10698 C.13. Since draft-ietf-httpbis-semantics-11 10700 * The entire document has been reorganized, with no changes to 10701 content except editorial for the reorganization 10702 () 10704 * Move IANA Upgrade Token Registry instructions from [HTTP/1.1] 10705 () 10707 C.14. Since draft-ietf-httpbis-semantics-12 10709 * In Appendix "Acknowledgements" (Appendix "Acknowledgements"), 10710 added acks for the work since 2014 () 10713 * In Section 15.3.7, specifically require that a client check the 10714 206 response header fields to determine what ranges are enclosed, 10715 since it cannot assume they exactly match those requested 10716 () 10718 * In Section 16.3, explain why new fields need to be backwards- 10719 compatible () 10721 * In Section 5.3, constrain field combination to be within a section 10722 () 10724 * In Section 5.6.7, mention that caching relaxes date sensitivity 10725 () 10727 * In Section 18.4, moved "*" field registration into main table 10728 () 10730 * In Section 1.2, reference HTTP/0.9 () 10733 * In Section 9.3.4, clarify handling of unrecognized fields 10734 () 10736 * In Section 15.2, align language about bodies and trailers with 204 10737 and 304 () 10739 * Moved table of content codings into Section 18.6, moved table of 10740 range units into Section 18.7 () 10743 * In Section 6, add an abstract data type for message to help define 10744 semantics without being dependent on the specific structure of 10745 HTTP/1.1 () 10747 * In Section 8.8.2.2, relax arbitrary 60-second comparison limit 10748 () 10750 * In Section 7.2, add ":authority" pseudo-header to Host discussion 10751 and make section applicable to both () 10754 * In Section 18.4, note that this document updates [RFC3864] 10755 () 10757 * Moved transfer-coding ABNF from [HTTP/1.1] to Section 10.1.4 and 10758 replaced "t-ranking" ABNF by equivalent "weight" 10759 () 10761 * In Section 11.5, replace "canonical root URI" by "origin" 10762 () 10764 * In Section 10.1.1, remove obsolete note about a change in RFC 723x 10765 () 10767 * Changed to using "payload" when defining requirements about the 10768 data being conveyed within a message, instead of the terms 10769 "payload body" or "response body" or "representation body", since 10770 they often get confused with the HTTP/1.1 message body (which 10771 includes transfer coding) () 10774 * Rewrite definition of HEAD method () 10777 * In Section 13.1.5, fix an off-by-one bug about how many chars to 10778 consider when checking for etags () 10781 * In Section 15.1, clarify that "no reason phrase" is fine as well 10782 () 10784 * In Section 15.3.4, remove an obsolete reference to the Warning 10785 response header field () 10788 * In Section 15.5.9, rephrase prose about connection re-use 10789 () 10791 * In Section 14.2, potentially allow Range handling on methods other 10792 than GET () 10794 * In Section 18.3, remove redundant text about status code 418 10795 () 10797 * In Section 17.16.1, rewrite requirement to refer to "secured 10798 connection" () 10800 * Make reference to [TLS13] normative () 10803 C.15. Since draft-ietf-httpbis-semantics-13 10805 * In Section 12.5.1, remove the unused "accept parameters" 10806 () 10808 * In Section 1.2, mention that RFC 1945 describes HTTP/0.9 as well 10809 () 10811 * In Section 14.5, describe non-standard use of the Content-Range 10812 header field (Section 14.4) as a request modifier to perform a 10813 partial PUT () 10815 * In Section 15.5.20, import the 421 (Misdirected Request) status 10816 code from [HTTP/2] () 10819 * In Section 2.3, rephrase the actual recipient parsing requirements 10820 () 10822 * In Section 16.1.2, mention request target forms in considerations 10823 for new methods () 10825 * Changed to using "content" instead of "payload" or "payload data" 10826 to avoid confusion with the payload of version-specific messaging 10827 frames () 10829 * In Section 13.1.3, Section 13.1.4, and Section 13.1.5, specify 10830 evaluation in a way similar to other conditional header fields 10831 () 10833 * In Section 6.6.1, specify that recipients can replace an invalid 10834 Date header field value with the time received 10835 () 10837 C.16. Since draft-ietf-httpbis-semantics-14 10839 * In Section 5.5, relax prohibition of characters in field values to 10840 CR and NUL () 10842 * In Section 15, clarify that status code values outside the range 10843 100..599 are invalid, and recommend error handling 10844 () 10846 * In Section 2.2, replaced requirement on semantic conformance with 10847 permission to ignore/workaround implementation-specific failures 10848 () 10850 * Avoid the term "whitelist" () 10853 * In Section 9.3.8, remove the normative requirement to use the 10854 message/http media type () 10857 * In Section 7.6, discuss extensibility () 10860 * In Section 5.5, tighten the recommendation for characters in newly 10861 defined fields, making it consistent with obs-text 10862 () 10864 * In Section 5.5, leading/trailing whitespace removal is at time of 10865 use, not parsing () 10868 * In Section 6, clarify that HTTP self-descriptive messages have an 10869 exception in that the request must be understood in order to parse 10870 and interpret the response () 10873 * Remove "Canonicalization and Text Defaults" 10874 () 10876 * In Section 10.1.3, refine what can be sent in Referer, and when 10877 () 10879 * In Section 11.5, explain that the protection space is not defined 10880 without additional information () 10883 * Simplify description of reactive content negotiation in 10884 Section 12.2 () 10886 * In Section 8.3.2, remove the "charset" ABNF production, and 10887 clarify where charsets appear () 10890 * In Section 12.5.3, clarify that selection _between_ multiple 10891 acceptable codings is only relevant when they have the same 10892 purpose () 10894 * In Section 13, rewrite introduction, mentioning extensibility 10895 () 10897 * Throughout, be consistent about 'content coding' vs 'content- 10898 coding' () 10900 * In Section 9.3.6, clarify that the port is mandatory in a CONNECT 10901 request target () 10902 and that the tunnel begins after the header section 10903 () 10905 * In Section 6.5, remove mid-stream trailers 10906 () 10908 * In Section 3.3, clarify duplexing semantics 10909 () 10911 * In Section 3.3, explain the implications of statelessness more 10912 clearly () 10914 * In Section 8.6, be more explicit about invalid and incorrect 10915 values ( and 10916 ) 10918 * Move discussion of statelessness from Section 3.7 to Section 3.3 10919 () 10921 * In Section 15.2.2, clarify that the upgraded protocol is in effect 10922 after the 101 response () 10925 * In Section 9.3.6, state that data received after the headers of a 10926 CONNECT message is version-specific () 10929 * In Section 4.2.3, clarify how normalization works, and align with 10930 RF3986 () 10932 * In Section 6.6.2, note that the Trailer field can be used to 10933 discover deleted trailers () 10936 * Throughout, remove unneeded normative references to [HTTP/1.1] 10937 () 10939 * In Section 10.1.4, explicitly require listing in Connection 10940 () 10942 C.17. Since draft-ietf-httpbis-semantics-15 10944 * For [HTTP/3], add an RFC Editor note to rename to "RFCnnn" before 10945 publication () 10947 * In Section 9.3.2, align prose about content in HEAD requests with 10948 description of GET () 10951 * In Section 5.3, remove the restriction to non-empty field line 10952 values () 10954 * Add forward references to definition of OWS 10955 () 10957 * In Section 17.10, add a security consideration regarding 10958 application handling of field names () 10961 C.18. Since draft-ietf-httpbis-semantics-16 10963 This draft addresses mostly editorial issues raised during or past 10964 IETF Last Call; see for a summary. 10967 Furthermore: 10969 * In Section 15.3.7, reinstate 'to a request' 10970 () 10972 * Align Section 16.3.1 with Section 16.3.2.1 10973 () 10975 * In Section 14.3, clarify that Accept-Ranges can be sent by any 10976 server, remove "none" from the ABNF because it is now a reserved 10977 range unit, and allow the field to be sent in a trailer section 10978 while noting why that is much less useful than as a header field 10979 () 10981 * In Section 7.6.3, don't specify TCP () 10984 * In Section 6.4, explain the "Content-" prefix 10985 () 10987 * In Section 7.4, check all target URIs for scheme semantic 10988 mismatches () 10990 * In Section 9.3.1, Section 9.3.2, and Section 9.3.5, clarify 10991 (again) that sending content in a request for a method that does 10992 not define such content will not interoperate without prior 10993 agreement, even if it is parsed correctly, and cannot be relied 10994 upon by an origin server unless they control the entire request 10995 chain () 10997 C.19. Since draft-ietf-httpbis-semantics-17 10999 * Move ABNF for obs-text into Section 5.5 11000 () 11002 * In Section 6.4.1, note that response metadata can be relevant as 11003 well () 11005 * In Section 6.6.2, use the term "signature" througout and lower 11006 expectations on what Trailer indicates without a trailer section 11007 () 11009 * In Section 8.3, cleanup mime sniffing discussion 11010 () 11012 * In Section 10.1.4, add a forward reference to "weight" 11013 () 11015 * In Section 12.5.3, clarify that the examples contains multiple 11016 values; also remove obsolete HTTP/1.0 note about qvalues 11017 () 11019 * In Section 15.4, remove incorrect mention of Etag as request field 11020 () 11022 * Move text about obs-fold in message/http to [HTTP/1.1]; also note 11023 that LF is forbidden in field values just as CR and NUL 11024 () 11026 * In Section 7.7, properly refer to text that has moved to 11027 [HTTP/1.1] () 11029 * Rewrite description of validators and move cache-related aspects 11030 into [CACHING] () 11032 * In Section 12.5.5, rephrase description to be more explanatory 11033 () 11035 * In Section 13.2.2, clarify that a false If-Range means ignore the 11036 Range () 11038 * In Section 13.1.3 and Section 13.1.4, restore text about missing 11039 modification date () 11042 * In Section 5.6.1.1, avoid duplicate normative requirement 11043 () 11045 * In Section 8.8.2.1, reference 'Date' more visibly 11046 () 11048 * In Section 11.7.3, state that Proxy-Authentication-Info can be 11049 used as trailer () 11051 * In Section 15.4, slightly clarify history of redirect status codes 11052 () 11054 * In Section 16.3.1, fix requirements for provisional registrations 11055 () 11057 * In Section 4.3, explicitly refer to how this spec defines access 11058 to http or https resources () 11061 * In Section 6.6.1, make clock a defined term and use that 11062 definition throughout the spec () 11065 * In Section 13.1, make preconditions consistent on when they are 11066 required to be evaluated () 11069 * Throughout, disambiguate "selected representation" and "selected 11070 response" (now "chosen response") () 11073 Acknowledgements 11075 Aside from the current editors, the following individuals deserve 11076 special recognition for their contributions to early aspects of HTTP 11077 and its core specifications: Marc Andreessen, Tim Berners-Lee, Robert 11078 Cailliau, Daniel W. Connolly, Bob Denny, John Franks, Jim Gettys, 11079 Jean-François Groff, Phillip M. Hallam-Baker, Koen Holtman, Jeffery 11080 L. Hostetler, Shel Kaphan, Dave Kristol, Yves Lafon, Scott 11081 D. Lawrence, Paul J. Leach, Håkon W. Lie, Ari Luotonen, Larry 11082 Masinter, Rob McCool, Jeffrey C. Mogul, Lou Montulli, David Morris, 11083 Henrik Frystyk Nielsen, Dave Raggett, Eric Rescorla, Tony Sanders, 11084 Lawrence C. Stewart, Marc VanHeyningen, and Steve Zilles. 11086 This edition builds on the many contributions that went into past 11087 specifications of HTTP, including RFC 1945, RFC 2068, RFC 2145, RFC 11088 2616, RFC 2617, RFC 2818, RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 11089 7234, and RFC 7235. The acknowledgements within those documents 11090 still apply. 11092 Since 2014, the following contributors have helped improve this 11093 specification by reporting bugs, asking smart questions, drafting or 11094 reviewing text, and evaluating open issues: 11096 Alan Egerton, Alex Rousskov, Amichai Rothman, Amos Jeffries, Anders 11097 Kaseorg, Andreas Gebhardt, Anne van Kesteren, Armin Abfalterer, Aron 11098 Duby, Asanka Herath, Asbjørn Ulsberg, Asta Olofsson, Attila Gulyas, 11099 Austin Wright, Barry Pollard, Ben Burkert, Benjamin Kaduk, Björn 11100 Höhrmann, Brad Fitzpatrick, Chris Pacejo, Colin Bendell, Cory 11101 Benfield, Cory Nelson, Daisuke Miyakawa, Dale Worley, Daniel 11102 Stenberg, Danil Suits, David Benjamin, David Matson, David Schinazi, 11103 Дилян Палаузов (Dilyan Palauzov), Eric Anderson, Eric Rescorla, Éric 11104 Vyncke, Erik Kline, Erwin Pe, Etan Kissling, Evert Pot, Evgeny 11105 Vrublevsky, Florian Best, Francesca Palombini, Igor Lubashev, James 11106 Callahan, James Peach, Jeffrey Yasskin, Kalin Gyokov, Kannan Goundan, 11107 奥 一穂 (Kazuho Oku), Ken Murchison, Krzysztof Maczyński, Lars Eggert, 11108 Lucas Pardue, Martin Duke, Martin Dürst, Martin Thomson, Martynas 11109 Jusevičius, Matt Menke, Matthias Pigulla, Mattias Grenfeldt, Michael 11110 Osipov, Mike Bishop, Mike Pennisi, Mike Taylor, Mike West, Mohit 11111 Sethi, Murray Kucherawy, Nathaniel J. Smith, Nicholas Hurley, Nikita 11112 Prokhorov, Patrick McManus, Piotr Sikora, Poul-Henning Kamp, Rick van 11113 Rein, Robert Wilton, Roberto Polli, Roman Danyliw, Samuel Williams, 11114 Semyon Kholodnov, Simon Pieters, Simon Schüppel, Stefan Eissing, 11115 Taylor Hunt, Todd Greer, Tommy Pauly, Vasiliy Faronov, Vladimir 11116 Lashchev, Wenbo Zhu, William A. Rowe Jr., Willy Tarreau, Xingwei Liu, 11117 Yishuai Li, and Zaheduzzaman Sarker. 11119 Index 11121 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 11123 1 11125 100 Continue (status code) Section 15.2.1 11126 100-continue (expect value) Section 10.1.1 11127 101 Switching Protocols (status code) Section 15.2.2 11128 1xx Informational (status code class) Section 15.2 11130 2 11132 200 OK (status code) Section 15.3.1 11133 201 Created (status code) Section 15.3.2 11134 202 Accepted (status code) Section 15.3.3 11135 203 Non-Authoritative Information (status code) Section 15.3.4 11136 204 No Content (status code) Section 15.3.5 11137 205 Reset Content (status code) Section 15.3.6 11138 206 Partial Content (status code) Section 15.3.7 11139 2xx Successful (status code class) Section 15.3 11141 3 11143 300 Multiple Choices (status code) Section 15.4.1 11144 301 Moved Permanently (status code) Section 15.4.2 11145 302 Found (status code) Section 15.4.3 11146 303 See Other (status code) Section 15.4.4 11147 304 Not Modified (status code) Section 15.4.5 11148 305 Use Proxy (status code) Section 15.4.6 11149 306 (Unused) (status code) Section 15.4.7 11150 307 Temporary Redirect (status code) Section 15.4.8 11151 308 Permanent Redirect (status code) Section 15.4.9 11152 3xx Redirection (status code class) Section 15.4 11154 4 11156 400 Bad Request (status code) Section 15.5.1 11157 401 Unauthorized (status code) Section 15.5.2 11158 402 Payment Required (status code) Section 15.5.3 11159 403 Forbidden (status code) Section 15.5.4 11160 404 Not Found (status code) Section 15.5.5 11161 405 Method Not Allowed (status code) Section 15.5.6 11162 406 Not Acceptable (status code) Section 15.5.7 11163 407 Proxy Authentication Required (status code) Section 15.5.8 11164 408 Request Timeout (status code) Section 15.5.9 11165 409 Conflict (status code) Section 15.5.10 11166 410 Gone (status code) Section 15.5.11 11167 411 Length Required (status code) Section 15.5.12 11168 412 Precondition Failed (status code) Section 15.5.13 11169 413 Content Too Large (status code) Section 15.5.14 11170 414 URI Too Long (status code) Section 15.5.15 11171 415 Unsupported Media Type (status code) Section 15.5.16 11172 416 Range Not Satisfiable (status code) Section 15.5.17 11173 417 Expectation Failed (status code) Section 15.5.18 11174 418 (Unused) (status code) Section 15.5.19 11175 421 Misdirected Request (status code) Section 15.5.20 11176 422 Unprocessable Content (status code) Section 15.5.21 11177 426 Upgrade Required (status code) Section 15.5.22 11178 4xx Client Error (status code class) Section 15.5 11180 5 11182 500 Internal Server Error (status code) Section 15.6.1 11183 501 Not Implemented (status code) Section 15.6.2 11184 502 Bad Gateway (status code) Section 15.6.3 11185 503 Service Unavailable (status code) Section 15.6.4 11186 504 Gateway Timeout (status code) Section 15.6.5 11187 505 HTTP Version Not Supported (status code) Section 15.6.6 11188 5xx Server Error (status code class) Section 15.6 11190 A 11192 Accept header field Section 12.5.1 11193 Accept-Charset header field Section 12.5.2 11194 Accept-Encoding header field Section 12.5.3 11195 Accept-Language header field Section 12.5.4 11196 Accept-Ranges header field Section 14.3 11197 Allow header field Section 10.2.1 11198 Authentication-Info header field Section 11.6.3 11199 Authorization header field Section 11.6.2 11200 accelerator Section 3.7, Paragraph 6 11201 authoritative response Section 17.1 11203 B 11205 browser Section 3.5 11207 C 11209 CONNECT method Section 9.3.6 11210 Connection header field Section 7.6.1 11211 Content-Encoding header field Section 8.4 11212 Content-Language header field Section 8.5 11213 Content-Length header field Section 8.6 11214 Content-Location header field Section 8.7 11215 Content-MD5 header field Section 18.4, Paragraph 9 11216 Content-Range header field Section 14.4; Section 14.5 11217 Content-Type header field Section 8.3 11218 cache Section 3.8 11219 cacheable Section 3.8, Paragraph 4 11220 client Section 3.3 11221 clock Section 5.6.7 11222 complete Section 6.1 11223 compress (Coding Format) Section 8.4.1.1 11224 compress (content coding) Section 8.4.1 11225 conditional request Section 13 11226 connection Section 3.3 11227 content Section 6.4 11228 content coding Section 8.4.1 11229 content negotiation Section 1.3, Paragraph 4 11230 control data Section 6.2 11232 D 11234 DELETE method Section 9.3.5 11235 Date header field Section 6.6.1 11236 Delimiters Section 5.6.2, Paragraph 3 11237 deflate (Coding Format) Section 8.4.1.2 11238 deflate (content coding) Section 8.4.1 11239 downstream Section 3.7, Paragraph 4 11241 E 11243 ETag field Section 8.8.3 11244 Expect header field Section 10.1.1 11245 effective request URI Section 7.1, Paragraph 8.1 11247 F 11249 Fields 11250 * Section 18.4, Paragraph 8 11251 Accept Section 12.5.1 11252 Accept-Charset Section 12.5.2 11253 Accept-Encoding Section 12.5.3 11254 Accept-Language Section 12.5.4 11255 Accept-Ranges Section 14.3 11256 Allow Section 10.2.1 11257 Authentication-Info Section 11.6.3 11258 Authorization Section 11.6.2 11259 Connection Section 7.6.1 11260 Content-Encoding Section 8.4 11261 Content-Language Section 8.5 11262 Content-Length Section 8.6 11263 Content-Location Section 8.7 11264 Content-MD5 Section 18.4, Paragraph 9 11265 Content-Range Section 14.4; Section 14.5 11266 Content-Type Section 8.3 11267 Date Section 6.6.1 11268 ETag Section 8.8.3 11269 Expect Section 10.1.1 11270 From Section 10.1.2 11271 Host Section 7.2 11272 If-Match Section 13.1.1 11273 If-Modified-Since Section 13.1.3 11274 If-None-Match Section 13.1.2 11275 If-Range Section 13.1.5 11276 If-Unmodified-Since Section 13.1.4 11277 Last-Modified Section 8.8.2 11278 Location Section 10.2.2 11279 Max-Forwards Section 7.6.2 11280 Proxy-Authenticate Section 11.7.1 11281 Proxy-Authentication-Info Section 11.7.3 11282 Proxy-Authorization Section 11.7.2 11283 Range Section 14.2 11284 Referer Section 10.1.3 11285 Retry-After Section 10.2.3 11286 Server Section 10.2.4 11287 TE Section 10.1.4 11288 Trailer Section 6.6.2 11289 Upgrade Section 7.8 11290 User-Agent Section 10.1.5 11291 Vary Section 12.5.5 11292 Via Section 7.6.3 11293 WWW-Authenticate Section 11.6.1 11294 Fragment Identifiers Section 4.2.5 11295 From header field Section 10.1.2 11296 field Section 5; Section 6.3 11297 field line Section 5.2, Paragraph 1 11298 field line value Section 5.2, Paragraph 1 11299 field name Section 5.2, Paragraph 1 11300 field value Section 5.2, Paragraph 2 11302 G 11304 GET method Section 9.3.1 11305 Grammar 11306 ALPHA Section 2.1 11307 Accept Section 12.5.1 11308 Accept-Charset Section 12.5.2 11309 Accept-Encoding Section 12.5.3 11310 Accept-Language Section 12.5.4 11311 Accept-Ranges Section 14.3 11312 Allow Section 10.2.1 11313 Authentication-Info Section 11.6.3 11314 Authorization Section 11.6.2 11315 BWS Section 5.6.3 11316 CR Section 2.1 11317 CRLF Section 2.1 11318 CTL Section 2.1 11319 Connection Section 7.6.1 11320 Content-Encoding Section 8.4 11321 Content-Language Section 8.5 11322 Content-Length Section 8.6 11323 Content-Location Section 8.7 11324 Content-Range Section 14.4 11325 Content-Type Section 8.3 11326 DIGIT Section 2.1 11327 DQUOTE Section 2.1 11328 Date Section 6.6.1 11329 ETag Section 8.8.3 11330 Expect Section 10.1.1 11331 From Section 10.1.2 11332 GMT Section 5.6.7 11333 HEXDIG Section 2.1 11334 HTAB Section 2.1 11335 HTTP-date Section 5.6.7 11336 Host Section 7.2 11337 IMF-fixdate Section 5.6.7 11338 If-Match Section 13.1.1 11339 If-Modified-Since Section 13.1.3 11340 If-None-Match Section 13.1.2 11341 If-Range Section 13.1.5 11342 If-Unmodified-Since Section 13.1.4 11343 LF Section 2.1 11344 Last-Modified Section 8.8.2 11345 Location Section 10.2.2 11346 Max-Forwards Section 7.6.2 11347 OCTET Section 2.1 11348 OWS Section 5.6.3 11349 Proxy-Authenticate Section 11.7.1 11350 Proxy-Authentication-Info Section 11.7.3 11351 Proxy-Authorization Section 11.7.2 11352 RWS Section 5.6.3 11353 Range Section 14.2 11354 Referer Section 10.1.3 11355 Retry-After Section 10.2.3 11356 SP Section 2.1 11357 Server Section 10.2.4 11358 TE Section 10.1.4 11359 Trailer Section 6.6.2 11360 URI-reference Section 4.1 11361 Upgrade Section 7.8 11362 User-Agent Section 10.1.5 11363 VCHAR Section 2.1 11364 Vary Section 12.5.5 11365 Via Section 7.6.3 11366 WWW-Authenticate Section 11.6.1 11367 absolute-URI Section 4.1 11368 absolute-path Section 4.1 11369 acceptable-ranges Section 14.3 11370 asctime-date Section 5.6.7 11371 auth-param Section 11.2 11372 auth-scheme Section 11.1 11373 authority Section 4.1 11374 challenge Section 11.3 11375 codings Section 12.5.3 11376 comment Section 5.6.5 11377 complete-length Section 14.4 11378 connection-option Section 7.6.1 11379 content-coding Section 8.4.1 11380 credentials Section 11.4 11381 ctext Section 5.6.5 11382 date1 Section 5.6.7 11383 day Section 5.6.7 11384 day-name Section 5.6.7 11385 day-name-l Section 5.6.7 11386 delay-seconds Section 10.2.3 11387 entity-tag Section 8.8.3 11388 etagc Section 8.8.3 11389 field-content Section 5.5 11390 field-name Section 5.1; Section 6.6.2 11391 field-value Section 5.5 11392 field-vchar Section 5.5 11393 first-pos Section 14.1.1; Section 14.4 11394 hour Section 5.6.7 11395 http-URI Section 4.2.1 11396 https-URI Section 4.2.2 11397 incl-range Section 14.4 11398 int-range Section 14.1.1 11399 language-range Section 12.5.4 11400 language-tag Section 8.5.1 11401 last-pos Section 14.1.1; Section 14.4 11402 media-range Section 12.5.1 11403 media-type Section 8.3.1 11404 method Section 9.1 11405 minute Section 5.6.7 11406 month Section 5.6.7 11407 obs-date Section 5.6.7 11408 obs-text Section 5.5 11409 opaque-tag Section 8.8.3 11410 other-range Section 14.1.1 11411 parameter Section 5.6.6 11412 parameter-name Section 5.6.6 11413 parameter-value Section 5.6.6 11414 parameters Section 5.6.6 11415 partial-URI Section 4.1 11416 port Section 4.1 11417 product Section 10.1.5 11418 product-version Section 10.1.5 11419 protocol-name Section 7.6.3 11420 protocol-version Section 7.6.3 11421 pseudonym Section 7.6.3 11422 qdtext Section 5.6.4 11423 query Section 4.1 11424 quoted-pair Section 5.6.4 11425 quoted-string Section 5.6.4 11426 qvalue Section 12.4.2 11427 range-resp Section 14.4 11428 range-set Section 14.1.1 11429 range-spec Section 14.1.1 11430 range-unit Section 14.1 11431 ranges-specifier Section 14.1.1 11432 received-by Section 7.6.3 11433 received-protocol Section 7.6.3 11434 rfc850-date Section 5.6.7 11435 second Section 5.6.7 11436 segment Section 4.1 11437 subtype Section 8.3.1 11438 suffix-length Section 14.1.1 11439 suffix-range Section 14.1.1 11440 t-codings Section 10.1.4 11441 tchar Section 5.6.2 11442 time-of-day Section 5.6.7 11443 token Section 5.6.2 11444 token68 Section 11.2 11445 transfer-coding Section 10.1.4 11446 transfer-parameter Section 10.1.4 11447 type Section 8.3.1 11448 unsatisfied-range Section 14.4 11449 uri-host Section 4.1 11450 weak Section 8.8.3 11451 weight Section 12.4.2 11452 year Section 5.6.7 11453 gateway Section 3.7, Paragraph 6 11454 gzip (Coding Format) Section 8.4.1.3 11455 gzip (content coding) Section 8.4.1 11457 H 11459 HEAD method Section 9.3.2 11460 Header Fields 11461 Accept Section 12.5.1 11462 Accept-Charset Section 12.5.2 11463 Accept-Encoding Section 12.5.3 11464 Accept-Language Section 12.5.4 11465 Accept-Ranges Section 14.3 11466 Allow Section 10.2.1 11467 Authentication-Info Section 11.6.3 11468 Authorization Section 11.6.2 11469 Connection Section 7.6.1 11470 Content-Encoding Section 8.4 11471 Content-Language Section 8.5 11472 Content-Length Section 8.6 11473 Content-Location Section 8.7 11474 Content-MD5 Section 18.4, Paragraph 9 11475 Content-Range Section 14.4; Section 14.5 11476 Content-Type Section 8.3 11477 Date Section 6.6.1 11478 ETag Section 8.8.3 11479 Expect Section 10.1.1 11480 From Section 10.1.2 11481 Host Section 7.2 11482 If-Match Section 13.1.1 11483 If-Modified-Since Section 13.1.3 11484 If-None-Match Section 13.1.2 11485 If-Range Section 13.1.5 11486 If-Unmodified-Since Section 13.1.4 11487 Last-Modified Section 8.8.2 11488 Location Section 10.2.2 11489 Max-Forwards Section 7.6.2 11490 Proxy-Authenticate Section 11.7.1 11491 Proxy-Authentication-Info Section 11.7.3 11492 Proxy-Authorization Section 11.7.2 11493 Range Section 14.2 11494 Referer Section 10.1.3 11495 Retry-After Section 10.2.3 11496 Server Section 10.2.4 11497 TE Section 10.1.4 11498 Trailer Section 6.6.2 11499 Upgrade Section 7.8 11500 User-Agent Section 10.1.5 11501 Vary Section 12.5.5 11502 Via Section 7.6.3 11503 WWW-Authenticate Section 11.6.1 11504 Host header field Section 7.2 11505 header section Section 6.3 11506 http URI scheme Section 4.2.1 11507 https URI scheme Section 4.2.2 11509 I 11511 If-Match header field Section 13.1.1 11512 If-Modified-Since header field Section 13.1.3 11513 If-None-Match header field Section 13.1.2 11514 If-Range header field Section 13.1.5 11515 If-Unmodified-Since header field Section 13.1.4 11516 idempotent Section 9.2.2 11517 inbound Section 3.7, Paragraph 4 11518 incomplete Section 6.1 11519 interception proxy Section 3.7, Paragraph 10 11520 intermediary Section 3.7 11522 L 11524 Last-Modified header field Section 8.8.2 11525 Location header field Section 10.2.2 11526 list-based field Section 5.5, Paragraph 7 11528 M 11530 Max-Forwards header field Section 7.6.2 11531 Media Type 11532 multipart/byteranges Section 14.6 11533 multipart/x-byteranges Section 14.6, Paragraph 4, Item 3 11534 Method 11535 * Section 18.2, Paragraph 3 11536 CONNECT Section 9.3.6 11537 DELETE Section 9.3.5 11538 GET Section 9.3.1 11539 HEAD Section 9.3.2 11540 OPTIONS Section 9.3.7 11541 POST Section 9.3.3 11542 PUT Section 9.3.4 11543 TRACE Section 9.3.8 11544 message Section 3.4; Section 6 11545 message abstraction Section 6 11546 messages Section 3.4 11547 metadata Section 8.8 11548 multipart/byteranges Media Type Section 14.6 11549 multipart/x-byteranges Media Type Section 14.6, Paragraph 4, 11550 Item 3 11552 N 11554 non-transforming proxy Section 7.7 11556 O 11558 OPTIONS method Section 9.3.7 11559 Origin Section 11.5 11560 origin Section 4.3.1 11561 origin server Section 3.6 11562 outbound Section 3.7, Paragraph 4 11564 P 11566 POST method Section 9.3.3 11567 PUT method Section 9.3.4 11568 Protection Space Section 11.5 11569 Proxy-Authenticate header field Section 11.7.1 11570 Proxy-Authentication-Info header field Section 11.7.3 11571 Proxy-Authorization header field Section 11.7.2 11572 phishing Section 17.1 11573 proxy Section 3.7, Paragraph 5 11575 R 11577 Range header field Section 14.2 11578 Realm Section 11.5 11579 Referer header field Section 10.1.3 11580 Retry-After header field Section 10.2.3 11581 recipient Section 3.4 11582 representation Section 3.2 11583 request Section 3.4 11584 request target Section 7.1 11585 resource Section 3.1; Section 4 11586 response Section 3.4 11587 reverse proxy Section 3.7, Paragraph 6 11589 S 11591 Server header field Section 10.2.4 11592 Status Code Section 15 11593 Status Codes 11594 Final Section 15, Paragraph 7 11595 Informational Section 15, Paragraph 7 11596 Interim Section 15, Paragraph 7 11597 Status Codes Classes 11598 1xx Informational Section 15.2 11599 2xx Successful Section 15.3 11600 3xx Redirection Section 15.4 11601 4xx Client Error Section 15.5 11602 5xx Server Error Section 15.6 11603 safe Section 9.2.1 11604 secured Section 4.2.2 11605 selected representation Section 3.2, Paragraph 4; Section 8.8; 11606 Section 13.1 11607 self-descriptive Section 6 11608 sender Section 3.4 11609 server Section 3.3 11610 singleton field Section 5.5, Paragraph 6 11611 spider Section 3.5 11613 T 11615 TE header field Section 10.1.4 11616 TRACE method Section 9.3.8 11617 Trailer Fields 11618 ETag Section 8.8.3 11619 Trailer header field Section 6.6.2 11620 target URI Section 7.1 11621 target resource Section 7.1 11622 trailer fields Section 6.5 11623 trailer section Section 6.5 11624 trailers Section 6.5 11625 transforming proxy Section 7.7 11626 transparent proxy Section 3.7, Paragraph 10 11627 tunnel Section 3.7, Paragraph 8 11629 U 11631 URI Section 4 11632 origin Section 4.3.1 11633 URI reference Section 4.1 11634 URI scheme 11635 http Section 4.2.1 11636 https Section 4.2.2 11637 Upgrade header field Section 7.8 11638 User-Agent header field Section 10.1.5 11639 upstream Section 3.7, Paragraph 4 11640 user agent Section 3.5 11642 V 11644 Vary header field Section 12.5.5 11645 Via header field Section 7.6.3 11646 validator Section 8.8 11647 strong Section 8.8.1 11648 weak Section 8.8.1 11650 W 11652 WWW-Authenticate header field Section 11.6.1 11654 X 11656 x-compress (content coding) Section 8.4.1 11657 x-gzip (content coding) Section 8.4.1 11659 Authors' Addresses 11661 Roy T. Fielding (editor) 11662 Adobe 11663 345 Park Ave 11664 San Jose, CA 95110 11665 United States of America 11667 Email: fielding@gbiv.com 11668 URI: https://roy.gbiv.com/ 11670 Mark Nottingham (editor) 11671 Fastly 11672 Prahran VIC 11673 Australia 11675 Email: mnot@mnot.net 11676 URI: https://www.mnot.net/ 11678 Julian Reschke (editor) 11679 greenbytes GmbH 11680 Hafenweg 16 11681 48155 Münster 11682 Germany 11684 Email: julian.reschke@greenbytes.de 11685 URI: https://greenbytes.de/tech/webdav/